useSlider

Hook that manages slider state, pointer dragging, and accessible range input behavior.

basic-demo

Usage#

import { useSlider } from '@primereact/headless/slider';
 
const slider = useSlider({ defaultValue: 50 });
 
return (
    <div {...slider.rootProps}>
        <div {...slider.trackProps}>
            <span {...slider.getRangeProps()} />
        </div>
        <span {...slider.getThumbProps(0)}>
            <input {...slider.getHiddenInputProps(0)} />
        </span>
    </div>
);

useSlider manages value state, pointer tracking, and keyboard input for a single or range slider — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects (rootProps, trackProps, getRangeProps, getThumbProps, getHiddenInputProps)
Single value and range mode with automatic thumb count
minStepsBetweenThumbs for enforcing minimum distance between range handles
Precise step rounding with floating-point precision handling
Exposes state.value and state.isDragging for custom rendering logic

Behavior#

Default Value#

Use defaultValue to set the initial slider value.

const slider = useSlider({ defaultValue: 50 });

For a range slider, pass an array.

const slider = useSlider({ defaultValue: [20, 80] });

Controlled#

Use value and onValueChange for full programmatic control.

const [value, setValue] = React.useState(50);
const slider = useSlider({
    value,
    onValueChange: (e) => setValue(e.value)
});

Step#

Set step to define the increment granularity.

const slider = useSlider({ step: 10 });

Range#

Pass an array as defaultValue or value to enable range mode. The hook detects the mode automatically via range().

const slider = useSlider({ defaultValue: [20, 80] });
 
// Render multiple thumbs
slider.range() &&
    [0, 1].map((index) => (
        <span key={index} {...slider.getThumbProps(index)}>
            <input {...slider.getHiddenInputProps(index)} />
        </span>
    ));

Minimum Thumb Distance#

Set minStepsBetweenThumbs to prevent range handles from overlapping.

const slider = useSlider({ defaultValue: [20, 80], minStepsBetweenThumbs: 10 });

Orientation#

Set orientation to 'vertical' for a vertical slider layout.

const slider = useSlider({ orientation: 'vertical' });

Disabled#

Set disabled to prevent all pointer and keyboard interaction.

const slider = useSlider({ disabled: true });

Value Change End#

Use onValueChangeEnd to receive a callback only when the user finishes dragging or releases the pointer. This is useful for expensive operations like API calls.

const slider = useSlider({
    defaultValue: 50,
    onValueChangeEnd: (e) => console.log('Final value:', e.value)
});

Using `state.value` and `state.isDragging`#

The hook exposes reactive state for custom UI logic.

const slider = useSlider({ defaultValue: 50 });
 
<span>{slider.state.value}</span>;
{
    slider.state.isDragging && <span>Dragging...</span>;
}

Custom Styling with Data Attributes#

Prop objects include orientation and state-dependent data attributes.

[data-orientation='horizontal'] {
    height: 1.25rem;
}
 
[data-orientation='vertical'] {
    width: 1.25rem;
    min-height: 100px;
}
 
[data-dragging] {
    cursor: grabbing;
}
 
[data-disabled] {
    opacity: 0.5;
    pointer-events: none;
}

API#

useSlider#

Name	Type	Default
`value`	`number` \| `number[]`	—
Value of the component.
`defaultValue`	`number` \| `number[]`	—
The default value for the input when not controlled by `value` .
`min`	`number`	`0`
Mininum boundary value.
`max`	`number`	`100`
Maximum boundary value.
`orientation`	`"horizontal"` \| `"vertical"`	`horizontal`
Orientation of the slider.
`step`	`number`	`1`
Step factor to increment/decrement the value.
`minStepsBetweenThumbs`	`number`	`0`
Minimum steps between thumbs.
`onValueChange`	`(event: useSliderChangeEvent) => void`	—
Callback fired when the ToggleButton's pressed state changes.
`onValueChangeEnd`	`(event: useSliderChangeEvent) => void`	—
Callback fired when the pointer interaction ends.
`disabled`	`boolean`	`false`
Whether the component is disabled.
`readOnly`	`boolean`	`false`
Whether the component is read-only.
`invalid`	`boolean`	`false`
When present, it specifies that the element should be invalid.
`onFocus`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback to invoke when a thumb input receives focus.
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback to invoke when a thumb input loses focus.

Accessibility#

See Slider Primitive for WAI-ARIA compliance details and keyboard support.