Pular para o conteúdo

Hooks

Abrir e fechar, esperar a digitação, lembrar entre visitas: os hooks que toda tela reescreve.

/hooks.mdmarkdown cru, para quem lê com agent em vez de olho

A biblioteca exporta, da raiz, os hooks que toda tela acaba escrevendo à mão: abrir e fechar, esperar a pessoa parar de digitar, lembrar um filtro entre visitas, pedir a próxima página quando a lista chega ao fim. Eles não trazem dependência nova, e são os mesmos que as peças usam por dentro: o Clipboard copia com useClipboard, o Carousel e os gráficos param de animar com useReducedMotion, e o EventCalendar move a linha de agora com useInterval.

import { useDebouncedValue, useDisclosure, useLocalStorage } from '@rivocode/ui'

Todos limpam o que abriram quando o componente desmonta: timer, escuta de evento, observer. E todos renderizam no servidor sem tocar em window: o que depende do navegador devolve o valor neutro no HTML e se corrige na hidratação.

Estado

useDisclosure

Aberto ou fechado, com as três ações. onOpen e onClose só disparam na passagem de estado, e não a cada chamada.

const [opened, { open, close, toggle }] = useDisclosure(false, {
  onClose: () => form.reset(),
})

<Button onClick={open}>Novo projeto</Button>
<Dialog open={opened} onOpenChange={(next) => (next ? open() : close())}>…</Dialog>

useToggle

Alterna entre false e true, ou gira numa lista de opções. Um argumento que é uma das opções vira o valor; qualquer outro, como o evento de um onClick, só alterna.

const [view, toggleView] = useToggle(['tabela', 'cartões'] as const)

<Button variant="secondary" onClick={() => toggleView()}>Ver como {view}</Button>

useCounter

Um número com piso, teto e passo. Passar do limite para no limite, sem erro.

const [quantity, { increment, decrement }] = useCounter(1, { min: 1, max: 10 })

useListState

Uma lista com as operações imutáveis de que uma tela precisa: append, prepend, insert, remove, reorder, swap, replace, update, filter e set. Cada uma devolve uma lista nova, e os handlers são os mesmos entre renders.

const [items, handlers] = useListState<Item>([])

handlers.append({ id: crypto.randomUUID(), description: '' })
handlers.reorder({ from: 2, to: 0 })
handlers.remove(index)

useSetState

Um objeto de estado que aceita o pedaço que mudou, e mescla. É o setState das classes, para quem guarda filtros num objeto só.

const [filters, setFilters] = useSetState({ status: 'todas', page: 1 })

setFilters({ status: 'vencidas', page: 1 })
setFilters((current) => ({ page: current.page + 1 }))

usePrevious

O valor anterior diferente do atual, e não o do render anterior: renderizar de novo com o mesmo valor não apaga a memória.

const previous = usePrevious(total)
const grew = previous !== undefined && total > previous

Tempo

useDebouncedValue

O valor só assenta depois de uma pausa. É o que se passa para a consulta, enquanto o campo continua ligado ao valor cru. O segundo item cancela a espera.

const [query, setQuery] = useState('')
const [settled] = useDebouncedValue(query, 300)
const projects = useProjects({ search: settled })

useDebouncedCallback e useThrottledCallback

A função devolvida é estável e chama sempre a versão mais nova da sua. O debounce roda uma vez, com o último argumento, depois da pausa; o throttle roda na hora e entrega o último da janela no fim dela. As duas têm cancel, flush e isPending, e cancelam sozinhas no desmonte.

Cancelar é o certo para a busca, que não deve rodar para uma tela que já saiu, e é o errado para o salvar automático: quem fecha a tela meio segundo depois da última tecla perde o que digitou. Para ele, passe { flushOnUnmount: true }, e o pendente sai no desmonte, com o último argumento. Chamar flush() num useEffect seu não resolve: a limpeza do hook roda antes da sua, e quando a sua chega já não há nada pendente.

const save = useDebouncedCallback((draft: Draft) => api.save(draft), 800, {
  flushOnUnmount: true,
})
const track = useThrottledCallback((top: number) => setShadow(top > 0), 100)

useInterval e useTimeout

Declarativos: null no atraso pausa. O useTimeout devolve clear e reset, para o aviso que some sozinho e recomeça a contar quando o mouse passa.

useInterval(() => refetch(), online ? 30_000 : null)

const { clear, reset } = useTimeout(() => setVisible(false), 5000)

useIdle

