72Começar
HextaUI

Button group

Botões unidos em um único controle, com emendas compartilhadas, separadores, addons de texto, aninhamento e pilhas verticais.

import {
  IconArchive,
  IconClock,
  IconDotsVertical,
  IconFlag,
} from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

export function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="Message actions">
      <Button variant="outline">
        <IconArchive data-icon="inline-start" />
        <span className="max-sm:sr-only">Archive</span>
      </Button>
      <Button variant="outline">
        <IconFlag data-icon="inline-start" />
        <span className="max-sm:sr-only">Report</span>
      </Button>
      <Button variant="outline">
        <IconClock data-icon="inline-start" />
        <span className="max-sm:sr-only">Snooze</span>
      </Button>
      <Button variant="outline" size="icon" aria-label="More actions">
        <IconDotsVertical />
      </Button>
    </ButtonGroup>
  )
}

Instalação

pnpm dlx shadcn@latest add https://hextaui.com/r/button-group.json

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

Uso

import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
<ButtonGroup aria-label="Text formatting">
  <Button variant="outline">Bold</Button>
  <Button variant="outline">Italic</Button>
  <Button variant="outline">Underline</Button>
</ButtonGroup>

O Button group une os botões que você já usa. Instale <Button /> também.

Composição

ButtonGroup
├── Button
├── ButtonGroupSeparator
├── ButtonGroupText
└── ButtonGroup

Exemplos

Tamanhos

Defina size em cada botão. Os cantos unidos permanecem retos em todos os tamanhos, e os cantos externos mantêm o raio do botão.

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

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

const sizes = ["xs", "sm", "default", "lg"] as const

export function ButtonGroupSizes() {
  return (
    <div className="flex flex-col items-center gap-3">
      {sizes.map((size) => (
        <ButtonGroup key={size} aria-label="Formatting">
          <Button variant="outline" size={size}>
            <IconBold data-icon="inline-start" />
            Bold
          </Button>
          <Button variant="outline" size={size}>
            <IconItalic data-icon="inline-start" />
            Italic
          </Button>
          <Button variant="outline" size={size}>
            <IconUnderline data-icon="inline-start" />
            Underline
          </Button>
        </ButtonGroup>
      ))}
    </div>
  )
}

Botão dividido

Botões preenchidos ficam colados, então adicione um <ButtonGroupSeparator /> entre eles. Um gatilho de dropdown pode ser qualquer segmento.

import { IconChevronDown, IconGitBranch } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export function ButtonGroupSplit() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <ButtonGroup aria-label="Deploy">
        <Button>
          <IconGitBranch data-icon="inline-start" />
          Deploy main
        </Button>
        <ButtonGroupSeparator />
        <DropdownMenu>
          <DropdownMenuTrigger
            render={<Button size="icon" aria-label="Choose branch" />}
          >
            <IconChevronDown />
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end">
            <DropdownMenuGroup>
              <DropdownMenuItem>Deploy staging</DropdownMenuItem>
              <DropdownMenuItem>Deploy preview</DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </ButtonGroup>
      <ButtonGroup aria-label="Delete">
        <Button variant="destructive">Delete</Button>
        <ButtonGroupSeparator />
        <Button variant="destructive" size="icon" aria-label="More">
          <IconChevronDown />
        </Button>
      </ButtonGroup>
    </div>
  )
}

Separadores

Separadores entre botões de ícone, com um toggle que informa seu estado pressionado.

"use client"

import * as React from "react"
import {
  IconPlayerPause,
  IconPlayerPlay,
  IconPlayerSkipBack,
  IconPlayerSkipForward,
} from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"

export function ButtonGroupPlayer() {
  const [playing, setPlaying] = React.useState(false)

  return (
    <ButtonGroup aria-label="Playback">
      <Button variant="secondary" size="icon" aria-label="Previous track">
        <IconPlayerSkipBack />
      </Button>
      <ButtonGroupSeparator />
      <Button
        variant="secondary"
        size="icon"
        aria-label={playing ? "Pause" : "Play"}
        aria-pressed={playing}
        onClick={() => setPlaying(!playing)}
      >
        {playing ? <IconPlayerPause /> : <IconPlayerPlay />}
      </Button>
      <ButtonGroupSeparator />
      <Button variant="secondary" size="icon" aria-label="Next track">
        <IconPlayerSkipForward />
      </Button>
    </ButtonGroup>
  )
}

Feedback dentro de um grupo

Quando o rótulo de um botão muda de largura durante o carregamento, o sucesso ou o erro, os segmentos seguintes deslizam junto em vez de dar um salto.

"use client"

import * as React from "react"
import { IconChevronDown } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"

function wait(ms: number) {
  return new Promise<void>((resolve) => setTimeout(resolve, ms))
}

async function fail(ms: number) {
  await wait(ms)
  throw new Error("Request failed")
}

