Segmented Control

Permite escolher uma ou várias opções dentro de um grupo compacto de segmentos, para alternar visualizações ou aplicar filtros rápidos sem saltar da tela atual.

Quando usar

Alternar entre visualizações ou modos do mesmo conteúdo: mudar a forma de exibir a mesma informação sem saltar da tela atual. Ex.: "Lista", "Grade".
Filtrar conteúdo por um critério simples: restringir uma lista de acordo com um status ou categoria, quando as opções são poucas e conhecidas de antemão. Ex.: "Todos", "Ativos", "Arquivados".
Comparar alternativas excludentes: escolher entre um conjunto reduzido de opções que competem entre si, como uma periodicidade ou um método. Ex.: "Mensal", "Anual".
Combinar mais de um filtro ao mesmo tempo: quando o critério permite, selecionar vários segmentos simultaneamente, já que selectedSegments aceita mais de um ID por vez. Ex.: combinar "Frete grátis" e "Em oferta" em um buscador de produtos.

Quando não usar

Escolher entre mais de 5 opções: o componente perde legibilidade e, no mobile, a área de toque de cada segmento fica pequena demais. Em vez disso, usar Select ou MultiSelect.
Exibir conteúdo extenso por seção: se cada opção abre um bloco grande de conteúdo em vez de apenas alternar uma visualização leve ou aplicar um filtro, usar Tabs.
Ativar ou desativar uma única condição binária: um interruptor de sim/não não precisa de um grupo de segmentos. Em vez disso, usar Toggle.
Escolher uma opção dentro de um formulário extenso: quando a escolha é mais um campo de um formulário com FormField (não uma visualização ou um filtro rápido), usar Radio ou Checkbox, que se integram melhor a esse contexto.

Anatomia

Somente texto

Ícone + texto

Texto + badge

Group (componente SegmentedControl): contêiner que agrupa os segmentos e aplica o espaçamento compartilhado. Expõe fullWidth para que todos os segmentos dividam a largura disponível em partes iguais.
Segment (componente SegmentedControl.Button): cada botão individual que representa uma opção selecionável dentro do grupo.
Text: conteúdo visível do segmento.
Icon (opcional): elemento localizado antes do texto, que reforça o critério representado.
Badge (opcional): elemento para exibir um contador ou um dado adicional associado ao segmento, como uma quantidade ou um desconto.

Variantes

Largura

Largura automática (padrão): cada segmento ocupa somente o espaço necessário para seu conteúdo. É o comportamento recomendado quando o grupo convive com outros elementos na mesma linha. Ex.: um filtro de "Todos"/"Ativos"/"Arquivados" ao lado do buscador de uma tabela.

fullWidth: cada segmento divide a largura disponível em partes iguais. Vantajoso no mobile ou quando o grupo ocupa um contêiner estreito por conta própria. Ex.: alternar entre "Lista" e "Grade" na parte superior de uma listagem.

Estados

Aplicação

Desktop

O Segmented Control costuma ficar junto ao elemento que filtra ou alterna: o cabeçalho de uma tabela, a barra superior de uma listagem ou o título de uma seção com visualizações alternativas. Ao ficar próximo desse conteúdo, a relação entre o controle e o que ele modifica fica clara sem precisar de um rótulo adicional.

Vendas

124 em aberto

Mobile

No mobile, o grupo de segmentos é aplicado dentro de um scroll pane horizontal: o contêiner recorta a largura disponível à tela e o usuário arrasta para acessar os segmentos que não cabem na largura visível, em vez de reduzir o tamanho de cada segmento ou forçar a quebra de linha.

Vendas

2 em aberto

Do and Don'ts

Mostrar a quantidade de itens de cada segmento com Badge, quando esse dado ajuda a decidir onde priorizar a atenção, como pedidos agrupados por status de envio.

Evite misturar critérios diferentes em um mesmo grupo, como status, visualização e periodicidade: cada segmento deve representar a mesma dimensão.

