Range slider

A range slider is an input field that merchants can use to select a numeric value within a given range (minimum and maximum values).

Examples

Use range sliders where merchants may need to select a percentage between 0 — 100.

Drag to resize example

Props

disabled
boolean
Disable input
error
string | ReactElement | (string | ReactElement)[]
Display an error message
helpText
React.ReactNode
Additional text to aid in use
id
string
ID for range input
labelRequired
string
Label for the range input
labelAction
Action
Adds an action to the label
labelHidden
boolean
Visually hide the label
max
number
Maximum possible value for range input
min
number
Minimum possible value for range input
output
boolean
Provide a tooltip while sliding, indicating the current value
prefix
React.ReactNode
Element to display before the input
step
number
Increment value for range input changes
suffix
React.ReactNode
Element to display after the input
valueRequired
number | DualValue
Initial value for range input
onBlur
() => void
Callback when focus is removed
onChangeRequired
(value: number | DualValue, id: string) => void
Callback when the range input is changed
onFocus
() => void
Callback when range input is focused

Accessibility

The range slider provides a large click and tap target for the slider thumbs. Merchants can also tap or click on the slider track to move the closest slider thumb.

Single-thumb slider

The default range slider component uses the ARIA 1.1 slider pattern to build upon the default HTML <input type="range">. The required label prop provides a label for the field that’s conveyed to assistive technologies when it receives focus. When the slider is used, the value prop should update visually and programmatically to reflect the current value.

To consistently provide the current value to assistive technologies, use the min and max props to provide the minimum and maximum values for the slider.

Dual-thumb slider

The dual-thumb range slider component uses the ARIA 1.1 slider (multi-thumb) pattern. However, the pattern isn’t consistently supported by screen readers, especially on mobile devices. Because of this, it’s best to pair the dual-thumb slider with a set of text fields for each value, or to provide another accessible method for entering information.

Keyboard

  • To move focus to a slider thumb, press the tab key to move forward and or shift + tab to move backward
  • When a thumb has focus, use the up and down or left and right arrow keys to move the thumb and update the associated value.

Default range slider

Use range sliders where merchants may need to select a percentage between 0 — 100.

Range slider for Android

Dual thumb range slider

Use a dual thumb range slider when merchants need to select a range of values.

Accessibility

See Material Design and development documentation about accessibility for Android:

Default range slider

Use range sliders where merchants may need to select a percentage between 0 — 100.

Range slider for iOS

Dual thumb range slider

Use a dual thumb range slider when merchants need to select a range of values.

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Best practices

Range sliders should:

  • Always be used with a label, even if that label is hidden.
  • When a label is visible, it should clearly communicate the purpose of the range input and its values (min, max, step, value)
  • Be labeled as “Optional” when you need to request input that’s not required
  • Validate input as soon as merchants have finished interacting with a field (but not before)
  • Always be used with two text field components when range slider has dual thumbs, to provide accessible alternatives to both the lower and upper thumbs

Content guidelines

Range label

A label is a short description of the requested input. Labels are not instructional text but they should be meaningful and clearly indicate what is expected. Labels should be:

  • Placed above the form field
  • Short and succinct (1–3 words)
  • Written in sentence case (the first word capitalized, the rest lowercase)
  • Saturation percentage

  • Banner width

  • What is the saturation value?

  • The banner width is:

Designating optional fields

Try to only ask for information that’s required. If you need to ask merchants to provide optional information, mark the field optional by placing the text “(optional)” at the end of the field’s label. Don’t mark required fields with asterisks.

  • Banner width (optional)

  • Banner width

Help text

Help text provides extra guidance or instruction to people filling out a form field. It can also be used to clarify how the information will be used. As with all form content, help text should be succinct and easy to read.

  • Video duration is calculated in seconds

  • Example: 134 seconds

Validation error messages

Error messages should:

  • Clearly explain what went wrong and how to fix it
  • Be short and concise, no more than a single sentence
  • Use passive voice so merchants don’t feel like they’re being blamed for the error
  • Video duration is required

  • You didn’t enter a duration