Slider Specification

Revision History

Version	User	Date	Notes
0.1	Danail Marinov	Apr 17, 2019	Initial draft
0.2	Danail Marinov	Apr 24, 2019	Update
0.2.1	Danail Marinov	Jun 17, 2019	Images update
1.0	Zdravko Kolev	Oct 30, 2019	Ticks dev stories and API
1.0.1	Danail Marino	Oct 30, 2019	More User stories added/Hands-off updated
1.1	Zdravko Kolev	Nov 8, 2019	Update test plan with slider ticks
2.0	Konstantin Dinev	May 5, 2022	Update range slider and ngModel
2.1	Konstantin Dinev	Sep 19, 2023	Removing thumb swap from test scenarios

1. Overview

Slider component allows users to make selections from a range of values. They offer range of values from which the user can select a single value, or a sub-range. Changes applied through a slider are immediate. Usually slider bars have icons, inputs or titles on their both sides. Sliders indicate the current state of the settings they control. Slider is a form component that can be used in both template-driven and reactive forms scenarios.

Types

Continuous slider - allows users to select a value along a subjective range
Discrete slider - can be adjusted to a specific value by referencing its value indicator

2. User Stories

As an end user I want to see the range available for selection.
As an end user I want to be able to use label on the slider along the track, that will display the selected value through its position.
As an end user I want to be able to focus slider and to change its values through keyboard.
As an end user, if I am using discrete slider, I want to have snapping to closest predetermined values for my selection when moving the sliders thumb.
As an end user, if I am using discrete slider, I want predetermined values to be clearly visible shown as tick marks.
As an end user I want to be able to make my selection of the slider's values through dragging the thumb.
As an end user I want to be able to make my selection of the slider's values through clicking on the track.
As an end user I want to be able to click on the thumb, then move it through the keyboard arrows.
As an end user I want to be able to view the selected range (track) when using two-thumb slider.
As an end user, I want to be able to change the positioning of the thumbs through separate data bound fields.
As an end user, I want to have boundaries that prevent me to drag the thumbs to the max or min values of the slider

As an end user, I want to be able to view slider's primary and/or secondary ticks along the slider track.
As an end user, I want to be able to view labels for slider's primary and/or secondary ticks along the slider track.
As an end user, I want to be able to move the slider thumb clicking very close to the slider's track (even if not clicked exactly on the slider).
As an end user, I want to see clear difference between primary and secondary ticks.
As an end user, I want to be able to change the orientation of the positioning of the primery/secondary ticks.
As and end user, I want to be able to change the rotation of the tick labels.

3. Behavior

3.1 Click and drag

Continuous and discrete sliders are controlled by clicking on the slider thumb, then dragging it along the slider bar.

3.2 Click jump

Continuous and discrete sliders are controlled by clicking on the slider bar, which determines slider thumb position.

3.3 Click and arrows

Continuous and discrete sliders are controlled by clicking on the slider thumb, which puts it on focus, then thumb's position is controlled by the keyboard arrows.

3.4 Tab and arrows

Continuous and discrete sliders are selected by using TAB key, then thumb's position is controlled by the keyboard arrows.

3.5 Using arrows

Using keyboard arrows to control slider thumb position:

continuous slider results in continuous increment/decrement operations.
discrete slider results in increment/decrement operations by changing thumb position on its predefined steps.

4. Anatomy

The size of the label has to shrink or enlarge based on the data type and size inside the label.

Tick Types and Orientation

5. States

5.1 Dark version

continuous (default)

discrete (default)

5.2 Light version

continuous (default)

discrete (default)

Hands-off: https://cloud.indigo.design/share/k6jrh8gvvwbk

6. Dev stories

As a developer I want to be able to choose between discrete and continuous slider.
As a developer I want to be able to specify intervals in discrete slider.
As a developer I want to be able to enable or disable slider.
As a developer I want to be able to edit all slider components such as thumb, track etc. and their properties such as color, shape etc.
As a developer I want to be able to edit ripple properties and animation for hover, pressed and focus state.
As a developer I want to be able to put the slider in a form and bind it to [(ngMode)] or a FormGroup.

<form #myForm="ngForm">
  <igx-slider [(ngModel)]="myModel.value"></igx-slider>
  <!-- Works one way - slider notifies the model, the other way only if the whole range object changes -->
  <igx-slider [(ngModel)]="myModel.range"></igx-slider>
  <!-- Works both ways because of the primitive value bindings -->
  <igx-slider [(upperValue)]="myModel.range.upper" [(lowerValue)]="myModel.range.lower"></igx-slider>
</form>

As a developer I want to be able to provide an array of primitive values that the slider could spread and visualize as thumb/tick labels.

<igx-slider [labels]="['spring', 'autumn', 'winter', 'summer']">
</igx-slider>

As a developer I want to be able to customize the label(s)' content.

<igx-slider
  [labels]="['spring', 'autumn', 'winter', 'summer']">
  <ng-template igxSliderThumbTo let-val let-labels="labels">
    <span>{{ labels[val.upper] }} </span>
   </ng-template>
</igx-slider>