Reservá-lo para um grupo reduzido de opções (até 5): assim ele se lê de uma olhada.

Evitar somar tantas opções que o grupo perca legibilidade.

Use labels curtos e sem verbos: eles nomeiam o estado ou a visualização, não uma ação, como "Ativos" ou "Arquivados".

Evite labels com verbos ou muito longos: eles forçam o truncamento ou a quebra de linha em vez de um nome de estado curto.

Acessibilidade

Foco visível ao navegar com o teclado: cada segmento exibe o anel de foco do Nimbus (:focus-visible) ao receber foco pela tecla Tab, sem depender só da cor para indicá-lo.
Estado de seleção exposto a leitores de tela: cada segmento comunica se está selecionado por meio de aria-pressed, o mesmo padrão de um grupo de botões de alternância (toggle buttons), não o de um grupo de radio buttons.
Navegação por Tab, não por setas: o grupo não reimplementa um roving tabindex; cada segmento é um ponto de tabulação independente e é selecionado com Enter ou Espaço, como qualquer botão nativo. Isso vale para a renderização padrão (<button>): com as="a" o segmento é um link e não ativa com Espaço.
Rótulo acessível independente do conteúdo visível: a prop label de SegmentedControl.Button permite dar um nome acessível diferente do conteúdo visível, útil quando o segmento é composto só por um ícone. Um ícone sem label e sem texto visível fica sem nome para um leitor de tela.
Estado desabilitado nativo: disabled em SegmentedControl.Button usa o atributo nativo do elemento <button>, então um segmento desabilitado fica fora da ordem de tabulação automaticamente. Com as="a" não há disabled nativo: um link não aceita esse atributo, então evite essa combinação se o segmento precisar ser desabilitado.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/segmented-control

Default

Full width

Seleção múltipla

import React, { useState } from "react";
import { SegmentedControl } from "@nimbus-ds/components";
import { mockSegmentedControlLabels as labels } from "lib/mocks/mock-labels";

const Example: React.FC = () => {
  const [selectedSegments, setSelectedSegments] = useState<string[]>([
    labels[0],
  ]);

  return (
    <SegmentedControl
      selectedSegments={selectedSegments}
      onSegmentsSelect={(segments) => {
        if (segments.length > 0) {
          setSelectedSegments(segments);
        }
      }}
    >
      {labels.map((label, index) => (
        <SegmentedControl.Button
          id={label}
          key={label}
          label={label}
          disabled={index === labels.length - 1}
        >
          {label}
        </SegmentedControl.Button>
      ))}
    </SegmentedControl>
  );
};

export default Example;

Props

As propriedades adicionais são passadas ao elemento <SegmentedControl>. Consulte a documentação do elemento div para ver a lista de atributos aceitos.

Componentes relacionados

Tabs — para alternar entre seções que exibem conteúdo extenso, não apenas uma visualização leve ou um filtro.
Toggle — para uma condição binária de sim/não, em vez de um grupo de opções.
Select — para escolher entre mais de 5 opções.
MultiSelect — para selecionar múltiplas opções dentro de um conjunto grande.
Badge — usado dentro de um segmento para exibir um contador ou um dado adicional.

SegmentedControl

Name	Type	Default	Description
children	React.ReactNode		The content of the segmented control. Should contain SegmentedControlButton components with unique id props.
fullWidth	boolean	'false'	Determines if segments span all available width.
selectedSegments*	array		The currently selected segment IDs. Allows for single or multiple selection.
onSegmentsSelect	object		Callback fired when the selected segments change.

SegmentedControl.Button

Name	Type	Default	Description
id*	string		Unique identifier for the segment button. Required for proper state management and accessibility.
label	string		Label of the segment used for accessibility.
fullWidth	boolean	'false'	Determines if segment spans all available width.
children	React.ReactNode		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

Ajude-nos a melhorar a documentação

Encontrou um problema ou tem uma sugestão? Conte para a gente.

Compartilhe seu feedback