This Wiki page is edited by participants of the WCAG Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.

Difference between revisions of "Using WAI-ARIA range attributes for range widgets such as progressbar, scrollbar, slider, and spinbutton"

From WCAG WG
Jump to: navigation, search
(Example 2: A slider)
Line 56: Line 56:
 
A widget with role <code>slider</code> lets a user select a value from within a given range. The slider represents the current value and the range of possible values via the size of the slider and the position of the handle. These  properties of the slider are represented by the attributes <code>aria-valuemin</code>, <code>aria-valuemax</code>, and <code>aria-valuenow</code>.
 
A widget with role <code>slider</code> lets a user select a value from within a given range. The slider represents the current value and the range of possible values via the size of the slider and the position of the handle. These  properties of the slider are represented by the attributes <code>aria-valuemin</code>, <code>aria-valuemax</code>, and <code>aria-valuenow</code>.
  
The following snippet from The Open Ajax Accessibility Examples, Example 32, shows WAI-ARIA mark-up for a slider created in JavaScript. Note that the JavaScript sets the attributes  <code>aria-valuemin</code>, <code>aria-valuemax</code>, and <code>aria-valuenow</code>:
+
The following snippet from the [http://oaa-accessibility.org/example/32/ Open Ajax Accessibility Examples, Example 32], shows WAI-ARIA mark-up for a slider created in JavaScript. Note that the JavaScript sets the attributes  <code>aria-valuemin</code>, <code>aria-valuemax</code>, and <code>aria-valuenow</code>:
  
 
<pre>
 
<pre>

Revision as of 02:02, 30 April 2013


Status

Applicability

{Technology} content with {relevant feature}.

WCAG references

User Agent and Assistive Technology Support Notes

  • Assistive technology only reads the value, and does not announce the aria-valuemin and aria-valuemax values. (Tested with JAWS, NVDA, VoiceOver)

Description

The objective of this technique is to use the aria-valuemax, aria-valuemin, aria-valuenow, and aria-valuetext properties of widgets with roles that are a subclass of the range abstract role to expose the range values of a user interface component. Examples of range widgets are progressbar, scrollbar, slider, and spinbutton.

Declaring the minimum and maximum values for the range allows assistive technology to react to arrow keys, validate the current value, or simply let the user know the size of the range.

Examples

Example 1: A spinbutton

A widget with role spinbutton lets a user enter a value from within a given range. The spinbutton shows the current value and presents controls to allow the user to increase and decrease the value. The maximum and minimum values are represented by aria-valuemax, aria-valuemin, and the current value by aria-valuenow.

The following snippet from The Open Ajax Accessibility Examples, Example 33, shows WAI-ARIA mark-up for a spinbutton from the source of the page. Note that the JavaScript of the page adds event listeners for both keyboard and mouse methods to increase and decrease the values

<label id="sb1_label" class="sbLabel" for="sb1">Choose a number between 0 and 100</label>
<div class="spinControl">
	<div id="sb1" class="spinbutton" role="spinbutton" aria-labelledby="sb1_label" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50" tabindex="0">
            50
	</div>
	<div id="sb1_up" class="button">
		<img src="images/button-arrow-up.png" role="presentation" alt="Increase value">	
	</div>
	<div id="sb1_down" class="button">
		<img src="images/button-arrow-down.png" role="presentation" alt="Decrease value">	
	</div>
</div>


Example 2: A slider

A widget with role slider lets a user select a value from within a given range. The slider represents the current value and the range of possible values via the size of the slider and the position of the handle. These properties of the slider are represented by the attributes aria-valuemin, aria-valuemax, and aria-valuenow.

The following snippet from the Open Ajax Accessibility Examples, Example 32, shows WAI-ARIA mark-up for a slider created in JavaScript. Note that the JavaScript sets the attributes aria-valuemin, aria-valuemax, and aria-valuenow:

   var handle = '<img id="' + id + '" class="' + (this.vert == true ? 'v':'h') +'sliderHandle" ' +
    'src="http://www.oaa-accessibility.org/media/examples/images/slider_' + (this.vert == true ? 'v':'h') + '.png" ' + 'role="slider" ' +
    'aria-valuemin="' + this.min +
    '" aria-valuemax="' + this.max +
    '" aria-valuenow="' + (val == undefined ? this.min : val) +
           '" aria-labelledby="' + label +
           '" aria-controls="' + controls + '" tabindex="0"></img>';

The following excerpt from the JavaScript for this example updates the value of the "aria-valuenow" attribute when the value of the slider handle is changed:

 slider.prototype.positionHandle = function($handle, val) {
    ...
   // Set the aria-valuenow position of the handle
  $handle.attr('aria-valuenow', val);
   ...
  }

This slider is available as part of the working example of Example 32 - Slider, on the OpenAjax Alliance site.

Resources

Related Techniques

Tests

Procedure

For a user interface component with the WAI-ARIA role attribute progressbar, scrollbar, slider, or spinbutton (or any other role defined as a subclass of the range abstract class):

  1. If the value for the range widget has a known maximum, check that the aria-valuemax attribute is provided.
  2. If the value for the range widget has a known minimum, check that the aria-valuemin attribute is provided.
  3. If the current value for the range widget is not known, check that the aria-valuenow attribute is not set.
  4. If the current value for the range widget is known, check that the aria-valuenow attribute is set to that value.
  5. If the aria-valuenow attribute is set but cannot be accurately represented as a number, check that the aria-valuetext attribute describes the current value.
  6. Check that the attribute values are updated to reflect the current state when the user interface component changes state.

Expected Results

  • All checks are true