useToggle - Toggle booleano simples com controles on, off e toggle

Q: Por que usar useToggle em vez de useState(false) puro?

useToggle fornece uma API semântica: toggle(), on(), off() e set(). Elimina o toggling !prev espalhado no JSX. É mais útil quando você tem vários toggles ou quer uma intenção mais clara nos manipuladores de eventos.

Q: Qual a diferença entre toggle(), on(), off() e set()?

toggle() inverte o valor atual para o seu oposto. on() sempre define o valor como true. off() sempre define o valor como false. set(value) define o valor para qualquer booleano que você passar.

Q: Por que o hook envolve o objeto de retorno em useMemo?

Sem useMemo, uma nova referência de objeto é criada a cada renderização. Isso pode causar re-renderizações desnecessárias em componentes filhos que recebem o objeto de toggle como prop. useMemo mantém a referência estável quando apenas as funções (já memoizadas) são usadas.

Q: Armadilha: Usei useToggle para um estado que o pai também precisa controlar. Isso está correto?

Não. useToggle possui seu próprio estado (não controlado). Se o pai precisar controlar o valor, passe o booleano como prop e use callbacks. Use useToggle apenas para estado de UI local.

Q: Qual é o tipo de retorno TypeScript de useToggle?

Ele retorna UseToggleReturn, uma interface com value: boolean, toggle: () => void, on: () => void, off: () => void e set: (value: boolean) => void. Nenhum genérico é necessário.

Receita

import { useState, useCallback, useMemo } from "react";
 
interface UseToggleReturn {
  /** Valor booleano atual */
  value: boolean;
  /** Inverte o valor */
  toggle: () => void;
  /** Define como true */
  on: () => void;
  /** Define como false */
  off: () => void;
  /** Define para um valor específico */
  set: (value: boolean) => void;
}
 
function useToggle(initialValue: boolean = false): UseToggleReturn {
  const [value, setValue] = useState(initialValue);
 
  const toggle = useCallback(() => setValue((v) => !v), []);
  const on = useCallback(() => setValue(true), []);
  const off = useCallback(() => setValue(false), []);
 
  return useMemo(
    () => ({ value, toggle, on, off, set: setValue }),
    [value, toggle, on, off]
  );
}

Quando usar isso: Você tem um estado booleano (modal aberto, barra lateral visível, modo escuro, flag de recurso) e deseja uma API mais limpa do que useState bruto com toggling !prev espalhado pelo seu JSX.

Exemplo de Funcionamento

"use client";
 
function Sidebar() {
  const sidebar = useToggle(false);
 
  return (
    <div style={{ display: "flex" }}>
      <aside
        style={{
          width: sidebar.value ? 250 : 0,
          overflow: "hidden",
          transition: "width 0.3s",
          background: "#f5f5f5",
          borderRight: "1px solid #e0e0e0",
        }}
      >
        <nav style={{ padding: 16, whiteSpace: "nowrap" }}>
          <ul style={{ listStyle: "none", padding: 0 }}>
            <li>Dashboard</li>
            <li>Settings</li>
            <li>Profile</li>
          </ul>
        </nav>
      </aside>
      <main style={{ flex: 1, padding: 16 }}>
        <button onClick={sidebar.toggle}>
          {sidebar.value ? "Fechar" : "Abrir"} Sidebar
        </button>
        <p>Conteúdo principal aqui</p>
      </main>
    </div>
  );
}
 
function DarkModeToggle() {
  const darkMode = useToggle(false);
 
  return (
    <div
      style={{
        background: darkMode.value ? "#1a1a2e" : "#ffffff",
        color: darkMode.value ? "#e0e0e0" : "#333",
        padding: 24,
        transition: "all 0.3s",
      }}
    >
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <input
          type="checkbox"
          checked={darkMode.value}
          onChange={darkMode.toggle}
        />
        Modo Escuro
      </label>
    </div>
  );
}
 
