Cursore

Panoramica

Slider supporta un singolo numero o un array di numeri per un intervallo. Componi l’etichetta, la traccia, l’indicatore e i cursori all’interno di Root.

Utilizzo

Stato non controllato

Usa defaultValue per impostare il volume iniziale. Lo slider gestisce le modifiche successive.

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>
);

Scelte visive

Confronta almeno i colori di accento e di successo ai valori minimo, centrale, massimo e disabilitato. Gli slider abilitati rimangono interattivi.

Anatomia

Inserisci la barra e le maniglie all’interno di Slider.Control, che gestisce l’interazione del puntatore. Questa struttura mostra uno slider con una sola maniglia.

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

Parte	Requisito	Scopo
`Root`	Obbligatorio	Gestisce il valore, i limiti, il passaggio e l’orientamento.
`Control`	Obbligatorio	Gestisce l’interazione del puntatore e posiziona le maniglie.
`Track`	Necessario per la barra stilizzata	Mostra l’intero intervallo di valori.
`Thumb`	Una per ogni valore regolabile	Fornisce una maniglia selezionabile con interazione da tastiera.
`Label`	Consigliato	Fornisce un’etichetta visibile; ogni maniglia necessita di un nome accessibile.
`Valore`	Facoltativo	Visualizza il valore numerico corrente.
`Indicator`	Facoltativo	Mostra la parte selezionata della traccia.

Per un intervallo, aggiungi una maniglia per ogni valore con il relativo index e un nome accessibile distinto. Le etichette e l’output numerico rimangono all’esterno di Control, quindi non diventano parte dell’area trascinabile.

Stato controllato

Passa value e aggiornalo con onValueChange per gestire lo stesso volume nello stato di React. Il callback riceve il valore successivo e i dettagli dell’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 per mantenere aggiornato il valore controllato durante un’interazione. onValueCommitted gestisce il valore finale al termine dell’interazione, ad esempio per salvarlo. Entrambi i callback sono disponibili anche in modalità non controllata senza gestire il valore. I dettagli della modifica includono l’event di origine, il reason dell’interazione, l’activeThumbIndex e cancel(). I dettagli di commit utilizzano il contratto generico degli eventi di Base UI e non includono l’annullamento delle modifiche. Una modifica annullata non viene confermata.

Intervallo

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>
);

Assegna ai cursori dell’intervallo nomi accessibili distinti e un index corrispondente al relativo valore. minStepsBetweenValues imposta la distanza minima in passaggi. Il tipo generico del valore della radice è un numero o un array di numeri in sola lettura. Per controllare un intervallo, memorizza l’array nello stato di React e passalo tramite value e onValueChange, proprio come per un singolo valore.

Tastiera e aspetto

I tasti freccia regolano un cursore attivo di un passaggio. Home e Fine lo spostano verso i limiti rispettando i vincoli dell’intervallo. orientation="vertical" modifica il layout e la direzione della tastiera. Usa disabled su Root per impedire modifiche. Imposta color="success" per la tavolozza alternativa; il valore predefinito è accent. Il valore predefinito di thumbAlignment è edge. Passa center o edge-client-only per sovrascriverlo. La composizione nativa di className, style e render rimane disponibile in ogni parte, incluse le funzioni di stato.

Con l’allineamento edge e edge-client-only, Base UI 1.8 e 1.9 non ricalcolano mai le dimensioni di una manopola dopo il ridimensionamento del relativo Slider.Control, e uno slider montato quando è nascosto mantiene nascoste le proprie manopole una volta visualizzato (mui/base-ui#5995). I componenti front di React riscontrano lo stesso problema al primo rendering. Usa thumbAlignment="center" finché una versione di Base UI non include la correzione (mui/base-ui#6000).

Integrazione nativa e tipi

Slider.Root deduce un numero o un array numerico di sola lettura da value o defaultValue, mantenendo tale tipo in entrambe le callback. SliderRootProps accetta entrambi per impostazione predefinita; utilizza SliderRootProps\<number> per gli helper a valore singolo o SliderRootProps\<readonly number[]> per gli helper di intervallo. Ogni parte ha un tipo di props esportato in twenty-ui/primitives/input: SliderRootProps, SliderControlProps, SliderTrackProps, SliderIndicatorProps, SliderThumbProps, SliderLabelProps e SliderValueProps. Le ref puntano a elementi div per Root, Control, Track, Indicator, Thumb e Label, e a un elemento output per Value. La ref di un Thumb punta alla sua maniglia visibile; il relativo nome accessibile e il valore del modulo nativo appartengono all’input di intervallo annidato. Utilizza name e form su Root per l’invio nativo, con un input per ciascun valore dell’intervallo.

Props

Il riferimento viene generato dai tipi dei componenti pubblici. Gli attributi nativi, inclusi i nomi accessibili e i gestori di eventi, sono accettati anche nelle parti che eseguono il rendering di elementi.

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"

predefinito:"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

predefinito:"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

predefinito:"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

predefinito:"100"

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

number

predefinito:"0"

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

number

predefinito:"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"

predefinito:"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

predefinito:"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"

predefinito:"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"

predefinito:"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

predefinito:"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.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Stato non controllato

Scelte visive

Anatomia

Stato controllato

Intervallo

Tastiera e aspetto

Integrazione nativa e tipi

Props

Slider.Root

Slider.Control

Slider.Track

Slider.Indicator

Slider.Thumb

Slider.Label

Slider.Value

​Panoramica

​Utilizzo

​Stato non controllato

​Scelte visive

​Anatomia

​Stato controllato

​Intervallo

​Tastiera e aspetto

​Integrazione nativa e tipi

​Props

​Slider.Root

​Slider.Control

​Slider.Track

​Slider.Indicator

​Slider.Thumb

​Slider.Label

​Slider.Value

Panoramica

Utilizzo

Stato non controllato

Scelte visive

Anatomia

Stato controllato

Intervallo

Tastiera e aspetto

Integrazione nativa e tipi

Props

Slider.Root

Slider.Control

Slider.Track

Slider.Indicator

Slider.Thumb

Slider.Label

Slider.Value