Slider
A slider lets people pick one value by dragging a handle along a track, as with volume or brightness. Change mode sets when your code is told: once when the drag ends, or live for a preview. Drag the handles below to feel how size, orientation, and theme change the control.
Reference docs
Choosing sliders and dials
Four components pick a value with a handle the reader drags. Each suits a different job:
- Slider: one value picked along a track, such as volume or brightness.
- Range slider: a low and a high value on one track, such as a price range.
- Dial: one value picked by turning a knob between two stops, such as an oven temperature.
- Continuous dial: a knob with no stops that adds up every turn, such as a jog wheel or a fine-tuning control.
One job belongs elsewhere. An exact number the reader knows is a number field.
Choosing a fill
Two fills suit different ranges, and centered
- Standard fill: a value that starts from zero or the beginning of a sequence, such as volume or brightness.
- Centered fill: a value whose zero or default sits in the middle of the range, such as stereo balance or exposure compensation.
Built in
sets whenchange-modechangefires: after the drag ends by default, on every move, after a pause, at a steady rate, or as often as your server keeps up (Change mode). can mark every stop on the grid thattickmarks sets.step- The arrow keys move by one
, and PageUp and PageDown move bystep .page-value reveals the current number as soon as the handle is pressed or focused.labeled- Its touch target is at least 48 by 48 pixels, even when it looks smaller.
- It takes part in forms and submits its value under
.name
Using sliders well
- Choose a range slider when the reader sets a minimum and a maximum together.
- Choose a dial when the value is picked by turning a knob between two stops.
- Show a formatted value, such as currency or units, through a value label.
- Pair
set totickmarksvalueswith a that lands on each stop.step
These rules follow Material 3 Expressive's guidance for sliders, on material.io.
Size
sizeextra-small to extra-large; omit it and the slider takes its size from your style configuration, which is extra-small unless you have changed it. A larger slider has a thicker track and a larger handle.
touch-targetoverflow, keeps the slider's visual size and lets the touch area spill past it; the style configuration supplies it and ships as overflow.
Range and step
stepminmaxvaluepage-valuestep
Value label
labeledvalue-label
Centered
centeredcenter-valueminmaxcenter-value
Orientation
orientationhorizontal by default. A vertical slider stands upright and needs at least 200 pixels of height.
Tickmarks
tickmarkscontrast-end-stop by default. Set it to values for one mark per stepnone for a plain track. A slider whose track-background slot is filled ignores tickmarks
Change mode
change-modechange event. The default, interaction-ended, fires once when the drag ends, because the positions along the way are not the reader's answer. immediate fires on every move, and debounced and throttled follow rate-limit-delay
adaptive fires no more often than once per rate-limit-delayasyncSinksink-duty-cycleasyncSinkadaptive paces as throttled does. Event pacing explains the measurement. Drag each slider below and compare the readouts.
Forms
A slider is form-associated. Give it namevalue
Disabled
disabled<fieldset> is disabled too.
Properties
| Property | Attribute | Type | Description |
|---|---|---|---|
ariaDescribedBy | aria-describedby | string | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
ariaDescription | aria-description | string | Not announced by assistive technology. ariaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
ariaErrorMessage | aria-errormessage | string | The ID of the element describing the value's error. Used only while ariaInvalid is "true". |
ariaInvalid | aria-invalid | string | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
ariaLabelledBy | aria-labelledby | string | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
asyncSink | ValueChangeSink | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than rateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. | |
centered | centered | booleandefault false | Fills from the middle of the track instead of from its start: from centerValue, or from the midpoint of min and max when centerValue is not set. See Centered. |
centerValue | center-value | number | The value the fill grows from, between min and max. Ignored unless centered is set.An assignment that is not a finite number is ignored, and centerValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
changeMode | change-modedebounced, immediate, interaction-ended, throttled, adaptive | ChangeEventModeChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by rateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against asyncSink. See Change mode. |
disabled | disabled | boolean | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
formread-only | HTMLFormElement | The form the component belongs to, or null when it has none. | |
labeled | labeled | booleandefault false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
labelsread-only | NodeList | The <label> elements associated with the element. | |
max | max | numberdefault 100 | The highest value the control can take. If min is not below it, min becomes max less 1.An assignment that is not a finite number is ignored, and max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
min | min | numberdefault 0 | The lowest value the control can take. A minimum that is not below max is replaced by max less 1.An assignment that is not a finite number is ignored, and min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
name | name | string | The name the element's value is submitted under with its form. See Forms. |
orientation | orientationhorizontal, vertical | SliderOrientationSliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
pageValue | page-value | number | How far PageUp and PageDown move the value. Defaults to ten times step.An assignment that is not a finite number is ignored, and pageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
rateLimitDelay | rate-limit-delay | numberdefault 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and rateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
sinkDutyCycle | sink-duty-cycle | numberdefault 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
size | sizeextra-small, small, medium, large, extra-large | SizeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
softDisabled | soft-disabled | booleandefault false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
step | step | numberdefault 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
tickmarks | tickmarksnone, contrast-end-stop, values | SliderTickmarkSliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the track-background slot is filled. See Tickmarks. |
touchTarget | touch-targetnone, overflow, wrapper | TouchTargetTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
value | value | number | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
valueLabel | value-label | string | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Slots
| Slot | Description |
|---|---|
track-background | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Events
| Event | Type | Detail | Description |
|---|---|---|---|
input | InputEvent | — | Fires during value changes as the user drags. It bubbles and is composed. |
change | Event | — | Fires when the value is committed (timing controlled by changeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Props
| Prop | Type | Description |
|---|---|---|
ariaDescribedBy | string | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
ariaDescription | string | Not announced by assistive technology. ariaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
ariaErrorMessage | string | The ID of the element describing the value's error. Used only while ariaInvalid is "true". |
ariaInvalid | string | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
ariaLabelledBy | string | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
asyncSink | ValueChangeSink | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than rateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. |
centered | booleandefault false | Fills from the middle of the track instead of from its start: from centerValue, or from the midpoint of min and max when centerValue is not set. See Centered. |
centerValue | number | The value the fill grows from, between min and max. Ignored unless centered is set.An assignment that is not a finite number is ignored, and centerValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
changeMode | ChangeEventModeTypeChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by rateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against asyncSink. See Change mode. |
disabled | boolean | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
formread-only (ref) | HTMLFormElement | The form the component belongs to, or null when it has none. |
labeled | booleandefault false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
labelsread-only (ref) | NodeList | The <label> elements associated with the element. |
max | numberdefault 100 | The highest value the control can take. If min is not below it, min becomes max less 1.An assignment that is not a finite number is ignored, and max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
min | numberdefault 0 | The lowest value the control can take. A minimum that is not below max is replaced by max less 1.An assignment that is not a finite number is ignored, and min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
name | string | The name the element's value is submitted under with its form. See Forms. |
orientation | SliderOrientationTypeSliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
pageValue | number | How far PageUp and PageDown move the value. Defaults to ten times step.An assignment that is not a finite number is ignored, and pageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
rateLimitDelay | numberdefault 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and rateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
sinkDutyCycle | numberdefault 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
size | SizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
softDisabled | booleandefault false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
step | numberdefault 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
tickmarks | SliderTickmarkTypeSliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the slot="track-background" child is filled. See Tickmarks. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
value | number | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
valueLabel | string | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Children
| Child | Description |
|---|---|
a child with slot="track-background" | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Events
| Prop | Argument | Description |
|---|---|---|
onInput | React.ChangeEvent<HTMLInputElement> | Fires during value changes as the user drags. It bubbles and is composed. |
onChange | React.ChangeEvent<HTMLInputElement> | Fires when the value is committed (timing controlled by changeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Parameters
| Parameter | Type | Description |
|---|---|---|
AriaDescribedBy | string? | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
AriaDescription | string? | Not announced by assistive technology. AriaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
AriaErrorMessage | string? | The ID of the element describing the value's error. Used only while AriaInvalid is "true". |
AriaInvalid | string? | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
AriaLabelledBy | string? | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
AsyncSink | ValueChangeSink? | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than RateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. |
Centered | bool?default false | Fills from the middle of the track instead of from its start: from CenterValue, or from the midpoint of Min and Max when CenterValue is not set. See Centered. |
CenterValue | double? | The value the fill grows from, between Min and Max. Ignored unless Centered is set.An assignment that is not a finite number is ignored, and CenterValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
ChangeMode | ChangeEventMode?ChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by RateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against AsyncSink. See Change mode. |
Disabled | bool? | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
Labeled | bool?default false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
Max | double?default 100 | The highest value the control can take. If Min is not below it, Min becomes Max less 1.An assignment that is not a finite number is ignored, and Max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
Min | double?default 0 | The lowest value the control can take. A minimum that is not below Max is replaced by Max less 1.An assignment that is not a finite number is ignored, and Min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
Name | string? | The name the element's value is submitted under with its form. See Forms. |
Orientation | SliderOrientation?SliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
PageValue | double? | How far PageUp and PageDown move the value. Defaults to ten times Step.An assignment that is not a finite number is ignored, and PageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
RateLimitDelay | int?default 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and RateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
SinkDutyCycle | double?default 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
Size | Size?Size.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
SoftDisabled | bool?default false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
Step | double?default 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and Step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
Tickmarks | SliderTickmark?SliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the TrackBackground render fragment is filled. See Tickmarks. |
TouchTarget | TouchTarget?TouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
Value | double? | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and Value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
ValueExpression | Expression<Func<double?>>? | Gets or sets an expression that identifies the bound value. |
ValueLabel | string? | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Render fragments
| Parameter | Type | Description |
|---|---|---|
TrackBackground | RenderFragment? | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Event callbacks
| Parameter | Type | Description |
|---|---|---|
OnInput | EventCallback<ChangeEventArgs> | Fires during value changes as the user drags. It bubbles and is composed. |
OnChange | EventCallback<ChangeEventArgs> | Fires when the value is committed (timing controlled by ChangeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Inputs
| Input | Type | Description |
|---|---|---|
ariaDescribedBy | string | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
ariaDescription | string | Not announced by assistive technology. ariaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
ariaErrorMessage | string | The ID of the element describing the value's error. Used only while ariaInvalid is "true". |
ariaInvalid | string | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
ariaLabelledBy | string | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
asyncSink | ValueChangeSink | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than rateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. |
centered | booleandefault false | Fills from the middle of the track instead of from its start: from centerValue, or from the midpoint of min and max when centerValue is not set. See Centered. |
centerValue | number | The value the fill grows from, between min and max. Ignored unless centered is set.An assignment that is not a finite number is ignored, and centerValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
changeMode | ChangeEventModeTypeChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by rateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against asyncSink. See Change mode. |
disabled | boolean | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
labeled | booleandefault false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
max | numberdefault 100 | The highest value the control can take. If min is not below it, min becomes max less 1.An assignment that is not a finite number is ignored, and max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
min | numberdefault 0 | The lowest value the control can take. A minimum that is not below max is replaced by max less 1.An assignment that is not a finite number is ignored, and min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
name | string | The name the element's value is submitted under with its form. See Forms. |
orientation | SliderOrientationTypeSliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
pageValue | number | How far PageUp and PageDown move the value. Defaults to ten times step.An assignment that is not a finite number is ignored, and pageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
rateLimitDelay | numberdefault 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and rateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
sinkDutyCycle | numberdefault 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
size | SizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
softDisabled | booleandefault false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
step | numberdefault 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
tickmarks | SliderTickmarkTypeSliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the track-background slot is filled. See Tickmarks. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
value | number | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
valueLabel | string | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Content projection
| Content | Description |
|---|---|
an element with slot="track-background" | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Outputs
| Output | Event | Description |
|---|---|---|
cwInput | InputEvent | Fires during value changes as the user drags. It bubbles and is composed. |
cwChange | Event | Fires when the value is committed (timing controlled by changeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Props
| Prop | Type | Description |
|---|---|---|
ariaDescribedBy | string | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
ariaDescription | string | Not announced by assistive technology. ariaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
ariaErrorMessage | string | The ID of the element describing the value's error. Used only while ariaInvalid is "true". |
ariaInvalid | string | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
ariaLabelledBy | string | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
asyncSink | ValueChangeSink | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than rateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. |
centered | booleandefault false | Fills from the middle of the track instead of from its start: from centerValue, or from the midpoint of min and max when centerValue is not set. See Centered. |
centerValue | number | The value the fill grows from, between min and max. Ignored unless centered is set.An assignment that is not a finite number is ignored, and centerValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
changeMode | ChangeEventModeTypeChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by rateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against asyncSink. See Change mode. |
disabled | boolean | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
labeled | booleandefault false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
max | numberdefault 100 | The highest value the control can take. If min is not below it, min becomes max less 1.An assignment that is not a finite number is ignored, and max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
min | numberdefault 0 | The lowest value the control can take. A minimum that is not below max is replaced by max less 1.An assignment that is not a finite number is ignored, and min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
name | string | The name the element's value is submitted under with its form. See Forms. |
orientation | SliderOrientationTypeSliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
pageValue | number | How far PageUp and PageDown move the value. Defaults to ten times step.An assignment that is not a finite number is ignored, and pageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
rateLimitDelay | numberdefault 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and rateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
sinkDutyCycle | numberdefault 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
size | SizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
softDisabled | booleandefault false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
step | numberdefault 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
tickmarks | SliderTickmarkTypeSliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the track-background slot is filled. See Tickmarks. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
value | number | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
valueLabel | string | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Slots
| Slot | Description |
|---|---|
track-background | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Events
| Event | Type | Description |
|---|---|---|
input | InputEvent | Fires during value changes as the user drags. It bubbles and is composed. |
change | Event | Fires when the value is committed (timing controlled by changeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Props
| Prop | Type | Description |
|---|---|---|
ariaDescribedBy | string | The IDs of the elements that describe the control, space-separated. An element elsewhere on the page is not found. |
ariaDescription | string | Not announced by assistive technology. ariaDescribedBy is no substitute: an ID elsewhere on the page is not found. |
ariaErrorMessage | string | The ID of the element describing the value's error. Used only while ariaInvalid is "true". |
ariaInvalid | string | Whether the control's value is invalid. A screen reader announces it; the control's appearance does not change. |
ariaLabelledBy | string | The IDs of the elements that label the control, space-separated. An element elsewhere on the page is not found: use aria-label. |
asyncSink | ValueChangeSink | The async work, such as a request to a server, that ChangeEventMode.Adaptive paces change events against: the control asks for the next one only when the last has finished, no faster than rateLimitDelay. A slow sink is asked less often, and is not called once per value change. Read the control's value inside it, as a change listener would. Ignored in every other mode. See Change mode. |
centered | booleandefault false | Fills from the middle of the track instead of from its start: from centerValue, or from the midpoint of min and max when centerValue is not set. See Centered. |
centerValue | number | The value the fill grows from, between min and max. Ignored unless centered is set.An assignment that is not a finite number is ignored, and centerValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Centered. |
changeMode | ChangeEventModeTypeChangeEventMode.Debounced, .Immediate, .InteractionEnded, .Throttled, .Adaptivedefault ChangeEventMode.InteractionEnded | When the control fires change while the user is still moving it. Debounced, Throttled and Adaptive are paced by rateLimitDelay, which Adaptive treats as a target, and Adaptive also paces against asyncSink. See Change mode. |
disabled | boolean | Whether the element is disabled. Also reads true while a disabled <fieldset> contains it. See Disabled. |
labeled | booleandefault false | Whether a label with the handle's value appears while the handle is pressed or focused. It stays briefly after a press ends. See Value label. |
max | numberdefault 100 | The highest value the control can take. If min is not below it, min becomes max less 1.An assignment that is not a finite number is ignored, and max keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
min | numberdefault 0 | The lowest value the control can take. A minimum that is not below max is replaced by max less 1.An assignment that is not a finite number is ignored, and min keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Centered. |
name | string | The name the element's value is submitted under with its form. See Forms. |
orientation | SliderOrientationTypeSliderOrientation.Horizontal, .Verticaldefault SliderOrientation.Horizontal | Sets whether the slider runs horizontally or vertically. It is at least 200px long either way. See Orientation. |
pageValue | number | How far PageUp and PageDown move the value. Defaults to ten times step.An assignment that is not a finite number is ignored, and pageValue keeps the value it already had. Assigning null or undefined unsets it, restoring the default. See Range and step. |
rateLimitDelay | numberdefault 150 | The delay in milliseconds that paces change events in the Debounced, Throttled and Adaptive change modes. Other modes ignore it.An assignment that is not a finite number is ignored, and rateLimitDelay keeps the value it already had. null and undefined are ignored on the same rule. See Change mode. |
sinkDutyCycle | numberdefault 1 | The share of the sink's time this control may occupy, above 0 and up to 1, for ChangeEventMode.Adaptive only. At 1 the next call goes out as soon as the last one finishes. Lower it when the sink is shared, so one person dragging does not saturate it: at 0.25 the control leaves three quarters of the time idle.An assignment that is not a finite number in (0, 1] is ignored, and the property keeps the value it already had. See Change mode. |
size | SizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.ExtraSmall, from the style configuration | Sets how large the component is, from extra-small to extra-large. A larger size makes it taller. See Size. |
softDisabled | booleandefault false | Disables the control but keeps it focusable and in the Tab order. It carries aria-disabled="true", and neither the pointer nor the keyboard changes its value. Use it when a disabled control must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. |
step | numberdefault 1 | The step between values. Where the control has a range, a step above the range is set to the range, and a step of 0 or less to 1.An assignment that is not a finite number is ignored, and step keeps the value it already had. null and undefined are ignored on the same rule. See Range and step, Tickmarks. |
tickmarks | SliderTickmarkTypeSliderTickmark.None, .ContrastEndStop, .Valuesdefault SliderTickmark.ContrastEndStop | The type of tickmarks to show. Ignored while the trackBackgroundSnippet snippet is filled. See Tickmarks. |
touchTarget | TouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configuration | The area that takes a touch, at least 48 by 48 pixels and centered on the component. overflow extends it past the component without changing the component's layout size, wrapper makes the component take up the whole area in the layout, and none limits it to the component's own size. See Size. |
value | number | The control's current value.An assignment that is not a finite number -- NaN, Infinity, or a string that does not parse as a number -- is ignored, and value keeps the last valid value it held. Assigning null or undefined unsets it, restoring the default. See Range and step, Forms. |
valueLabel | string | Text shown and announced in place of the value; if not set, the value itself. A screen reader reads it as the value, and as the control's name when aria-label is not set. See Value label. |
A value set from code beyond minmax
Snippets
| Snippet | Description |
|---|---|
trackBackgroundSnippet | Content that shows through the slider's track in place of its colors. Tickmarks and the end stop are not drawn while it is filled. |
Events
| Prop | Type | Description |
|---|---|---|
onInput | InputEvent | Fires during value changes as the user drags. It bubbles and is composed. |
onChange | Event | Fires when the value is committed (timing controlled by changeMode). It bubbles. |
change is sent only when the value differs from the last one sent. A value set from code fires no event at all.
Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the extra-small column's handle-length row is --ct-slider-xsmall-handle-length, which defaults to 44px.
Size
Token names spell extra-small as xsmall and extra-large as xlarge.
| Name | extra-small | small | medium | large | extra-large |
|---|---|---|---|---|---|
handle-length | 44px --ct-slider-xsmall-handle-length | 44px --ct-slider-small-handle-length | 44px --ct-slider-medium-handle-length | 68px --ct-slider-large-handle-length | 108px --ct-slider-xlarge-handle-length |
track-corner-end-end-radius | same as track-corner-radius --ct-slider-xsmall-track-corner-end-end-radius | same as track-corner-radius --ct-slider-small-track-corner-end-end-radius | same as track-corner-radius --ct-slider-medium-track-corner-end-end-radius | same as track-corner-radius --ct-slider-large-track-corner-end-end-radius | same as track-corner-radius --ct-slider-xlarge-track-corner-end-end-radius |
track-corner-end-start-radius | same as track-corner-radius --ct-slider-xsmall-track-corner-end-start-radius | same as track-corner-radius --ct-slider-small-track-corner-end-start-radius | same as track-corner-radius --ct-slider-medium-track-corner-end-start-radius | same as track-corner-radius --ct-slider-large-track-corner-end-start-radius | same as track-corner-radius --ct-slider-xlarge-track-corner-end-start-radius |
track-corner-radius | 8px --ct-slider-xsmall-track-corner-radius | 8px --ct-slider-small-track-corner-radius | 12px --ct-slider-medium-track-corner-radius | 16px --ct-slider-large-track-corner-radius | 28px --ct-slider-xlarge-track-corner-radius |
track-corner-start-end-radius | same as track-corner-radius --ct-slider-xsmall-track-corner-start-end-radius | same as track-corner-radius --ct-slider-small-track-corner-start-end-radius | same as track-corner-radius --ct-slider-medium-track-corner-start-end-radius | same as track-corner-radius --ct-slider-large-track-corner-start-end-radius | same as track-corner-radius --ct-slider-xlarge-track-corner-start-end-radius |
track-corner-start-start-radius | same as track-corner-radius --ct-slider-xsmall-track-corner-start-start-radius | same as track-corner-radius --ct-slider-small-track-corner-start-start-radius | same as track-corner-radius --ct-slider-medium-track-corner-start-start-radius | same as track-corner-radius --ct-slider-large-track-corner-start-start-radius | same as track-corner-radius --ct-slider-xlarge-track-corner-start-start-radius |
track-thickness | 16px --ct-slider-xsmall-track-thickness | 24px --ct-slider-small-track-thickness | 40px --ct-slider-medium-track-thickness | 56px --ct-slider-large-track-thickness | 96px --ct-slider-xlarge-track-thickness |
Other tokens
These stay the same whatever the size.
| Token | Value |
|---|---|
--ct-slider-active-handle-space | 5px --ct-slider-active-handle-space |
--ct-slider-active-handle-width | 2px --ct-slider-active-handle-width |
--ct-slider-active-tick-mark-color | --ct-sys-color-on-primary --ct-slider-active-tick-mark-color |
--ct-slider-active-tick-mark-opacity | 1 --ct-slider-active-tick-mark-opacity |
--ct-slider-active-track-color | --ct-sys-color-primary --ct-slider-active-track-color |
--ct-slider-center-space | 4px --ct-slider-center-space |
--ct-slider-disabled-active-tick-mark-color | --ct-sys-color-inverse-on-surface --ct-slider-disabled-active-tick-mark-color |
--ct-slider-disabled-active-track-color | --ct-sys-color-on-surface --ct-slider-disabled-active-track-color |
--ct-slider-disabled-active-track-opacity | 0.38 --ct-slider-disabled-active-track-opacity |
--ct-slider-disabled-handle-color | --ct-sys-color-on-surface --ct-slider-disabled-handle-color |
--ct-slider-disabled-handle-opacity | 0.38 --ct-slider-disabled-handle-opacity |
--ct-slider-disabled-inactive-tick-mark-color | --ct-sys-color-on-surface --ct-slider-disabled-inactive-tick-mark-color |
--ct-slider-disabled-inactive-track-color | --ct-sys-color-on-surface --ct-slider-disabled-inactive-track-color |
--ct-slider-disabled-inactive-track-opacity | 0.12 --ct-slider-disabled-inactive-track-opacity |
--ct-slider-disabled-tick-mark-opacity | 0.38 --ct-slider-disabled-tick-mark-opacity |
--ct-slider-handle-color | --ct-sys-color-primary --ct-slider-handle-color |
--ct-slider-handle-space | 6px --ct-slider-handle-space |
--ct-slider-handle-width | 4px --ct-slider-handle-width |
--ct-slider-inactive-tick-mark-color | --ct-sys-color-on-secondary-container --ct-slider-inactive-tick-mark-color |
--ct-slider-inactive-tick-mark-opacity | 1 --ct-slider-inactive-tick-mark-opacity |
--ct-slider-inactive-track-color | --ct-sys-color-secondary-container --ct-slider-inactive-track-color |
--ct-slider-tick-mark-size | 4px --ct-slider-tick-mark-size |
--ct-slider-value-indicator-block-space | 12px --ct-slider-value-indicator-block-space |
--ct-slider-value-indicator-container-color | --ct-sys-color-inverse-surface --ct-slider-value-indicator-container-color |
--ct-slider-value-indicator-inline-space | 16px --ct-slider-value-indicator-inline-space |
--ct-slider-value-indicator-label-font | --ct-sys-typescale-label-large-font --ct-slider-value-indicator-label-font |
--ct-slider-value-indicator-label-line-height | --ct-sys-typescale-label-large-line-height --ct-slider-value-indicator-label-line-height |
--ct-slider-value-indicator-label-size | --ct-sys-typescale-label-large-size --ct-slider-value-indicator-label-size |
--ct-slider-value-indicator-label-text-color | --ct-sys-color-inverse-on-surface --ct-slider-value-indicator-label-text-color |
--ct-slider-value-indicator-label-tracking | --ct-sys-typescale-label-large-tracking --ct-slider-value-indicator-label-tracking |
--ct-slider-value-indicator-label-weight | --ct-sys-typescale-label-large-weight --ct-slider-value-indicator-label-weight |
Names and states
A slider has the slider role, which follows the WAI-ARIA Authoring Practices: Slider pattern.
- The accessible name is the slider's
aria-label, else , else the current number. Always setvalue-labelaria-label, because the number alone says nothing about what the slider sets. - A screen reader announces the value as the slider's own
aria-valuetextif you set one, else , else the number. It also announces the limits fromvalue-label andmin and the direction frommax .orientation - Six settings shape what a screen reader announces:
aria-label,aria-valuetext, ,aria-labelledby ,aria-describedby , andaria-invalid . Any other ARIA attribute has no effect.aria-errormessage - An ID that points to an element elsewhere on the page is not found, so name the slider with
aria-labelinstead. - A screen reader announces the
text only whilearia-errormessage isaria-invalid"true". Set as a property.aria-invalid is not announced.aria-description- The value label is announced politely while
is set.labeled - For a low and a high value on one track, use a range slider.
Keyboard and focus
| Key | Action |
|---|---|
| Right Arrow, Up Arrow | Increase the value by one step |
| Left Arrow, Down Arrow | Decrease the value by one step |
| Page Up | Increase the value by page-value |
| Page Down | Decrease the value by page-value |
| Home | Go to min |
| End | Go to max |
The slider ignores these keys while a pointer drag is in progress.
- Keyboard focus rings the handle and nothing else.
removes the slider from the Tab order. A slider has no soft-disabled state.disabled
Pointer and touch
The touch target is at least 48 by 48 pixels unless touch-targetnone, and even the smaller target is above the 24 by 24 pixels that WCAG 2.5.8 asks for. See Size for the setting.
Display settings
- Forced colors: the handle and value label take system colors with visible borders, and the handle gains a thicker ring on hover and while dragged.
- Reduced motion: the handle, value label, focus ring, and fill transitions turn off.
- Right to left: the track mirrors, and Right Arrow and Page Up decrease the value while Left Arrow and Page Down increase it.
Standards
With its defaults, the slider meets three WCAG 2.2 success criteria:
Three more depend on how you use it:
- 3.3.1 Error Identification (A): set
andaria-invalid as properties, and show the error text on the page.aria-errormessage - 2.5.3 Label in Name (A): where visible text labels the slider, start its
aria-labelwith the same words. - 4.1.2 Name, Role, Value (A): set
aria-labelon each slider so that its name states its purpose.