72Começar
HextaUI

Toggle

Um botão que fica ligado ou desligado, com um preenchimento que se assenta ao ser pressionado, uma transição clara do hover para o estado ligado e ícones que podem se preencher conforme o estado.

import { IconBold, IconItalic, IconUnderline } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleDemo() {
  return (
    <div className="flex items-center gap-1">
      <Toggle aria-label="Bold" defaultPressed>
        <IconBold />
      </Toggle>
      <Toggle aria-label="Italic">
        <IconItalic />
      </Toggle>
      <Toggle aria-label="Underline">
        <IconUnderline />
      </Toggle>
    </div>
  )
}

Instalação

pnpm dlx shadcn@latest add https://hextaui.com/r/toggle.json

Adiciona o componente, os tokens de tema do HextaUI e quaisquer componentes do HextaUI dos quais ele depende.

Uso

import { Toggle } from "@/components/ui/toggle"
<Toggle aria-label="Bold">
  <IconBold />
</Toggle>

Passar o mouse sobre um toggle desligado mostra um tom leve; ligá-lo assenta um preenchimento mais forte e leva o rótulo ao contraste total, então ligado nunca parece hover.

Exemplos

Outline

variant="outline" adiciona uma borda e uma superfície, para toggles que ficam sozinhos.

import { IconBookmark } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleOutline() {
  return (
    <div className="flex items-center gap-2">
      <Toggle variant="outline" aria-label="Bookmark">
        <IconBookmark />
      </Toggle>
      <Toggle variant="outline">
        <IconBookmark />
        Bookmark
      </Toggle>
    </div>
  )
}

Com texto

Ícones e rótulos ficam lado a lado. Toggles com texto visível não precisam de aria-label.

import { IconItalic, IconTextWrap } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleText() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle>
        <IconItalic />
        Italic
      </Toggle>
      <Toggle variant="outline" defaultPressed>
        <IconTextWrap />
        Wrap lines
      </Toggle>
      <Toggle variant="outline">Show hidden files</Toggle>
    </div>
  )
}

Preenchido quando ligado

Adicione group-data-pressed/toggle:fill-current a um ícone outline e ele se preenche quando o toggle é ligado.

import { IconBookmark, IconHeart, IconStar } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleFilledIcon() {
  return (
    <div className="flex items-center gap-1">
      <Toggle aria-label="Like" defaultPressed>
        <IconHeart className="group-data-pressed/toggle:fill-current" />
      </Toggle>
      <Toggle aria-label="Star">
        <IconStar className="group-data-pressed/toggle:fill-current" />
      </Toggle>
      <Toggle aria-label="Save">
        <IconBookmark className="group-data-pressed/toggle:fill-current" />
      </Toggle>
    </div>
  )
}

Tamanhos

sm, default e lg. Toggles apenas com ícone permanecem quadrados.

import { IconBold } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleSizes() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <Toggle size="sm" aria-label="Bold, small">
          <IconBold />
        </Toggle>
        <Toggle aria-label="Bold">
          <IconBold />
        </Toggle>
        <Toggle size="lg" aria-label="Bold, large">
          <IconBold />
        </Toggle>
      </div>
      <div className="flex items-center gap-2">
        <Toggle size="sm" variant="outline">
          Small
        </Toggle>
        <Toggle variant="outline">Default</Toggle>
        <Toggle size="lg" variant="outline">
          Large
        </Toggle>
      </div>
    </div>
  )
}

Pill

shape="pill" arredonda totalmente as pontas, para toggles dentro de superfícies arredondadas como um compositor de chat.

import { IconSparkles, IconWorld } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function TogglePill() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle shape="pill" defaultPressed>
        <IconSparkles />
        Think
      </Toggle>
      <Toggle shape="pill" variant="outline">
        <IconWorld />
        Search
      </Toggle>
    </div>
  )
}

Desabilitado

Um toggle desabilitado continua mostrando se está ligado, mas não pode ser pressionado nem focado.

import { IconBold, IconUnderline } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleDisabled() {
  return (
    <div className="flex items-center gap-2">
      <Toggle disabled aria-label="Bold">
        <IconBold />
      </Toggle>
      <Toggle disabled defaultPressed aria-label="Underline">
        <IconUnderline />
      </Toggle>
      <Toggle disabled variant="outline">
        Read-only mode
      </Toggle>
    </div>
  )
}

Controlado

Passe pressed e onPressedChange. O rótulo permanece o mesmo enquanto o ícone acompanha o estado.

"use client"

import * as React from "react"
import { IconMicrophone, IconMicrophoneOff } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleControlled() {
  const [muted, setMuted] = React.useState(false)

  return (
    <div className="flex items-center gap-3 text-sm">
      <Toggle
        variant="outline"
        aria-label="Mute microphone"
        pressed={muted}
        onPressedChange={setMuted}
      >
        {muted ? <IconMicrophoneOff /> : <IconMicrophone />}
      </Toggle>
      <span className="text-muted-foreground">
        Microphone is {muted ? "muted" : "on"}
      </span>
    </div>
  )
}

Da direita para a esquerda

Os ícones precedem o rótulo a partir da direita.

import { IconAlignRight, IconBold, IconItalic } from "@tabler/icons-react"

import { Toggle } from "@/components/ui/toggle"

export function ToggleRtl() {
  return (
    <div dir="rtl" className="flex items-center gap-2">
      <Toggle variant="outline" defaultPressed>
        <IconBold />
        عريض
      </Toggle>
      <Toggle variant="outline">
        <IconItalic />
        مائل
      </Toggle>
      <Toggle variant="outline" aria-label="محاذاة لليمين">
        <IconAlignRight />
      </Toggle>
    </div>
  )
}

Teclado

TeclaAção
SpaceEnterLiga ou desliga o toggle com foco.
TabMove o foco para o próximo toggle.

Acessibilidade

  • O toggle é um button com aria-pressed, então os leitores de tela anunciam se está ligado.
  • Dê aos toggles apenas com ícone um aria-label que nomeie a ação ("Silenciar microfone") e mantenha-o igual nos dois estados. Mudá-lo junto com o estado pressionado soa como uma dupla negação.
  • Em telas touch, a área de toque cresce para pelo menos 44px, exceto dentro de um toggle group, onde os vizinhos se sobreporiam.
  • Com movimento reduzido, nada escala; o preenchimento apenas aparece com fade.

Referência da API

Toggle

PropTipoPadrão
variant
"default" | "outline""default"
size
"default" | "sm" | "lg""default"
shape
"default" | "pill""default"
pressed
boolean–
defaultPressed
booleanfalse
onPressedChange
(pressed, details) => void–
disabled
booleanfalse
valueIdentifica o toggle dentro de um toggle group.
string–
className
string | (state) => string–
nativeButton
booleantrue
render
ReactElement | (props, state) => ReactElement<button>
AtributoDescrição
data-slot="toggle"O botão, com data-variant e data-size.
data-pressedPresente quando o toggle está ligado.
data-disabledPresente quando o toggle está desabilitado.

Relacionados

Usado em blocos

Blocos que se baseiam em Toggle.