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.

Inicial

Controlado

Full Width

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;

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/segmented-control

Segmented Control

Definição

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.

Quando usar

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.

Quando não usar

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.

Critérios de usabilidade e produtividade

Navegação fluida com teclado: Permitir mover-se entre as opções usando setas e selecionar com Enter ou Space.

Boas práticas de acessibilidade

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.

Anatomia

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

Dependências

Este componente utiliza:

Icons
Badge

Variantes

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.

Estados

Selected (active)
Rest (default)
Hover
Pressed
Disabled

Do and Don'ts

✅ 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)

Props

Additional props are passed to the <SegmentedControl> element. See div docs for a list of props accepted by the <SegmentedControl> element.

SegmentedControl

Name	Type	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	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