useSlider

Usage#

import { useSlider } from '@primereact/headless/slider';

const slider = useSlider({ defaultValue: 50 });
 
<div {...slider.rootProps}>
    <div {...slider.trackProps}>
        <span {...slider.getRangeProps()} />
    </div>
    <span {...slider.getHandleProps(0)}>
        <input {...slider.getHiddenInputProps(0)} />
    </span>
</div>;

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

Features#

• Single and range modes, passing an array value automatically enables range mode with per-handle props
• Pointer and keyboard input, drag tracking plus arrow keys, Home/End, and PageUp/PageDown with precise step rounding
• Handle distance constraints, minStepsBetweenHandles prevents range handles from crossing or overlapping
• Orientation aware, horizontal and vertical layouts share the same props and state
• Reactive state, state.value and state.isDragging are available for custom rendering like tooltips or live badges
• Deferred commits, onValueChangeEnd fires only when the user releases the pointer, ideal for expensive side effects

Working with callbacks#

Controlled value#

Use value and onValueChange for full programmatic control. In range mode both value and defaultValue are arrays.

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

Deferring expensive work with onValueChangeEnd#

onValueChange fires on every step, use onValueChangeEnd to run network requests or heavy computations only after the user releases.

const slider = useSlider({
    defaultValue: 50,
    onValueChange: (e) => setPreview(e.value),
    onValueChangeEnd: (e) => saveToServer(e.value)
});

Range with minimum distance#

Combine an array defaultValue with minStepsBetweenHandles to keep handles spaced.

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

Using live state for custom UI#

state.value and state.isDragging let you render tooltips or highlight styling without extra state.

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

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#

Accessibility#

Arrow keys step the value, Home/End jump to min/max, and PageUp/PageDown step in larger increments. See Primitive for full WAI-ARIA compliance details.