Slider
A slider is an input control that allows users to adjust a single value or a value range along a defined linear scale. It provides a draggable handle mapped to a continuous or discrete interval.
import {SliderModule} from "@qualcomm-ui/angular/slider"Usage
The slider component lets users select a single value or a range of values by moving one or two thumbs along a track. Sliders are ideal for adjusting settings such as volume, brightness, or selecting a numeric range.
Examples
Simple
Use the simple API to create a slider using minimal markup.
<q-slider
class="sm:w-80"
hint="Some contextual help here"
label="Choose a value"
[defaultValue]="[25]"
/>
Composite
Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.
<div class="sm:w-80" q-slider-root [defaultValue]="[25]">
<label q-slider-label>Choose a value</label>
<div q-slider-value-text></div>
<div q-slider-control>
<div q-slider-track>
<div q-slider-range></div>
</div>
<div q-slider-thumb [index]="0">
<input q-slider-hidden-input />
</div>
</div>
<div q-slider-marker-group>
@for (value of markers; track value) {
<span q-slider-marker [value]="value">{{ value }}</span>
}
</div>
<span q-slider-hint>Some contextual help here</span>
</div>
Min/Max/Step
Use min, max, and step to control the slider's value range and increments:
min: The minimum value of the slider (default is 0).max: The maximum value of the slider (default is 100).step: The increment/decrement step value (default is 1).
<q-slider
class="sm:w-80"
[defaultValue]="[50]"
[max]="70"
[min]="20"
[step]="5"
/>
Origin
Use origin to control where the track is filled from for single-value sliders:
start: Fills from the start of the track to the thumb. Useful when the value represents an absolute value (default).center: Fills from the center of the track to the thumb. Useful when the value represents an offset or relative value.end: Fills from the end of the track to the thumb. Useful when the value represents an offset from the end.
<q-slider
class="sm:w-80"
label="Start (default)"
origin="start"
[defaultValue]="[50]"
/>
<q-slider
class="sm:w-80"
label="Center"
origin="center"
[defaultValue]="[50]"
/>
<q-slider
class="sm:w-80"
label="End"
origin="end"
[defaultValue]="[50]"
/>
Tooltip
Use tooltip to display the slider's value in a tooltip rather than above the component.
<q-slider class="mt-3 sm:w-80" tooltip [defaultValue]="[25]" />
Display
You can customize the tooltip's content by using the composite API and passing a function to display on the q-slider-thumb-indicator component.
import {Component} from "@angular/core"
import {SliderModule} from "@qualcomm-ui/angular/slider"
@Component({
imports: [SliderModule],
selector: "slider-tooltip-display-demo",
template: `
<div class="mt-3 sm:w-80" q-slider-root [defaultValue]="[25, 65]">
<div q-slider-control>
<div q-slider-track>
<div q-slider-range></div>
</div>
<div q-slider-thumb [index]="0">
<input q-slider-hidden-input />
<div q-slider-thumb-indicator [display]="displayFromTooltip"></div>
</div>
<div q-slider-thumb [index]="1">
<input q-slider-hidden-input />
<div q-slider-thumb-indicator [display]="displayToTooltip"></div>
</div>
</div>
<q-slider-markers />
</div>
`,
})
export class SliderTooltipDisplayDemo {
displayFromTooltip = (value: number) => `From ${value}%`
displayToTooltip = (value: number) => `To ${value}%`
}Markers
Track Markers
By default, the component generates 11 default marks based on the slider's min and max values. You can provide your own set using marks.
<q-slider
class="sm:w-80"
[defaultValue]="[30]"
[marks]="[20, 30, 40, 50, 60, 70]"
[max]="70"
[min]="20"
/>
Side Markers
For more compact designs, you can display the min and max markers at the ends of the track using sideMarkers.
<q-slider
class="sm:w-80"
sideMarkers
[defaultValue]="[30]"
[max]="70"
[min]="20"
/>
Range
Set value or defaultValue with two values to create a range slider.
<q-slider class="sm:w-80" [defaultValue]="[20, 50]" />
Minimum Steps Between Thumbs
To prevent overlapping thumbs, use minStepsBetweenThumbs to set a minimum distance between them.
<q-slider
class="sm:w-80"
[defaultValue]="[20, 50]"
[minStepsBetweenThumbs]="10"
/>
Display
By default, range values are displayed separated by an em dash (—). You can customize this by passing a separator string or a function to display.
<q-slider class="sm:w-80" [defaultValue]="[20, 50]" [display]="display" />
Size
Set size to adjust the size of the thumbs. Available sizes are sm (small) and md (medium, default).
<q-slider class="sm:w-80" size="sm" [defaultValue]="[50]" />
Variant
Set variant to adjust the visual style of the slider. Available variants are neutral and primary (default).
<q-slider class="sm:w-80" variant="neutral" [defaultValue]="[50]" />
Hint
Use hint to add additional guidance or context to the user below the slider.
<q-slider class="sm:w-80" hint="Additional context" [defaultValue]="[50]" />
Disabled
Use disabled to prevent user interaction.
<q-slider class="sm:w-80" disabled [defaultValue]="[50]" />
Focus Callback
The focusChanged output allows you to listen for focus events on the slider's thumbs.
<div class="sm:w-80">
<q-slider
[defaultValue]="[25, 75]"
(focusChanged)="onFocusChange($event)"
/>
<output class="mt-4 block">
currently focused:
<strong>{{ currentOutput }}</strong>
</output>
</div>
Value Callbacks
Use valueChanged or valueChangedEnd to monitor the value of the slider.
<div class="sm:w-80">
<q-slider
[defaultValue]="value"
(valueChanged)="onValueChange($event)"
(valueChangedEnd)="onValueChangeEnd($event)"
/>
<output class="mt-4 block">
live value:
<strong>{{ value.join(", ") }}</strong>
</output>
<output class="mt-4 block">
final value:
<strong>{{ finalValue.join(", ") }}</strong>
</output>
</div>
Forms
Template Forms
States
When using template forms, the disabled, readOnly, and invalid properties govern the interactive state of the control.
<q-slider disabled label="Disabled" [defaultValue]="[25]" />
<q-slider readOnly label="Read only" [defaultValue]="[25]" />
<q-slider invalid label="Invalid" [defaultValue]="[25]" />
Validation
This example shows a range slider where values must be at least 30 units apart.
<form
#formRef="ngForm"
class="flex flex-col gap-5 sm:w-80"
(ngSubmit)="onSubmit(formRef)"
>
<q-slider
errorText="Range must be at least 30"
hint="At least 30"
label="Select a range"
name="slider"
[invalid]="isRangeTooSmall()"
[(ngModel)]="value"
/>
<button
emphasis="primary"
q-button
size="sm"
type="submit"
variant="fill"
>
Submit
</button>
</form>
Reactive Forms
State Guidelines
The disabled and invalid properties have no effect when using Reactive Forms. Use the equivalent Reactive Form bindings instead:
disabledField = new FormControl([30, 70])
invalidField = new FormControl([31, 60], {
validators: [minRangeValidator],
})
ngOnInit() {
this.disabledField.disable()
this.invalidField.markAsDirty()
}
Composite API and Shortcuts
The Slider component provides a composite API should you need more control over the slider's behavior and appearance.
Anatomy
The composite API is based on the following components and directives:
q-slider-root: The main component that wraps the slider subcomponents.q-slider-label: The slider main label.q-slider-valueText: The slider current value as text.q-slider-control: The container for the thumb(s) and its track and range.q-slider-track: The track along which the thumb(s) move.q-slider-range: The filled portion of the track.q-slider-thumbscomponent orq-slider-thumb + q-slider-hiddenInput: The draggable handle(s).q-slider-thumb-indicator: The thumb tooltip.q-slider-hint: The hint text below the slider.q-slider-errorText: The error message below the slider.q-slider-markerscomponent orq-slider.MarkerGroup + q-slider.Marker: The markers along the track.
Thumbs
If you need more control over the thumbs, you can use the q-slider-thumb directive instead of the q-slider-thumbs shortcut component.
Note that q-slider-thumbs automatically creates a range slider when the slider's value or defaultValue is set accordingly.
import {Component} from "@angular/core"
import {SliderModule} from "@qualcomm-ui/angular/slider"
@Component({
imports: [SliderModule],
selector: "range-slider",
template: `
<div q-slider-root [defaultValue]="[25, 50]">
<div q-slider-value-text></div>
<div q-slider-control>
<div q-slider-track>
<div q-slider-range></div>
</div>
<div q-slider-thumb [index]="0">
<input q-slider-hidden-input />
</div>
<div q-slider-thumb [index]="1">
<input q-slider-hidden-input />
</div>
</div>
</div>
`,
})
export class RangeSlider {}Thumbs with tooltips
Setting tooltip on the q-slider-thumbs or q-slider-thumb component is the equivalent of the following composition:
import {Component} from "@angular/core"
import {SliderModule} from "@qualcomm-ui/angular/slider"
@Component({
imports: [SliderModule],
selector: "slider-with-tooltip",
template: `
<div q-slider-root [defaultValue]="[25, 65]">
<div q-slider-control>
<div q-slider-track>
<div q-slider-range></div>
</div>
<div q-slider-thumb [index]="0">
<input q-slider-hidden-input />
<div q-slider-thumb-indicator></div>
</div>
<div q-slider-thumb [index]="1">
<input q-slider-hidden-input />
<div q-slider-thumb-indicator></div>
</div>
</div>
</div>
`,
})
export class SliderWithTooltip {}Markers
The q-slider-markers component is a convenient shortcut to display custom track markers. But you can also create your own markers using the q-slider-marker-group and q-slider-marker directives.
import {Component} from "@angular/core"
import {SliderModule} from "@qualcomm-ui/angular/slider"
@Component({
imports: [SliderModule],
selector: "slider-with-custom-markers",
template: `
<div q-slider-root [defaultValue]="[25, 50]">
<div q-slider-value-text></div>
<div q-slider-control>
<div q-slider-track>
<div q-slider-range></div>
</div>
<q-slider-thumbs />
</div>
<div q-slider-marker-group>
<span q-slider-marker [value]="0">0</span>
<span q-slider-marker [value]="25">25</span>
<span q-slider-marker [value]="50">50</span>
<span q-slider-marker [value]="75">75</span>
<span q-slider-marker [value]="100">100</span>
</div>
</div>
`,
})
export class SliderWithCustomMarkers {}API
q-slider
The q-slider component extends the q-slider-root directive with the following props:
| Prop | Type | Default |
|---|---|---|
How to display range values: a separator string or a function that receives the
value array and returns a string. | | string | '—' |
The error message to display when the slider value is invalid. | string | |
Optional hint text to display below the slider. | string | |
The label text for the slider. | string | |
The list of marks to display along the slider track. | number[] | |
Whether to display markers on the sides of the slider. | boolean | |
Whether to display the thumb value as a tooltip. | boolean |
| string
| ((
value: number[],
) => string)
stringstringstringnumber[]
booleanbooleanComposite API
q-slider-root
| Prop | Type | Default |
|---|---|---|
The aria-label of each slider thumb. Useful for providing an accessible name to
the slider | | string | |
The id of the elements that labels each slider thumb. Useful for providing an
accessible name to the slider | | string | |
The initial value of the input when rendered. Use when you don't need to
control the value of the input. This property will be ignored if you
opt into controlled state via form control bindings. | InputSigna | |
The document's text/writing direction. | 'ltr' | 'rtl' | |
Controls whether the input is disabled in template-driven forms. When true,
prevents user interaction and applies visual styling to indicate the disabled
state. | boolean | |
Function that returns a human readable value for the slider thumb | (details: { | |
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron. | () => | |
HTML id attribute. If
omitted, a unique identifier will be generated for accessibility.) | string | |
Controls the visual error state of the input. When true, applies semantic error
styling to indicate validation failure. | boolean | |
The maximum value of the slider | number | 100 |
The minimum value of the slider | number | 0 |
The minimum permitted steps between multiple thumbs. minStepsBetweenThumbs * step should reflect the gap between the thumbs.- step: 1 and minStepsBetweenThumbs: 10 => gap is 10- step: 10 and minStepsBetweenThumbs: 2 => gap is 20 | number | 0 |
The name of the input field. Useful for form submission. | string | |
The orientation of the slider | | 'horizontal' | "horizontal" |
The origin of the slider range. The track is filled from the origin
to the thumb for single values. - "start": Useful when the value represents an absolute value - "center": Useful when the value represents an offset (relative) - "end": Useful when the value represents an offset from the end | | 'start' | "start" |
Whether the input is read-only. When true, prevents user interaction while
keeping the input focusable and visible. | boolean | |
Controls whether the input is required in template-driven forms. When
true, the input must have a value for form validation to pass. | boolean | |
The size of the slider. | 'sm' | 'md' | |
The step value of the slider | number | 1 |
The alignment of the slider thumb relative to the track - center: the thumb will extend beyond the bounds of the slider track.- contain: the thumb will be contained within the bounds of the track. | | 'contain' | "contain" |
The slider thumbs dimensions | { | |
The variant of the slider. | | 'primary' | |
Function invoked when the slider focus changes | { | |
Value change callback. | { | |
Function invoked when the slider value change is done | { |
| string
| string[]
| string
| string[]
id of the elements that labels each slider thumb. Useful for providing an
accessible name to the sliderInputSigna'ltr' | 'rtl'
boolean(details: {
index: number
value: number
}) => string
() =>
| Node
| ShadowRoot
| Document
stringbooleannumbernumbernumberminStepsBetweenThumbs * step should reflect the gap between the thumbs.-
step: 1 and minStepsBetweenThumbs: 10 => gap is 10-
step: 10 and minStepsBetweenThumbs: 2 => gap is 20string| 'horizontal'
| 'vertical'
| 'start'
| 'end'
| 'center'
- "start": Useful when the value represents an absolute value
- "center": Useful when the value represents an offset (relative)
- "end": Useful when the value represents an offset from the end
booleanboolean'sm' | 'md'
number| 'contain'
| 'center'
-
center: the thumb will extend beyond the bounds of the slider track.-
contain: the thumb will be contained within the bounds of the track.{
height: number
width: number
}
| 'primary'
| 'neutral'
{
focusedNode: T
focusedValue: string
}
{
value: number[]
}
{
value: number[]
}
QdsSliderPropsq-slider-label
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-focus | |
data-invalid | |
data-orientation | Orientation |
data-part | 'label' |
data-scope | 'slider' |
style |
data-disableddata-draggingdata-focusdata-invaliddata-orientationOrientationdata-part'label'data-scope'slider'styleq-slider-value-text
| Prop | Type | Default |
|---|---|---|
How to display range values: a separator string or a function that receives the
value array and returns a string. | | string | ' - ' |
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
| string
| ((
value: number[],
) => string)
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-focus | |
data-invalid | |
data-orientation | Orientation |
data-part | 'value-text' |
data-scope | 'slider' |
data-disableddata-focusdata-invaliddata-orientationOrientationdata-part'value-text'data-scope'slider'q-slider-control
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-focus | |
data-invalid | |
data-orientation | Orientation |
data-part | 'control' |
data-scope | 'slider' |
style |
data-disableddata-draggingdata-focusdata-invaliddata-orientationOrientationdata-part'control'data-scope'slider'styleq-slider-track
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-focus | |
data-invalid | |
data-orientation | Orientation |
data-part | 'track' |
data-scope | 'slider' |
style |
data-disableddata-draggingdata-focusdata-invaliddata-orientationOrientationdata-part'track'data-scope'slider'styleq-slider-range
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-focus | |
data-invalid | |
data-orientation | Orientation |
data-part | 'range' |
data-scope | 'slider' |
style |
data-disableddata-draggingdata-focusdata-invaliddata-orientationOrientationdata-part'range'data-scope'slider'styleq-slider-thumbs shortcut
q-slider-thumb
| Prop | Type |
|---|---|
The slider thumb's index. | number |
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
The name associated with the slider thumb's input (when used in a form). | string |
numberstringstring| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-focus | |
data-index | number |
data-name | string |
data-orientation | Orientation |
data-part | 'thumb' |
data-scope | 'slider' |
style | |
tabIndex | number |
data-disableddata-draggingdata-focusdata-indexnumberdata-namestringdata-orientationOrientationdata-part'thumb'data-scope'slider'styletabIndexnumberq-slider-thumb-indicator
| Prop | Type | Default |
|---|---|---|
Custom value display: a function that receives the value and returns a
string. | ( | ' - ' |
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
(
value: number,
) => string
string| Attribute / Property | Value |
|---|---|
data-orientation | Orientation |
data-part | 'thumb-indicator' |
data-scope | 'slider' |
style |
data-orientationOrientationdata-part'thumb-indicator'data-scope'slider'styleq-slider-hidden-input
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-scope | 'slider' |
hidden | boolean |
data-scope'slider'hiddenbooleanq-slider-markers shortcut
| Prop | Type |
|---|---|
An array of numbers indicating where to place the markers. If not
provided, the component will generate 11 evenly spaced markers based on
the min and max slider values. | number[] |
number[]
min and max slider values.q-slider-marker-group
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-orientation | Orientation |
data-part | 'marker-group' |
data-scope | 'slider' |
style |
data-orientationOrientationdata-part'marker-group'data-scope'slider'styleq-slider-marker
| Prop | Type |
|---|---|
The value the marker should indicate. | number |
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
numberstring| Attribute / Property | Value |
|---|---|
data-disabled | |
data-orientation | Orientation |
data-part | 'marker' |
data-scope | 'slider' |
data-state | | 'over-value' |
data-value | number |
style |
data-disableddata-orientationOrientationdata-part'marker'data-scope'slider'data-state| 'over-value'
| 'under-value'
| 'at-value'
data-valuenumberstyleq-slider-hint
| Prop | Type |
|---|---|
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-invalid | |
data-orientation | Orientation |
data-part | 'hint' |
data-scope | 'slider' |
hidden | boolean |
data-disableddata-draggingdata-invaliddata-orientationOrientationdata-part'hint'data-scope'slider'hiddenbooleanq-slider-error-text
| Prop | Type | Default |
|---|---|---|
Error indicator icon. | | LucideIconData | CircleAlert |
id attribute. If
omitted, a unique identifier will be generated for accessibility. | string |
| LucideIconData
| string
string| Attribute / Property | Value |
|---|---|
data-disabled | |
data-dragging | |
data-invalid | |
data-orientation | Orientation |
data-part | 'error-text' |
data-scope | 'slider' |
hidden | boolean |
data-disableddata-draggingdata-invaliddata-orientationOrientationdata-part'error-text'data-scope'slider'hiddenboolean