ARIA property
aria-valuetext
A readable version of the current value, for when the number is not what people say. Large, rather than 3.
It replaces the number in what people hear, because assistive technology should read this instead of aria-valuenow whenever it is present. That is the whole reason to use it, and it is also the trap.
Which roles may carry aria-valuetext
- Value
- string
- Filed as
- A property, which is how ARIA files it and not a rule about how often it changes.
- Roles that may carry it
range,separator,spinbutton- Roles that inherit it
meter,progressbar,scrollbar,slider,spinbutton
Those lists are not advice. Browsers are required to ignore a non-global attribute sitting on a role that does not support it, so aria-valuetext on the wrong element is not weak, it is absent. You can read it in the DOM and nobody using a screen reader can.
Every role above comes from the specification's own list for this attribute, checked name for name. The normative definition stays with the W3C, in the aria-valuetext section of the ARIA specification.
Keeping aria-valuetext true
Because this value wins, a stale one hides a perfectly correct aria-valuenow underneath it, and the number you can read in the DOM is not the one being announced. So it has to be rewritten in the same step as the value, every time, with no exceptions for the code path you added last. This attribute is the spec's own counterexample to the idea that properties sit still while states move, because it changes on every interaction and is filed as a property. Use it only where the raw number would be unhelpful, and take it off the moment the value becomes a plain number again.
How aria-valuetext gets checked
There are test rules that check an ARIA attribute is one that exists, is allowed on the role underneath it, and carries a value of the right type. What they map to is ARIA's own author requirements rather than any WCAG criterion, so a misplaced attribute breaks ARIA without being a WCAG failure by itself. It becomes one under 4.1.2 Name, Role, Value the moment the missing or wrong value means the control's state cannot be worked out programmatically, which is what usually happens next.
Nothing automated catches the failure this page is about. A stale value is a valid value, on a permitted role, with the right type. It is only wrong about the world.
Attributes you will meet alongside aria-valuetext
- aria-disabled Says a control is present but not available. Unlike the disabled attribute, it stays focusable, so people can still find out it is there.
- aria-errormessage Points at the message explaining why this field is invalid. Only meaningful while aria-invalid is set.
- aria-invalid Says a field's value has failed validation.
- aria-orientation Whether a widget runs horizontally or vertically, which decides which arrow keys move through it.
- aria-readonly The value can be read but not changed. Unlike disabled, it is still part of the form.
- aria-required Says a field has to be filled in before the form can be submitted.
- aria-valuemax The highest value a range control accepts.
- aria-valuemin The lowest value a range control accepts.
Every ARIA state and property · Every ARIA role · ARIA explained