Verdadeiro depois de um prazo sem teclado, ponteiro, roda ou toque.

const idle = useIdle(5 * 60_000)

useLocalStorage e useSessionStorage

O valor guardado em JSON, com o padrão enquanto nada foi gravado. Duas chamadas com a mesma chave andam juntas na mesma aba, e o localStorage acompanha a outra aba pelo evento storage. Armazenamento bloqueado ou cheio não derruba a tela: o valor segue em memória. No servidor, vale o padrão.

const [columns, setColumns, resetColumns] = useLocalStorage({
  key: 'faturas:colunas',
  defaultValue: ['número', 'cliente', 'valor'],
})

useClickOutside

Devolve a ref do elemento; o clique fora dele chama a função. nodes diz o que mais conta como dentro, como o gatilho que abriu o painel.

const ref = useClickOutside<HTMLDivElement>(() => setOpen(false), { enabled: open })

Antes de usar, confira se a peça já não resolve: Popover, Menu, Dialog e Sheet fecham no clique fora sozinhos.

useHotkeys

Atalho de teclado no documento. mod é Cmd no Mac e Ctrl fora dele, e os modificadores precisam bater exatamente: mod+k não dispara com mod+shift+k. Com o foco num campo de texto o atalho não dispara, para k não roubar a letra de quem digita; desligue com ignoreFields: false quando o atalho precisar valer dentro do campo.

useHotkeys([
  ['mod+k', () => setPaletteOpen(true)],
  ['shift+n', () => startProject()],
  ['?', () => setHelpOpen(true)],
])

A tecla é comparada pelo caractere que ela digita, e não pela posição no teclado. Três regras saem disso:

  • Símbolo ignora o shift. Em ?, +, ! ou nos dígitos, o shift é o que o layout exige para chegar ao caractere, então ele não conta: ? dispara com o shift+/ do teclado americano e com a tecla própria do ABNT2, e 1 dispara no AZERTY, onde o dígito pede shift. Escreva o caractere que sai (?), e não a combinação que o produz: shift+/ também é aceito, mas é traduzido pelo teclado americano. Em letra o shift conta, e a não dispara com A.
  • Letra vale pelo caractere. No AZERTY, z dispara na tecla que digita z, e não na tecla que fica onde o Z americano fica.
  • A posição só vale quando o caractere não diz qual é a tecla: o ˚ do Option+K no Mac, a letra cirílica do Ctrl+C num teclado russo, o Unidentified. A fileira de números vale sempre pela posição, para mod+1 funcionar no AZERTY, onde a tecla digita &.

useInfiniteScroll

A próxima página quando a sentinela no fim da lista entra na tela, com folga de 200px. Nada é pedido enquanto loading for verdadeiro ou hasMore for falso, e a sentinela é observada de novo quando a página chega: se a lista ainda não encheu a tela, a próxima é pedida sem esperar rolagem.

const { sentinelRef } = useInfiniteScroll({
  onLoadMore: fetchNextPage,
  hasMore: hasNextPage,
  loading: isFetchingNextPage,
})

<ul>{rows}</ul>
<div ref={sentinelRef} />

Para milhares de linhas, junte com a VirtualList: ela desenha só o que está na tela.

useIntersection

A última entrada do IntersectionObserver para o elemento da ref.

const { ref, entry } = useIntersection<HTMLDivElement>({ threshold: 0.5 })
const seen = entry?.isIntersecting ?? false

useElementSize

Largura e altura do elemento, pelo ResizeObserver. Zero no servidor.

const { ref, width } = useElementSize<HTMLDivElement>()
const columns = width > 720 ? 3 : 1

Se a pergunta é sobre a janela, e não sobre um elemento, é classe utilitária com sm: e lg:, ou useMobile().

useClipboard

copy devolve se deu certo; copied fica verdadeiro pelo timeout e volta sozinho. A falha fica em error.

const { copy, copied } = useClipboard({ timeout: 2000 })

<Button variant="secondary" onClick={() => copy(accessKey)}>
  {copied ? 'Copiado' : 'Copiar chave'}
</Button>

Para o botão de copiar comum, a peça Clipboard já é isso, com o ícone e o nome acessível que muda.

useReducedMotion, useDocumentTitle e useNetworkStatus

const reduced = useReducedMotion()
useDocumentTitle(`${count} faturas vencidas`)
const { online } = useNetworkStatus()

