Grupo de alternância

Um grupo de alternância é uma fila de escolhas que se lê como um único controlo. Constrói-o a partir de items, e diz qual está ligado com value.

Grupo básico

toggleGroup({
  label: 'Alinhamento do texto',
  value: 'center',
  items: [
    { value: 'left', label: 'Esquerda' },
    { value: 'center', label: 'Centro' },
    { value: 'right', label: 'Direita' },
  ],
})

Cadeias simples

toggleGroup({ label: 'Densidade', value: 'confortável', items: ['compacta', 'confortável', 'espaçosa'] })

Ligações

É esta a forma que um site estático normalmente quer: cada segmento é uma página. Os itens com href são desenhados como âncoras e o ativo é marcado com aria-current="page" — e não aria-pressed, porque uma ligação não é um botão que ficou carregado.

Documentação UI Exemplos

toggleGroup({
  label: 'Secção',
  value: 'ui',
  items: [
    { value: 'docs', label: 'Documentação', href: '/pt/docs' },
    { value: 'ui', label: 'UI', href: '/pt/ui' },
    { value: 'examples', label: 'Exemplos', href: '/pt/examples' },
  ],
})

Mais do que um ligado

Passa um array em value. O contentor é um group simples em qualquer dos casos — um radiogroup estaria errado, já que estes são botões carregados e não rádios.

toggleGroup({
  label: 'Formatação',
  value: ['bold', 'underline'],
  items: [
    { value: 'bold', label: 'Negrito' },
    { value: 'italic', label: 'Itálico' },
    { value: 'underline', label: 'Sublinhado' },
  ],
})

Tamanhos e variantes

stack({ gap: 'md' },
  toggleGroup({ size: 'sm', label: 'Pequeno', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'md', label: 'Médio', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'lg', label: 'Grande', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ variant: 'ghost', label: 'Ghost', value: 'b', items: ['a', 'b', 'c'] }),
)

Itens desativados

toggleGroup({
  label: 'Renderização',
  value: 'static',
  items: [
    { value: 'static', label: 'Estática' },
    { value: 'islands', label: 'Ilhas' },
    { value: 'ssr', label: 'SSR', disabled: true },
  ],
})

Numa barra de ferramentas

stack({ direction: 'row', gap: 'md', wrap: true, align: 'center' },
  toggleGroup({ label: 'Alinhamento', value: 'Esquerda', size: 'sm', items: ['Esquerda', 'Centro', 'Direita'] }),
  divider({ orientation: 'vertical' }),
  toggleGroup({ label: 'Estilo', value: ['Negrito'], size: 'sm', items: ['Negrito', 'Itálico'] }),
)

Quando usar outra coisa

Se a escolha for submetida com um formulário, usa choiceGroup() — rádios a sério, sem script nenhum. Se cada segmento for uma página, prefere a forma em ligações acima. Um grupo de alternância serve para uma escolha sobre a qual a própria página atua.

Props

Prop	Tipo	Predefinição	Descrição
`items`	`Array`	`[]`	Cadeias, ou objetos { value, label, href, disabled }.
`value`	`string \| number \| Array`	—	Que item está ligado. Um array quando podem ser vários.
`label`	`string`	—	Nome acessível do grupo.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Aplicado a todos os itens.
`variant`	`'outline' \| 'ghost' \| 'soft'`	`'outline'`	O aspeto de um item desligado.