bq-slider provides a visual representation of an adjustable value, enabling users to change settings by dragging a handle along a horizontal track. It supports both single-value and range selection, making it suitable for filters, settings panels, and any input where a numeric value within a bounded range is appropriate.
When to use
Use slider when
- Users need to select a value or range within a continuous or stepped numeric scale
- Approximate values are acceptable — for example, adjusting volume, brightness, or a price filter
- Real-time visual feedback on the selected value adds meaningful context
- The range has a clear minimum and maximum that can be conveyed with a horizontal track
Do not use slider when
- Users must enter a precise value — prefer a number input instead
- The set of valid options is very small (1–3) — prefer a radio group or segmented control
- The interface is space-constrained and the track cannot be rendered with sufficient width
- Values are non-numeric, such as weekdays or named categories
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Value label | The start label showing the current value (or minimum for range); visible when enable-value-indicator is set |
| 2 | Handle | The draggable thumb that sets the value |
| 3 | Track | The full horizontal rail; the highlighted segment (progress area) shows the selected value or range |
| 4 | Value label end | The end label showing the maximum for range type; only visible when enable-value-indicator and type="range" are both set |
Design guidelines
Type
Single (default)
A single handle slides along the track to represent one value. Use this for individual settings such as volume, zoom level, or brightness — any scenario where one number is all that matters.
States
Every slider supports five states: default, hover, focus, active, and disabled. The handle enlarges slightly on hover and focus to provide a clear interactive target. The disabled state dims the track and handle and prevents all interaction — use it to display a read-only preset value.Value feedback
Useenable-value-indicator to show the numeric value beside the track at all times. This is appropriate when the exact number matters to the user, such as a temperature, percentage, or step count. Use enable-tooltip when you want feedback only while the user is actively dragging, keeping the interface clean at rest. Pair it with tooltip-always-visible to keep the tooltip permanently visible.
Width
The slider fills its container’s available width. Constrain the width of its parent container to control how large the track appears — a very short track makes precise selection difficult.Usage
Single
The default slider type. Drag the handle to select a single numeric value within themin–max range.
Range
Settype="range" and pass a two-element array as value to let users select both a minimum and maximum simultaneously.
Options
Disabled
Add thedisabled attribute to prevent interaction while still rendering the slider. Use this to display a preset or locked value that users cannot modify.
Value indicator
Setenable-value-indicator to display the current numeric value as a label beside the track. For range sliders both the minimum and maximum labels are shown — useful when the exact number is meaningful to the user.
Tooltip
Setenable-tooltip to show a tooltip above the active handle while dragging. The tooltip hides again once the user releases the handle.
Tooltip always visible
Addtooltip-always-visible to keep the tooltip permanently visible rather than only while dragging. This requires enable-tooltip to be set.
Min, max, and step
Control the selectable range withmin and max and the increment granularity with step. All selected values are rounded to the nearest multiple of step.
Decimal values
Enable decimal increments by setting a fractionalstep value. This provides increased granularity for precise adjustments — useful when selecting specific percentages or fractional coefficients.
Gap
Usegap to set the minimum distance the two handles must maintain between each other. This is useful when the selected range must span at least a minimum interval — for example, ensuring a time window covers at least one hour.
Best practices
DoProvide a clear, concise label that describes the purpose of the slider and the scale it represents — for example, “Volume” or “Price range”.
Don’tUse long or ambiguous labels. If users cannot tell what the slider controls at a glance, they may set incorrect values without realizing it.
DoShow the selected value alongside the slider using
enable-value-indicator or enable-tooltip whenever the exact number matters to the user’s decision.Don’tLeave the slider without any value feedback when precision is important. Users cannot reliably read off an exact number from the handle position alone.
DoChoose
min, max, and step values that reflect meaningful increments for the context — for example, steps of 5 or 10 for a percentage, or steps of 0.05 for a fractional coefficient.Don’tUse ranges that result in very large step counts or non-discrete increments where the relationship between handle position and value is unclear to users.
DoSet
gap on range sliders when the minimum and maximum handles must stay a meaningful distance apart — for example, when a time range must span at least one hour.Don’tUse a slider for very narrow ranges (1–3 values). With only a few valid positions the drag interaction is awkward and a radio group or button group communicates the options more clearly.
Accessibility
bq-slider renders native <input type="range"> elements inside its shadow DOM (input-min and input-max shadow parts). This means the built-in browser keyboard and screen-reader support for range inputs is available out of the box:
- Keyboard navigation —
ArrowLeft/ArrowDowndecreases the value by one step;ArrowRight/ArrowUpincreases it.Homesets the value tomin;Endsets it tomax. - Screen reader announcement — the browser announces the current numeric value and the min/max boundaries when the handle receives focus.
role="slider"— comes from the native<input type="range">.
- Providing an accessible label — wrap
bq-sliderin a<label>or usearia-label/aria-labelledbyon the host element so screen readers can announce what the slider controls. - Avoid using sliders for highly precise values — drag interactions can be imprecise. When an exact value is critical, supplement the slider with a visible number input that reflects the same value.
- Range sliders and assistive technologies — not all screen readers handle two-thumb range inputs equally well. Test with your target assistive technologies and consider providing a complementary text summary of the selected range.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
debounceTime | debounce-time | Time in milliseconds to wait before emitting bqChange after each value change | number | 0 |
disabled | disabled | If true, the slider is disabled and non-interactive | boolean | false |
enableTooltip | enable-tooltip | If true, a tooltip shows the current value while dragging | boolean | false |
enableValueIndicator | enable-value-indicator | If true, the current value is shown as a label beside the track | boolean | false |
gap | gap | Minimum distance to maintain between the two handles; only applies when type="range" | number | 0 |
max | max | Maximum selectable value | number | 100 |
min | min | Minimum selectable value | number | 0 |
name | name | Name of the form control, submitted with the form as a name/value pair | string | — |
step | step | Increment between selectable values; selected values are rounded to the nearest multiple of step | number | 1 |
tooltipAlwaysVisible | tooltip-always-visible | If true, the tooltip is permanently visible; requires enable-tooltip to be set | boolean | false |
type | type | Slider variant — single for one handle, range for two handles | 'single' | 'range' | 'single' |
value | value | Current value. A number for single type (e.g. 30); a two-element array string for range type (e.g. "[20,70]"). In React and Vue, pass the array directly: value={[20, 70]}. | number | [number, number] | string | — |
Events
| Event | Description | Type |
|---|---|---|
bqBlur | Emitted when the slider loses focus | CustomEvent<HTMLBqSliderElement> |
bqChange | Emitted when the slider value changes | CustomEvent<{ value: number | [number, number]; el: HTMLBqSliderElement }> |
bqFocus | Emitted when the slider gains focus | CustomEvent<HTMLBqSliderElement> |
Slots
| Slot | Description |
|---|---|
| (none) | This component has no public slots. |
Shadow parts
| Part | Description |
|---|---|
base | The component’s base wrapper |
container | The container of the slider |
track-area | The full horizontal track rail |
progress-area | The highlighted progress segment between the handles |
input-min | The <input type="range"> for the value (single) or minimum value (range) |
input-max | The <input type="range"> for the maximum value (range only) |
label-start | The value label for the value (single) or minimum value (range); visible with enable-value-indicator |
label-end | The value label for the maximum value (range only); visible with enable-value-indicator |
CSS custom properties
| Variable | Description | Default |
|---|---|---|
--bq-slider--size | Height of the track and progress area | 4px |
--bq-slider--border-radius | Border radius of the track and progress area | var(--bq-radius--xs) |
--bq-slider--thumb-size | Size of the draggable thumb on hover | 13px |
--bq-slider--progress-color | Background color of the filled progress segment | var(--bq-ui--brand) |
--bq-slider--trackarea-color | Background color of the unfilled track area | var(--bq-ui--secondary) |
Resources
Interactive playground
Explore slider variants and states in Storybook
Source code
View the component source on GitHub