Summary

Added optional data-text-unit and data-text-preposition attributes to range slider. It now reads {{ value }} of {{ max }} when calling out the range slider value. The of can be changed using data-text-preposition as needed for use cases or different languages.

Additionally, this PR enhances the storybook controls to easily allow users to set the min, max, step, and newly added data attribute values.

Important
The new JS file does not contain a teardown method at this time. Compared to other components, it appears we only teardown dynamic components, remove event listeners, and reset logic-related values.

It did not seem necessary to add a teardown to remove the aria-valuetext attribute at this time.

Breaking change

⚠️ This is potentially a breaking change.

Existing users will not need to change anything by default but will need to edit markup if they’d like to include the new unit feature.

Related issue

Closes #5431

Related pull requests

Changelog and guidance update →

USWDS - Range: Remove redundant ARIA attributes #5413 →

Preview link

Range slider →

Problem statement

When using the range slider with a screen reader, users are left without context. Because sliders rely on context from their implementation, we should allow devs to provide additional context to for screen readers as well as some way to let users know how far along the slider the handle is.

Solution

This PR improves SR callouts in two ways.

The first, is adding the max value to the callout. Now when the slider moves, it will read the current value, then “of max value” where max value is the numerical max value.

Next, is adding an additional data-text-unit attribute. This attribute can be set to any unit the user can choose to include. Some examples may include:

• Percent
• Temperature
• Stars (rating)
• Decibles
• etc…

Essentially dependent on the use case of the slider.

When included, the screen reader will update to read out along the following examples:

• “30 percent of 100”
• “72 degrees Fahrenheit of 90”
• “3.5 stars of 5”
• “3 pizza slices of 8”
• etc.

With the addition of the data-text-preposition attribute, devs can change the language between the units and the total to fit whatever language they are developing for.

For example:

Spanish:

Note
Screen readers will still rely on system settings to read numbers in correct language

New data attributes

data-text-unit - Set the data-text-unit attribute to include a unit with screen reader callouts. This provides additional context to assistive technology users. It is empty by default. Adding a value will be read as: "x units of y".

data-text-preposition - Set the preposition between units and total. By default, we'll use of (i.e. 40 percent of 100). This will allow devs to update the verbiage depending on language.

Further consideration

Devs should still provide proper context before users reach the slider. It is important for both visual, and screen-reader users, that the usability guidance is followed.

This is also a JS solution. JS is required to set update the aria-valuetext attribute, which is standard across various accessible slider components researched during this work.

You can view some examples from W3C WAI.

Note
The examples at the above link are all nonsemantic examples, and are built using divs, ARIA attributes, and JS

Testing and review

1. Visit Range slider →
2. In controls, add a data-text-unit
3. Leave data-text-prepostion empty
4. Refresh page
5. Activate screen reader
6. Interact with the range slider
7. Confirm callouts have been improved
8. Confirmed preposition defaults to of
9. In controls, add a data-text-preposition
10. Interact with the range slider
11. Confirm of is replaced with your new value
12. If desired, play around with the unit to listen to other use cases
13. Feel free to play with min, max, and step if you want to customize the range slider for different use cases

Testing checklist

• If unit is present, screen reader reads out unit with value
• If unit is not present, screen reader still reads value and max value
• Screen reader callouts are justifiably enhanced
• Context is improved for screen reader users

Note
Sometimes storybook has trouble initializing JS. If changes aren’t taking place or if readout is not reading properly, try refreshing the page and listening again.