Segmented Control
Segmented Control é um componente composto de seleção exclusivo que permite aos usuários escolher uma ou várias opções de um grupo predefinido.
import React from "react";
import { SegmentedControl } from "@nimbus-ds/components";
import { mockSegmentedControlLabels as labels } from "lib/mocks/mock-labels";
const Example: React.FC = () => (
<SegmentedControl>
{labels.map((label, index) => (
<SegmentedControl.Button
key={label}
label={label}
// Disable latest segment
disabled={index === labels.length - 1}
>
{label}
</SegmentedControl.Button>
))}
</SegmentedControl>
);
export default Example;
Instale o componente via terminal.
npm install @nimbus-ds/segmented-control
Segmented Control
O Segmented Control é um componente composto de seleção exclusivo que permite aos usuários escolher uma ou várias opções de um grupo predefinido. Eles são projetados para casos de seleção rápida e contextual, como filtros de produtos ou visualizações alternativas.
- Filtrar visualizações ou produtos por um critério específico (por exemplo, status do pedido).
- Alternar entre visualizações ou modos dentro da mesma tela.
- Agrupar opções de seleção simples em um espaço reduzido.
- Substituir menus suspensos ou checkboxes para opções que precisam de uma interação mais rápida.
- Não usar para critérios complexos ou hierárquicos (use filtros avançados ou modais).
- Não usar mais de 5 opções por grupo. Nesses casos, avalie usar Chips ou um menu suspenso.
- Evite usá-lo se as opções não forem mutuamente exclusivas (prefira checkboxes ou toggles).
- Evite usá-los junto com outros elementos de seleção, pois podem complicar as tarefas do usuário.
- Navegação fluida com teclado: Permitir mover-se entre as opções usando setas e selecionar com Enter ou Space.
- Suporte completo de navegação por teclado: As opções devem ser acessíveis com Tab e selecionáveis com Enter ou Space.
- Manejo correto do foco: O foco deve ser indicado visualmente e mover-se logicamente entre opções.
- Uso correto de roles ARIA: Usar role="radiogroup" e role="radio" conforme apropriado para descrever a relação entre opções.
O segmented control pode conter:
- Icon (opcional)
- Text (opcional)
- Badge (opcional, para indicar quantidades)

Todos esses elementos podem ser usados de maneira variada criando diferentes casos de uso segundo a necessidade e objetivo. Exemplos válidos:
- Apenas texto
- Texto + badge
- Ícone + texto
- Apenas ícone

Este componente utiliza:
- Icons
- Badge
Selection:
- Basic. All rest default: Todas as opções não selecionadas por padrão.
- Controlled. Single select : Uma única opção selecionada ao mesmo tempo.

Device:
- Desktop. Largura automática segundo quantidade de opções.
- Mobile. Largura fixa à largura da resolução da tela.


- Selected (active)
- Rest (default)
- Hover
- Pressed
- Disabled

✅ Do
- Usar para filtros simples de até 5 itens
- Se o componente está relacionado com ações de produtos, alinhe-o com filtros visíveis ou cabeçalhos de seção.
- No mobile, coloque o componente em uma posição acessível (por exemplo, sticky na parte superior).
- Se há uma opção que representa o estado "Todos", use essa opção como pré-selecionada.
❌ Don't
- Não misturar critérios distintos em um mesmo grupo
- Não usar ícones sem contexto se não forem universais
- Não abusar do uso de badges se não agregarem valor
- Não quebrar a altura de 32px (consistência visual)
Additional props are passed to the <SegmentedControl> element. See div docs for a list of props accepted by the <SegmentedControl> element.
SegmentedControl
Name | Type | Default | Description |
---|---|---|---|
children* | ReactElement<SegmentedControlButtonProps | SegmentedControlButtonSkeletonProps>[]; | The content of the segmented control. | |
fullWidth | boolean | Determines if segments span all available width. | |
selectedSegments* | array | The currently selected segment indices. Allows for single or multiple selection. | |
onSegmentsSelect* | object | Callback fired when the selected segments change. This will only be called if the change results in at least one selected segment. |
SegmentedControl.Button
Name | Type | Default | Description |
---|---|---|---|
label* | string | Label of the segment. | |
selected | boolean | Determines if segment is active. | |
fullWidth | boolean | Determines if segment spans all available width. | |
children | Represents all of the things React can render. Where {@link ReactElement} only represents JSX, `ReactNode` represents everything that can be rendered. |
SegmentedControl.ButtonSkeleton
Name | Type | Default | Description |
---|