Range
<sl-range> | SlRange
Ranges allow the user to select a single value within a given range using a slider.
<sl-range></sl-range>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange />;
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
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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange 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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange 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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange min={0} max={10} step={1} />;
Disabled
Use the disabled attribute to disable a slider.
<sl-range disabled></sl-range>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange disabled />;
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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange tooltip="bottom" />;
Disable the Tooltip
To disable the tooltip, set tooltip to none.
<sl-range tooltip="none"></sl-range>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange 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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => ( <SlRange style={{ '--track-color-active': 'var(--sl-color-primary-600)', '--track-color-inactive': 'var(--sl-color-primary-200)' }} /> );
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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => ( <SlRange min={-100} max={100} style={{ '--track-color-active': 'var(--sl-color-primary-600)', '--track-color-inactive': 'var(--sl-color-primary-200)', '--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>
import SlRange from '@shoelace-style/shoelace/dist/react/range'; const App = () => <SlRange min={0} max={100} step={1} tooltipFormatter={value => `Total - ${value}%`} />;
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.11.0/cdn/components/range/range.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.11.0/cdn/components/range/range.js';
To import this component using a bundler:
import '@shoelace-style/shoelace/dist/components/range/range.js';
To import this component as a React component:
import SlRange from '@shoelace-style/shoelace/dist/react/range';
Slots
| Name | Description |
|---|---|
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.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
name
|
The name of the range, submitted as a name/value pair with form data. |
string
|
''
|
|
value
|
The current value of the range, submitted as a name/value pair with form data. |
number
|
0
|
|
label
|
The range’s label. If you need to display HTML, use the label slot instead. |
string
|
''
|
|
helpText
help-text
|
The range’s help text. If you need to display HTML, use the help-text slot instead. |
string
|
''
|
|
disabled
|
Disables the range. |
|
boolean
|
false
|
min
|
The minimum acceptable value of the range. |
number
|
0
|
|
max
|
The maximum acceptable value of the range. |
number
|
100
|
|
step
|
The interval at which the range will increase and decrease. |
number
|
1
|
|
tooltip
|
The preferred placement of the range’s tooltip. |
'top' | 'bottom' | 'none'
|
'top'
|
|
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. |
(value: number) => string
|
- | |
form
|
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of a
form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
|
string
|
''
|
defaultValue
|
The default value of the form control. Primarily used for resetting the form control. |
number
|
0
|
|
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.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
sl-blur |
onSlBlur |
Emitted when the control loses focus. | - |
sl-change |
onSlChange |
Emitted when an alteration to the control’s value is committed by the user. | - |
sl-focus |
onSlFocus |
Emitted when the control gains focus. | - |
sl-input |
onSlInput |
Emitted when the control receives input. | - |
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 | Description | Arguments |
|---|---|---|
focus() |
Sets focus on the range. |
options: FocusOptions
|
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 true when valid and
false when invalid.
|
- |
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. |
message: string
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--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.
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.