;
};
`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
The slider consists of a horizontal track, a filled progress region that visualizes the selected value, a draggable handle (thumb), and optional value labels at each end.
| 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
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.
Two handles define a minimum and maximum. Use this when users need to select an interval — for example, a price range, a time window, or a quantity bracket.
### 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
Use `enable-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 the `min`–`max` range.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return (
console.log("value:", e.detail.value)}
/>
);
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {
onSliderChange(event: CustomEvent<{ value: number }>) {
console.log("value:", event.detail.value);
}
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Range
Set `type="range"` and pass a two-element array as `value` to let users select both a minimum and maximum simultaneously.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return (
console.log("range:", e.detail.value)}
/>
);
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {
onRangeChange(event: CustomEvent<{ value: [number, number] }>) {
console.log("range:", event.detail.value);
}
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
## Options
### Disabled
Add the `disabled` attribute to prevent interaction while still rendering the slider. Use this to display a preset or locked value that users cannot modify.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Value indicator
Set `enable-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.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Tooltip
Set `enable-tooltip` to show a tooltip above the active handle while dragging. The tooltip hides again once the user releases the handle.
bq-slider {
width: 100%;
max-width: 400px;
padding: var(--bq-spacing-xl);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Tooltip always visible
Add `tooltip-always-visible` to keep the tooltip permanently visible rather than only while dragging. This requires `enable-tooltip` to be set.
bq-slider {
width: 100%;
max-width: 400px;
padding: var(--bq-spacing-xl);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Min, max, and step
Control the selectable range with `min` and `max` and the increment granularity with `step`. All selected values are rounded to the nearest multiple of `step`.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Decimal values
Enable decimal increments by setting a fractional `step` value. This provides increased granularity for precise adjustments — useful when selecting specific percentages or fractional coefficients.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Gap
Use `gap` 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.
bq-slider { width: 100%; max-width: 400px; }
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqSlider } from "@beeq/react";
export default function App() {
return ;
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqSlider],
template: ``,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Form integration
`bq-slider` is form-associated and submits its current value as form data. It does not expose `required`, so use it for adjustable values rather than mandatory completion checks.
body {
padding: var(--bq-spacing-l);
}
.slider-form {
display: grid;
gap: var(--bq-spacing-m);
}
.slider-form__actions {
display: flex;
gap: var(--bq-spacing-s);
justify-content: flex-end;
}
.slider-form__output {
margin: 0;
padding: var(--bq-spacing-s);
border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary);
border-radius: var(--bq-radius--s);
background: var(--bq-ui--secondary);
color: var(--bq-text--primary);
white-space: pre-wrap;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useState } from "react";
import { BqButton, BqSlider } from "@beeq/react";
export default function SliderForm() {
const [data, setData] = useState("{}");
return (
);
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqSlider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqButton, BqSlider],
template: `
`,
})
export class SliderFormComponent {
data = "{}";
handleSubmit(event: SubmitEvent): void {
event.preventDefault();
this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
}
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
## Best practices
Do
Provide a clear, concise label that describes the purpose of the slider and the scale it represents — for example, "Volume" or "Price range".
Don't
Use long or ambiguous labels. If users cannot tell what the slider controls at a glance, they may set incorrect values without realizing it.
Do
Show the selected value alongside the slider using `enable-value-indicator` or `enable-tooltip` whenever the exact number matters to the user's decision.
Don't
Leave the slider without any value feedback when precision is important. Users cannot reliably read off an exact number from the handle position alone.
Do
Choose `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't
Use ranges that result in very large step counts or non-discrete increments where the relationship between handle position and value is unclear to users.
Do
Set `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't
Use 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 `` 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` / `ArrowDown` decreases the value by one step; `ArrowRight` / `ArrowUp` increases it. `Home` sets the value to `min`; `End` sets it to `max`.
* **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 ``.
As a developer you are responsible for:
* **Providing an accessible label** — wrap `bq-slider` in a `
`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
The slider consists of a horizontal track, a filled progress region that visualizes the selected value, a draggable handle (thumb), and optional value labels at each end.
| 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