mozilla

Revision 24916 of Using the progressbar role

  • Revision slug: Accessibility/ARIA/ARIA_Techniques/Using_the_progressbar_role
  • Revision title: Using the progressbar role
  • Revision id: 24916
  • Created:
  • Creator: hhillen
  • Is current revision? No
  • Comment 387 words added, 2 words removed

Revision Content

Description

This technique demonstrates how to use the progressbar role.

The progressbar role should be used for an element that displays the progress status for a task that take a long time or consists of several steps.

A progressbar indicates that the user's request has been received and the application is making progress toward completing the requested action. If the actual value of the progressbar can be determined, the developer has to indicate this progress using the aria-valuenowaria-valuemin, and aria-valuemax attributes. If the progress value  is indeterminate, the developer should omit the aria-valuenow attribute.

As the task progresses, the aria-valuenow value has to be updated dynamically to indicate this progress to assistive technology products. 

If the progressbar is describing the loading progress of a particular region of a page, the author SHOULD use aria-describedby to point to the status, and set the aria-busy attribute to true on the region until it is finished loading. It is not possible for the user to alter the value of a progressbar because it is always readonly.

Note: Assistive technologies generally will render the value of aria-valuenow as a percent of the range between the value of aria-valuemin and aria-valuemax, unless aria-valuetext is specified. It is best to set the values for aria-valuemin, aria-valuemax, and aria-valuenow in a manner that is appropriate for this calculation.
Note: Elements with the role progressbar have an implicit aria-readonly value of true.

Possible effects on user agents and assistive technology 

 

Note: Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: Basic progressbar with percentage values

<div role="preogressbar" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100">20 %</div>

 

Example 2: Using aria-valuetext 

<div role="preogressbar" aria-valuenow="20" aria-valuemin="0" aria-valuetext="Step 2: Copying files... " aria-valuemax="100">
  Step 2: Copying files...
</div>

 

Working Examples:

Notes 

ARIA attributes used

Related ARIA techniques 

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

Revision Source

<h3>Description</h3>
<p>This technique demonstrates how to use the <a class=" external" href="http://www.w3.org/TR/wai-aria/roles#progressbar" title="http://www.w3.org/TR/wai-aria/roles#progressbar"><code>progressbar</code></a> role.</p>
<p>The <code>progressbar</code> role should be used for an element that displays the progress status for a task that take a long time or consists of several steps.</p>
<p>A progressbar indicates that the user's request has been received and the application is making progress toward completing the requested action. If the actual value of the progressbar can be determined, the developer has to indicate this progress using the <a class="property-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuenow"><code>aria-valuenow</code></a>, <a class="property-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemin"><code>aria-valuemin</code></a>, and <code><a class="property-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemax">aria-valuemax</a> </code>attributes. If the progress value  is indeterminate, the developer should omit the <a class="property-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuenow"><code>aria-valuenow</code></a> attribute.</p>
<p>As the task progresses, the <code>aria-valuenow</code> value has to be updated dynamically to indicate this progress to assistive technology products. </p>
<p>If the <code>progressbar</code> is describing the loading progress of a particular region of a page, the author <strong class="rfc2119">SHOULD</strong> use <a class="property-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-describedby"><code>aria-describedby</code></a> to point to the status, and set the <a class="state-reference external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-busy"><code>aria-busy</code></a> attribute to <code>true</code> on the region until it is finished loading. It is not possible for the user to alter the value of a <code>progressbar</code> because it is always readonly.</p>
<pre class="note"><strong>Note: </strong>Assistive technologies generally will render the value of <a class="property-reference" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuenow"><code>aria-valuenow</code></a> as a percent of the range between the value of <a class="property-reference" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemin"><code>aria-valuemin</code></a> and <a class="property-reference" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemax"><code>aria-valuemax</code></a>, unless <a class="property-reference" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuetext"><code>aria-valuetext</code></a> is specified. It is best to set the values for aria-valuemin, aria-valuemax, and aria-valuenow in a manner that is appropriate for this calculation.</pre>
<pre class="note"><strong>Note:</strong> Elements with the role <code>progressbar</code> have an implicit <code>aria-readonly</code> value of <code>true</code>.</pre>
<h3>Possible effects on user agents and assistive technology </h3>
<p> </p>
<div class="note"><strong>Note:</strong> Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.</div>
<h3>Examples</h3>
<h4>Example 1: Basic progressbar with percentage values</h4>
<pre class="brush: html">&lt;div role="preogressbar" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100"&gt;20 %&lt;/div&gt;</pre>
<p> </p>
<h4>Example 2: Using aria-valuetext </h4>
<pre class="brush: html">&lt;div role="preogressbar" aria-valuenow="20" aria-valuemin="0" aria-valuetext="Step 2: Copying files... " aria-valuemax="100"&gt;
  Step 2: Copying files...
&lt;/div&gt;</pre>
<p> </p>
<h4>Working Examples:</h4>

<h3>Notes </h3>
<h3>ARIA attributes used</h3>
<ul> <li><a class=" external" href="http://www.w3.org/TR/wai-aria/roles#progressbar" title="http://www.w3.org/TR/wai-aria/roles#progressbar">progressbar</a></li> <li><a class=" external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuenow" title="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuenow">aria-valuenow</a></li> <li><a class=" external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemin" title="ARIA techniques">aria-valuemin</a></li> <li><a class=" external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemax" title="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuemax">aria-valuemax</a></li> <li><a class=" external" href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuetext" title="http://www.w3.org/TR/wai-aria/states_and_properties#aria-valuetext">aria-valuetext</a></li>
</ul>
<h3>Related ARIA techniques </h3>
<h3>Compatibility</h3>
<p class="comment">TBD: Add support information for common UA and AT product combinations</p>
<h3>Additional resources</h3>
Revert to this revision