Slider

1.1.1

Permite seleccionar un valor o un intervalo de valores dentro de un rango conocido, deslizando un controlador sobre una pista horizontal.

Ver en Storybook

Ver en Github

Ver paquete de npm

Reportar un bug

Cuándo usar

Ajustar un valor dentro de un rango conocido: cuando el usuario se mueve entre un mínimo y un máximo definidos y puede aproximarse al valor deseado sin necesidad de tipearlo. Ej.: "Radio de envío en kilómetros", "Volumen de las notificaciones".
Filtrar por un intervalo de valores: usar la variante Range para definir un mínimo y un máximo al mismo tiempo, con un solo control. Ej.: "Precio: $0 - $5.000".
Priorizar la velocidad de selección sobre la precisión exacta: cuando alcanza con acercarse al valor deseado y no hace falta un número exacto. Ej.: ajustar el brillo o el volumen.
Simplificar la entrada en pantallas táctiles: evitar el teclado numérico en ajustes frecuentes y aproximados, donde arrastrar resulta más directo que escribir.

Cuándo no usar

Ingresar un valor exacto: cuando el usuario necesita escribir un número preciso en lugar de aproximarse arrastrando un controlador. En su lugar, usar Input. Ej.: "Precio de lista", "Número de documento".
Elegir entre dos opciones excluyentes: una decisión binaria no necesita un recorrido de valores intermedios. En su lugar, usar Toggle o Checkbox.
Elegir entre pocas opciones discretas con nombre propio: cuando los valores no forman una escala continua sino un conjunto reducido de opciones con nombre. En su lugar, usar Radio. Ej.: talles "S", "M", "L".
Mostrar un progreso no interactivo: cuando el usuario no controla el valor y solo se necesita comunicar un avance. En su lugar, usar Progress Bar.

Anatomía

Track base: pista que representa el rango completo de valores disponibles, entre min y max.
Active track: porción de la pista que indica visualmente el valor o el intervalo seleccionado; su color cambia según la prop appearance.
Thumb: controlador que el usuario arrastra, hace clic o navega con el teclado para modificar el valor. En el modo Single hay un solo Thumb; en Range hay dos, uno por extremo del intervalo. Su borde siempre queda en el color primary, sin importar el appearance elegido para el Active track.

Variantes

Default: un solo Thumb para seleccionar un valor escalar dentro del rango. Ej.: "Radio de envío en km".

Range: dos Thumbs para definir un intervalo entre un mínimo y un máximo. Ej.: "Precio: $0 - $5.000".

Step: restringe el recorrido a incrementos discretos definidos por la prop step, en vez de un desplazamiento continuo. Ej.: ajustar de a 10 unidades.

Estados

Aplicación

El Slider aparece en formularios y paneles de configuración donde el usuario ajusta un valor o un intervalo dentro de un rango conocido, como filtros de búsqueda, configuraciones de envío o preferencias de la tienda. Como el componente no muestra por sí solo ni una etiqueta ni el valor actual, siempre convive con un Label o Text que identifica qué se está ajustando y con un Text que expone el valor seleccionado.

Radio de envío

15 km

Do and Don'ts

Descuento

50%

100

Acompañar el slider con una etiqueta y el valor actual, para que el usuario sepa qué está ajustando y cuánto.

Evitar dejar el slider sin etiqueta ni valor visible: el usuario pierde la referencia de qué está ajustando.

Precio

$5.000

Usar la variante Range cuando ambos extremos del intervalo son relevantes, como un rango de precio, y sumar los valores límite (min/max) debajo del track para dar contexto sin necesidad de arrastrar.

Precio de lista

$1.234

Evitar pedir un valor exacto con un Slider: usar Input cuando el número no admite aproximación.

Accesibilidad

Navegación por teclado: el Thumb se renderiza como un button nativo enfocable; ArrowRight/ArrowUp incrementa el valor y ArrowLeft/ArrowDown lo decrementa según step, mientras que Home lleva al mínimo y End al máximo.
Atributos ARIA: cada Thumb expone role="slider" con aria-valuemin, aria-valuemax y aria-valuenow, más un aria-label que por defecto queda en inglés ("Value", "Minimum value", "Maximum value"). Pasar siempre ariaLabel (o minAriaLabel/maxAriaLabel en Range) en el idioma de la interfaz.
Foco visible: al navegar con teclado, el Thumb muestra el anillo de foco estándar de Nimbus alrededor del controlador.
Estado disabled: el atributo disabled bloquea la interacción por mouse, touch y teclado, y atenúa el color del Thumb y del Active track.
Valor que refuerza el mensaje sin depender solo del color: el color del Active track (definido por appearance) refuerza visualmente el valor seleccionado, pero como el Slider no muestra el número por sí solo, conviene acompañarlo siempre con un Text que exponga el valor actual en lugar de depender únicamente de la posición del Thumb.

Implementación

Instalá el componente vía terminal.

npm install @nimbus-ds/components

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;

Props

Las propiedades adicionales se pasan al elemento <Slider>. Consultá la documentación de atributos del elemento input para ver el listado equivalente de atributos nativos.

Componentes relacionados

Input — Para entrada de valores numéricos exactos, cuando no admite aproximación.
Toggle — Para una decisión binaria, sin recorrido de valores intermedios.
Radio — Para elegir entre pocas opciones discretas con nombre propio.
Progress Bar — Para mostrar un progreso no interactivo, sin control del usuario.

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.

Ayudanos a mejorar la documentación

¿Encontraste un problema o tenés una sugerencia? Contanos.

Compartí tu opinión