Hooks personalizados no React: como criar os seus

Um hook personalizado é uma função cujo nome começa com use e que chama outros hooks. Você escreve um quando dois componentes precisam da mesma lógica com estado: leve as chamadas de useState e useEffect para a função, retorne o que o componente precisa e chame-a em cada componente.

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>
    );
}

Os dois spoilers chamam useToggle, e abrir um deixa o outro fechado. Cada chamada executa o próprio useState, então cada componente recebe o próprio valor. Um hook personalizado compartilha lógica, não estado.

As regras para escrever um

• O nome começa com use e uma letra maiúscula: useToggle, useOnlineStatus. A regra de lint dos hooks usa o prefixo para encontrar chamadas de hooks e verificá-las.
• Ele chama pelo menos um hook. Um auxiliar que não chama hooks é uma função comum; chame-o de formatDate, não useFormatDate, para que ele possa ser chamado em qualquer lugar, inclusive dentro de condições.
• Ele segue as regras dos hooks: chame hooks no nível superior dele e chame-o só a partir de componentes ou de outros hooks personalizados.
• Ele retorna o que for útil. Um array ([on, toggle]) é prático quando quem chama renomeia os valores; um objeto ({ data, loading, error }) se lê melhor com três ou mais.

useLocalStorage: estado que sobrevive a um recarregamento

O useState esquece tudo ao recarregar. Este hook lê o valor inicial do localStorage e grava de volta cada mudança.

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>
    );
}

A prévia roda em um frame isolado em que o navegador bloqueia o localStorage, então aqui você vai ver o aviso no Console e o hook volta para estado comum. Em uma página normal, o nome sobrevive a um recarregamento. O try/catch não serve só para esta prévia: modos de navegação privada, cookies bloqueados e uma cota cheia também fazem o armazenamento lançar erros em apps reais. Passar uma função para o useState significa que o armazenamento é lido uma vez, na primeira renderização.

useDebounce: espere o usuário parar de digitar

Uma caixa de busca não deve disparar uma requisição a cada tecla. O useDebounce retorna uma cópia de um valor que só atualiza depois que ele parou de mudar por um intervalo definido.

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>
    );
}

Digite uma palavra rápido: Typed acompanha cada tecla, Debounced alcança meio segundo depois que você para, e o Console registra uma busca. Cada tecla muda value, então o React executa a limpeza (clearTimeout) antes de iniciar um novo timer. Troque 500 por 0 e cada tecla registra a própria busca.

useWindowWidth: assinar com limpeza

Um hook que ouve o navegador precisa remover o listener quando o componente sai, ou cada montagem deixa um para trás.

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>
    );
}

Redimensione a janela do navegador e o número acompanha. Clique no botão e o Console mostra o listener sendo removido. Apague o return do efeito e depois monte e desmonte algumas vezes: você recebe uma linha added a cada vez e nenhuma removed, então os listeners antigos se acumulam. Para valores do navegador como este, o useSyncExternalStore é o hook que o React criou para a tarefa, e é uma boa coisa para chamar dentro de um hook personalizado.

A lógica é compartilhada, o estado não

Dois componentes que chamam o mesmo hook recebem duas cópias separadas de tudo o que há dentro dele. Isso surpreende quem espera que um hook funcione como uma variável global.

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>
    );
}

Clique em qualquer um dos botões e só aquele contador se move. Se os dois devem mostrar o mesmo número, mova o estado para App e passe-o para baixo, ou coloque-o em um context. Um hook personalizado pode envolver esse estado compartilhado por conveniência (useCart() lendo um CartContext), mas o compartilhamento vem do context, não do hook.

Quando escrever um hook personalizado

Extraia um hook quando o mesmo grupo de chamadas de hooks aparece em dois componentes, ou quando a lógica de efeitos de um componente é longa o bastante para que um nome a explique melhor (useOnlineStatus() se lê melhor do que vinte linhas de listeners). Não envolva uma única chamada de useState em um hook só para renomeá-la, e não escreva hooks que só chamam useEffect para definir estado a partir de props; calcule esse valor durante a renderização.