Slider

1.1.0

O componente Slider permite aos usuários selecionar um valor único ou um intervalo de valores deslizando um controle ao longo de uma faixa horizontal.

Default

Range

Step

Disabled

import React, { useState } from "react";
import { Slider } from "@nimbus-ds/components";

const Example: React.FC = () => {
  const [value, setValue] = useState(50);

  return (
    <Slider
      value={value}
      min={0}
      max={100}
      onChange={setValue}
    />
  );
};

export default Example;

Anatomia do componente

O componente é composto por uma faixa horizontal (track) que representa o intervalo de valores, um controle (thumb) que se desloca sobre a faixa para selecionar um valor, e a porção ativa da faixa (fill) que indica visualmente o valor selecionado.

Track: Faixa horizontal que representa o intervalo completo de valores possíveis.
Fill: Porção ativa da faixa que indica visualmente o valor ou intervalo selecionado.
Thumb: Controle que o usuário arrasta para selecionar um valor.

Guidelines

O componente Slider é um controle de entrada que permite aos usuários selecionar um valor único ou um intervalo de valores deslizando um controle ao longo de uma faixa horizontal. É ideal para ajustar configurações que têm um impacto escalar imediato, priorizando a velocidade de seleção sobre a precisão extrema.

Quando usar

Para ajustar valores numéricos dentro de um intervalo conhecido e limitado (ex. raio de entrega em quilômetros).
Em filtros de busca para definir intervalos de preços ou dimensões (variante Range).
Quando o usuário precisa explorar o efeito de uma mudança em tempo real, como volume ou brilho.
Para simplificar a entrada de dados em dispositivos móveis onde o teclado pode ser invasivo.

Quando não usar

Para valores que requerem precisão absoluta (ex. inserir um número de documento ou um preço exato). Nesse caso, usar um Input.
Se o intervalo de valores é muito amplo ou indefinido, dificultando a manipulação do controle.
Para opções binárias (Sim/Não); nesses casos, é preferível usar um Toggle ou Checkbox.

Variantes

Single: Um único controle para selecionar um valor escalar único.
Range: Dois controles que permitem definir um intervalo (mínimo e máximo).

Estados

O componente apresenta os seguintes estados: repouso, hover, ativo e com o valor no máximo.

Critérios de usabilidade e produtividade

Feedback visual imediato: O valor selecionado deve ser mostrado dinamicamente enquanto o usuário desloca o controle para evitar erros.
Zonas de interação amplas: O controle deve ter uma área de toque suficiente (mínimo 44px) para facilitar o uso a partir do app móvel da Nuvemshop.
Incrementos lógicos: Definir passos (steps) coerentes com a magnitude do valor para evitar deslocamentos acidentais.

Boas práticas de acessibilidade

Navegação por teclado: O componente responde às teclas ArrowRight/Up para incrementar e ArrowLeft/Down para decrementar o valor. Também suporta Home para ir ao mínimo e End para ir ao máximo.
Atributos ARIA: Implementa role="slider" com aria-valuemin, aria-valuemax e aria-valuenow para que os leitores de tela comuniquem o estado do controle.
Contraste de cor: A faixa ativa tem um contraste de pelo menos 3:1 em relação ao fundo para garantir sua visibilidade (WCAG AA).

Recomendações de uso

Incluir rótulos nas extremidades do slider para dar contexto ao intervalo.
Usar a variante Range quando os valores dependem um do outro.
Manter o slider alinhado com a largura do contêiner para maximizar a precisão do percurso.
Não usar sliders sem um rótulo claro que explique o que está sendo ajustado.
Evitar colocar sliders em diálogos muito pequenos que limitem o movimento horizontal.
Não omitir o valor numérico atual, pois o usuário pode perder a referência.

Dependências

Label - Para identificar o propósito do slider.
Text - Para mostrar os limites (mín/máx) e o valor atual selecionado.

Componentes relacionados

Input - Pode ser usado para entrada de valores numéricos quando se requer precisão absoluta.
ProgressBar - Para mostrar progresso (não interativo).

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/components

Props

Propriedades adicionais são repassadas ao elemento <Slider>. Consulte a documentação do elemento input para ver a lista de atributos aceitos pelo elemento <Slider>.

Slider

Name	Type	Default	Description
value*	number		The current value of the slider (single mode).
onChange	object		Callback fired when the value changes.
onChangeEnd	object		Callback fired when the user finishes interacting with the slider.
ariaLabel	string	'Value'	Accessible label for the slider thumb.
min	number	'0'	The minimum value of the slider range.
max	number	'100'	The maximum value of the slider range.
step	number	'1'	The step increment between values.
appearance	'danger' 'neutral' 'primary' 'success' 'warning'	'primary'	Visual appearance of the slider fill.
disabled	boolean	'false'	Whether the slider is disabled.
data-testid	string		This is an attribute used to identify a DOM node for testing purposes.

Slider.Range

Name	Type	Default	Description
minValue*	number		The current minimum value selected on the slider.
maxValue*	number		The current maximum value selected on the slider.
onChange	object		Callback fired when the min or max value changes.
onMinChange	object		Callback fired when the min value changes.
onMaxChange	object		Callback fired when the max value changes.
onChangeEnd	object		Callback fired when the user finishes interacting with the slider.
minAriaLabel	string	'Minimum value'	Accessible label for the minimum value thumb.
maxAriaLabel	string	'Maximum value'	Accessible label for the maximum value thumb.
min	number	'0'	The minimum value of the slider range.
max	number	'100'	The maximum value of the slider range.
step	number	'1'	The step increment between values.
appearance	'danger' 'neutral' 'primary' 'success' 'warning'	'primary'	Visual appearance of the slider fill.
disabled	boolean	'false'	Whether the slider is disabled.
data-testid	string		This is an attribute used to identify a DOM node for testing purposes.