Deslizador

Resumen

Slider admite un único número o una matriz de números para un intervalo. Componga su etiqueta, pista, indicador y controladores dentro de Root.

”Uso”

Estado no controlado.

Usa defaultValue para establecer el volumen inicial. El control deslizante gestiona los cambios posteriores.

import { Slider } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const VolumeSlider = () => (
  <Slider.Root name="volume" defaultValue={40} min={0} max={100} step={1}>
    <Text
      render={<div />}
      style={{ display: 'flex', justifyContent: 'space-between' }}
    >
      <Slider.Label>Volume</Slider.Label>
      <Slider.Value />
    </Text>
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
);

Opciones visuales

Compare los colores de acento y éxito en los valores mínimo, medio, máximo y deshabilitado. Los controles deslizantes habilitados siguen siendo interactivos.

Anatomía

Coloca la pista y los controles dentro de Slider.Control, que gestiona la interacción del puntero. Este árbol muestra un control deslizante con un solo control.

Slider.Root
├── Slider.Label
├── Slider.Value
└── Slider.Control
    └── Slider.Track
        ├── Slider.Indicator
        └── Slider.Thumb

Parte	Requisito	Propósito
`Root`	Obligatorio	Gestiona el valor, los límites, el paso y la orientación.
`Control`	Obligatorio	Gestiona la interacción del puntero y posiciona los controles.
`Track`	Necesario para la pista con estilo	Muestra el intervalo de valores completo.
`Thumb`	Uno por cada valor ajustable	Proporciona un control enfocable con interacción mediante teclado.
`Label`	Recomendado	Proporciona una etiqueta visible; cada control necesita un nombre accesible.
`Valor`	Opcional	Muestra el valor numérico actual.
`Indicator`	Opcional	Muestra la parte seleccionada de la pista.

Para un intervalo, añade un control para cada valor con su index correspondiente y un nombre accesible distinto. Las etiquetas y la salida numérica permanecen fuera de Control, por lo que no pasan a formar parte del área arrastrable.

Estado controlado.

Pasa value y actualízalo con onValueChange para gestionar el mismo volumen en el estado de React. La devolución de llamada recibe el siguiente valor y los detalles del evento.

import { useState } from 'react';
import { Slider } from 'twenty-ui/primitives/input';