export function ButtonGroupFeedback() {
  const [shouldFail, setShouldFail] = React.useState(false)

  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <ButtonGroup aria-label="Save changes">
        <Button
          feedback
          loadingLabel="Saving changes"
          successLabel="All changes saved"
          errorLabel="Couldn't save"
          onClick={() => (shouldFail ? fail(900) : wait(900))}
        >
          Save
        </Button>
        <ButtonGroupSeparator />
        <Button size="icon" aria-label="More save options">
          <IconChevronDown />
        </Button>
      </ButtonGroup>
      <label className="flex items-center gap-2 text-sm text-muted-foreground">
        <input
          type="checkbox"
          checked={shouldFail}
          onChange={(event) => setShouldFail(event.target.checked)}
        />
        Fail next save
      </label>
    </div>
  )
}

Vertical

orientation="vertical" empilha os segmentos. Os separadores ficam horizontais automaticamente.

"use client"

import * as React from "react"
import { IconMinus, IconPlus } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"

export function ButtonGroupVertical() {
  const [zoom, setZoom] = React.useState(100)

  return (
    <div className="flex flex-wrap items-start justify-center gap-8">
      <div className="flex items-center gap-4">
        <ButtonGroup orientation="vertical" aria-label="Zoom">
          <Button
            variant="outline"
            size="icon"
            aria-label="Zoom in"
            disabled={zoom >= 200}
            onClick={() => setZoom((value) => Math.min(200, value + 25))}
          >
            <IconPlus />
          </Button>
          <Button
            variant="outline"
            size="icon"
            aria-label="Zoom out"
            disabled={zoom <= 25}
            onClick={() => setZoom((value) => Math.max(25, value - 25))}
          >
            <IconMinus />
          </Button>
        </ButtonGroup>
        <p className="text-sm text-muted-foreground tabular-nums">{zoom}%</p>
      </div>
      <ButtonGroup orientation="vertical" aria-label="Sort">
        <Button variant="outline">Newest first</Button>
        <Button variant="outline">Oldest first</Button>
        <Button variant="outline">Most discussed</Button>
      </ButtonGroup>
      <ButtonGroup orientation="vertical" aria-label="Position">
        <Button variant="secondary">Top</Button>
        <ButtonGroupSeparator />
        <Button variant="secondary">Bottom</Button>
      </ButtonGroup>
    </div>
  )
}

Grupos aninhados

Grupos dentro de um grupo se tornam clusters separados, com um espaço entre eles, cada um unido por conta própria.

"use client"

import * as React from "react"
import { IconArrowLeft, IconArrowRight } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

const pages = [1, 2, 3, 4]

export function ButtonGroupNested() {
  const [page, setPage] = React.useState(1)

  return (
    <ButtonGroup aria-label="Pagination">
      <ButtonGroup>
        <Button
          variant="outline"
          size="icon"
          aria-label="Previous page"
          disabled={page === 1}
          onClick={() => setPage(page - 1)}
        >
          <IconArrowLeft className="rtl:-scale-x-100" />
        </Button>
        <Button
          variant="outline"
          size="icon"
          aria-label="Next page"
          disabled={page === pages.length}
          onClick={() => setPage(page + 1)}
        >
          <IconArrowRight className="rtl:-scale-x-100" />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        {pages.map((value) => (
          <Button
            key={value}
            variant={value === page ? "secondary" : "outline"}
            size="icon"
            aria-current={value === page ? "page" : undefined}
            onClick={() => setPage(value)}
          >
            {value}
          </Button>
        ))}
      </ButtonGroup>
    </ButtonGroup>
  )
}

Com texto e um input

<ButtonGroupText /> adiciona um rótulo ou prefixo. Renderize-o como um <label> para dar nome ao input. O input se estica para preencher a linha.

"use client"

import * as React from "react"
import { IconCopy, IconLink } from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupText } from "@/components/ui/button-group"

export function ButtonGroupInput() {
  const [value, setValue] = React.useState("hextaui.com/docs/button-group")

  return (
    <ButtonGroup className="w-full max-w-md" aria-label="Share link">
      <ButtonGroupText render={<label htmlFor="share-url" />}>
        <IconLink />
        https://
      </ButtonGroupText>
      <input
        id="share-url"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        className="h-9 rounded-md border border-input bg-background px-3 text-sm transition-shadow outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-focus-ring focus-visible:outline-hidden dark:bg-input/30 pointer-coarse:text-touch"
      />
      <Button
        variant="outline"
        feedback
        successLabel="Copied"
        errorLabel="Blocked"
        onClick={() => navigator.clipboard.writeText(`https://${value}`)}
      >
        <IconCopy data-icon="inline-start" />
        Copy
      </Button>
    </ButtonGroup>
  )
}

Desativado e inválido

Desative ou marque um único segmento com aria-invalid. Um segmento inválido sobe acima de seus vizinhos para que seu anel vermelho nunca fique coberto.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

