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.

25
Some contextual help here
<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.

25
Some contextual help here
<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).
50
<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.
50
50
50
<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.

30
<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.

30
20
70
<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.

20 - 50
<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.

20 - 50
<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.

from 20 to 50
<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).

50
<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).

50
<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.

50
Additional context
<q-slider class="sm:w-80" hint="Additional context" [defaultValue]="[50]" />

Disabled

Use disabled to prevent user interaction.

50
<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.

25 - 75
currently focused: none
<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.

25 - 75
live value: 25, 75 final value: 25, 75
<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.

25
25
25
<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.

30 - 70
At least 30
<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:

30 - 70
31 - 60
Range must be at least 30
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-thumbs component or q-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-markers component or q-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:

PropTypeDefault
How to display range values: a separator string or a function that receives the value array and returns a string.
| string
| ((
value: number[],
) => 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
Type
| string
| ((
value: number[],
) => string)
Description
How to display range values: a separator string or a function that receives the value array and returns a string.
Type
string
Description
The error message to display when the slider value is invalid.
Type
string
Description
Optional hint text to display below the slider.
Type
string
Description
The label text for the slider.
Type
number[]
Description
The list of marks to display along the slider track.
Type
boolean
Description
Whether to display markers on the sides of the slider.
Type
boolean
Description
Whether to display the thumb value as a tooltip.

Composite API

q-slider-root

PropTypeDefault
The aria-label of each slider thumb. Useful for providing an accessible name to the slider
| string
| string[]
The id of the elements that labels each slider thumb. Useful for providing an accessible name to the slider
| string
| 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: {
index: number
value: number
}) => string
A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.
() =>
| Node
| ShadowRoot
| Document
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'
| 'vertical'
"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'
| 'end'
| 'center'
"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'
| 'center'
"contain"
The slider thumbs dimensions
{
height: number
width: number
}
The variant of the slider.
| 'primary'
| 'neutral'
Function invoked when the slider focus changes
{
focusedNode: T
focusedValue: string
}
Value change callback.
{
value: number[]
}
Function invoked when the slider value change is done
{
value: number[]
}
Type
| string
| string[]
Description
The aria-label of each slider thumb. Useful for providing an accessible name to the slider
Type
| string
| string[]
Description
The id of the elements that labels each slider thumb. Useful for providing an accessible name to the slider
Type
InputSigna
Description
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.
Type
'ltr' | 'rtl'
Description
The document's text/writing direction.
Type
boolean
Description
Controls whether the input is disabled in template-driven forms. When true, prevents user interaction and applies visual styling to indicate the disabled state.
Type
(details: {
index: number
value: number
}) => string
Description
Function that returns a human readable value for the slider thumb
Type
() =>
| Node
| ShadowRoot
| Document
Description
A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.
Type
string
Description
HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)
Type
boolean
Description
Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.
Type
number
Description
The maximum value of the slider
Type
number
Description
The minimum value of the slider
Type
number
Description
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
Type
string
Description
The name of the input field. Useful for form submission.
Type
| 'horizontal'
| 'vertical'
Description
The orientation of the slider
Type
| 'start'
| 'end'
| 'center'
Description
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
Type
boolean
Description
Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.
Type
boolean
Description
Controls whether the input is required in template-driven forms. When true, the input must have a value for form validation to pass.
Type
'sm' | 'md'
Description
The size of the slider.
Type
number
Description
The step value of the slider
Type
| 'contain'
| 'center'
Description
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.
Type
{
height: number
width: number
}
Description
The slider thumbs dimensions
Type
| 'primary'
| 'neutral'
Description
The variant of the slider.
Type
{
focusedNode: T
focusedValue: string
}
Description
Function invoked when the slider focus changes
Type
{
value: number[]
}
Description
Value change callback.
Type
{
value: number[]
}
Description
Function invoked when the slider value change is done

q-slider-label

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-value-text

PropTypeDefault
How to display range values: a separator string or a function that receives the value array and returns a string.
| string
| ((
value: number[],
) => string)
' - '
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
| string
| ((
value: number[],
) => string)
Description
How to display range values: a separator string or a function that receives the value array and returns a string.
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-control

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-track

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-range

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-thumbs shortcut

PropType
Whether to display the thumb value as a tooltip.
boolean
Type
boolean
Description
Whether to display the thumb value as a tooltip.

q-slider-thumb

PropType
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
Type
number
Description
The slider thumb's index.
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.
Type
string
Description
The name associated with the slider thumb's input (when used in a form).

q-slider-thumb-indicator

PropTypeDefault
Custom value display: a function that receives the value and returns a string.
(
value: number,
) => string
' - '
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
(
value: number,
) => string
Description
Custom value display: a function that receives the value and returns a string.
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-hidden-input

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-markers shortcut

PropType
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[]
Type
number[]
Description
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.

q-slider-marker-group

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-marker

PropType
The value the marker should indicate.
number
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
number
Description
The value the marker should indicate.
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-hint

PropType
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.

q-slider-error-text

PropTypeDefault
Error indicator icon.
| LucideIconData
| string
CircleAlert
id attribute. If omitted, a unique identifier will be generated for accessibility.
string
Type
| LucideIconData
| string
Description
Error indicator icon.
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.