Slider
<wa-slider>
Ranges allow the user to select a single value within a given range using a slider.
<wa-slider label="Number of cats" hint="Limit six per household" name="value" value="3" min="0" max="6" with-markers with-tooltip > <span slot="reference">Less</span> <span slot="reference">More</span> </wa-slider>
This component works with standard <form>
elements. Please refer to the section on form controls to learn more about form submission and client-side validation.
Examples Jump to heading
Labels Jump to heading
Use the label
attribute to give the slider an accessible label. For labels that contain HTML, use the label
slot instead.
<wa-slider label="Volume" min="0" max="100"></wa-slider>
Hint Jump to heading
Add descriptive hint to a slider with the hint
attribute. For hints that contain HTML, use the hint
slot instead.
<wa-slider label="Volume" hint="Controls the volume of the current song." min="0" max="100"></wa-slider>
Showing tooltips Jump to heading
Use the with-tooltip
attribute to display a tooltip with the current value when the slider is focused or being dragged.
<wa-slider label="Quality" name="quality" min="0" max="100" value="50" with-tooltip></wa-slider>
Setting min, max, and step Jump to heading
Use the min
and max
attributes to define the slider's range, and the step
attribute to control the increment between values.
<wa-slider label="Between zero and one" min="0" max="1" step="0.1" value="0.5" with-tooltip></wa-slider>
Showing markers Jump to heading
Use the with-markers
attribute to display visual indicators at each step increment. This works best with sliders that have a smaller range of values.
<wa-slider label="Size" name="size" min="0" max="8" value="4" with-markers></wa-slider>
Adding references Jump to heading
Use the reference
slot to add contextual labels below the slider. References are automatically spaced using space-between
, making them easy to align with the start, center, and end positions.
<wa-slider label="Speed" name="speed" min="1" max="5" value="3" with-markers> <span slot="reference">Slow</span> <span slot="reference">Medium</span> <span slot="reference">Fast</span> </wa-slider>
If you want to show a reference next to a specific marker, you can add position: absolute
to it and set the left
, right
, top
, or bottom
property to a percentage that corresponds to the marker's position.
Formatting the value Jump to heading
Customize how values are displayed in tooltips and announced to screen readers using the valueFormatter
property. Set it to a function that accepts a number and returns a formatted string. The Intl.NumberFormat API
is particularly useful for this.
<!-- Percent --> <wa-slider id="slider__percent" label="Percentage" name="percentage" value="0.5" min="0" max="1" step=".01" with-tooltip ></wa-slider ><br /> <script> const slider = document.getElementById('slider__percent'); const formatter = new Intl.NumberFormat('en-US', { style: 'percent' }); customElements.whenDefined('wa-slider').then(() => { slider.valueFormatter = value => formatter.format(value); }); </script> <!-- Duration --> <wa-slider id="slider__duration" label="Duration" name="duration" value="12" min="0" max="24" with-tooltip></wa-slider ><br /> <script> const slider = document.getElementById('slider__duration'); const formatter = new Intl.NumberFormat('en-US', { style: 'unit', unit: 'hour', unitDisplay: 'long' }); customElements.whenDefined('wa-slider').then(() => { slider.valueFormatter = value => formatter.format(value); }); </script> <!-- Currency --> <wa-slider id="slider__currency" label="Currency" name="currency" min="0" max="100" value="50" with-tooltip></wa-slider> <script> const slider = document.getElementById('slider__currency'); const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', currencyDisplay: 'symbol', maximumFractionDigits: 0, }); customElements.whenDefined('wa-slider').then(() => { slider.valueFormatter = value => formatter.format(value); }); </script>
Range selection Jump to heading
Use the range
attribute to enable dual-thumb selection for choosing a range of values. Set the initial thumb positions with the min-value
and max-value
attributes.
<wa-slider label="Price Range" hint="Select minimum and maximum price" name="price" range min="0" max="100" min-value="20" max-value="80" with-tooltip id="slider__range" > <span slot="reference">$0</span> <span slot="reference">$50</span> <span slot="reference">$100</span> </wa-slider> <script> const slider = document.getElementById('slider__range'); const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }); customElements.whenDefined('wa-slider').then(() => { slider.valueFormatter = value => formatter.format(value); }); </script>
For range sliders, the minValue
and maxValue
properties represent the current positions of the thumbs. When the form is submitted, both values will be included as separate entries with the same name.
const slider = document.querySelector('wa-slider[range]'); // Get the current values console.log(`Min value: ${slider.minValue}, Max value: ${slider.maxValue}`); // Set the values programmatically slider.minValue = 30; slider.maxValue = 70;
Vertical Sliders Jump to heading
Set the orientation
attribute to vertical
to create a vertical slider. Vertical sliders automatically center themselves and fill the available vertical space.
<div style="display: flex; gap: 1rem;"> <wa-slider orientation="vertical" label="Volume" name="volume" value="65" style="width: 80px"></wa-slider> <wa-slider orientation="vertical" label="Bass" name="bass" value="50" style="width: 80px"></wa-slider> <wa-slider orientation="vertical" label="Treble" name="treble" value="40" style="width: 80px"></wa-slider> </div>
Range sliders can also be vertical.
<div style="height: 300px; display: flex; align-items: center; gap: 2rem;"> <wa-slider label="Temperature Range" orientation="vertical" range min="0" max="100" min-value="30" max-value="70" with-tooltip tooltip-placement="right" id="slider__vertical-range" > </wa-slider> </div> <script> const slider = document.getElementById('slider__vertical-range'); slider.valueFormatter = value => { return new Intl.NumberFormat('en', { style: 'unit', unit: 'fahrenheit', unitDisplay: 'short', minimumFractionDigits: 0, maximumFractionDigits: 1, }).format(value); }; </script>
Size Jump to heading
Control the slider's size using the size
attribute. Valid options include small
, medium
, and large
.
<wa-slider size="small" value="50" label="Small"></wa-slider><br /> <wa-slider size="medium" value="50" label="Medium"></wa-slider><br /> <wa-slider size="large" value="50" label="Large"></wa-slider>
Indicator Offset Jump to heading
By default, the filled indicator extends from the minimum value to the current position. Use the indicator-offset
attribute to change the starting point of this visual indicator.
<wa-slider label="Cat playfulness" hint="Energy level during playtime" name="value" value="0" min="-5" max="5" indicator-offset="0" with-markers with-tooltip > <span slot="reference">Lazy</span> <span slot="reference">Zoomies</span> </wa-slider>
Disabled Jump to heading
Use the disabled
attribute to disable a slider.
<wa-slider label="Disabled" value="50" disabled></wa-slider>
Required Jump to heading
Mark a slider as required using the required
attribute. Users must interact with required sliders before the form can be submitted.
<form action="about:blank" target="_blank" method="get"> <wa-slider name="slide" label="Required slider" min="0" max="10" required></wa-slider> <br /> <button type="submit">Submit</button> </form>
Slots Jump to heading
Learn more about using slots.
Name | Description |
---|---|
label
|
The slider label. Alternatively, you can use the label attribute. |
hint
|
Text that describes how to use the input. Alternatively, you can use the hint attribute. instead. |
reference
|
One or more reference labels to show visually below the slider. |
Attributes & Properties Jump to heading
Learn more about attributes and properties.
Name | Description | Reflects | |
---|---|---|---|
validationTarget |
Override validation target to point to the focusable element
|
||
label label |
The slider's label. If you need to provide HTML in the label, use the
label slot instead.Type
string Default
'' |
||
hint hint |
The slider hint. If you need to display HTML, use the hint slot instead.
Type
string Default
'' |
||
name name |
The name of the slider. This will be submitted with the form as a name/value pair.
Type
string |
|
|
minValue min-value |
The minimum value of a range selection. Used only when range attribute is set.
Type
number Default
0 |
||
maxValue max-value |
The maximum value of a range selection. Used only when range attribute is set.
Type
number Default
50 |
||
defaultValue value |
The default value of the form control. Primarily used for resetting the form control.
Type
number |
|
|
value |
The current value of the slider, submitted as a name/value pair with form data.
Type
number |
||
range range |
Converts the slider to a range slider with two thumbs.
Type
boolean Default
false |
|
|
isRange |
Get if this is a range slider
Type
boolean |
||
disabled disabled |
Disables the slider.
Type
boolean Default
false |
||
readonly readonly |
Makes the slider a read-only field.
Type
boolean Default
false |
|
|
orientation orientation |
The orientation of the slider.
Type
'horizontal' | 'vertical' Default
'horizontal' |
|
|
size size |
The slider's size.
Type
'small' | 'medium' | 'large' Default
'medium' |
|
|
indicatorOffset indicator-offset |
The starting value from which to draw the slider's fill, which is based on its current value.
Type
number |
||
form form |
The form to associate this control with. If omitted, the closest containing
<form> will be used. The value of
this attribute must be an ID of a form in the same document or shadow root.Type
null Default
null |
|
|
min min |
The minimum value allowed.
Type
number Default
0 |
||
max max |
The maximum value allowed.
Type
number Default
100 |
||
step step |
The granularity the value must adhere to when incrementing and decrementing.
Type
number Default
1 |
||
required required |
Makes the slider a required field.
Type
boolean Default
false |
|
|
autofocus autofocus |
Tells the browser to focus the slider when the page loads or a dialog is shown.
Type
boolean |
||
tooltipDistance tooltip-distance |
The distance of the tooltip from the slider's thumb.
Type
number Default
8 |
||
tooltipPlacement tooltip-placement |
The placement of the tooltip in reference to the slider's thumb.
Type
'top' | 'right' | 'bottom' | 'left' Default
'top' |
|
|
withMarkers with-markers |
Draws markers at each step along the slider.
Type
boolean Default
false |
||
withTooltip with-tooltip |
Draws a tooltip above the thumb when the control has focus or is dragged.
Type
boolean Default
false |
||
valueFormatter |
A custom formatting function to apply to the value. This will be shown in the tooltip and announced by screen
readers. Must be set with JavaScript. Property only.
Type
(value: number) => string |
Methods Jump to heading
Learn more about methods.
Name | Description | Arguments |
---|---|---|
focus() |
Sets focus to the slider. | |
blur() |
Removes focus from the slider. | |
stepDown() |
Decreases the slider's value by step . This is a programmatic change, so input and change events will not be
emitted when this is called. |
|
stepUp() |
Increases the slider's value by step . This is a programmatic change, so input and change events will not be
emitted when this is called. |
Events Jump to heading
Learn more about events.
Name | Description |
---|---|
change |
Emitted when an alteration to the control's value is committed by the user. |
blur |
Emitted when the control loses focus. |
focus |
Emitted when the control gains focus. |
input |
Emitted when the control receives input. |
wa-invalid |
Emitted when the form control has been checked for validity and its constraints aren't satisfied. |
CSS custom properties Jump to heading
Learn more about CSS custom properties.
Name | Description |
---|---|
--track-size |
The height or width of the slider's track.
Default
0.75em
|
--marker-width |
The width of each individual marker.
Default
0.1875em
|
--marker-height |
The height of each individual marker.
Default
0.1875em
|
--thumb-width |
The width of the thumb.
Default
1.25em
|
--thumb-height |
The height of the thumb.
Default
1.25em
|
Custom States Jump to heading
Learn more about custom states.
Name | Description | CSS selector |
---|---|---|
disabled |
Applied when the slider is disabled. | :state(disabled) |
dragging |
Applied when the slider is being dragged. | :state(dragging) |
focused |
Applied when the slider has focus. | :state(focused) |
user-valid |
Applied when the slider is valid and the user has sufficiently interacted with it. | :state(user-valid) |
user-invalid |
Applied when the slider is invalid and the user has sufficiently interacted with it. | :state(user-invalid) |
CSS parts Jump to heading
Learn more about CSS parts.
Name | Description |
---|---|
label |
The element that contains the sliders's label. |
hint |
The element that contains the slider's description. |
slider |
The focusable element with role="slider" . Contains the track and reference slot. |
track |
The slider's track. |
indicator |
The colored indicator that shows from the start of the slider to the current value. |
markers |
The container that holds all the markers when with-markers is used. |
marker |
The individual markers that are shown when with-markers is used. |
references |
The container that holds references that get slotted in. |
thumb |
The slider's thumb. |
thumb-min |
The min value thumb in a range slider. |
thumb-max |
The max value thumb in a range slider. |
tooltip |
The tooltip, a <wa-tooltip> element. |
tooltip__tooltip |
The tooltip's tooltip part. |
tooltip__content |
The tooltip's content part. |
tooltip__arrow |
The tooltip's arrow part. |
Dependencies Jump to heading
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.
Importing Jump to heading
The autoloader is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.
To manually import this component from the CDN, use the following code.
import 'https://early.webawesome.com/[email protected]/dist/components/slider/slider.js';
To manually import this component from NPM, use the following code.
import '@awesome.me/webawesome/dist/components/slider/slider.js';
To manually import this component from React, use the following code.
import '@awesome.me/webawesome/dist/react/slider';