Primitiveaction

Toggle Group

Stable

Uma fileira de Toggles que compartilha um estado: seleção única ou `multiple`, com foco itinerante. Cada item é o Toggle do Up Web DS — o Button com estado pressionado —, então um item no grupo e um toggle sozinho são o mesmo controle. Use para uma barra de ferramentas de estados liga/desliga (formatação, filtros), inclusive quando vários podem estar ligados; para trocar entre vistas ou modos, em que exatamente uma opção vale, use o Segmented Control.

Instalação

npx up-web-ds add toggle-group

Preview

Basic

Multiple

Outline

Sizes

Vertical

Icon Only

With Separator

Disabled

Controlled

50 itens em Stable, Experimental.

All states

Basic

Multiple

Outline

Sizes

Vertical

Icon Only

With Separator

Disabled

Controlled

50 itens em Stable, Experimental.

Usage

@/components/ui/toggle-group

import {
  ToggleGroup,
  ToggleGroupItem,
} from '@/components/ui/toggle-group'

Toggle Group

1
2
3
4
5<ToggleGroup aria-label="Alinhamento do texto" defaultValue={['left']}>
  <ToggleGroupItem value="left">Esquerda</ToggleGroupItem>
  <ToggleGroupItem value="center">Centro</ToggleGroupItem>
  <ToggleGroupItem value="right">Direita</ToggleGroupItem>
</ToggleGroup>

Props

ToggleGroupContext

Estende P. Aceita também os atributos padrão de um elemento React (2 não listados).

ToggleGroup

Props de ToggleGroup
Prop	Type	Default	Description
size	`ToggleGroupSize`	`'default'`	The size of every item, from the Button scale.
variant	`ToggleGroupVariant`	`'default'`	The look of every item. `outline` joins the items into one bordered shape; `default` keeps them apart as transparent toggles.
className	`string \| ((state: ToggleGroupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
defaultValue	`readonly string[]`	sem valor padrão	The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`.
disabled	`boolean`	`false`	Whether the toggle group should ignore user interaction.
loopFocus	`boolean`	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
multiple	`boolean`	`false`	When `false` only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When `true` multiple items can be pressed.
onValueChange	`((groupValue: string[], eventDetails: ToggleGroup.ChangeEventDetails) => void)`	sem valor padrão	Callback fired when the pressed states of the toggle group changes.
orientation	`Orientation`	`'horizontal'`
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleGroupState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: ToggleGroupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.
value	`readonly string[]`	sem valor padrão	The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`.

Estende ToggleGroupPrimitive.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ToggleGroupItem

Props de ToggleGroupItem
Prop	Type	Default	Description
size	`ToggleGroupSize`	sem valor padrão	Overrides the group's size for this item.
variant	`ToggleGroupVariant`	sem valor padrão	Overrides the group's variant for this item. Inside a group, leave it to the group: an `outline` row with one `default` item stops being one shape.
className	`string \| ((state: ToggleState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
defaultPressed	`boolean`	`false`	Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
onPressedChange	`((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void)`	sem valor padrão	Callback fired when the pressed state is changed.
pressed	`boolean`	sem valor padrão	Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: ToggleState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.
value	`string`	sem valor padrão	A unique string that identifies the toggle when used inside a toggle group.

Estende Omit<ToggleProps, 'variant' | 'size'>. Aceita também os atributos padrão de um elemento React (283 não listados).

ToggleGroupSeparator

Props de ToggleGroupSeparator
Prop	Type	Default	Description
decorative	`boolean`	sem valor padrão
className	`string \| ((state: SeparatorState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
orientation	`Orientation`	`'horizontal'`	The orientation of the separator.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, SeparatorState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende SeparatorProps. Aceita também os atributos padrão de um elemento React (275 não listados).

Composition

O grupo carrega o nome, o estado (value/defaultValue), a variante e o tamanho; os itens herdam variante e tamanho por contexto. O separador fica entre itens e corre perpendicular ao eixo do grupo.

Composição de ToggleGroup

ToggleGroup

ToggleGroup
- ToggleGroupItem
- ToggleGroupSeparator

Metadata

Notas de acessibilidade

Teclado verificado por teste e em navegador: o grupo custa uma parada de Tab, as setas percorrem os itens com wrap (Cima/Baixo quando vertical), Home e End vão às pontas, e Space/Enter alternam; um item desabilitado é pulado pelas setas e recusa a alternância, e o anel de foco é visível ao chegar pelo teclado. Leitor de tela verificado por teste: a fileira é um group nomeado por aria-label, e cada item reporta o próprio aria-pressed — em seleção única, pressionar um solta o outro; em multiple, acumula. Item só de ícone leva aria-label. Touch verificado em viewport de 375px com emulação de toque: os itens medem 32, 36 e 40px nos três tamanhos e 32/36px nos só de ícone, acima do mínimo de 24x24 da política do Up Web DS, e o toque alterna. Reduced motion verificado com prefers-reduced-motion: reduce — a única transição é a de cor e anel herdada do Button, resposta a input e não movimento, então permanece; o empurrão de 1px do Button já é removido pelo Toggle.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: action
Status: Stable

Origem e distribuição

Fonte: coss registry / toggle-group
Licença: MIT
URL: https://coss.com/ui/r/toggle-group.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: Nenhum
Construído sobre: Separator Toggle
Usado por: Nenhum ainda