WAI-ARIA: aria-valuenow (Property)

Description

Defines the current value for a range widget. See related aria-valuetext.

This property is used, for example, on a range widget such as a slider or progress bar.

If the current value is not known (for example, an indeterminate progress bar), the author SHOULD NOT set the aria-valuenow attribute. If the aria-valuenow attribute is absent, no information is implied about the current value. If the aria-valuenow has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax and aria-valuemin.

The value of aria-valuenow is a decimal number. If the range is a set of numeric values, then aria-valuenow is one of those values. For example, if the range is [0, 1], a valid aria-valuenow is 0.5. A value outside the range, such as -2.5 or 1.1, is invalid.

For progressbar elements and scrollbar elements, assistive technologies SHOULD render the value to users as a percent, calculated as a position on the range from aria-valuemin to aria-valuemax if both are defined, otherwise the actual value with a percent indicator. For elements with role slider and spinbutton, assistive technologies SHOULD render the actual value to users.

When the rendered value cannot be accurately represented as a number, authors SHOULD use the aria-valuetext attribute in conjunction with aria-valuenow to provide a user-friendly representation of the range’s current value. For example, a slider may have rendered values of small, medium, and large. In this case, the values of aria-valuetext would be one of the strings: small, medium, or large.

Note: If aria-valuetext is specified, assistive technologies render that instead of the value of aria-valuenow.

Browser Compatibility For aria-valuenow

Example

HTML Example

<div id="percent-loaded" role="progressbar" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">&nbsp;</div>

JavaScript Example

Find the progress bar in the DOM.

var progressBar = document.getElementById(“percent-loaded”);
Set its ARIA roles and states, so that assistive technologies know what kind of widget it is.
progressBar.setAttribute(“role”, “progressbar”);
progressBar.setAttribute(“aria-valuemin”, 0);
progressBar.setAttribute(“aria-valuemax”, 100);

Create a function that can be called at any time to update the value of the progress bar.

function updateProgress(percentComplete) {
progressBar.setAttribute("aria-valuenow", percentComplete);
}

HTML5 Example

<p><progress id="progress-bar" value="0" max="100">0% complete</progress> <button id="update-button">Update</button></p>

Supporting JavaScript

… and here is the JavaScript code that will ensure the progress bar still works in older browsers:

var progressBar = document.getElementById("progress-bar");

Check to see if the browser supports the HTML5 tag.
var supportsHTML5Progress = (typeof (HTMLProgressElement) !== “undefined”);

function setupProgress() {
if (!supportsHTML5Progress) {
HTML5 isn’t supported in this browser, so we need to add
// ARIA roles and states to the element.
progressBar.setAttribute(“role”, “progressbar”);
progressBar.setAttribute(“aria-valuemin”, 0);
progressBar.setAttribute(“aria-valuemax”, 100);
}
}

function updateProgress(percentComplete) {
if (!supportsHTML5Progress) {
HTML5 isn’t supported by this browser,
// so we need to update the aria-valuenow attribute
progressBar.setAttribute(“aria-valuenow”, percentComplete);
} else {
// HTML5 is supported, so update the value attribute instead.
progressBar.setAttribute(“value”, percentComplete);
}

progressBar.textContent = percentComplete + "% complete";
}
function initDemo() {
setupProgress(); 
Setup the progress bar.
Bind a click handler to the button, which will update the progress bar to 75%.
document.getElementById("update-button").addEventListener("click", function (e) {
updateProgress(75);
e.preventDefault();
}, false);
}
initDemo();

Characteristics

Used in Roles

• range
• scrollbar
• separator
• slider
• spinbutton

Inherits into Roles

• progressbar

Value

Any real numerical value.

Semantic HTML

No HTML element equivalent.

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-valuenow.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-valuenow.