export const VolumeSlider = () => {
  const [volume, setVolume] = useState(40);

  return (
    <Slider.Root
      name="volume"
      value={volume}
      onValueChange={setVolume}
      min={0}
      max={100}
      step={1}
    >
      <Slider.Label>Volume</Slider.Label>
      <Slider.Value />
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
};

Usa onValueChange para mantener actualizado el valor controlado durante una interacción. onValueCommitted gestiona el valor final cuando termina la interacción, por ejemplo, para guardarlo. Ambas devoluciones de llamada también están disponibles en el modo no controlado sin gestionar el valor. Los detalles del cambio incluyen el event de origen, el reason de la interacción, el activeThumbIndex y cancel(). Los detalles de confirmación utilizan el contrato de eventos genérico de Base UI y no incluyen la cancelación de cambios. Un cambio cancelado no se confirma.

Rango

import { Slider } from 'twenty-ui/primitives/input';

export const PriceRange = () => (
  <Slider.Root
    defaultValue={[25, 75]}
    min={0}
    max={100}
    minStepsBetweenValues={10}
  >
    <Slider.Label>Price range</Slider.Label>
    <Slider.Value />
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb index={0} aria-label="Minimum price" />
        <Slider.Thumb index={1} aria-label="Maximum price" />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
);

Asigne nombres accesibles distintos a los controladores del intervalo y un index correspondiente a su valor. minStepsBetweenValues establece la separación mínima en pasos. El tipo de valor genérico de la raíz es un número o una matriz de números de solo lectura. Para controlar un intervalo, almacena la matriz en el estado de React y pásala mediante value y onValueChange, igual que para un único valor.

Teclado y apariencia

Las teclas de flecha ajustan un controlador enfocado en un paso. Inicio y Fin lo mueven hacia los límites respetando las restricciones del intervalo. orientation="vertical" cambia el diseño y la dirección del teclado. Use disabled en Root para impedir cambios. Establezca color="success" para la paleta alternativa; la predeterminada es accent. El valor predeterminado de thumbAlignment es edge. Pasa center o edge-client-only para anularlo. La composición nativa de className, style y render sigue estando disponible en cada parte, incluidas las funciones de estado.

Con la alineación edge y edge-client-only, Base UI 1.8 y 1.9 nunca vuelven a medir un tirador después de que cambie el tamaño de su Slider.Control, y un control deslizante montado mientras está oculto mantiene sus tiradores ocultos cuando se muestra (mui/base-ui#5995). Los componentes frontales de React presentan el mismo problema en su primer renderizado. Use thumbAlignment="center" hasta que una versión de Base UI incluya la corrección (mui/base-ui#6000).

Integración y tipos nativos

Slider.Root infiere un número o un arreglo numérico de solo lectura a partir de value o defaultValue, y conserva ese tipo en ambas devoluciones de llamada. SliderRootProps acepta ambos de forma predeterminada; usa SliderRootProps\<number> para los ayudantes de valor único o SliderRootProps\<readonly number[]> para los ayudantes de rango. Cada parte tiene un tipo de props exportado en twenty-ui/primitives/input: SliderRootProps, SliderControlProps, SliderTrackProps, SliderIndicatorProps, SliderThumbProps, SliderLabelProps y SliderValueProps. Las refs se dirigen a elementos div para Root, Control, Track, Indicator, Thumb y Label, y a un elemento output para Value. La ref de un Thumb se dirige a su controlador visible; su nombre accesible y el valor de formulario nativo pertenecen a la entrada de rango anidada. Usa name y form en Root para el envío nativo, con una entrada por cada valor de rango.

”Props”

La referencia se genera a partir de los tipos de componentes públicos. Los atributos nativos, incluidos los nombres accesibles y los controladores de eventos, también se aceptan en las partes que representan elementos.

Slider.Root

string | ((state: SliderRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

"accent" | "success"

predeterminado:"accent"

Color of the indicator and thumbs.

number | readonly number[]

The uncontrolled value of the slider when it’s initially rendered.To render a controlled slider, use the value prop instead.

boolean

predeterminado:"false"

Whether the slider should ignore user interaction.

string

Identifies the form that owns the slider inputs. Useful when the slider is rendered outside the form.

NumberFormatOptions

Options to format the value.

number

predeterminado:"10"

The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.

LocalesArgument

The locale used by Intl.NumberFormat when formatting the value. Defaults to the user’s runtime locale.

number

predeterminado:"100"

The maximum allowed value of the slider. Should not be equal to min.

number

predeterminado:"0"

The minimum allowed value of the slider. Should not be equal to max.

number

predeterminado:"0"

The minimum steps between values in a range slider.

string

Identifies the field when a form is submitted.

((value: TValue extends number ? number : TValue, eventDetails: SliderRootChangeEventDetails) => void)

Callback function that is fired when the slider’s value changed. Receives the new value as the first argument; the originating event is available as eventDetails.event. The value is also reflected on eventDetails.event.target.value for form integration.The eventDetails.reason indicates what triggered the change:

'input-change' when the hidden range input emits a change event (for example, via form integration)
'track-press' when the control track is pressed
'drag' while dragging a thumb
'keyboard' for keyboard input
'none' when the change is triggered without a specific interaction

((value: TValue extends number ? number : TValue, eventDetails: SliderRootCommitEventDetails) => void)

Callback function that is fired when a value change is committed. Does not fire if the value did not change, or if the change was canceled. Warning: This is a generic event, not a change event.The eventDetails.reason indicates what triggered the commit:

'drag' while dragging a thumb
'track-press' when the control track is pressed
'keyboard' for keyboard input
'input-change' when the hidden range input emits a change event (for example, via form integration)
'none' when the commit occurs without a specific interaction

"horizontal" | "vertical"

predeterminado:"horizontal"

The component orientation.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

number

predeterminado:"1"

The granularity with which the slider can step through values. (A “discrete” slider.) The min prop serves as the origin for the valid values. We recommend (max - min) to be evenly divisible by the step.

CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

"center" | "edge-client-only" | "edge"

predeterminado:"edge"

How the thumb(s) are aligned relative to Slider.Control when the value is at min or max:

center: The center of the thumb is aligned with the control edge
edge: The thumb is inset within the control such that its edge is aligned with the control edge
edge-client-only: Same as edge but renders after React hydration on the client, reducing bundle size in return

"none" | "push" | "swap"

predeterminado:"push"

Controls how thumbs behave when they collide during pointer interactions.

'push' (default): Thumbs push each other without restoring their previous positions when dragged back.
'swap': Thumbs swap places when dragged past each other.
'none': Thumbs cannot move past each other; excess movement is ignored.

number | readonly number[]

The value of the slider. For range sliders, provide an array with one value per thumb.

Slider.Control

string | ((state: SliderControlState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderControlState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderControlState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Track

string | ((state: SliderTrackState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderTrackState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderTrackState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Indicator

string | ((state: SliderIndicatorState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderIndicatorState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderIndicatorState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Thumb

string

A string value forwarded to the aria-valuetext attribute of the input. Ignored when getAriaValueText is provided.

string | ((state: SliderThumbState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

predeterminado:"false"

Whether the thumb should ignore user interaction.

((index: number) => string) | null

A function which returns a string value for the aria-label attribute of the input.

((formattedValue: string, value: number, index: number) => string) | null

A function which returns a string value for the aria-valuetext attribute of the input. This is important for screen reader users.

number

The index of the thumb which corresponds to the index of its value in the value or defaultValue array. This prop is required to support server-side rendering for range sliders with multiple thumbs.

Ref<HTMLInputElement>

A ref to access the nested input element.

FocusEventHandler<HTMLInputElement>

A blur handler forwarded to the input.

FocusEventHandler<HTMLInputElement>

A focus handler forwarded to the input.

KeyboardEventHandler<HTMLInputElement>

A keydown handler forwarded to the input.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderThumbState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderThumbState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

number

Optional tab index attribute forwarded to the input.

Slider.Label

string | ((state: SliderRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Value

string | ((state: SliderValueState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderValueState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SliderValueState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Desarrolladores

Aplicaciones

API

Autoalojamiento

Contribuir

Biblioteca de IU

Resumen

”Uso”

Estado no controlado.

Opciones visuales

Anatomía

Estado controlado.

Rango

Teclado y apariencia

Integración y tipos nativos

”Props”

Slider.Root

Slider.Control

Slider.Track

Slider.Indicator

Slider.Thumb

Slider.Label

Slider.Value

​Resumen

​”Uso”

​Estado no controlado.

​Opciones visuales

​Anatomía

​Estado controlado.

​Rango

​Teclado y apariencia

​Integración y tipos nativos

​”Props”

​Slider.Root

​Slider.Control

​Slider.Track

​Slider.Indicator

​Slider.Thumb

​Slider.Label

​Slider.Value

Resumen

”Uso”

Estado no controlado.

Opciones visuales

Anatomía

Estado controlado.

Rango

Teclado y apariencia

Integración y tipos nativos

”Props”

Slider.Root

Slider.Control

Slider.Track

Slider.Indicator

Slider.Thumb

Slider.Label

Slider.Value