Slider

An input for selecting a value, or a range of values, from a given range.

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
Supports touch, mouse and pointer interactions, including clicking the track
Supports a range of values with multiple thumbs, with a configurable minimum gap between them
Supports custom step, largeStep and min/max values
Supports marks/ticks along the track
Accepts defaultValue as a single number for one thumb, or a list of numbers for a range
Works with the Field component for form integration

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

Use two thumbs to let users pick a range of 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

Render slider.marker elements to show ticks - with a label - 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

Prevent the slider from being interacted with.

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, keeping both in sync by updating one whenever the other changes. Both are mounted as independent instances (autoMount="{false}" + a fixed rootId) so a custom entry file can wire them together, the same pattern Combobox's custom filter example uses. Both components' own onValueChange call into one shared setValue() function instead of writing to each other directly, so there's a single guard - skip if it's already the current value - rather than a syncing flag guessing which call is the "real" one.

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 { getHydrationData, mount } from 'fluid-primitives';
import { NumberInput } from 'fluid-primitives/number-input';
import { Slider } from 'fluid-primitives/slider';

(() => {
    // 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 kept as the bare number this needs.
    let currentValue = getHydrationData('ui:numberInput', 'synced-number-input')?.props
        .defaultValue as 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 }) => {
        const instance = new Slider({
            ...props,
            onValueChange: ({ value }) => setValue(value[0]),
        });
        instance.init();
        return instance;
    });

    const numberInput = mount('ui:numberInput', 'synced-number-input', ({ props }) => {
        const instance = new NumberInput({
            ...props,
            onValueChange: ({ valueAsNumber }) => {
                if (!Number.isNaN(valueAsNumber)) setValue(valueAsNumber);
            },
        });
        instance.init();
        return instance;
    });
})();

With a Field

Wrap the slider in ui:field.root to get label association and name/disabled/invalid state propagated to the thumb automatically - a donation amount picker, with marks for common preset 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 its current value in a small tooltip while it's being dragged - it's hidden the rest of the time.

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 (e.g. 0.01) to get fine-grained, decimal precision instead of whole numbers - useful whenever the value represents something more precise than an integer count.

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\|array` 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
`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.

Slider

Features

Anatomy

Installation

Examples

Range

With marks

Disabled

With a number input

With a Field

With a dragging indicator

With decimal values

API Reference

slider.root

Rendered data attributes

slider.label

Rendered data attributes

slider.valueText

Rendered data attributes

slider.control

Rendered data attributes

slider.track

Rendered data attributes

slider.range

Rendered data attributes

slider.thumb

Rendered data attributes

slider.hiddenInput

slider.markerGroup

Rendered data attributes

slider.marker

Rendered data attributes

slider.draggingIndicator

Rendered data attributes

Machine JavaScript API

Accessibility

On this page