export function ButtonGroupDisabled() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <ButtonGroup aria-label="Post actions">
        <Button variant="outline">Edit</Button>
        <Button variant="outline" disabled>
          Publish
        </Button>
        <Button variant="outline">Share</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Date range">
        <Button variant="outline">Start</Button>
        <Button variant="outline" aria-invalid>
          Missing date
        </Button>
        <Button variant="outline">End</Button>
      </ButtonGroup>
    </div>
  )
}

Largura total

Dê uma largura ao grupo e flex-1 a cada botão para dividir o espaço igualmente.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

export function ButtonGroupFullWidth() {
  return (
    <ButtonGroup className="w-full max-w-md" aria-label="Range">
      <Button variant="outline" className="flex-1">
        Day
      </Button>
      <Button variant="outline" className="flex-1">
        Week
      </Button>
      <Button variant="outline" className="flex-1">
        Month
      </Button>
    </ButtonGroup>
  )
}

Como fieldset

Use render para gerar um <fieldset> dentro de formulários.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

export function ButtonGroupFieldset() {
  return (
    <ButtonGroup render={<fieldset />} aria-label="Reply">
      <Button variant="outline">Reply</Button>
      <Button variant="outline">Reply all</Button>
      <Button variant="outline">Forward</Button>
    </ButtonGroup>
  )
}

Da direita para a esquerda

Os cantos unidos, os separadores e os clusters aninhados são espelhados em layouts da direita para a esquerda.

"use client"

import * as React from "react"
import {
  IconArchive,
  IconArrowLeft,
  IconArrowRight,
  IconChevronDown,
  IconDotsVertical,
} from "@tabler/icons-react"

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"

const pages = [1, 2, 3]

export function ButtonGroupRtl() {
  const [page, setPage] = React.useState(1)

  return (
    <div dir="rtl" className="flex flex-col items-center gap-3">
      <ButtonGroup aria-label="إجراءات">
        <Button variant="outline">
          <IconArchive data-icon="inline-start" />
          أرشفة
        </Button>
        <Button variant="outline">إبلاغ</Button>
        <Button variant="outline" size="icon" aria-label="المزيد">
          <IconDotsVertical />
        </Button>
      </ButtonGroup>
      <ButtonGroup aria-label="نشر">
        <Button>نشر الآن</Button>
        <ButtonGroupSeparator />
        <Button size="icon" aria-label="خيارات">
          <IconChevronDown />
        </Button>
      </ButtonGroup>
      <ButtonGroup aria-label="الصفحات">
        <ButtonGroup>
          <Button
            variant="outline"
            size="icon"
            aria-label="السابق"
            disabled={page === 1}
            onClick={() => setPage(page - 1)}
          >
            <IconArrowLeft className="rtl:-scale-x-100" />
          </Button>
          <Button
            variant="outline"
            size="icon"
            aria-label="التالي"
            disabled={page === pages.length}
            onClick={() => setPage(page + 1)}
          >
            <IconArrowRight className="rtl:-scale-x-100" />
          </Button>
        </ButtonGroup>
        <ButtonGroup>
          {pages.map((value) => (
            <Button
              key={value}
              variant={value === page ? "secondary" : "outline"}
              size="icon"
              aria-current={value === page ? "page" : undefined}
              onClick={() => setPage(value)}
            >
              {value}
            </Button>
          ))}
        </ButtonGroup>
      </ButtonGroup>
    </div>
  )
}

Teclado

TeclaAção
TabPercorre os segmentos em ordem. O segmento em foco sobe para que seu anel e sua borda nunca fiquem cobertos.
EnterSpaceAtiva o botão em foco.

Acessibilidade

  • O grupo tem role="group". Dê a ele um aria-label que descreva o conjunto, como “Message actions”.
  • Segmentos só com ícone precisam do próprio aria-label.
  • Os separadores são expostos como separators com a orientação correta. Adicione decorative quando a linha for apenas visual.

Referência da API

Cada parte renderiza um <div> e aceita seus atributos.

ButtonGroup

PropTipoPadrão
orientation
"horizontal" | "vertical""horizontal"
render
ReactElement | (props, state) => ReactElement<div>
AtributoDescrição
data-slot="button-group"Selecione grupos no CSS.
data-orientationA orientação atual.

ButtonGroupSeparator

PropTipoPadrão
orientationO padrão é o oposto da orientação do grupo.
"horizontal" | "vertical"–
decorativeOculta a linha dos leitores de tela.
booleanfalse
render
ReactElement | (props, state) => ReactElement<div>
AtributoDescrição
data-slot="button-group-separator"Seleciona os separadores no CSS.
data-orientationA orientação resolvida.

ButtonGroupText

PropTipoPadrão
renderRenderize um <label> para dar nome a um input do grupo.
ReactElement | (props, state) => ReactElement<div>
AtributoDescrição
data-slot="button-group-text"Seleciona os segmentos de texto no CSS.

Relacionados