function FeatureFlags() {
  const betaFeature = useToggle(false);
  const notifications = useToggle(true);
 
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <label>
        <input
          type="checkbox"
          checked={betaFeature.value}
          onChange={betaFeature.toggle}
        />
        Recursos Beta
      </label>
      <label>
        <input
          type="checkbox"
          checked={notifications.value}
          onChange={notifications.toggle}
        />
        Notificações
      </label>
      <div style={{ display: "flex", gap: 8 }}>
        <button onClick={notifications.on}>Habilitar Todas</button>
        <button onClick={notifications.off}>Desabilitar Todas</button>
      </div>
    </div>
  );
}

O que isso demonstra:

sidebar.toggle substitui () => setOpen(!open) por uma API mais limpa
darkMode.value é lido naturalmente em expressões de template
notifications.on e notifications.off fornecem chamadas explícitas para definir como true/false
Múltiplos toggles são independentes e podem ser compostos livremente

Mergulho Profundo

Como Funciona

toggle usa uma atualização funcional (v) => !v para sempre inverter com base no valor atual, evitando problemas de closure obsoleta.
on e off definem valores absolutos, úteis para botões de reset ou manipuladores de eventos que devem sempre definir um estado específico.
useCallback memoiza todas as funções para que sejam referencialmente estáveis entre renderizações, seguras para passar como props ou usar em arrays de dependência.
useMemo envolve o objeto de retorno para que os consumidores recebam uma referência estável quando apenas as funções (que já são estáveis) são usadas.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Padrão	Descrição
`initialValue`	`boolean`	`false`	Valor inicial

Retorno	Tipo	Descrição
`value`	`boolean`	Estado atual
`toggle`	`() => void`	Inverte o valor
`on`	`() => void`	Define como `true`
`off`	`() => void`	Define como `false`
`set`	`(value: boolean) => void`	Define para qualquer booleano

Variações

Retorno de tupla: Para uma API mais semelhante ao useState, retorne uma tupla:

function useToggle(initial = false): [boolean, () => void] {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue((v) => !v), []);
  return [value, toggle];
}
 
// Uso
const [isOpen, toggleOpen] = useToggle();

Com reducer: Para lógica de toggle complexa com histórico de ações:

function useToggle(initial = false) {
  const [value, dispatch] = useReducer(
    (state: boolean, action: "toggle" | "on" | "off") => {
      switch (action) {
        case "toggle": return !state;
        case "on": return true;
        case "off": return false;
      }
    },
    initial
  );
 
  return { value, dispatch };
}

Toggle persistente: Combine com useLocalStorage para toggles que sobrevivem à atualização:

function usePersistentToggle(key: string, initial = false) {
  const [value, setValue] = useLocalStorage(key, initial);
  const toggle = useCallback(() => setValue((v) => !v), [setValue]);
  const on = useCallback(() => setValue(true), [setValue]);
  const off = useCallback(() => setValue(false), [setValue]);
  return { value, toggle, on, off };
}

Notas de TypeScript

O tipo de retorno é uma interface nomeada, tornando fácil passar o objeto de toggle como prop.
Nenhum genérico é necessário, pois o valor é sempre boolean.
A função set aceita boolean diretamente (não uma união com função atualizadora) para manter a API simples.

Armadilhas

Exagero - Para um único toggle usado uma vez, useState(false) puro é suficiente. Correção: Use useToggle quando tiver vários toggles ou quiser a API semântica on/off/toggle.
Identidade do objeto - Sem useMemo, o objeto retornado cria uma nova referência a cada renderização, o que pode causar re-renderizações desnecessárias em filhos. Correção: O useMemo na receita cuida disso.
Controlado vs. não controlado - Este hook possui seu próprio estado. Se o pai precisar controlar o valor, passe o estado para baixo como props. Correção: Use useToggle para estado de UI local, não estado compartilhado.

Alternativas

