Slider

A slider for picking a value, or a range of values, between a minimum and a maximum.

Volume 30

<ui:slider.root defaultValue="30">
    <div class="flex justify-between">
        <ui:slider.label>Volume</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb />
    </ui:slider.control>
</ui:slider.root>

Features

Full keyboard navigation support with arrow, page and home/end keys
Touch, mouse and pointer input, including clicks on the track
A range of values with several thumbs and a minimum gap between them
Custom step, largeStep, min and max
Marks along the track
defaultValue as a single number for one thumb, or a list of numbers for a range
Works with the Field component

Anatomy

    
    
            <primitives:slider.root>
    <primitives:slider.label />
    <primitives:slider.valueText />
    <primitives:slider.control>
        <primitives:slider.track>
            <primitives:slider.range />
        </primitives:slider.track>
        <primitives:slider.thumb index="0">
            <primitives:slider.hiddenInput />
        </primitives:slider.thumb>
        <primitives:slider.markerGroup>
            <primitives:slider.marker value="25" />
        </primitives:slider.markerGroup>
    </primitives:slider.control>
</primitives:slider.root>

        

Installation

typo3 ui:add slider

Read more about installing Components and Primitives.

Examples

Range

Render a slider.thumb for each end of the range, with index 0 and 1, and pass two numbers as defaultValue. minStepsBetweenThumbs="10" keeps the thumbs of the price range at least 10 steps apart. In a form, end the name with [] (price[]) for PHP to receive both values.

Price range 25 - 75

<ui:slider.root defaultValue="{0: 25, 1: 75}" minStepsBetweenThumbs="10">
    <div class="flex justify-between">
        <ui:slider.label>Price range</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb index="0" />
        <ui:slider.thumb index="1" />
    </ui:slider.control>
</ui:slider.root>

With marks

Add slider.marker elements inside a slider.markerGroup to show labeled ticks along the track.

Zoom level 40

<ui:slider.root defaultValue="{0: 40}">
    <div class="flex justify-between">
        <ui:slider.label>Zoom level</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb />
    </ui:slider.control>
    <ui:slider.markerGroup>
        <ui:slider.marker value="0">0%</ui:slider.marker>
        <ui:slider.marker value="25">25%</ui:slider.marker>
        <ui:slider.marker value="50">50%</ui:slider.marker>
        <ui:slider.marker value="75">75%</ui:slider.marker>
        <ui:slider.marker value="100">100%</ui:slider.marker>
    </ui:slider.markerGroup>
</ui:slider.root>

Disabled

Set disabled="{true}" to block interaction with the slider.

Brightness 50

<ui:slider.root defaultValue="{0: 50}" disabled="{true}">
    <div class="flex justify-between">
        <ui:slider.label>Brightness</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb />
    </ui:slider.control>
</ui:slider.root>

With a number input

Pair the slider with a number input for precise entry: dragging the thumb updates the number, and typing a number moves the thumb. Both are mounted by hand (autoMount="{false}" with a fixed rootId, see Mount one instance yourself) so the entry file can connect them.

Discount

<f:variable name="defaultValue" value="50" />

<div class="flex flex-col items-center gap-4">
    <ui:slider.root rootId="synced-slider" autoMount="{false}" defaultValue="{defaultValue}" class="max-w-55">
        <ui:slider.label>Discount</ui:slider.label>
        <ui:slider.control>
            <ui:slider.track>
                <ui:slider.range />
            </ui:slider.track>
            <ui:slider.thumb />
        </ui:slider.control>
    </ui:slider.root>

    <ui:numberInput.root rootId="synced-number-input" autoMount="{false}" defaultValue="{defaultValue}" min="0" max="100" class="shrink-0">
        <ui:numberInput.control>
            <ui:numberInput.decrementTrigger />
            <ui:numberInput.input />
            <ui:numberInput.incrementTrigger />
        </ui:numberInput.control>
    </ui:numberInput.root>
</div>

<vite:asset entry="EXT:docs/Resources/Private/Components/ui/SliderExamples/WithNumberInput.entry.ts" />

import { mount } from 'fluid-primitives';
import { NumberInput } from 'fluid-primitives/number-input';
import { Slider } from 'fluid-primitives/slider';

(() => {
    let currentValue: number | undefined;

    function setValue(next: number) {
        if (next === currentValue) return;
        currentValue = next;
        slider?.api.setValue([next]);
        numberInput?.api.setValue(next);
    }

    const slider = mount('ui:slider', 'synced-slider', ({ props }) =>
        new Slider({
            ...props,
            onValueChange: ({ value }) => setValue(value[0]),
        }).init()
    );

    const numberInput = mount('ui:numberInput', 'synced-number-input', ({ props }) => {
        // NumberInput's own defaultValue is the shared initial value - unlike Slider's own (always
        // normalized to a float[] client-side, one per thumb), it's a single value, the number this needs.
        currentValue = Number(props.defaultValue);

        return new NumberInput({
            ...props,
            onValueChange: ({ valueAsNumber }) => {
                if (!Number.isNaN(valueAsNumber)) setValue(valueAsNumber);
            },
        }).init();
    });
})();

