React Custom Hooks: How to Write Your Own, with Examples

A custom hook is a function whose name starts with use and that calls other hooks. You write one when two components need the same stateful logic: move the useState and useEffect calls into the function, return what the component needs, and call it from each component.

import { useState } from 'react';

function useToggle(initial = false) {
    const [on, setOn] = useState(initial);
    const toggle = () => setOn((v) => !v);
    return [on, toggle];
}

function Spoiler({ title, children }) {
    const [open, toggle] = useToggle();
    return (
        <div style={{ marginBottom: 8 }}>
            <button onClick={toggle}>{open ? 'Hide' : 'Show'} {title}</button>
            {open && <p>{children}</p>}
        </div>
    );
}

export default function App() {
    return (
        <div>
            <Spoiler title="ending">The butler did it.</Spoiler>
            <Spoiler title="sequel">The butler did it again.</Spoiler>
        </div>
    );
}

Both spoilers call useToggle, and opening one leaves the other closed. Each call runs its own useState, so each component gets its own value. A custom hook shares logic, not state.

The rules for writing one

• The name starts with use and a capital letter: useToggle, useOnlineStatus. The lint rule for hooks uses the prefix to find hook calls and check them.
• It calls at least one hook. A helper that calls no hooks is an ordinary function; name it formatDate, not useFormatDate, so it can be called anywhere, including inside conditions.
• It follows the rules of hooks: call hooks at its top level, and call it only from components or other custom hooks.
• It returns whatever is useful. An array ([on, toggle]) is handy when callers rename the values; an object ({ data, loading, error }) reads better for three or more.

useLocalStorage: state that survives a reload

useState forgets everything on reload. This hook reads the starting value from localStorage and writes every change back.

import { useState, useEffect } from 'react';

function readStored(key, fallback) {
    try {
        const raw = window.localStorage.getItem(key);
        return raw === null ? fallback : JSON.parse(raw);
    } catch {
        console.warn('localStorage is not available, keeping the value in memory');
        return fallback;
    }
}

function useLocalStorage(key, initial) {
    const [value, setValue] = useState(() => readStored(key, initial));

    useEffect(() => {
        try {
            window.localStorage.setItem(key, JSON.stringify(value));
        } catch {
            // Storage blocked or full: the value still works for this visit
        }
    }, [key, value]);

    return [value, setValue];
}

export default function App() {
    const [name, setName] = useLocalStorage('demo-name', '');
    return (
        <div>
            <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Your name" />
            <p>Hello, {name || 'stranger'}.</p>
        </div>
    );
}

The preview runs in a sandboxed frame where the browser blocks localStorage, so here you will see the warning in the Console and the hook falls back to plain state. In a normal page the name survives a reload. The try/catch is not only for this preview: private browsing modes, blocked cookies and a full quota all make storage throw in real apps too. Passing a function to useState means storage is read once, on the first render.

useDebounce: wait until the user stops typing

A search box should not fire a request on every keystroke. useDebounce returns a copy of a value that only updates after it has stopped changing for a set delay.

import { useState, useEffect } from 'react';

function useDebounce(value, delay) {
    const [debounced, setDebounced] = useState(value);

    useEffect(() => {
        const id = setTimeout(() => setDebounced(value), delay);
        return () => clearTimeout(id);
    }, [value, delay]);

    return debounced;
}

export default function App() {
    const [text, setText] = useState('');
    const query = useDebounce(text, 500);

    useEffect(() => {
        if (query) console.log('search for:', query);
    }, [query]);

    return (
        <div>
            <input value={text} onChange={(e) => setText(e.target.value)} placeholder="Search" />
            <p>Typed: {text}</p>
            <p>Debounced: {query}</p>
        </div>
    );
}

Type a word quickly: Typed follows every key, Debounced catches up half a second after you stop, and the Console logs one search. Each keystroke changes value, so React runs the cleanup (clearTimeout) before starting a new timer. Change 500 to 0 and every keystroke logs its own search.

useWindowWidth: subscribe with cleanup

A hook that listens to the browser must remove its listener when the component goes away, or every mount leaves one behind.

import { useState, useEffect } from 'react';

function useWindowWidth() {
    const [width, setWidth] = useState(window.innerWidth);

    useEffect(() => {
        const onResize = () => setWidth(window.innerWidth);
        window.addEventListener('resize', onResize);
        console.log('resize listener added');
        return () => {
            window.removeEventListener('resize', onResize);
            console.log('resize listener removed');
        };
    }, []);

    return width;
}

function WidthBadge() {
    const width = useWindowWidth();
    return <p>This frame is {width}px wide: {width < 500 ? 'narrow' : 'wide'} layout.</p>;
}

export default function App() {
    const [show, setShow] = useState(true);
    return (
        <div>
            <button onClick={() => setShow(!show)}>{show ? 'Unmount' : 'Mount'} badge</button>
            {show && <WidthBadge />}
        </div>
    );
}

Resize the browser window and the number follows. Click the button and the Console shows the listener being removed. Delete the return from the effect, then mount and unmount a few times: you get an added line each time and no removed, so the old listeners pile up. For browser values like this one, useSyncExternalStore is the hook React built for the job, and it is a good thing to call inside a custom hook.

Logic is shared, state is not

Two components calling the same hook get two separate copies of everything inside it. That surprises people who expect a hook to work like a global variable.

import { useState } from 'react';

function useCounter() {
    const [count, setCount] = useState(0);
    return [count, () => setCount((c) => c + 1)];
}

function Counter({ name }) {
    const [count, increment] = useCounter();
    return (
        <p>
            {name}: {count} <button onClick={increment}>+1</button>
        </p>
    );
}

export default function App() {
    return (
        <div>
            <Counter name="First" />
            <Counter name="Second" />
        </div>
    );
}

Click either button and only that counter moves. If both should show the same number, move the state into App and pass it down, or put it in context. A custom hook can wrap that shared state for convenience (useCart() reading a CartContext), but the sharing comes from the context, not from the hook.

When to write a custom hook

Extract a hook when the same group of hook calls appears in two components, or when one component's effect logic is long enough that a name would explain it better (useOnlineStatus() reads better than twenty lines of listeners). Do not wrap a single useState call in a hook just to rename it, and do not write hooks that only call useEffect to set state from props; compute that value during render instead.