Range
sl-range
Ranges allow the user to select a single value within a given range using a slider.
Examples
Basic Range
<sl-range></sl-range>
sl-range
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.
Labels
Use the label
attribute to give the range an accessible label. For labels that contain HTML,
use the label
slot instead.
<sl-range label="Volume" min="0" max="100"></sl-range>
sl-range label="Volume" min="0" max="100"
Help Text
Add descriptive help text to a range with the help-text
attribute. For help texts that contain
HTML, use the help-text
slot instead.
<sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"></sl-range>
sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"
Min, Max, and Step
Use the min
and max
attributes to set the range’s minimum and maximum values,
respectively. The step
attribute determines the value’s interval when increasing and
decreasing.
<sl-range min="0" max="10" step="1"></sl-range>
sl-range min="0" max="10" step="1"
Disabled
Use the disabled
attribute to disable a slider.
<sl-range disabled></sl-range>
sl-range disabled=true
Tooltip Placement
By default, the tooltip is shown on top. Set tooltip
to bottom
to show it below
the slider.
<sl-range tooltip="bottom"></sl-range>
sl-range tooltip="bottom"
Disable the Tooltip
To disable the tooltip, set tooltip
to none
.
<sl-range tooltip="none"></sl-range>
sl-range tooltip="none"
Custom Track Colors
You can customize the active and inactive portions of the track using the
--track-color-active
and --track-color-inactive
custom properties.
<sl-range style=" --track-color-active: var(--sl-color-primary-600); --track-color-inactive: var(--sl-color-primary-100); " ></sl-range>
sl-range[style=" --track-color-active: var(--sl-color-primary-600); --track-color-inactive: var(--sl-color-primary-100); "]
Custom Track Offset
You can customize the initial offset of the active track using the --track-active-offset
custom
property.
<sl-range min="-100" max="100" style=" --track-color-active: var(--sl-color-primary-600); --track-color-inactive: var(--sl-color-primary-100); --track-active-offset: 50%; " ></sl-range>
sl-range[min="-100" max="100" style=" --track-color-active: var(--sl-color-primary-600); --track-color-inactive: var(--sl-color-primary-100); --track-active-offset: 50%; "]
Custom Tooltip Formatter
You can change the tooltip’s content by setting the tooltipFormatter
property to a function
that accepts the range’s value as an argument.
<sl-range min="0" max="100" step="1" class="range-with-custom-formatter"></sl-range> <script> const range = document.querySelector('.range-with-custom-formatter'); range.tooltipFormatter = value => `Total - ${value}%`; </script>
sl-range.range-with-custom-formatter min="0" max="100" step="1" javascript: const range = document.querySelector(.range-with-custom-formatter); range.tooltipFormatter = value => `Total - ${value}%`;
Component Props
Property | Default | Details |
---|---|---|
name
|
''
|
The name of the range, submitted as a name/value pair with form data. |
value
|
0
|
The current value of the range, submitted as a name/value pair with form data. |
label
|
''
|
The range’s label. If you need to display HTML, use the |
helpText
help-text
|
''
|
The range’s help text. If you need to display HTML, use the help-text slot instead. |
disabled
|
false
|
Disables the range. |
min
|
0
|
The minimum acceptable value of the range. |
max
|
100
|
The maximum acceptable value of the range. |
step
|
1
|
The interval at which the range will increase and decrease. |
tooltip
|
'top'
|
The preferred placement of the range’s tooltip. |
tooltipFormatter
|
— |
A function used to format the tooltip’s value. The range’s value is passed as the first and only argument. The function should return a string to display in the tooltip. |
form
|
''
|
By default, form controls are associated with the nearest containing
|
defaultValue
|
0
|
The default value of the form control. Primarily used for resetting the form control. |
validity
|
— |
— Gets the validity state object |
validationMessage
|
— |
— Gets the validation message |
updateComplete
|
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Slots
Name | Details |
---|---|
label
|
The range’s label. Alternatively, you can use the label attribute. |
help-text
|
Text that describes how to use the input. Alternatively, you can use the
help-text attribute.
|
Learn more about using slots.
Events
Name | Name | Name | React Event | Details | |
---|---|---|---|---|---|
sl-blur
|
sl-blur
|
sl-blur
|
onSlBlur
|
Emitted when the control loses focus. |
|
sl-change
|
sl-change
|
sl-change
|
onSlChange
|
Emitted when an alteration to the control’s value is committed by the user. |
|
sl-focus
|
sl-focus
|
sl-focus
|
onSlFocus
|
Emitted when the control gains focus. |
|
sl-input
|
sl-input
|
sl-input
|
onSlInput
|
Emitted when the control receives input. |
|
sl-invalid
|
sl-invalid
|
sl-invalid
|
onSlInvalid
|
Emitted when the form control has been checked for validity and its constraints aren’t satisfied. |
Learn more about events.
Methods
Name | Details |
---|---|
focus()
|
Sets focus on the range. |
blur()
|
Removes focus from the range. |
stepUp()
|
Increments the value of the range by the value of the step attribute. |
stepDown()
|
Decrements the value of the range by the value of the step attribute. |
checkValidity()
|
Checks for validity but does not show a validation message. Returns |
getForm()
|
Gets the associated form, if one exists. |
reportValidity()
|
Checks for validity and shows the browser’s validation message if the control is invalid. |
setCustomValidity()
|
Sets a custom validation message. Pass an empty string to restore validity. |
Learn more about methods.
Custom Properties
Name | Details |
---|---|
--thumb-size
|
The size of the thumb. |
--tooltip-offset
|
The vertical distance the tooltip is offset from the track. |
--track-color-active
|
The color of the portion of the track that represents the current value. |
--track-color-inactive
|
The of the portion of the track that represents the remaining value. |
--track-height
|
The height of the track. |
--track-active-offset
|
The point of origin of the active track. |
Learn more about customizing CSS custom properties.
CSS Parts
Name | Description |
---|---|
form-control
|
The form control that wraps the label, input, and help text. |
form-control-label
|
The label’s wrapper. |
form-control-input
|
The range’s wrapper. |
form-control-help-text
|
The help text’s wrapper. |
base
|
The component’s base wrapper. |
input
|
The internal <input> element. |
tooltip
|
The range’s tooltip. |
Learn more about customizing CSS parts.