Introduction: Why Hooks Deserve This Much Attention
Before hooks existed, sharing stateful logic between React components meant reaching for Higher-Order Components (HOCs) or the render props pattern — both of which worked, but both of which came with real costs: wrapper hell in your component tree, awkward prop naming collisions, and code that was genuinely harder to trace through. Hooks, introduced in React 16.8, solved this cleanly. A custom hook is nothing more than a JavaScript function whose name starts with use and which is allowed to call other hooks internally. That's the entire technical definition. But the practice of writing good custom hooks — ones that are reusable, predictable, and don't leak implementation details — is a skill that takes deliberate study.
This article is a complete treatment of that skill. We're not going to stop at three toy examples. We're going to build ten real, production-worthy hooks, understand exactly why each line of each hook exists, cover the TypeScript patterns that make them safe to reuse across a large codebase, learn how to actually test them in isolation, and finish with how to package the whole thing into a publishable npm library. If you read this article fully and rebuild these hooks yourself, you will have a genuinely reusable toolkit you can drop into every project going forward — and more importantly, you'll understand the underlying patterns well enough to design new hooks confidently on your own.
Part 1: The Rules of Hooks, and Why They Exist
Before writing custom hooks, you need a proper mental model of why the "Rules of Hooks" exist, not just what they are. The two rules are:
- Only call hooks at the top level of a function component or another
hook — never inside loops, conditions, or nested functions.
- Only call hooks from React function components or from other custom
hooks — never from regular JavaScript functions.
These rules aren't arbitrary style preferences. React tracks hook state using call order. Internally, when your component renders, React walks through your function body and matches each useState, useEffect, useRef call to a slot in an internal linked list, purely based on the order they were called in. If you conditionally skip a hook call on one render but not another — for example, wrapping a useState call in an if statement — the order shifts, and React can no longer correctly match state to the right slot. The result is corrupted state, hooks reading the wrong values, and bugs that are maddeningly difficult to trace because they only manifest under specific conditional branches.
// This breaks React's internal bookkeeping
function BrokenComponent({ condition }) {
if (condition) {
const [value, setValue] = useState(0); // sometimes called, sometimes not
}
const [other, setOther] = useState(""); // slot position shifts depending on `condition`
}
Understanding this internal mechanism — rather than just memorizing "don't put hooks in conditionals" — is what lets you debug genuinely confusing hook-related bugs quickly, and it's essential background before writing your own hooks, since a custom hook that internally violates this rule will silently corrupt the state of every component that uses it.
Part 2: Anatomy of a Good Custom Hook
A good custom hook has three properties:
It owns its complexity. The consumer of the hook shouldn't need to understand useEffect cleanup timing, AbortController, or debounce timers to use it correctly. All of that complexity lives inside the hook.
It exposes a minimal, predictable API. Ideally a hook returns either a single value, a tuple ([value, setter], mirroring useState's own convention), or a small object with clearly named properties. Avoid returning a dozen loosely related values — that's a sign the hook is doing too many unrelated jobs and should be split.
It composes cleanly with other hooks. A hook built well can be used inside another custom hook without surprising behavior — this composability is where hooks show their real power over the HOC pattern they replaced.
With that framework in place, let's build the actual library.
Part 3: useLocalStorage — State Synced to Persistent Storage
This is one of the most commonly needed custom hooks, and also one of the easiest to get subtly wrong.
import { useState, useEffect, useCallback } from "react";
function useLocalStorage(key, initialValue) {
const readValue = useCallback(() => {
if (typeof window === "undefined") return initialValue; // SSR safety
try {
const item = window.localStorage.getItem(key);
return item ? JSON.parse(item) : initialValue;
} catch (error) {
console.warn(`Error reading localStorage key "${key}":`, error);
return initialValue;
}
}, [key, initialValue]);
const [storedValue, setStoredValue] = useState(readValue);
const setValue = useCallback(
(value) => {
try {
const valueToStore = value instanceof Function ? value(storedValue) : value;
setStoredValue(valueToStore);
if (typeof window !== "undefined") {
window.localStorage.setItem(key, JSON.stringify(valueToStore));
window.dispatchEvent(new StorageEvent("local-storage", { key }));
}
} catch (error) {
console.warn(`Error setting localStorage key "${key}":`, error);
}
},
[key, storedValue]
);
useEffect(() => {
function handleStorageChange(event) {
if (event.key && event.key !== key) return;
setStoredValue(readValue());
}
window.addEventListener("storage", handleStorageChange);
window.addEventListener("local-storage", handleStorageChange);
return () => {
window.removeEventListener("storage", handleStorageChange);
window.removeEventListener("local-storage", handleStorageChange);
};
}, [key, readValue]);
return [storedValue, setValue];
}
Let's walk through exactly why every piece of this exists, because a naive implementation misses several real-world requirements:
SSR safety. If this hook runs during server-side rendering (Next.js, Remix), window doesn't exist. The typeof window === "undefined" check prevents a hard crash during server rendering — a mistake that trips up nearly every beginner writing their first localStorage hook.
Try/catch around JSON parsing. localStorage can contain corrupted or manually-edited data (a user opening DevTools and typing garbage into storage, or an old schema version from a previous app update). Without the try/catch, a single malformed value crashes the entire hook on mount.
Functional updates. Supporting setValue(prev => prev + 1), not just setValue(5), mirrors useState's own API — and it matters because without it, any consumer needing to update based on the previous value has to read storedValue from a closure that might be stale, exactly the bug class covered in the JavaScript closures article.
Cross-tab synchronization. The native storage event fires in other tabs when localStorage changes — but critically, it does not fire in the same tab that made the change. That's why we manually dispatch a custom local-storage event after every write, and listen for both events. Without this, opening the same app in two browser tabs and updating a value in one tab wouldn't update the other tab's in-memory state, even though the underlying storage is correctly synced.
This hook alone demonstrates the core principle from Part 2: all of this complexity — SSR checks, error handling, cross-tab sync — is completely hidden from anyone using the hook. They just write const [theme, setTheme] = useLocalStorage("theme", "dark") and get correct behavior in every scenario.
Debouncing comes up constantly — search inputs, autosave, resize handlers — but there are actually two distinct patterns worth separating clearly, because conflating them is a common source of confusion.
Debouncing a value (delay reacting to a value until it stops changing):
function useDebounce(value, delay = 300) {
const [debouncedValue, setDebouncedValue] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebouncedValue(value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debouncedValue;
}
Debouncing a callback function (delay the function call itself, useful for things like autosave triggered by an event handler rather than a changing value):
function useDebouncedCallback(callback, delay = 300) {
const timeoutRef = useRef(null);
const callbackRef = useRef(callback);
useEffect(() => {
callbackRef.current = callback;
}, [callback]);
const debouncedFn = useCallback(
(...args) => {
if (timeoutRef.current) clearTimeout(timeoutRef.current);
timeoutRef.current = setTimeout(() => {
callbackRef.current(...args);
}, delay);
},
[delay]
);
useEffect(() => {
return () => {
if (timeoutRef.current) clearTimeout(timeoutRef.current);
};
}, []);
return debouncedFn;
}
Notice the callbackRef pattern here — it's a subtle but important detail. If we captured callback directly inside debouncedFn's closure, every time the parent component re-rendered with a new callback function reference (which happens constantly if the parent doesn't memoize it), our debounce timer logic would use a stale, outdated version of the function. By storing the latest callback in a ref and always reading callbackRef.current inside the timeout, we guarantee the most recent version of the callback runs, regardless of how many times the component re-rendered while the timer was pending. This ref-for-latest-value pattern is one of the most useful advanced techniques in custom hook design, and it reappears throughout this article.
When to use which: use useDebounce when you have a value (search input text) and want a component to re-render only after it settles — the search API call pattern from earlier in this series. Use useDebouncedCallback when you're debouncing an imperative action itself, like an autosave function triggered on every keystroke.
Part 5: useFetch — Data Fetching With Cancellation, Caching, and Retry
A production-worthy fetch hook needs to handle more than the happy path.
function useFetch(url, options = {}) {
const [state, setState] = useState({ data: null, loading: true, error: null });
const optionsRef = useRef(options);
optionsRef.current = options;
useEffect(() => {
if (!url) return;
const controller = new AbortController();
let isMounted = true;
setState({ data: null, loading: true, error: null });
fetch(url, { ...optionsRef.current, signal: controller.signal })
.then((res) => {
if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
return res.json();
})
.then((data) => {
if (isMounted) setState({ data, loading: false, error: null });
})
.catch((err) => {
if (err.name === "AbortError") return; // expected during cleanup, not a real error
if (isMounted) setState({ data: null, loading: false, error: err });
});
return () => {
isMounted = false;
controller.abort();
};
}, [url]);
return state;
}
Three details worth explaining deeply:
AbortController and the race condition it prevents. Imagine a component that fetches data based on a userId prop, and that prop changes quickly (a user clicking through a list of profiles rapidly). Without cancellation, if the first fetch (for user A) is slow and the second fetch (for user B) is fast, the second response could arrive first, get set into state, and then the first (now outdated) response for user A arrives afterward and overwrites the correct state with stale data. AbortController cancels the in-flight request when the effect re-runs (because url changed) or the component unmounts, preventing this exact race condition.
The isMounted flag alongside AbortController. You might wonder why we need both. AbortController prevents the fetch from completing, but in some edge cases (particularly with certain fetch polyfills or when the abort happens mid-JSON-parsing), a .then() callback can still fire after unmount. The isMounted flag is a defensive backstop against calling setState on an unmounted component, which React will warn about in the console.
The optionsRef pattern. If we included options directly in the effect's dependency array, and the consumer passed a new object literal on every render (useFetch(url, { headers: {...} })), the effect would re-run on every single render, regardless of whether url actually changed — a very common and very subtle bug. By storing options in a ref and reading optionsRef.current inside the effect, we decouple the effect's re-run condition (only url changing) from unstable object references passed by the consumer.
Part 6: useToggle — Simple, But Illustrates a Design Principle
function useToggle(initialValue = false) {
const [value, setValue] = useState(initialValue);
const toggle = useCallback(() => setValue((v) => !v), []);
const setTrue = useCallback(() => setValue(true), []);
const setFalse = useCallback(() => setValue(false), []);
return [value, { toggle, setTrue, setFalse }];
}
This hook is intentionally simple, but the return shape teaches an important design lesson: returning [value, actions] — an array with a value and an object of related actions — is a clean, extensible pattern. Compare this to useState's [value, setValue] tuple; we're following the same convention while accommodating more than one action, without needing a five-element array where the consumer has to remember positional ordering.
Sometimes CSS media queries aren't enough — you need to conditionally render entirely different components based on screen size, not just different styles.
function useMediaQuery(query) {
const [matches, setMatches] = useState(() => {
if (typeof window === "undefined") return false;
return window.matchMedia(query).matches;
});
useEffect(() => {
const mediaQueryList = window.matchMedia(query);
const listener = (event) => setMatches(event.matches);
setMatches(mediaQueryList.matches); // sync in case it changed between render and effect
mediaQueryList.addEventListener("change", listener);
return () => mediaQueryList.removeEventListener("change", listener);
}, [query]);
return matches;
}
Usage:
function Navigation() {
const isMobile = useMediaQuery("(max-width: 767px)");
return isMobile ? <MobileMenu /> : <DesktopMenu />;
}
The lazy initializer in useState again avoids a server/client mismatch — computing window.matchMedia eagerly during the initial render would crash during SSR, exactly the same class of problem we solved in useLocalStorage.
function useIntersectionObserver(options = {}) {
const [entry, setEntry] = useState(null);
const elementRef = useRef(null);
useEffect(() => {
const node = elementRef.current;
if (!node) return;
const observer = new IntersectionObserver(([observedEntry]) => {
setEntry(observedEntry);
}, options);
observer.observe(node);
return () => observer.disconnect();
}, [options.threshold, options.root, options.rootMargin]);
return [elementRef, entry];
}
Usage for lazy-loading an image only when it scrolls into view:
function LazyImage({ src, alt }) {
const [ref, entry] = useIntersectionObserver({ threshold: 0.1 });
const isVisible = entry?.isIntersecting;
return (
<div ref={ref}>
{isVisible ? <img src={src} alt={alt} /> : <div className="h-48 bg-slate-800" />}
</div>
);
}
This hook is a genuinely good example of hiding real complexity: the IntersectionObserver API itself is imperative and callback-based, entirely foreign to React's declarative style. Wrapping it in a hook translates that imperative browser API into a clean piece of derived state (entry) that a component can simply read.
Part 9: useEventListener — A General-Purpose DOM Event Hook
function useEventListener(eventName, handler, element = window) {
const savedHandler = useRef(handler);
useEffect(() => {
savedHandler.current = handler;
}, [handler]);
useEffect(() => {
const targetElement = element?.current ?? element;
if (!targetElement?.addEventListener) return;
const eventListener = (event) => savedHandler.current(event);
targetElement.addEventListener(eventName, eventListener);
return () => targetElement.removeEventListener(eventName, eventListener);
}, [eventName, element]);
}
This uses the same savedHandler ref-for-latest-value pattern from useDebouncedCallback — critical here because otherwise, every time the consuming component re-renders with a new inline handler function (() => {...} defined directly in JSX, a very common pattern), the effect would tear down and re-attach the event listener on every single render, which is both wasteful and, in rare cases involving rapid re-renders, can cause missed events during the brief window of removal and re-attachment.
Usage:
function ResizeAwareComponent() {
const [width, setWidth] = useState(window.innerWidth);
useEventListener("resize", () => setWidth(window.innerWidth));
return <p>Window width: {width}px</p>;
}
Part 10: usePrevious — Accessing the Previous Render's Value
function usePrevious(value) {
const ref = useRef();
useEffect(() => {
ref.current = value;
});
return ref.current;
}
This deceptively small hook is genuinely useful for comparing current and previous props or state — for example, detecting whether a value increased or decreased to conditionally show an "up" or "down" indicator:
function PriceDisplay({ price }) {
const previousPrice = usePrevious(price);
const direction = previousPrice != null && price > previousPrice ? "up" : "down";
return <span className={direction === "up" ? "text-green-400" : "text-red-400"}>${price}</span>;
}
The reason this works is subtle and worth understanding fully: the useEffect (with no dependency array, so it runs after every render) updates ref.current to the current render's value — but effects run after the render completes. So during the render itself, ref.current still holds whatever was set during the previous render's effect. This timing gap between "what renders" and "when effects run" is exactly what makes usePrevious work.
Part 11: TypeScript — Making the Library Genuinely Safe to Reuse
A hook library without proper types is significantly less valuable in any serious codebase. Here's useLocalStorage fully typed with generics:
function useLocalStorage<T>(
key: string,
initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] {
const readValue = useCallback((): T => {
if (typeof window === "undefined") return initialValue;
try {
const item = window.localStorage.getItem(key);
return item ? (JSON.parse(item) as T) : initialValue;
} catch {
return initialValue;
}
}, [key, initialValue]);
const [storedValue, setStoredValue] = useState<T>(readValue);
const setValue = useCallback(
(value: T | ((prev: T) => T)) => {
const valueToStore = value instanceof Function ? value(storedValue) : value;
setStoredValue(valueToStore);
window.localStorage.setItem(key, JSON.stringify(valueToStore));
},
[key, storedValue]
);
return [storedValue, setValue];
}
With this, useLocalStorage<boolean>("dark-mode", false) correctly infers that the setter only accepts a boolean or a function returning a boolean — TypeScript will flag setDarkMode("yes") as an error at compile time, before it ever becomes a runtime bug. This is the exact generics pattern discussed in the TypeScript-for-React article in this series, applied specifically to hook design.
Part 12: Testing Custom Hooks in Isolation
Hooks can't be called outside a component, which means testing them naively is awkward. The @testing-library/react package's renderHook utility solves this cleanly:
npm install --save-dev @testing-library/react
import { renderHook, act } from "@testing-library/react";
import { useToggle } from "./useToggle";
test("useToggle flips the boolean value", () => {
const { result } = renderHook(() => useToggle(false));
expect(result.current[0]).toBe(false);
act(() => {
result.current[1].toggle();
});
expect(result.current[0]).toBe(true);
});
renderHook mounts your hook inside a minimal, invisible test component internally, giving you result.current to inspect the hook's return value after each update. The act() wrapper is required around anything that triggers a state update — it ensures React fully flushes the update before your assertion runs, preventing flaky, timing-dependent test failures.
Testing useDebounce requires fake timers, since we don't want tests to actually wait 300ms in real time:
import { renderHook } from "@testing-library/react";
import { useDebounce } from "./useDebounce";
test("useDebounce delays the value update", () => {
jest.useFakeTimers();
const { result, rerender } = renderHook(({ value }) => useDebounce(value, 300), {
initialProps: { value: "a" },
});
expect(result.current).toBe("a");
rerender({ value: "b" });
expect(result.current).toBe("a"); // still old value, timer hasn't fired
act(() => jest.advanceTimersByTime(300));
expect(result.current).toBe("b"); // now updated
jest.useRealTimers();
});
This kind of test is exactly what catches regressions if someone later "simplifies" the hook and accidentally removes the debounce delay entirely — a genuine risk in any shared library as more people contribute to it over time.
Part 13: Composing Hooks Together
The real power of custom hooks shows up when you build higher-level hooks from the primitives you've already written. Here's a useDebouncedSearch hook built entirely by composing useDebounce and useFetch:
function useDebouncedSearch(query, delay = 400) {
const debouncedQuery = useDebounce(query, delay);
const url = debouncedQuery ? `/api/search?q=${encodeURIComponent(debouncedQuery)}` : null;
return useFetch(url);
}
Three lines, zero new useEffect calls, zero new cleanup logic — because all of that complexity already lives inside useDebounce and useFetch. This composability is the payoff for the careful, encapsulated design discussed throughout this article. A poorly designed hook (one that leaks implementation details or has an awkward API) is painful to compose; a well-designed one nearly disappears into the next layer built on top of it.
Part 14: Common Pitfalls to Avoid
Forgetting cleanup functions. Every setTimeout, setInterval, event listener, or subscription started inside a useEffect needs a corresponding cleanup in the returned function. Skipping this is the single most common source of memory leaks and "why is this firing twice" bugs in custom hooks.
Including unstable references in dependency arrays. Passing a new object or array literal on every render, then including it in a useEffect dependency array, causes the effect to re-run every render regardless of whether the meaningful content actually changed. The optionsRef pattern from useFetch is the standard fix.
Returning too much from a single hook. If a hook returns eight loosely related values, that's a sign it's actually doing the job of two or three separate hooks and should be split for clarity and reusability.
Not handling the SSR case. Any hook touching window, document, or localStorage needs an explicit guard for server-side rendering environments, or it will crash Next.js/Remix apps during the server render pass.
Part 15: Structuring and Publishing the Library
Bringing all ten hooks together into a real, publishable package:
my-hooks/
src/
useLocalStorage.ts
useDebounce.ts
useDebouncedCallback.ts
useFetch.ts
useToggle.ts
useMediaQuery.ts
useIntersectionObserver.ts
useEventListener.ts
usePrevious.ts
index.ts
__tests__/
useToggle.test.ts
useDebounce.test.ts
package.json
tsconfig.json
// src/index.ts
export { useLocalStorage } from "./useLocalStorage";
export { useDebounce } from "./useDebounce";
export { useDebouncedCallback } from "./useDebouncedCallback";
export { useFetch } from "./useFetch";
export { useToggle } from "./useToggle";
export { useMediaQuery } from "./useMediaQuery";
export { useIntersectionObserver } from "./useIntersectionObserver";
export { useEventListener } from "./useEventListener";
export { usePrevious } from "./usePrevious";
Mark React as a peer dependency, not a direct dependency, since the consuming project already has its own React instance:
{
"name": "@yourusername/react-hooks",
"version": "1.0.0",
"peerDependencies": {
"react": ">=16.8.0"
},
"devDependencies": {
"react": "^18.0.0"
}
}
Building this with tsup (covered in depth in the npm publishing article in this series) produces both ESM and CommonJS outputs with generated type definitions, ready to npm publish.
Part 15.5: One More Pattern — useClickOutside
Dropdowns, modals, and popovers almost universally need to close when a user clicks outside their boundary. This is a small hook, but it demonstrates a technique not yet covered: attaching a listener to document while excluding clicks that originate from inside a specific ref'd element.
function useClickOutside(callback) {
const ref = useRef(null);
const callbackRef = useRef(callback);
useEffect(() => {
callbackRef.current = callback;
}, [callback]);
useEffect(() => {
function handleClick(event) {
if (ref.current && !ref.current.contains(event.target)) {
callbackRef.current(event);
}
}
document.addEventListener("mousedown", handleClick);
return () => document.removeEventListener("mousedown", handleClick);
}, []);
return ref;
}
Usage:
function Dropdown({ onClose, children }) {
const ref = useClickOutside(onClose);
return <div ref={ref} className="absolute bg-slate-800 rounded-lg p-2">{children}</div>;
}
Two details worth calling out. First, mousedown is used instead of click — this matters because mousedown fires before mouseup/click, which means if the dropdown's own toggle button is what opened it, using click could cause a same-click open-then-immediately-close race, since the outside-click handler and the toggle handler might both fire for the same interaction depending on event bubbling order. Using mousedown avoids this specific timing collision in most real implementations. Second, this hook again uses the callbackRef latest-value pattern from Part 4 and Part 9 — by this point in the article, this pattern should feel familiar rather than mysterious, which is exactly the goal: once you've internalized why it's needed, you'll recognize the situations that call for it instinctively, rather than needing to look it up each time.
Let's prove the composability claim with something substantial: a form-handling hook built entirely from patterns already covered in this article, plus a few new ones specific to form state.
function useForm(initialValues, validate) {
const [values, setValues] = useState(initialValues);
const [errors, setErrors] = useState({});
const [touched, setTouched] = useState({});
const [isSubmitting, setIsSubmitting] = useState(false);
const handleChange = useCallback((name, value) => {
setValues((prev) => ({ ...prev, [name]: value }));
}, []);
const handleBlur = useCallback(
(name) => {
setTouched((prev) => ({ ...prev, [name]: true }));
if (validate) {
const validationErrors = validate(values);
setErrors(validationErrors);
}
},
[values, validate]
);
const handleSubmit = useCallback(
(onSubmit) => async (event) => {
event.preventDefault();
const allTouched = Object.keys(values).reduce(
(acc, key) => ({ ...acc, [key]: true }),
{}
);
setTouched(allTouched);
const validationErrors = validate ? validate(values) : {};
setErrors(validationErrors);
if (Object.keys(validationErrors).length > 0) return;
setIsSubmitting(true);
try {
await onSubmit(values);
} finally {
setIsSubmitting(false);
}
},
[values, validate]
);
const reset = useCallback(() => {
setValues(initialValues);
setErrors({});
setTouched({});
}, [initialValues]);
return { values, errors, touched, isSubmitting, handleChange, handleBlur, handleSubmit, reset };
}
Notice what this hook does not need to reimplement: debouncing validation calls (it could compose useDebouncedCallback around the validate call for expensive async validation), persisting draft form state (it could compose useLocalStorage to auto-save values on every change), or detecting whether the form has unsaved changes (it could compose usePrevious to compare values against the last saved state). This is the actual payoff of building a hook library methodically instead of writing one-off logic per project: a new, fairly complex piece of functionality like form handling becomes mostly composition, with very little genuinely new code.
Here's the auto-save composition made concrete:
function useAutoSaveForm(initialValues, validate, storageKey) {
const [draft, setDraft] = useLocalStorage(storageKey, initialValues);
const form = useForm(draft, validate);
useEffect(() => {
setDraft(form.values);
}, [form.values]);
return form;
}
Four lines on top of two existing hooks, and now every form using this pattern automatically persists drafts across page reloads and browser crashes — a feature that would otherwise require careful, hook-specific implementation.
A few performance details matter more in a shared hook library than in one-off component code, precisely because these hooks will be used dozens or hundreds of times across a real application.
Stabilize returned functions with useCallback. Every hook in this library that returns a function (toggle, setValue, handleChange) wraps it in useCallback. This isn't optional polish — if a consuming component passes toggle down to a React.memo-wrapped child (the pattern discussed in the React performance article in this series), an unstabilized function reference defeats that child's memoization on every single render of the parent, silently undoing an optimization the consumer thought they had.
Avoid creating new objects in the hook's return value on every render. Returning { toggle, setTrue, setFalse } as a fresh object literal on every render (even if the three functions themselves are individually memoized) still creates referential inequality for the object itself, which matters if a consumer passes that whole object as a prop to a memoized child. For hooks with more than one or two returned actions, consider memoizing the returned object itself with useMemo if you know it's likely to be passed as a single prop elsewhere.
function useToggle(initialValue = false) {
const [value, setValue] = useState(initialValue);
const toggle = useCallback(() => setValue((v) => !v), []);
const setTrue = useCallback(() => setValue(true), []);
const setFalse = useCallback(() => setValue(false), []);
const actions = useMemo(() => ({ toggle, setTrue, setFalse }), [toggle, setTrue, setFalse]);
return [value, actions];
}
Be deliberate about effect dependency granularity. In useIntersectionObserver, notice the dependency array uses options.threshold, options.root, options.rootMargin individually rather than the whole options object. This is intentional — depending on the whole object would cause the observer to be torn down and recreated on every render where the consumer passes a fresh object literal (an extremely common pattern), even when the actual threshold values never changed.
Frequently Asked Questions
Should every piece of reusable logic become a custom hook? No. If the logic is genuinely only used in one component and unlikely to be reused, extracting it into a separate hook adds an indirection cost without a corresponding reuse benefit. Extract a custom hook once you have a second real use case, or when a single component's logic has grown complex enough that separating it improves readability even without reuse.
Can custom hooks call other custom hooks? Yes, and this is exactly the composability demonstrated in useDebouncedSearch and useAutoSaveForm above. This is one of the biggest advantages hooks have over the older HOC pattern, where composing multiple HOCs together created deeply nested wrapper components that were painful to debug in React DevTools.
Do I need to prefix every internal helper function with use? No — only functions that actually call other hooks internally need the use prefix, because that's what signals to React's linter (eslint-plugin-react-hooks) and to other developers that the Rules of Hooks apply to this function. A regular helper function that doesn't call useState, useEffect, or any other hook should not be prefixed with use, since doing so misleadingly implies hook rules apply to it.
How many hooks are too many for one library? There's no fixed number, but organize by domain once you exceed roughly 15-20 hooks — separate packages or clearly divided folders for form-related hooks, data-fetching hooks, and browser/DOM hooks, rather than one flat, unorganized list that becomes hard to discover and document.
Conclusion
Every hook in this library follows the same underlying philosophy: hide complexity, expose a minimal API, and design for composability. Once you've internalized these eleven patterns — persistent state, debouncing (both value and callback variants), safe data fetching with cancellation, responsive queries, intersection observation, general event handling, click-outside detection, and previous-value tracking — you have the actual building blocks needed to solve the vast majority of stateful logic problems that come up in real frontend projects, without reaching for a third-party library every time. And because you understand exactly why each line exists, not just what it does, you're equipped to design entirely new hooks for problems this article never covered, using the same underlying principles: hide the imperative complexity, expose a small and predictable surface area, and make sure the pieces compose cleanly with one another.
It's also worth connecting this back to the rest of this series deliberately. The AbortController pattern in useFetch is the same defensive technique that matters when integrating AI APIs, covered in the chatbot integration article — a slow AI response racing against a component unmount or a rapidly changing conversation ID is exactly the same race condition useFetch prevents for ordinary data fetching. The TypeScript generics applied to useLocalStorage here are a direct, practical application of the discriminated-union and generic-component patterns from the TypeScript-for-React article. And the discipline of profiling before optimizing, discussed at length in the React performance article, applies just as much to a shared hook library as it does to individual components — don't add useMemo around your returned action objects until you've actually confirmed a memoized child is being defeated by referential inequality, rather than adding it reflexively to every hook in the library "just in case."
If you build and genuinely use even half of these hooks across a real project, you'll notice a concrete shift in how you approach new features: instead of asking "how do I write this logic," you'll increasingly ask "which of my existing hooks can I compose to get most of this for free," which is the actual mark of a mature, well-designed personal toolkit rather than a pile of one-off utility functions.
Muhammad Farhan is a Frontend Developer specializing in React.js and Tailwind CSS, based in Dera Ismail Khan, Pakistan.
Portfolio: Muhammad Fahan