As a developer I want to be able to change the type of the slider affecting value selection as single or range.

<igx-slider [labels]="['spring', 'autumn', 'winter', 'summer']" [type]="sliderType">
</igx-slider>

As a developer, I want to be able to track the changes of the values per every slide.
As a developer, I want to have the ability to manipulate the slider values through two way data binding.
As a developer, I want to be able to change the sliding behavior from continuous to discrete and vice versa.

<igx-slider [continuous]="true">
</igx-slider>

As a developer, I want to be able to set a minimum and maximum values representing the beginning and end of a number sequence.

[begin....end]

<igx-slider [minValue]="20" [maxValue]="80">
</igx-slider>

As a developer, I want to have the ability to set boundaries, limiting the sliding range in a given sequence of numbers.

[begin..lowerBound.......upperBound...end]

<igx-slider [lowerBound]="30" [upperBound]="70">
</igx-slider>

As a developer, I want to have the ability to set the visibility duration of the thumb label that shows the slider value.
As a developer, I want to be able to manipulate the positioning of the slider thumb through the API.
As a developer, I want to be able to pass a custom templates that could modify the thumb label representation

<igx-slider>
 <ng-template igxSliderthumbFrom let-val let-labels="labels">
    <span>{{ val }}</span>
  </ng-template>
</igx-slider>

As a developer I want to be able to enable tick marks that will help me easily determine slider scale and track easily the thumb positioning, as well as to set different tick intervals.

<igx-slider [primaryTicks]="6">
</igx-slider>

As a developer I want to be able to change the orientation of the tick marks - Mirror | Top | Bottom

<igx-slider [ticksOrientation]="'top'">
</igx-slider>

As a developer I want to be able to set two different types of ticks - primary and secondary. By default the height of the primary ticks are 16px, and for the secondary 8px.

<igx-slider [primaryTicks]="6" [secondaryTicks]="7">
</igx-slider>

As a developer I want to be able to show or hide ticks label

<igx-slider [primaryTickLabels]="true" [secondaryTickLabels]="false">
</igx-slider>

As a developer I want to be able to change ticks label orientation - horizontal | toptobottom | bottomtotop

<igx-slider [tickLabelsOrientation]="'horizontal'">
</igx-slider>

7. Acceptance criteria

The developer can create a slider by only giving the min/max ranges.
The developer can create sliders consisting of one or two thumb(s).
The developer can set boundaries limiting the slider range.
The developer can choose between continuous or discrete slide.
The developer can set custom templates representing the thumb(s) label(s).

8. ARIA Support

role - indicates the type of the widget (slider).
aria-valuemin - minimum allowed value for a range selector
aria-valuemax - maximum allowed value for a range selector
aria-readonly - Indicates whether the element is editable.

9. API

Enums

Name	Description	Values
TickLabelsOrientation	Controls the rotation of the tick labels.	`horizontal` \| `toptobottom` \| `bottomtotop`
TicksOrientation	Controls the ticks orientation.	`mirror` \| `top` \| `bottom`
SliderType	Changes the type of the slider	`SLIDER` \| `RANGE`

Interfaces

IRangeSliderValue

Name	Type	Description
lower	number	The lower value of the range slider or the lower index of the labels collection
upper	number	The upper value of the range slider or the upper index of the labels collection

ISliderValueChangeEventArgs

Name	Type	Description
oldValue	number \| IRangeSliderValue	Previous value of the slider
new	number \| IRangeSliderValue	Current value of the slider

Inputs

General

Name	Description	Type	Default value
id	Unique identifier of the component. If not provided it will be automatically generated.	string	igx-slider-0
disabled	Disables or enables UI interaction.	boolean	false
continuous	Marks slider as continuous. By default the slider is considered as discrete. Continuous slider does not have ticks and does not show bubble labels for values.	boolean	false
lowerBound	The lower boundary of the slider value. If not set is the same as min value.	number	0
upperBound	The lower boundary of the slider value. If not set is the same as max value.	number	100
lowerValue	The lower value of a RANGE slider.	number	0
upperValue	The upper value of a RANGE slider.	number	100
minValue	The minimum value for the slider.	number	0
maxValue	The maximal value for the slider.	number	100
step	The incremental/decremental step of the value when dragging the thumb. The step should be greater than 0.	number	1
thumbLabelVisibilityDuration	The duration visibility of thumbs labels.	number	750 ms
type	Sets the SliderType, which is SLIDER or RANGE.	SliderType	SLIDER
value	The slider value. If the slider is of type SLIDER the argument is number. By default if no value is set the default value is same as lower upper bound. If the slider type is RANGE then the argument is object containing lower and upper properties for the values. By default if no value is set the default value is for lower value it is the same as lower bound and if no value is set for the upper value it is the same as the upper bound.	number\|IRangeSliderValue
labels	Enables lableView, by accepting a collection of primitive values with more than one element. Each element will be equally spread over the slider and it will serve as a thumb label.	array	empty array

Tick inputs

