Understanding aria-valuetext

Published: 15 August 2026

This article explains aria-valuetext in plain language. It show how to give a numeric value a more useful text description for assistive technology.

1. Starting with aria-valuenow

In the previous article on aria-valuenow, we looked at how aria-valuenow tells assistive technology the current numeric value of a custom slider.

We used this volume slider:

<span id="volume-label">Volume</span>

<div
  role="slider"
  tabindex="0"
  aria-labelledby="volume-label"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="40"
>
</div>

Here, aria-valuenow="40" tells assistive technology:

“The current value of this slider is 40.”

That works well because the number itself is meaningful.

But what if the number is only being used internally, and there is a more useful way to describe the value to the user?

This is where aria-valuetext comes in.

2. When the numeric value is not enough

The slider still needs a numeric value because that is how the control works internally. But this number may not be the best information to give the user.

Imagine that our volume slider still uses values from 0 to 100, but shows the user simpler descriptions instead:

• 0 to 30 = Low
• 31 to 70 = Medium
• 71 to 100 = High

The slider might still have:

aria-valuenow="40"

So assistive technology gets the current numeric value of 40.

But visually, the interface may be showing:

“Medium”

In this case, the numeric value is correct, but it may not be the most useful information for the user.

3. Adding aria-valuetext

aria-valuetext provides a text description of the current value.

For our volume slider, we can add:

aria-valuetext="Medium"

So the slider becomes:

<span id="volume-label">Volume</span>

<div
  role="slider"
  tabindex="0"
  aria-labelledby="volume-label"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="40"
  aria-valuetext="Medium"
>
</div>

The two attributes now give users different information:

• aria-valuenow="40" gives users the current numeric value
• aria-valuetext="Medium" gives users a more useful text description of that value

You can think of it like this:

“The current numeric value is 40, but tell the user it is Medium.”

If the slider changes, JavaScript needs to keep both values up to date.

For example, if the slider moves to 80:

aria-valuenow="80"
aria-valuetext="High"

aria-valuenow is still used internally by the browser to work out the value’s position within the range.

aria-valuetext is meant to replace what gets announced to the user, not sit alongside it. When aria-valuetext is used, assistive technology should announce the text instead of the number. For example, “Medium” instead of “40”.

Note: In our testing, some screen reader and browser combinations announced both the number and the text. This is different from the behaviour described in the ARIA specification, so it is worth testing your own implementation.

4. When should you use aria-valuetext?

Use aria-valuetext if it can give users more useful information than aria-valuenow.

For example:

• 40 may be more useful as “Medium”
• 1 may be more useful as “Monday”
• 3 may be more useful as “Large”

Test page

Testing aria-valuetext