useReducedMotion segue a preferência do sistema; useDocumentTitle ignora título vazio e só devolve o de antes com restoreOnUnmount; useNetworkStatus diz true no servidor, para a faixa de "sem conexão" não piscar no primeiro quadro.

useUnsavedChanges

Avisa ao sair com mudança que ainda não foi salva. Enquanto o primeiro argumento for verdadeiro, fechar a aba, recarregar ou ir para outro site abre o aviso do próprio navegador, pelo beforeunload, com o texto dele: nenhum navegador atual mostra mensagem própria ali.

const { confirmLeave } = useUnsavedChanges(form.formState.isDirty)

<Button variant="ghost" onClick={() => confirmLeave(() => router.push('/clientes'))}>
  Voltar para clientes
</Button>

A navegação dentro do app não passa pelo beforeunload, e a biblioteca não conhece o seu roteador. O confirmLeave(leave) chama leave direto quando não há mudança, e só depois da confirmação quando há. Com { prompt: 'dialog', blocker: useBlocker(isDirty) }, a pergunta é o AlertDialog da casa, aberto por blocked e respondido por proceed e reset, no "Cancelar" da tela e na troca de rota do React Router ou do TanStack Router. A receita, com a SaveBar, está na página da SaveBar.

useMounted e useIsFirstRender

useMounted é falso no servidor e na hidratação, e verdadeiro depois: é o que separa o que só existe no navegador. useIsFirstRender é verdadeiro só no primeiro render.

const mounted = useMounted()
return mounted ? <RelativeTime value={sentAt} /> : null

useMediaQuery e useMobile

Já existiam, e continuam onde estavam: useMobile() é o mesmo corte de 640px que as peças leem.

O que não existe, de propósito

useFocusTrap. A Base UI já prende o foco onde ele precisa ficar preso: Dialog, AlertDialog, Sheet, e o Popover com modal e um PopoverClose dentro. Prender o foco fora de uma sobreposição é o que a WCAG 2.1.2 chama de armadilha de teclado; se a tela pede isso, ela pede uma dessas peças.

No React Native

@rivocode/ui-native exporta os doze que não dependem do navegador, com o mesmo código do web - o arquivo é gerado a partir da mesma fonte, e não copiado: useDisclosure, useToggle, useCounter, useListState, useSetState, usePrevious, useIsFirstRender, useDebouncedValue, useDebouncedCallback, useThrottledCallback, useInterval e useTimeout.

import { useDebouncedValue, useDisclosure } from '@rivocode/ui-native'

O useUnsavedChanges também atravessa, com código próprio, porque o gatilho é outro: não há beforeunload no aparelho. No Expo Router, passe preventRemove: usePreventRemove (de expo-router): o native stack não emite beforeRemove no voltar do cabeçalho nem no voltar do Android, e só respeita a saída segurada de antemão. Com ele o hook segura as três saídas, e o "Descartar" solta a trava e segue a navegação pedida; a função tem que ser a mesma em todo render, porque o hook a chama como hook. No stack em JavaScript, navigation (o useNavigation()) basta, pelo beforeRemove. Sem nenhum dos dois, ele segura só o voltar do Android pelo BackHandler, e só quando há onLeave, chamado depois do "Descartar".

import { usePreventRemove } from 'expo-router'

const guard = useUnsavedChanges(dirty, { preventRemove: usePreventRemove })

A pergunta é sempre o AlertDialog da casa, igual no iOS e no Android: o hook acende blocked e a tela o renderiza com proceed, reset e labels. O confirmLeave(leave) é o mesmo do web.

Os outros não portam, e cada um tem o motivo:

Hook Por que não No lugar
useLocalStorage, useSessionStorage Não há Web Storage; o AsyncStorage é assíncrono e não é peer o armazenamento do app
useClickOutside Não há clique fora de uma árvore de toque o Sheet e o Dialog fecham no fundo
useHotkeys Não há teclado global no aparelho —
useInfiniteScroll, useIntersection A lista nativa já faz onEndReached e onViewableItemsChanged da FlatList
useElementSize O layout já mede onLayout
useClipboard O expo-clipboard é peer opcional, atrás de ./clipboard a peça Clipboard de lá
useReducedMotion A Reanimated, que já é peer, exporta o seu useReducedMotion da Reanimated
useDocumentTitle Não há documento —
useNetworkStatus Pediria o NetInfo, que não é peer @react-native-community/netinfo no app
useIdle Não há evento de atividade global AppState
useMounted Não há servidor nem hidratação —

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.