sp-slider
Attributes and Properties #
disabled
disabled
boolean
false
dragging
dragging
boolean
false
editable
editable
boolean
formatOptions
format-options
NumberFormatOptions | undefined
hideStepper
hide-stepper
boolean
false
highlight
highlight
boolean
false
indeterminate
indeterminate
boolean
false
label
label
string
''
labelVisibility
label-visibility
'text' | 'value' | 'none' | undefined
max
max
number | 'next' | undefined
100
min
min
number | 'previous' | undefined
0
name
name
string
''
quiet
quiet
boolean
false
step
step
number | undefined
1
tickLabels
tick-labels
boolean
false
tickStep
tick-step
number
0
type
type
string
''
value
value
number
variant
variant
string
Slots #
default slot
handle
Events #
change
Event
An alteration to the value of the element has been committed by the user.
input
Event
The value of the element has changed.
sp-slider-handle-ready
CustomEvent
Description #
<sp-slider>
allows users to quickly select a value within a range. They should be used when the upper and lower bounds of the range are invariable.
Usage #
yarn add @spectrum-web-components/slider
Import the side effectful registration of <sp-slider>
via:
import '@spectrum-web-components/slider/sp-slider.js';
When leveraging the editable
attribute, the @spectrum-web-components/number-field/sp-number-field.js
dependency will be asynchronously loaded via a dynamic import to reduce JS payload for applications not leveraging this feature. In the case that you would like to import those transverse dependencies statically, import the side effectful registration of <sp-slider>
as follows:
import '@spectrum-web-components/slider/sync/sp-slider.js';
When looking to leverage the Slider
base class as a type and/or for extension purposes, do so via:
import { Slider } from '@spectrum-web-components/slider';
Variants #
Standard #
<sp-slider label="Slider Label"></sp-slider>
<sp-slider label="Slider Label - Disabled" disabled></sp-slider>
Filled #
<sp-slider label="Slider Label" variant="filled"></sp-slider>
<sp-slider
label="Slider Label - Disabled"
variant="filled"
disabled
></sp-slider>
Tick #
<sp-slider label="Slider Label" variant="tick" tick-step="5"></sp-slider>
<sp-slider
label="Slider Label - Disabled"
variant="tick"
tick-step="5"
disabled
></sp-slider>
Tick with Labels #
<sp-slider
label="Slider Label"
variant="tick"
tick-step="5"
tick-labels
></sp-slider>
<sp-slider
label="Slider Label - Disabled"
variant="tick"
tick-step="5"
tick-labels
disabled
></sp-slider>
Ramp #
<sp-slider label="Slider Label" variant="ramp"></sp-slider>
<sp-slider label="Slider Label - Disabled" variant="ramp" disabled></sp-slider>
Editable #
An <sp-slider>
element can be paired with an <sp-number-field>
element via the editable
attribute. The <sp-number-field>
will be passed all of the standard options from the <sp-slider>
element (e.g. min
, max
, formatOptions
, etc.) and will also accept the hide-stepper
attribute in order to prevent the display of its stepper UI.
<sp-slider
label="Angle (editable)"
editable
hide-stepper
min="0"
max="360"
format-options='{
"style": "unit",
"unit": "degree",
"unitDisplay": "narrow"
}'
></sp-slider>
<sp-slider
label="Hours of the day (editable)"
editable
max="24"
min="0"
value="7.25"
step="0.25"
style="--spectrum-slider-editable-number-field-width: 100px;"
format-options='{
"style": "unit",
"unit": "hour"
}'
></sp-slider>
Quiet #
<sp-slider quiet editable value="50"></sp-slider>
<sp-slider quiet disabled editable value="50"></sp-slider>
Indeterminate #
The indeterminate attribute will be passed to the internal <sp-number-field>
element and alter its visual delivery until a change has been made to the <sp-slider>
element at which point the change
event that is dispatched can be understood as always removing the indeterminate attribute from the <sp-slider>
.
<sp-slider indeterminate editable value="50"></sp-slider>
<sp-slider indeterminate disabled editable value="50"></sp-slider>
Advanced normalization #
By default, sp-slider
assumes a linear scale between the min
and max
values. For advanced applications, it is sometimes necessary to specify a custom "normalization."
Normalization is the process of converting a slider to a value between 0 and 1 where 0 represents the minimum and 1 represents the maximum. See the
Labels and Formatting #
An <sp-slider>
or <sp-slider-handle>
element will process its numeric value with new Intl.NumberFormat(this.resolvedLanguage, this.formatOptions).format(this.value)
in order to prepare it for visual delivery in the input. In order to customize this processing supply your own Intl.NumberFormatOptions
via the formatOptions
property, or format-options
attribute as seen below.
this.resolvedLanguage
represents the language in which the <sp-slider>
or <sp-slider-handle>
element is currently being delivered. By default, this value will represent the language established by the lang
attribute on the root <html>
element while falling back to navigator.language
when that is not present. This value can be customized via a language context provided by a parent element that listens for the sp-language-context
event and supplies updated language settings to the callback
function contained therein. Applications leveraging the <sp-theme>
<sp-slider
min="0"
max="1"
step="0.01"
value="0.5"
label="Slider Label"
format-options='{
"style": "percent"
}'
></sp-slider>
More advanced formatting is available by specifying a formatting function to the getAriaHandleText
property on an sp-slider
or sp-slider-handle
. Or, for a multi-handle slider, you can format the combined value label for all handles by passing a formatting function to the getAriaValueText
property on the parent sp-slider
.
Units not included in Intl.NumberFormatOptions
#
While Intl.NumberFormatOptions
does support a pixel
, pixels
, points
, etc.) that are not supported therein. When this occurs, an <sp-slider>
element will attempt to polyfill support for this unit. See the following example delivering { style: "unit", unit: "px" }
below:
<sp-slider
style="width: 200px"
value="500"
format-options='{
"style": "unit",
"unit": "px"
}'
>
Document width in pixels
</sp-slider>
Note: the polyfilling done here is very simplistic and is triggered by supplying options that would otherwise cause the Intl.NumberFormat()
call to throw an error. Once the unsupporting unit of px
causes the construction of the object to throw, a backup formatter/parser pair will be created without the supplied unit data. When the style
is set to unit
, the unit
value will be adopted as the static unit display. This means that neither pluralization nor translation will be handled within the <sp-number-field>
element itself. If pluralization or translation is important to the delivered interface, please be sure to handle passing those strings into to element via the formatOptions
property reactively to the value of the element or locale of that page in question.
Label Visibility #
By default, an <sp-slider>
element has both a "text" label and a "value" label. The "value" label is output by the element itself based on its state, but the "text" label must be supplied by the consuming developer in order for the <sp-slider>
to be delivered in an accessible manner.
Either or both of these can be suppressed visually as needed by your application UI, while still fulfilling their role in delivering a quality accessibility tree to the browser. This delivery is controlled by the label-visibility
attribute (or labelVisibility
property) which accepts text
, value
, or none
as values.
Use label-visibility="text"
to suppress the "value" label:
<sp-slider
label="No visible value label"
label-visibility="text"
value="50"
></sp-slider>
Use label-visibility="value"
to suppress the "text" label:
<sp-slider label="No visible text label" label-visibility="value"></sp-slider>
Use label-visibility="none"
to suppress the "text" label:
<sp-slider label="No visible labels" label-visibility="none"></sp-slider>
In each case outlined above the content for both labels will be made available to screen readers, so be sure to manage the content delivered to visitors in that context.
Events #
Like the <input type="range">
element after which the <sp-slider>
is fashioned, it will dispatch input
events in a stream culminating with a change
event (representing the final commit of the value
to the element) once the user has finished interacting with the element. Both other these events can access the value
of their dispatching target via event.target.value
. In this way, a steaming listener pattern similar to the following can prove useful:
const slider = document.querySelector('sp-slider');
const endListener = ({ target }) => {
target.addEventListener('input', startListener);
target.removeEventListener('input', streamListener);
target.removeEventListener('change', endListener);
console.log(target.value);
};
const streamListener = ({ target }) => {
console.log(target.value);
};
const startListener = ({ target }) => {
target.removeEventListener('input', startListener);
target.addEventListener('input', streamListener);
target.addEventListener('change', endListener);
console.log(target.value);
};
slider.addEventListener('input', startListener);