Pacote	Nome do Hook	Notas
`usehooks-ts`	`useToggle`	Retorno de tupla `[value, toggle]`
`@uidotdev/usehooks`	`useToggle`	Mínimo, retorno de tupla
`ahooks`	`useToggle`	Suporta toggle não booleano entre dois valores
`react-use`	`useToggle`	Toggle booleano simples

FAQs

Por que usar useToggle em vez de useState(false) puro?

useToggle fornece uma API semântica: toggle(), on(), off() e set().
Elimina o toggling !prev espalhado no JSX.
É mais útil quando você tem vários toggles ou quer uma intenção mais clara nos manipuladores de eventos.

Qual a diferença entre toggle(), on(), off() e set()?

toggle() inverte o valor atual para o seu oposto.
on() sempre define o valor como true.
off() sempre define o valor como false.
set(value) define o valor para qualquer booleano que você passar.

Por que o hook envolve o objeto de retorno em useMemo?

Sem useMemo, uma nova referência de objeto é criada a cada renderização. Isso pode causar re-renderizações desnecessárias em componentes filhos que recebem o objeto de toggle como prop. useMemo mantém a referência estável quando apenas as funções (já memoizadas) são usadas.

Por que toggle() usa uma atualização funcional (v) => !v em vez de !value?

A atualização funcional lê o estado atual no momento da execução, não no momento em que a função foi criada. Isso evita bugs de closure obsoleta quando toggle() é chamado de manipuladores de eventos ou efeitos.

Posso usar o padrão de retorno de tupla em vez do padrão de objeto?

Sim. A seção Variações mostra uma variante de tupla:

const [isOpen, toggleOpen] = useToggle();

Use a tupla para casos simples e o objeto para múltiplos controles (on, off, set).

Como faço um toggle persistir entre atualizações de página?

Combine com useLocalStorage:

function usePersistentToggle(key: string, initial = false) {
  const [value, setValue] = useLocalStorage(key, initial);
  const toggle = useCallback(() => setValue((v) => !v), [setValue]);
  return { value, toggle };
}

Armadilha: Passei o objeto de toggle como prop e meu filho re-renderiza toda vez. Por quê?

Se você desestruturar e recriar o objeto no pai, a referência muda. Passe o objeto envolvido por useMemo diretamente, ou passe funções estáveis individuais (toggle, on, off) como props separadas.

Armadilha: Usei useToggle para um estado que o pai também precisa controlar. Isso está correto?

Não. useToggle possui seu próprio estado (não controlado). Se o pai precisar controlar o valor, passe o booleano como prop e use callbacks. Use useToggle apenas para estado de UI local.

Qual é o tipo de retorno TypeScript de useToggle?

Ele retorna UseToggleReturn, uma interface com value: boolean, toggle: () => void, on: () => void, off: () => void e set: (value: boolean) => void. Nenhum genérico é necessário.

Posso usar useReducer em vez de useState para o toggle?

Sim. A seção Variações mostra uma variante baseada em reducer que dispara ações de string como "toggle", "on" e "off". Isso é útil para lógica de toggle complexa ou rastreamento de histórico de ações.

Relacionados

useLocalStorage - persiste o estado do toggle
useKeyboardShortcut - toggle com um atalho de teclado
useClickOutside - fecha ao clicar fora

Receita

import { useState, useCallback, useMemo } from "react";
 
interface UseToggleReturn {
  /** Valor booleano atual */
  value: boolean;
  /** Inverte o valor */
  toggle: () => void;
  /** Define como true */
  on: () => void;
  /** Define como false */
  off: () => void;
  /** Define para um valor específico */
  set: (value: boolean) => void;
}
 
function useToggle(initialValue: boolean = false): UseToggleReturn {
  const [value, setValue] = useState(initialValue);
 
  const toggle = useCallback(() => setValue((v) => !v), []);
  const on = useCallback(() => setValue(true), []);
  const off = useCallback(() => setValue(false), []);
 
  return useMemo(
    () => ({ value, toggle, on, off, set: setValue }),
    [value, toggle, on, off]
  );
}

