Slider Specification - IgniteUI/igniteui-webcomponents GitHub Wiki
Slider Specification
Contents
- Overview
- User Stories
- Functionality
- Test Scenarios
- Accessibility
- Assumptions and Limitations
- References
Owned by
Team Name: CodeX
Developer Name: Maria Tsvyatkova
Designer Name:
Requires approval from
- Peer Developer Name | Date:
- Simeon Simeonov | Date:
Signed off by
- Radoslav Mirchev | Date:
- Radoslav Karaivanov | Date:
Revision History
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 | Maria Tsvyatkova | 19-Aug-2021 | Initial version |
| 2 | Radoslav Karaivanov | 2024-02-08 | Deprecated range slider aria-label attributes |
1. Overview
igc-slider component allows users to select values within a range. The users can select a single value, or a sub-range.
Types:
- Continuous slider - the users can select a value along a subjective range.
- Discrete slider - the slider is adjusted to a specific value. The allowed selections could be indicated with tick marks and the slider thumb will snap to them.
Objectives
The slider component indicates the current state of the settings they control. The changes made with them have immediate effect.
Acceptance criteria
- The slider can be set to continuous or discrete.
- Minimum and maximum values for the slider could be specified.
- The slider can have one or two thumbs.
- The slider can have boundaries limiting its range.
- The slider should have a step property to specify the increment/decrement values.
- Tick marks could be displayed and their position modified.
- Labels could be displayed for the tick marks and their orientation could be changed.
2. User Stories
Developer stories:
- Story 1: As a developer, I want to choose between discrete and continuous slider, so that I can decide whether the ticks and bubble labels for the values are visible or not.
- Story 2: As a developer, I want to be able to specify intervals for the discrete slider, so that I can change the step by which the slider value is changed.
- Story 3: As a developer, I want to enable or disable the slider, so that I can decide whether the user can interact with it.
- Story 4: As a developer, I want to change the type of the slider, so that I can set the value selection to single or range.
- Story 5: As a developer, I want to know the previous and the current values per every slide, so that I can track the changes.
- Story 6: As a developer, I want to manipulate the slider values using two way data binding, so that I can update the values dynamically.
- Story 7: As a developer, I want to set minimum and maximum values, so that I can decide what values are displayed at the start and at the end of the track. Start and end value can be e.g. 0 and 100 and thumb default position 0 which is left end or -50 and +50 and thumb default position 0 which is middle.
- Story 8: As a developer, I want to set boundaries, so that I can limit the sliding range in a given number sequence.
- Story 9: As a developer, I want to modify the visibility duration of the thumb label which shows the current slider value, so that I can specify how many milliseconds it will be visible.
- Story 10: As a developer, I want to enable tick marks and set different tick intervals, so that I can easily determine slider scale and track the thumb positioning.
- Story 11: As a developer, I want to change the orientation of the tick marks, so that I can display them on top, bottom or both (mirrored).
- Story 12: As a developer, I want to have to different types of tick marks - primary and secondary, so that I can display them with different height. By default, the primary ticks are 16px, and the secondary ticks are 8px.
- Story 13: As a developer, I want to manipulate tick labels, so that I can decide whether primary and secondary tick labels are displayed or not.
- Story 14: As a developer, I want to change tick label orientation, so that I can display the labels horizontally, top-to-bottom or bottom-to-top oriented.
- Story 15: As a developer, I want to be able to modify the style of the slider elements, so that I can change their appearance to correspond to the application design.
- Story 16: As a developer, I want to provide an array of primitive values that the slider can spread and visualize as thumb/tick labels, so that I can display them on the track.
End-user stories:
- Story 1: As an end-user, I want to see the available range, so that I can easily choose the value I want to select.
- Story 2: As an end-user, I want to have a label that will display the current value above the thumb, so that I can track when it is updated.
- Story 3: As an end-user, I want to focus the slider, so that I can change its values through the keyboard.
- Story 4: As an end-user, I want to have snapping to closest predetermined values for my selection while moving the thumb when using the discrete slider, so that I can easily change values based on the step.
- Story 5: As an end-user, I want to have a discrete slider with predetermined values displayed as tick marks, so that I can easily see them.
- Story 6: As an end-user, I want to move the thumb, so that I can change the selected value.
- Story 7: As an end-user, I want to click on the track or very close to it, so that I can change the current value.
- Story 8: As an end-user, I want to have the track within the two thumbs to be highlighted, so that I can see the selected range.
- Story 9: As an end-user, I want to have boundaries, so that I can move the thumbs only within a given minimum and maximum values which can be different from the min and max values of the slider.
- Story 10: As an end-user, I want to see the primary and secondary ticks and their labels, so that I can scale the slider track.
- Story 11: As an end-user, I want to see a clear difference between primary and secondary ticks, so that I can easily determine the most important values.
- Story 12: As an end-user, I want to change the tick position, so that I can display them on top/bottom/both.
- Story 13: As an end-user, I want to change the tick label orientation, so that I can see them horizontally, toptobottom or bottomtotop orientated.
3. Functionality
3.1. End-User Experience
Slider should support one or two thumbs i.e. 20x20 ovals on material theme and come in discrete/continuous modes with enabled/disabled state. You can also see for the material theme below that the track is 6px wide while the base is 4px wide and both are rounded at their ends.
Slider types
Tick types and orientation
Dark version
- continuous
- discrete
Light version
- continuous
- discrete
3.2. Developer Experience
<igc-slider
step="5"
lower-bound="20"
upper-bound="80"
primary-ticks="5"
secondary-ticks="20"
hide-secondary-labels
</igc-slider>
3.3. Globalization/Localization
Describe any special localization requirements such as the number of localizable strings, regional formats
3.4. Keyboard Navigation
| Keys | Description |
|---|---|
| Right Arrow | Increases slider value one step. |
| Up Arrow | Increases slider value one step. |
| Left Arrow | Decreases slider value one step. |
| Down Arrow | Decreases slider value one step. |
| Page Up | Increases temperature slider value multiple steps (1/10th of its range). |
| Page Down | Decreases temperature slider value multiple steps (1/10th of its range). |
| Home | Sets slider to its minimum value. |
| End | Sets slider to its maximum value. |
3.5. API
Interfaces
IRangeSliderValue
| Name | Description | Type |
|---|---|---|
lower |
The lower value of the range slider or the lower index of the labels collection. | number |
upper |
The upper value of the range slider or the upper index of the labels collection. | number |
IgcSliderBaseComponent
Properties
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
min |
The minimum value of the slider. | number |
0 |
false |
max |
The maximum value of the slider. | number |
100 |
false |
lowerBound |
The lower boundary of the slider value. If not set is the same as min value. | number |
undefined |
false |
upperBound |
The upper boundary of the slider value. If not set is the same as max value. | number |
undefined |
false |
disabled |
Disables or enables UI interaction. | boolean |
false |
true |
discreteTrack |
Marks the slider track as discrete so it displays the steps. | boolean |
false |
false |
hideTooltip |
Hides thumb tooltip. | boolean |
false |
false |
step |
Specifies the granularity that the value must adhere to. If set to 0 no stepping is implied and any value in the range is allowed. | number |
1 |
false |
labelFormatter |
Specifies a custom function to format the labels. | (value: number) => string |
undefined |
false |
primaryTicks |
Sets the number of primary ticks. If the property is set to 1 or 2, primary ticks are displayed at the beginning and at the end of the track. |
number |
0 |
false |
secondaryTicks |
Sets the number of secondary ticks. It should be greater than one for the ticks to be displayed. | number |
0 |
false |
hidePrimaryLabels |
Hides primary tick labels. | boolean |
false |
false |
hideSecondaryLabels |
Hides secondary tick labels. | boolean |
false |
false |
tickOrientation |
Changes the orientation of the ticks. | mirror | start | end |
end |
false |
?tickLabelRotation |
Sets the degrees for the rotation of the tick labels. | 0 | 90 | -90 | ?45 |
0 |
true |
IgcSliderComponent
Properties
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
value |
The current slider value. | number |
0 |
false |
ariaLabel |
The aria label of the thumb. | string |
undefined |
false |
Events
| Name | Description | Cancelable | Parameters |
|---|---|---|---|
igcChange |
Emitted when a value change is committed. | false |
number |
igcInput |
Emitted when the value is changed. | false |
number |
Methods
| Name | Description | Arguments |
|---|---|---|
stepUp |
Increment the value with one step. | |
stepDown |
Decrement the value with one step. |
IgcRangeSliderComponent
Properties
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
lower |
The current value of the lower thumb. | number |
0 |
false |
upper |
The current value of the upper thumb. | number |
0 |
false |
thumbLabelUpper |
The aria label of the lower thumb. | string |
undefined |
false |
thumbLabelLower |
The aria label of the upper thumb. | string |
undefined |
false |
Events
| Name | Description | Cancelable | Parameters |
|---|---|---|---|
igcChange |
Emitted when a value change is committed. | false |
IgcRangeSliderValue |
igcInput |
Emitted when the value is changed. | false |
IgcRangeSliderValue |
CSS Parts
| Name | Description |
|---|---|
| base | The base wrapper of the slider. |
| track | The track of the slider. |
| fill | Part of the track which is highlighted based on the slider value. |
| step | The visual representation of the step that is used to increment/decrement the value. |
| tick | The divider of the slider track. |
| tick-label | The label for the tick. |
| thumb | The thumb that can be moved to change the value of the slider. |
| thumb-label | The label displayed above the thumb. |
4. Test Scenarios
Slider
- Value should be restricted by min, max, lowerBound, upperBound and step properties.
- Value should be changed when clicking on the slider.
- Value should be changed when dragging the thumb.
- Track fill should be displayed between the start and current values.
- igcInput event should be emitted while dragging the thumb.
- igcChange event should be emitted when dragging the thumb stops.
- Thumb should have correct aria attributes set.
- stepUp/stepDown method should increase/decrease the value with 1 step.
Range
- Lower value should be restricted by min, max, lowerBound, upperBound, step properties.
- Upper value should be restricted by min, max, lowerBound, upperBound, step properties.
- Closest thumb value should be changed when clicking on the slider.
- Lower or upper value should be changed when dragging the thumb.
- When the lower thumb is dragged beyond the upper thumb, the upper thumb should be focused and its dragging should continue.
- Track fill should be displayed between the lower and upper values.
- igcInput event should be emitted while dragging any of the thumbs.
- igcChange event should be emitted when dragging the any of the thumbs stops.
- Thumbs should have correct aria attributes set.
Common
- Min value should be restricted by the max value.
- Max value should be restricted by the min value.
- Lower bound should be restricted by the min, max and upper bound values.
- Upper bound should be restricted by the min, max and lower bound values.
- Any value on the track should be accepted when step is set to 0.
- Primary tick marks should be displayed when primaryTickMarks is greater than 0.
- Secondary tick marks should be displayed when secondaryTickMarks is greater than 0.
- Track and track fill should be continuos lines by default.
- Track and track fill should have dashes and gaps based on the step when discreteTrack is set to true.
- Primary tick mark labels should appear when there are primary tick marks.
- Secondary tick mark labels should appear when there are secondary tick marks.
- Primary tick mark labels should be hidden when hidePrimaryLabels is set to true.
- Secondary tick mark labels should be hidden when hideSecondaryLabels is set to true.
- Tick marks and their labels should be displayed correctly when tickOrientation is start, end or mirror.
- Tick mark labels should be displayed correctly when tickLabelRotation is 0, 90 or -90.
- UI interactions should not be possible when the slider is disabled.
- Tick mark labels and thumb tooltip should be formatted by the labelFormatter function.
- Thumb tooltip should be displayed on hovering the thumb.
- Thumb tooltip should not be displayed when hideTooltip is set to true.
- Thumb value should be increased or decreased with 1 step when pressing right/top or down/left arrow keys.
- Thumb value should be increased/decreased with 1/10th of the slider range when pressing page up/down keys.
- Thumb value should be set to minimum when pressing home key.
- Thumb value should be set to maximum when pressing end key.
5. Accessibility
ARIA Support
- slider thumbs have
role="slider"; aria-valuemin- the minimum allowed value;aria-valuemax- the maximum allowed value;aria-valuenow- the current value;aria-valuetext- the formatted label of the current value;aria-disabled- indicates if the slider is disabled;aria-label- the label of the slider;
RTL Support
6. Assumptions and Limitations
| Assumptions | Limitation Notes |
|---|---|
7. References
Specify all referenced external sources