With a field

Wrap the slider in ui:field.root to pass name, disabled and invalid to the thumb. The demo is a donation amount picker with marks at common amounts.

Donation amount $ 25

Choose an amount to support this event - every contribution helps.

<ui:field.root name="donationAmount" class="max-w-xs">
    <ui:slider.root defaultValue="25" min="0" max="200" step="5">
        <div class="flex items-center justify-between">
            <ui:slider.label>Donation amount</ui:slider.label>
            <span class="text-sm text-muted-foreground">
                $
                <ui:slider.valueText />
            </span>
        </div>
        <ui:slider.control>
            <ui:slider.track>
                <ui:slider.range />
            </ui:slider.track>
            <ui:slider.thumb />
        </ui:slider.control>
        <ui:slider.markerGroup>
            <ui:slider.marker value="10">$10</ui:slider.marker>
            <ui:slider.marker value="25">$25</ui:slider.marker>
            <ui:slider.marker value="50">$50</ui:slider.marker>
            <ui:slider.marker value="100">$100</ui:slider.marker>
        </ui:slider.markerGroup>
    </ui:slider.root>
    <ui:field.helperText>Choose an amount to support this event - every contribution helps.</ui:field.helperText>
</ui:field.root>

With a dragging indicator

Nest slider.draggingIndicator inside a slider.thumb to show the current value in a small tooltip while that thumb is dragged.

Progress 50

<ui:slider.root defaultValue="{0: 50}">
    <div class="flex justify-between">
        <ui:slider.label>Progress</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb>
            <ui:slider.draggingIndicator />
        </ui:slider.thumb>
    </ui:slider.control>
</ui:slider.root>

With decimal values

Set step to a fraction like 0.01 for decimal precision, for example for prices or ratings.

Precision level 7.98

<ui:slider.root defaultValue="7.98" min="5" max="10" step="0.01">
    <div class="flex justify-between">
        <ui:slider.label>Precision level</ui:slider.label>
        <ui:slider.valueText />
    </div>
    <ui:slider.control>
        <ui:slider.track>
            <ui:slider.range />
        </ui:slider.track>
        <ui:slider.thumb />
    </ui:slider.control>
</ui:slider.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

slider.root

Contains every part of the slider. Renders a <div> element.

Name	Description	Required	Default
`disabled`	`boolean` Whether the slider is disabled.	No	-
`readOnly`	`boolean` Whether the slider is read-only.	No	-
`invalid`	`boolean` Whether the slider is invalid.	No	-
`name`	`string` The name associated with each slider thumb (when used in a form).	No	-
`form`	`string` The associate form of the underlying hidden input elements.	No	-
`defaultValue`	`float\|integer\|float[]\|integer[]` The initial value of the slider when rendered - a single number for one thumb, or a list of numbers (one per thumb) for a range. Use when you don't need to control the value of the slider.	No	-
`min`	`float` The minimum value of the slider.	No	0
`max`	`float` The maximum value of the slider.	No	100
`step`	`float` The step value of the slider.	No	1
`largeStep`	`float` The step value of the slider when the `Shift` key is held, or the `PageUp`/`PageDown` keys are used. Defaults to `10 * step`.	No	-
`minStepsBetweenThumbs`	`float` The minimum permitted steps between multiple thumbs. `minStepsBetweenThumbs * step` reflects the gap between the thumbs.	No	0
`orientation`	`Enum\Orientation` The orientation of the slider.	No	Horizontal
`origin`	`Enum\SliderOrigin` The origin of the slider range. The track is filled from the origin to the thumb for single values. `start` is useful when the value represents an absolute value, `center` when it represents an offset (relative), and `end` when it represents an offset from the end.	No	Start
`thumbAlignment`	`Enum\SliderThumbAlignment` The alignment of the slider thumb relative to the track. `center` lets the thumb extend beyond the bounds of the track, `contain` keeps it within the track's bounds.	No	Contain
`thumbSize`	`array` The slider thumb dimensions, with a `width` and `height` key.	No	-
`thumbCollisionBehavior`	`Enum\SliderThumbCollisionBehavior` Controls how thumbs behave when they collide during pointer interactions. `none` keeps thumbs from moving past each other, `push` makes them push each other, `swap` makes them swap places.	No	None
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`provider`	`string` The `id` of the `.provider` this root takes its `rootId` and props from.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-root`	<uid>
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the slider
`data-dragging`	Present when in the dragging state
`data-invalid`	Present when invalid
`data-focus`	Present when focused

slider.label

Renders an accessible label for the slider. Renders a <label> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-label`	<uid>
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the label
`data-invalid`	Present when invalid
`data-dragging`	Present when in the dragging state
`data-focus`	Present when focused