Name	Description	Type	Default value
primaryTicks	Sets the number of `primary` ticks	number	0
secondaryTicks	Sets the number of `secondary` ticks	number	0
primaryTickLabels	show/hide `primary` tick labels	boolean	true
secondaryTicksLabels	show/hide `secondary` tick labels	boolean	true
ticksOrientation	changes the orientation of the `ticks`	enum	bottom
tickLabelsOrientation	changes the rotation of the `tick labels`	enum	horizontal

Getters

Name	Description	Type
lowerLabel	Returns the value of the lower thumb label	number \| string
upperLabel	Returns the value of the upper thumb label	number \| string

Events

Name	Description	Cancelable	Parameters
valueChange	This event is emitted when user has stopped interacting the thumb and value is changed.	no	ISliderValueChangeEventArgs
upperValueChange	This event is emitted when `upperValue` changes in a RANGE slider.	no	number
lowerValueChange	This event is emitted when `lowerValue` changes in a RANGE slider.	no	number

6. Test Scenarios

Automation

Base

SLIDER type

The value should be correlated with the upperValue.
Continuous(smooth) sliding should be allowed - should be tested

RANGE type

When lower/upper values are not set, they should take the values of lower/upper bounds.
When the lower thumb gets to the upper thumb, the focus should change to the upper, in order to continue sliding and vica versa. - removed because of #13403 The spec actually does not specify this behavior.
Continuous(smooth) sliding should be allowed - should be tested

Label view

When labels is set, the rendering of the slider should corresponds to that collection. - should be tested
When labels view is enabled the min/max and step setters should not respond to user manipulations, and the default values should be taken. - - should be tested
When labels view is enabled, tick marks(steps) should be shown equally spread based on the labels length. - should be tested
When lower/upper bounds are set, the slide limitations should be applied. - should be tested
Continuous(smooth) sliding should not be allowed. - should be tested
Set labels to empty array and null. - should be tested
The view should be enabled only when the collection has more than 1 element. - should be tested

COMMON

When lower/upper bound are not set, they should take the values of min/max.
API modifications should be allowed for the min/max/lower/upper values, lower/upper bounds, value, continuous and disabled.
Min value should not exceed but decrease when it's bigger than the max value.
Max value should not go below min value and increase with 1.
When lower bound exceeds **upper **bound it should take the value of the min.
The value should always track as first the range between lower/upper bound, then the range between min/max value, independently of the slider type.
The slider thumb/s should be moving when pressing left/right arrow keys.
When the slider is disabled the interaction with the UI should not be possible.
Tick marks(steps) should appear when the step is more then 1.
should be able to track the value changes per every slide action through an event emitter. - should be tested
Custom templates for the lower/upper thumb labels should be allowed - should be tested
Dynamically change the type of the slider SLIDE, RANGE, LABEL - should be tested
The aria properties should be successfully applied. - should be tested
When upper bound is lower or equal than the lower bound it should take the value of the max. - should be tested

Slider Ticks

Test plan for ticks:

Test slider visualization with primary ticks. Set 4 primary ticks with step equal to 25, and check their existence.

<igx-slider [step]="25" [primaryTicks]="4">
</igx-slider>

Test enabling of primaryTickLabels. Enable and disable them. Toggle their visibility and verify it.
Check primaryTicks length, it should be equal to 16px.
Test slider visualization with secondaryTicks. Set 4 secondary ticks with step equal to 25, and check their existence.

<igx-slider [step]="25" [secondaryTicks]="4">
</igx-slider>

Test enabling of secondaryTickLabels. Enable and disable them. Toggle their visibility and verify it.
Check secondaryTicks length, it should be equal to 8px.
Test slider visualization with both primary and secondary ticks. Set 4 primary and 4 secondary ticks with step equal to 5, and check their existence.

<igx-slider [step]="5" [primaryTicks]="4" [secondaryTicks]="4">
</igx-slider>

Test tickOrientation with top, bottom and mirror.
Test tickLabelsOrientation with horizontal, toptobottom, bottomtotop
Test the scenario when tickOrientation is set to top or mirror, the thumb labels should be visible on slide action.
Test ticks primary rendering on dinamic change. Create labels array of 7 items. Remove dinamically 2 items from the labels array (now the labels array has only 5 items) and verify that the ticks are updated based on the labels. End result 5 primaryTicks.

<igx-slider #slider
	[labels]="labels"
    [tickLabelsOrientation]="1"
    [ticksOrientation]="2">
</igx-slider>

public labels = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];

Test slide action with the following configuration: a. tickLabelOrientation = toptobottom b. ticksOrientation = mirror c. primaryTicks = 10 d. secondaryTicks = 1 e. Slider type = range f. rangeValue with lower(25) and uppser(75) values g. Step = 5 Result: On lower thumb slide action the lower value should change to 15 (two steps on the left) and the upper value should change to 90 (three steps on the right), and the lower thumb should be located on the secondaryTick with label 15.00, as for the upper thumb, it should be located on the primaryTick with label 90.00

<igx-slider #slider [type]="1" [value]="rangeValue" [step]="5" [lowerBound]="0"
                    [tickLabelsOrientation]="1"
                    [ticksOrientation]="ticksOrientation"
                    [primaryTicks]="10"
                    [secondaryTicks]="1">
                </igx-slider>