Primitivenavigation

Segmented Control

Stable

Uma escolha entre poucas opções, com todas visíveis ao mesmo tempo. Compartilha a escala de altura com o Tabs. É primitive e não recipe: o que ele acrescenta é semântica própria — grupo nomeado de seleção única com foco itinerante e tamanho que desce por contexto — não uma aparência de outro primitive. Para uma barra de ferramentas ou seleção múltipla, feita de toggles com a forma do Button, use o Toggle Group.

Instalação

npx up-web-ds add segmented-control

Preview

Default

Sizes

With Icon

Disabled

Vertical

All states

Default

Sizes

With Icon

Disabled

Vertical

Usage

@/components/ui/segmented-control

import {
  SegmentedControl,
  SegmentedControlItem,
} from '@/components/ui/segmented-control'

Segmented Control

1
2
3
4
5
6
7
8<SegmentedControl
  aria-label="Modo de visualização"
  defaultValue={['lista']}
>
  <SegmentedControlItem value="lista">Lista</SegmentedControlItem>
  <SegmentedControlItem value="grade">Grade</SegmentedControlItem>
  <SegmentedControlItem value="tabela">Tabela</SegmentedControlItem>
</SegmentedControl>

Props

SegmentedControl

Props de SegmentedControl
Prop	Type	Default	Description
size	`SegmentedControlSize`	`'default'`
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).

SegmentedControlItem

Props de SegmentedControlItem
Prop	Type	Default	Description
size	`SegmentedControlSize`	sem valor padrão
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 TogglePrimitive.Props. Aceita também os atributos padrão de um elemento React (283 não listados).

Composition

A linha carrega o nome e o tamanho; cada segmento é um item dela. O tamanho é declarado uma vez no root e desce por contexto — repetido por item, é um tamanho que alguém esquece.

Composição de SegmentedControl

SegmentedControl

SegmentedControl
- SegmentedControlItem

Metadata

Notas de acessibilidade

Teclado e leitor de tela verificados por teste: a linha é um group nomeado — sem nome ela anuncia como um punhado de botões sem relação, e "Grade, pressionado" diz o que está ligado mas nunca sobre o quê. O foco é roving: Tab entra uma vez e as setas percorrem os segmentos com wrap, então um controle de três opções custa uma parada e não três. Escolher um solta o outro; uma linha com dois segmentos pressionados parou de responder à própria pergunta. Um segmento desabilitado permanece na linha, anunciado como desabilitado, em vez de renumerá-la e mover o que as setas alcançam. O anel de foco é visível, verificado em navegador ao chegar pelo teclado. Touch verificado em viewport de 375px com emulação de toque: os três tamanhos medem 32, 36 e 40px de altura no layout real — acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8 — e o toque escolhe. Reduced motion verificado em navegador com prefers-reduced-motion: reduce — a transição é de cor e sombra, resposta a input e não movimento, então permanece: não há deslocamento a gatear.

Classificação

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

Origem e distribuição

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

Acessibilidade

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

Dependências

Pacotes: class-variance-authority
Ícones: Nenhum
Construído sobre: Nenhum
Usado por: Tabs