Button Group

Formulario

Agrupa botões colados visualmente, resolvendo bordas internas e arredondando só as pontas, na horizontal ou na vertical.

Carregando

Instalação

Recebe correções por update de versão. O caminho recomendado.

npm i @trdr/ui

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

Uso

import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@trdr/ui/button-group"

export function Exemplo() {
  return <ButtonGroup />
}

Variantes

GrupoValoresPadrão
orientation
horizontalvertical
horizontal

Props

ButtonGroupPropsestende React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof buttonGroupVariants>
ButtonGroupTextPropsestende React.HTMLAttributes<HTMLDivElement>
ButtonGroupSeparatorPropsestende React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>

Quando usar

Use o ButtonGroup para colar visualmente uma sequencia curta de botoes que agem como um bloco so: um paginador (anterior, copiar, proximo), um seletor de intervalo (1D, 1S, 1M, 1A), um par comprar/vender, uma barra de ferramentas compacta. Ele compoe o Button existente sem exigir que o consumidor mude nenhuma classe nos filhos: o proprio ButtonGroup resolve a borda duplicada entre botoes vizinhos e arredonda so as pontas da sequencia, nao cada botao individualmente.

Quando nao usar

Nao use ButtonGroup para acoes que nao tem relacao entre si (um botao de salvar longe de um botao de excluir, por exemplo): colar visualmente sugere que os botoes formam um conjunto coerente, e usar o grupo para acoes desconexas confunde mais do que ajuda. Para um conjunto de opcoes onde so uma fica selecionada por vez (como um filtro de abas), prefira um toggle-group quando ele existir: o ButtonGroup e so composicao visual, ele nao coordena selecao nem estado entre os filhos.

Anatomia

  • ButtonGroup (data-slot="button-group", role="group"): a raiz, flex com os filhos esticados (items-stretch) para todos terem a mesma altura. Aceita orientation horizontal (padrao) ou vertical.
  • ButtonGroupSeparator (data-slot="button-group-separator"): divisor fino entre botoes, quando espacamento e cor de fundo nao bastam para separar dois grupos de acao dentro do mesmo ButtonGroup. Orientacao padrao vertical (para um grupo horizontal); passe orientation="horizontal" dentro de um grupo vertical.
  • ButtonGroupText (data-slot="button-group-text"): rotulo ou prefixo estatico (nao clicavel) dentro do grupo, por exemplo uma etiqueta antes de um par de botoes de incremento/decremento.

Acessibilidade

A raiz carrega role="group": quando o proposito do conjunto nao e obvio pelo texto dos botoes (um grupo so de icones, por exemplo), adicione aria-label no ButtonGroup descrevendo o conjunto. O foco de cada botao continua visivel mesmo colado ao vizinho: o grupo eleva o z-index do botao focado para o anel de foco nunca ficar escondido atras da borda do botao ao lado. Todo botao so com icone dentro do grupo ainda precisa do proprio aria-label, a regra do Button nao muda por estar dentro de um ButtonGroup.

Slots e tokens

Todo elemento renderizado carrega um data-slot para estilizar partes internas sem depender de classe da biblioteca. Os tokens listados são extraídos do código fonte.

[data-slot="button-group"][data-slot="button-group-separator"][data-slot="button-group-text"]
5 tokens usados
bg-borderbg-surface-secondaryborder-bordertext-content-secondarytext-l3