Exemplo de Funcionamento

"use client";
 
function Sidebar() {
  const sidebar = useToggle(false);
 
  return (
    <div style={{ display: "flex" }}>
      <aside
        style={{
          width: sidebar.value ? 250 : 0,
          overflow: "hidden",
          transition: "width 0.3s",
          background: "#f5f5f5",
          borderRight: "1px solid #e0e0e0",
        }}
      >
        <nav style={{ padding: 16, whiteSpace: "nowrap" }}>
          <ul style={{ listStyle: "none", padding: 0 }}>
            <li>Dashboard</li>
            <li>Settings</li>
            <li>Profile</li>
          </ul>
        </nav>
      </aside>
      <main style={{ flex: 1, padding: 16 }}>
        <button onClick={sidebar.toggle}>
          {sidebar.value ? "Fechar" : "Abrir"} Sidebar
        </button>
        <p>Conteúdo principal aqui</p>
      </main>
    </div>
  );
}
 
function DarkModeToggle() {
  const darkMode = useToggle(false);
 
  return (
    <div
      style={{
        background: darkMode.value ? "#1a1a2e" : "#ffffff",
        color: darkMode.value ? "#e0e0e0" : "#333",
        padding: 24,
        transition: "all 0.3s",
      }}
    >
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <input
          type="checkbox"
          checked={darkMode.value}
          onChange={darkMode.toggle}
        />
        Modo Escuro
      </label>
    </div>
  );
}
 
function FeatureFlags() {
  const betaFeature = useToggle(false);
  const notifications = useToggle(true);
 
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <label>
        <input
          type="checkbox"
          checked={betaFeature.value}
          onChange={betaFeature.toggle}
        />
        Recursos Beta
      </label>
      <label>
        <input
          type="checkbox"
          checked={notifications.value}
          onChange={notifications.toggle}
        />
        Notificações
      </label>
      <div style={{ display: "flex", gap: 8 }}>
        <button onClick={notifications.on}>Habilitar Todas</button>
        <button onClick={notifications.off}>Desabilitar Todas</button>
      </div>
    </div>
  );
}

O que isso demonstra:

sidebar.toggle substitui () => setOpen(!open) por uma API mais limpa
darkMode.value é lido naturalmente em expressões de template
notifications.on e notifications.off fornecem chamadas explícitas para definir como true/false
Múltiplos toggles são independentes e podem ser compostos livremente

Mergulho Profundo

Como Funciona

toggle usa uma atualização funcional (v) => !v para sempre inverter com base no valor atual, evitando problemas de closure obsoleta.
on e off definem valores absolutos, úteis para botões de reset ou manipuladores de eventos que devem sempre definir um estado específico.
useCallback memoiza todas as funções para que sejam referencialmente estáveis entre renderizações, seguras para passar como props ou usar em arrays de dependência.
useMemo envolve o objeto de retorno para que os consumidores recebam uma referência estável quando apenas as funções (que já são estáveis) são usadas.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Padrão	Descrição
`initialValue`	`boolean`	`false`	Valor inicial

Retorno	Tipo	Descrição
`value`	`boolean`	Estado atual
`toggle`	`() => void`	Inverte o valor
`on`	`() => void`	Define como `true`
`off`	`() => void`	Define como `false`
`set`	`(value: boolean) => void`	Define para qualquer booleano

Variações

Retorno de tupla: Para uma API mais semelhante ao useState, retorne uma tupla:

function useToggle(initial = false): [boolean, () => void] {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue((v) => !v), []);
  return [value, toggle];
}
 
// Uso
const [isOpen, toggleOpen] = useToggle();

Com reducer: Para lógica de toggle complexa com histórico de ações:

function useToggle(initial = false) {
  const [value, dispatch] = useReducer(
    (state: boolean, action: "toggle" | "on" | "off") => {
      switch (action) {
        case "toggle": return !state;
        case "on": return true;
        case "off": return false;
      }
    },
    initial
  );
 
  return { value, dispatch };
}

