Slider

1.1.0

El componente Slider permite a los usuarios seleccionar un valor único o un rango de valores deslizando un controlador a lo largo de una pista 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;

Anatomía del componente

El componente se compone de una pista horizontal (track) que representa el rango de valores, un controlador (thumb) que se desplaza sobre la pista para seleccionar un valor, y la porción activa de la pista (fill) que indica visualmente el valor seleccionado.

Track: Pista horizontal que representa el rango completo de valores posibles.
Fill: Porción activa de la pista que indica visualmente el valor o rango seleccionado.
Thumb: Controlador que el usuario arrastra para seleccionar un valor.

Guidelines

El componente Slider es un control de entrada que permite a los usuarios seleccionar un valor único o un rango de valores deslizando un controlador a lo largo de una pista horizontal. Es ideal para ajustar configuraciones que tienen un impacto escalar inmediato, priorizando la velocidad de selección sobre la precisión extrema.

Cuándo usar

Para ajustar valores numéricos dentro de un rango conocido y limitado (ej. radio de entrega en kilómetros).
En filtros de búsqueda para definir rangos de precios o dimensiones (variante Range).
Cuando el usuario necesita explorar el efecto de un cambio en tiempo real, como el volumen o el brillo.
Para simplificar la entrada de datos en dispositivos móviles donde el teclado puede resultar invasivo.

Cuándo no usar

Para valores que requieren precisión absoluta (ej. ingresar un número de documento o un precio exacto). En su lugar, usar un Input.
Si el rango de valores es demasiado amplio o indefinido, dificultando la manipulación del controlador.
Para opciones binarias (Sí/No); en estos casos, es preferible usar un Toggle o Checkbox.

Variantes

Single: Un solo controlador para seleccionar un valor escalar único.
Range: Dos controladores que permiten definir un intervalo (mínimo y máximo).

Estados

El componente presenta los siguientes estados: reposo, hover, activo y con el valor al máximo.

Criterios de usabilidad y productividad

Feedback visual inmediato: El valor seleccionado debe mostrarse dinámicamente mientras el usuario desplaza el controlador para evitar errores.
Zonas de interacción amplias: El controlador debe tener un área táctil suficiente (mínimo 44px) para facilitar la gestión desde la app móvil de Tiendanube.
Incrementos lógicos: Definir pasos (steps) coherentes con la magnitud del valor para evitar desplazamientos accidentales.

Buenas prácticas de accesibilidad

Navegación por teclado: El componente responde a las teclas ArrowRight/Up para incrementar y ArrowLeft/Down para decrementar el valor. También soporta Home para ir al mínimo y End para ir al máximo.
Atributos ARIA: Implementa role="slider" con aria-valuemin, aria-valuemax y aria-valuenow para que los lectores de pantalla comuniquen el estado del control.
Contraste de color: La pista activa tiene un contraste de al menos 3:1 respecto al fondo para asegurar su visibilidad (WCAG AA).

Recomendaciones de uso

Incluir etiquetas en los extremos del slider para dar contexto al rango.
Usar la variante Range cuando los valores dependen uno del otro.
Mantener el slider alineado con el ancho del contenedor para maximizar la precisión del recorrido.
No usar sliders sin una etiqueta clara que explique qué se está ajustando.
Evitar colocar sliders en diálogos muy pequeños que limiten el movimiento horizontal.
No omitir el valor numérico actual, ya que el usuario podría perder la referencia.

Dependencias

Label - Para identificar el propósito del slider.
Text - Para mostrar los límites (mín/máx) y el valor actual seleccionado.

Componentes relacionados

Input - Puede ser usado para entrada de valores numéricos cuando se requiere precisión absoluta.
ProgressBar - Para mostrar progreso (no interactivo).

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/components

Props

Las propiedades adicionales se pasan al elemento <Slider>. Consultá la documentación para ver la lista de atributos aceptados por el 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.