Communicating Value and Limits for Range Widgets
Introduction
ARIA defines the following roles as range widgets, which means they communicate a value that is typically numeric and constrained to defined limits.
meterprogressbarscrollbarseparator(if focusable)sliderspinbutton
For example, a spin button for choosing a day within the month of January would allow integer values that range from 1 to 31. In some cases, the value is represented numerically, but is not presented as a number to users. For instance, a spin button for choosing a day of the week could support values from 1 to 7 but they could be presented to the user as day names, e.g., "Monday", "Tuesday", etc.
This section describes considerations for using the following four properties that communicate characteristics of a range widget:
| Property | Definition |
|---|---|
aria-valuemin |
Defines the minimum value allowed by a range widget. |
aria-valuemax |
Defines the maximum value allowed by a range widget. |
aria-valuenow |
Defines the current value of a range widget. This value is a number greater than or equal to aria-valuemin and less than or equal to aria-valuemax (if they are specified). |
aria-valuetext |
If a numeric value is not sufficiently descriptive, this property can define a text description of the current value of a range widget. |
Using aria-valuemin, aria-valuemax and aria-valuenow
When the value of a range widget is constrained to known limits, the aria-valuemin and aria-valuemax properties are used to inform assistive technologies of the minimum and maximum values of the range.
For some widgets, assistive technologies use this information to present the current value as a percentage.
When using these properties, set aria-valuemin to the lowest value allowed for the widget and aria-valuemax to the highest allowed value.
If values for aria-valuemin and aria-valuemax are not set, default values are exposed to assistive technologies unless the widget is a spinbutton, which is the only range widget that does not have default limits.
The aria-valuenow property is used to inform assistive technologies of the current value of a range widget.
Set aria-valuenow to the current value of the widget, ensuring the value of aria-valuenow falls within the range defined by aria-valuemin and aria-valuemax.
If the current value of a progressbar or spinbutton is indeterminate or unknown, omit the aria-valuenow property.
The aria-valuenow property is required for the meter, scrollbar, separator (if the element is focusable), and slider roles.
The range widget roles have the following default values and requirements for aria-valuemin, aria-valuemax and aria-valuenow.
| Role | aria-valuemin(default) |
aria-valuemax(default) |
aria-valuemin(required) |
aria-valuemax(required) |
aria-valuenow(required) |
|---|---|---|---|---|---|
meter |
0 | 100 | No | No | Yes |
progressbar |
0 | 100 | No | No | No |
scrollbar |
0 | 100 | No | No | Yes |
separator (if focusable) |
0 | 100 | No | No | Yes |
slider |
0 | 100 | No | No | Yes |
spinbutton |
None | None | No | No | No |
Using aria-valuetext
When the element's values are contained within a range but those values are not numeric (such as "small", "medium" and "large"),
or they are numeric but there is value in communicating more information than just a number,
aria-valuetext is used to surface the text value to assistive technologies.
Only use aria-valuetext when aria-valuenow is not sufficiently meaningful for users because using aria-valuetext will prevent assistive technologies from communicating aria-valuenow.
For example, for a battery indicator, it would be useful to know how many minutes are remaining, in addition to the percentage of charge remaining.
<span id="battery-label">Battery</span>
<span role="meter" aria-labelledby="battery-label"
aria-valuenow="5"
aria-valuetext="5%, 18 minutes remaining.">
</span>
Range properties with meter
The aria-valuemin and aria-valuemax properties only need to be set for elements with role meter if the meter's minimum value is not 0 or its maximum value is not 100.
It is necessary, however, to always specify a value for aria-valuenow and to ensure the value is greater than or equal to the minimum allowed value and less than or equal to the maximum allowed value.
A detailed description of the meter role is in the meter design pattern.
This example of a meter shows the current Central Processing Unit (CPU) usage.
<span id="cpu_usage_label">CPU usage</span>
<!-- The CPU usage uses the default values of 0 and 100 for aria-valuemin and aria-valuemax -->
<div role="meter"
aria-valuenow="90"
aria-labelledby="cpu_usage_label">
</div>
The aria-valuetext property can be set to a string that makes the meter value understandable. For example, a CPU usage meter value might be conveyed as aria-valuetext="90% of CPU is being used".
Here is another example of a meter that has a range different from the default of 0 for aria-valuemin and 100 for aria-valuemax.
<span id="ph_alkaline_meter_label">Alkaline pH(Power of Hydrogen) Level</span>
<div role="meter"
aria-valuenow="9"
aria-valuemin="7"
aria-valuemax="14"
aria-labelledby="ph_alkaline_meter_label">
</div>Range properties with progress bars
The aria-valuemin and aria-valuemax properties only need to be set for the progressbar role when the progress bar's minimum is not 0 or the maximum value is not 100.
The aria-valuenow property needs to be set for a progressbar if its value is known (e.g. not indeterminate).
If the aria-valuenow property is set, the author needs to make sure it is within the minimum and maximum values.
Following is an example of a progress bar represented by an SVG.
<div><span id="loadlabel">Loading:</span>
<!-- The progress bar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax -->
<span role="progressbar"
aria-labelledby="loadlabel"
aria-valuenow="33" >
<svg width="100" height="10">
<rect x="0" y="0" height="10" width="100" stroke="black" fill="none"/>
<rect x="0" y="0" height="10" width="33" fill="green" />
</svg>
</span>
</div>This progress bar can also be made using the native HTML progress element.
<label for="loadstatus">Loading:</label>
<progress id="loadstatus" max="100" value="33"></progress>
To represent an indeterminate progress bar where the value range is unknown, omit the aria-valuenow attribute.
<img role="progressbar" src="spinner.gif" alt="Loading...">Range properties with scrollbars
The aria-valuemin and aria-valuemax properties only need to be set for the scrollbar role when it's minimum value is not 0 or the maximum value is not 100. The aria-valuenow property is required for scrollbar and the author needs to make sure it is within the minimum and maximum values.
aria-valuenow will generally be exposed as a percentage between aria-valuemin and aria-valuemax calculated by assistive technologies.
<span id="pi-label">Pi</div>
<div id="pi">
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</div>
<div class="rail">
<!-- The scrollbar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax -->
<div
class="thumb"
role="scrollbar"
aria-labelledby="pi-label"
aria-controls="pi"
aria-orientation="horizontal"
aria-valuenow="25">
</div>
</div>Range properties with sliders
The aria-valuemin and aria-valuemax properties only need to be set for the slider role when the slider's minimum is not 0 or the maximum value is not 100.
The aria-valuenow property is required for slider role and the author needs to make sure it is within the minimum and maximum values.
A detailed description of the slider role can be found in the slider design pattern and slider (multi-thumb) design pattern.
The following example shows a temperature controller.
In this example, aria-valuenow is meaningful to the user, and so aria-valuetext is not used.
<div class="rail">
<div id="thumb" role="slider" aria-valuemin="50" aria-valuenow="68" aria-valuemax="100"
aria-label="Temperature (F)" tabindex="0">
</div>
</div>The slider example above can be made using the HTML <input type="range"> element.
<input type="range" min="50" value="68" max="100" aria-label="Temperature (F)">
The following example is a fan control. The aria-valuenow value is "1", which is not meaningful to the user. The aria-valuetext property is used so that assistive technology will surface its value ("low") instead.
<div class="rail">
<div id="thumb" role="slider" aria-valuemin="0" aria-valuenow="1" aria-valuemax="3"
aria-valuetext="low" aria-label="Fan speed" tabindex="0" >
</div>
<div class="value"> Off </div>
<div class="value"> Low </div>
<div class="value"> Medium </div>
<div class="value"> High </div>
</div>Range properties with spin buttons
The aria-valuemin and aria-valuemax properties are used only when a spinbutton has a defined range.
They do not have default values, so if they are not specified, range limits will not be exposed to assistive technologies.
Similarly, the aria-valuenow property is set only when a spinbutton has a value.
If it is not set, a value is not exposed to assistive technologies for the spinbutton.
aria-valuetext can be used when appropriate.
A detailed description of the spinbutton role can be found in the spinbutton design pattern.
The following example sets the price of paperclips in cents.
<div role="spinbutton" aria-labelledby="price-label" aria-valuenow="50" tabindex="0">
<button id="lower-price">Lower</button>
<button id="raise-price">Raise</button>
<span id="price-label">Price per paperclip: $</span><span id="price">0.50</span>
</div>If there are minimum and maximum allowed values, set the aria-valuemin and aria-valuemax properties.
<div role="spinbutton" aria-labelledby="price-label"
aria-valuemin="1" aria-valuenow="50" aria-valuemax="200" tabindex="0">
<button id="lower-price">Lower</button>
<button id="raise-price">Raise</button>
<span id="price-label">Price per paperclip: $</span><span id="price">0.50</span>
</div>The spin button example above can be made using the native HTML <input type="number"> element.
<label>Price per paperclip: $<input type="number" min="0.01" value="0.5" max="2" step="0.01"></label>