WAI-ARIA: aria-valuenow (Property)

Defines the current value for a range widget.

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.

 

Example

HTML Example

 

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

0% complete Update

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

number
Any real numerical value.

Semantic HTML

No HTML element equivalent.

 

Reference