componentes / segmented-control

SegmentedControl

Uma escolha única entre poucas opções, para alternar entre visões do mesmo conteúdo.

Como usar

Coloque `SegmentedItem`s dentro de um `SegmentedControl`. É um `radiogroup`: um item fica sempre selecionado, as setas movem e selecionam (ignorando os desabilitados) e o `aria-label` é obrigatório. Funciona controlado (`value`) ou não (`defaultValue`). Para navegar entre seções use `Tabs`.

preview

SegmentedControl.tsx

import { SegmentedControl, SegmentedItem } from "vaiperui";
 
<SegmentedControl aria-label="Visualização" defaultValue="list">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
  <SegmentedItem value="map">Mapa</SegmentedItem>
</SegmentedControl>

Cores

preview

primary

success

warning

danger

cores.tsx

<SegmentedControl aria-label="…" defaultValue="list" variantColor="primary">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" variantColor="success">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" variantColor="warning">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" variantColor="danger">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>

Tamanhos

preview

tamanhos.tsx

<SegmentedControl aria-label="…" defaultValue="list" size="sm">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" size="md">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" size="lg">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>

Raio

preview

none

full

raio.tsx

<SegmentedControl aria-label="…" defaultValue="list" radius="none">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" radius="sm">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" radius="md">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" radius="lg">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" radius="full">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>

Cor personalizada

preview

Laranja

Violeta

cor-personalizada.tsx

<SegmentedControl aria-label="…" defaultValue="list" customColor="#f97316">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>
 
<SegmentedControl aria-label="…" defaultValue="list" customColor="#8b5cf6">
  <SegmentedItem value="list">Lista</SegmentedItem>
  <SegmentedItem value="grid">Grade</SegmentedItem>
</SegmentedControl>

Estados

preview

desabilitado

estados.tsx

<SegmentedControl aria-label="…" disabled>…</SegmentedControl>

Props

Prop	Valores	Padrão	Descrição
aria-label	string	obrigatório	Nomeia o que o controle seleciona
value	string	nenhum	Item selecionado (controlado)
defaultValue	string	nenhum	Item inicial (não controlado)
onValueChange	(value: string) => void	nenhum	Chamado quando a seleção muda
disabled	boolean	false	Desabilita o controle todo
variantColor / customColor	ControlColors \| CustomColor	neutro	Cor do texto do item selecionado; neutro se nenhum for definido
size	sm \| md \| lg	md	Tamanho do controle e do texto
radius	none \| sm \| md \| lg \| full	md	Arredondamento dos cantos
animation	none \| smooth \| fast \| bounce	smooth	Transição entre estados
SegmentedItem: value, disabled	string, boolean	nenhum	O valor do item; desabilita só este item

Acessibilidade

O contêiner tem `role="radiogroup"` e `aria-disabled` quando o controle inteiro está `disabled`.
Cada `SegmentedItem` é um botão com `role="radio"` e `aria-checked`.
Roving tabindex: só o item selecionado entra na ordem do Tab (`tabIndex=0`).
As setas movem o foco e selecionam ao mesmo tempo, dão a volta e ignoram itens desabilitados.

Teclado

Tecla	Ação
Tab	Move o foco para dentro e para fora do grupo (no item selecionado).
Right / Down	Seleciona o próximo item habilitado.
Left / Up	Seleciona o item anterior habilitado.
Enter / Space	Seleciona o item focado (clique nativo do botão).

Tenha em mente

Passe `aria-label` ou `aria-labelledby` no `SegmentedControl`; o componente não dá nome ao grupo.
Informe `value` ou `defaultValue`; sem item selecionado todos têm `tabIndex=-1` e o grupo não é alcançável pelo teclado.
Home e End não são tratados.