slider.valueText

Displays a textual representation of the current value. Renders a <span> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-value-text`	<uid>
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the valuetext
`data-invalid`	Present when invalid
`data-focus`	Present when focused

slider.control

Wraps the track and thumbs, and handles pointer interaction with the track. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-control`	<uid>
`data-dragging`	Present when in the dragging state
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the control
`data-invalid`	Present when invalid
`data-focus`	Present when focused

slider.track

Renders the full length of the slider's track. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-track`	<uid>
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-dragging`	Present when in the dragging state
`data-orientation`	The orientation of the track
`data-focus`	Present when focused

slider.range

Renders the filled portion of the track between the origin and the thumb(s). Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-range`	<uid>
`data-dragging`	Present when in the dragging state
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the range

slider.thumb

Renders a draggable handle for one value. Takes an index prop to identify which value it controls. Renders a <div> element.

Name	Description	Required	Default
`index`	`integer` The index of the thumb. Use a distinct index per `slider.thumb` for a range slider with multiple thumbs.	No	0
`name`	`string` The name of the thumb. Defaults to the root `name`.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-thumb`	<uid>
`data-index`	The index of the item
`data-name`
`data-disabled`	Present when disabled
`data-orientation`	The orientation of the thumb
`data-focus`	Present when focused
`data-dragging`	Present when in the dragging state

slider.hiddenInput

Provides a native input for form submission, nested inside a slider.thumb. Renders an <input> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

slider.markerGroup

Groups the marks/ticks rendered along the track. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-marker-group`	<uid>
`data-orientation`	The orientation of the markergroup

slider.marker

Renders a single mark/tick at a given value. Renders a <div> element.

Name	Description	Required	Default
`value`	`float` The value along the track at which to render the marker.	Yes	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-marker`	<uid>
`data-orientation`	The orientation of the marker
`data-value`	The value of the item
`data-disabled`	Present when disabled
`data-state`	"under-value" \| "over-value" \| "at-value"

slider.draggingIndicator

Displays the current value while its thumb is being dragged. Nested inside a slider.thumb, whose index it follows automatically. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-slider-dragging-indicator`	<uid>
`data-orientation`	The orientation of the draggingindicator
`data-state`	"open" \| "closed"

Machine JavaScript API

Name	Type	Description
`value`	`number[]`	The value of the slider.
`dragging`	`boolean`	Whether the slider is being dragged.
`focused`	`boolean`	Whether the slider is focused.
`setValue`	`(value: number[]) => void`	Function to set the value of the slider.
`getThumbValue`	`(index: number) => number`	Returns the value of the thumb at the given index.
`setThumbValue`	`(index: number, value: number) => void`	Sets the value of the thumb at the given index.
`getValuePercent`	`(value: number) => number`	Returns the percent of the thumb at the given index.
`getPercentValue`	`(percent: number) => number`	Returns the value of the thumb at the given percent.
`getThumbPercent`	`(index: number) => number`	Returns the percent of the thumb at the given index.
`setThumbPercent`	`(index: number, percent: number) => void`	Sets the percent of the thumb at the given index.
`getThumbMin`	`(index: number) => number`	Returns the min value of the thumb at the given index.
`getThumbMax`	`(index: number) => number`	Returns the max value of the thumb at the given index.
`increment`	`(index: number) => void`	Function to increment the value of the slider at the given index.
`decrement`	`(index: number) => void`	Function to decrement the value of the slider at the given index.
`focus`	`VoidFunction`	Function to focus the slider. This focuses the first thumb.
`getRootState`	`() => RootState`	Returns the state of the slider
`getThumbState`	`(props: ThumbProps) => ThumbState`	Returns the state of a specific thumb
`getMarkerState`	`(props: MarkerProps) => MarkerState`	Returns the state of a specific marker

Accessibility

Key	Description
`ArrowRight`	Increments the slider based on defined step
`ArrowLeft`	Decrements the slider based on defined step
`ArrowUp`	Increases the value by the step amount.
`ArrowDown`	Decreases the value by the step amount.
`PageUp`	Increases the value by the `largeStep` amount.
`PageDown`	Decreases the value by the `largeStep` amount.
`Shift + ArrowUp`	Increases the value by the `largeStep` amount.
`Shift + ArrowDown`	Decreases the value by the `largeStep` amount.
`Home`	Sets the value to its minimum.
`End`	Sets the value to its maximum.