Toggle persistente: Combine com useLocalStorage para toggles que sobrevivem à atualização:

function usePersistentToggle(key: string, initial = false) {
  const [value, setValue] = useLocalStorage(key, initial);
  const toggle = useCallback(() => setValue((v) => !v), [setValue]);
  const on = useCallback(() => setValue(true), [setValue]);
  const off = useCallback(() => setValue(false), [setValue]);
  return { value, toggle, on, off };
}

Notas de TypeScript

O tipo de retorno é uma interface nomeada, tornando fácil passar o objeto de toggle como prop.
Nenhum genérico é necessário, pois o valor é sempre boolean.
A função set aceita boolean diretamente (não uma união com função atualizadora) para manter a API simples.

Armadilhas

Exagero - Para um único toggle usado uma vez, useState(false) puro é suficiente. Correção: Use useToggle quando tiver vários toggles ou quiser a API semântica on/off/toggle.
Identidade do objeto - Sem useMemo, o objeto retornado cria uma nova referência a cada renderização, o que pode causar re-renderizações desnecessárias em filhos. Correção: O useMemo na receita cuida disso.
Controlado vs. não controlado - Este hook possui seu próprio estado. Se o pai precisar controlar o valor, passe o estado para baixo como props. Correção: Use useToggle para estado de UI local, não estado compartilhado.

Alternativas

Pacote	Nome do Hook	Notas
`usehooks-ts`	`useToggle`	Retorno de tupla `[value, toggle]`
`@uidotdev/usehooks`	`useToggle`	Mínimo, retorno de tupla
`ahooks`	`useToggle`	Suporta toggle não booleano entre dois valores
`react-use`	`useToggle`	Toggle booleano simples

FAQs

Por que usar useToggle em vez de useState(false) puro?

useToggle fornece uma API semântica: toggle(), on(), off() e set().
Elimina o toggling !prev espalhado no JSX.
É mais útil quando você tem vários toggles ou quer uma intenção mais clara nos manipuladores de eventos.

Qual a diferença entre toggle(), on(), off() e set()?

toggle() inverte o valor atual para o seu oposto.
on() sempre define o valor como true.
off() sempre define o valor como false.
set(value) define o valor para qualquer booleano que você passar.

Por que o hook envolve o objeto de retorno em useMemo?

Por que toggle() usa uma atualização funcional (v) => !v em vez de !value?

Posso usar o padrão de retorno de tupla em vez do padrão de objeto?

Sim. A seção Variações mostra uma variante de tupla:

const [isOpen, toggleOpen] = useToggle();

Use a tupla para casos simples e o objeto para múltiplos controles (on, off, set).

Como faço um toggle persistir entre atualizações de página?

Combine com useLocalStorage:

function usePersistentToggle(key: string, initial = false) {
  const [value, setValue] = useLocalStorage(key, initial);
  const toggle = useCallback(() => setValue((v) => !v), [setValue]);
  return { value, toggle };
}

Armadilha: Passei o objeto de toggle como prop e meu filho re-renderiza toda vez. Por quê?

Armadilha: Usei useToggle para um estado que o pai também precisa controlar. Isso está correto?

Não. useToggle possui seu próprio estado (não controlado). Se o pai precisar controlar o valor, passe o booleano como prop e use callbacks. Use useToggle apenas para estado de UI local.

Qual é o tipo de retorno TypeScript de useToggle?

Ele retorna UseToggleReturn, uma interface com value: boolean, toggle: () => void, on: () => void, off: () => void e set: (value: boolean) => void. Nenhum genérico é necessário.

Posso usar useReducer em vez de useState para o toggle?

Relacionados

useLocalStorage - persiste o estado do toggle
useKeyboardShortcut - toggle com um atalho de teclado
useClickOutside - fecha ao clicar fora

useToggle - Toggle booleano simples com controles on, off e toggle

Buscar na documentação

useToggle - Toggle booleano simples com controles on, off e toggle