Skip to content

Commit

Permalink
Add guidance section for range related properties (pull #1279)
Browse files Browse the repository at this point in the history 
Resolves issue #255 by adding a section 
That describes how to use aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext.

Co-authored-by: Valerie R Young <[email protected]>
Co-authored-by: Matt King <[email protected]>
Co-authored-by: Carolyn MacLeod <[email protected]>
Co-authored-by: JaEun Jemma Ku <[email protected]>
  • Loading branch information
@zcorpan @mcking65
@carmacleod @a11ydoer
5 people authored Jul 7, 2020
1 parent 33cb0ba commit 7efa6e5
Showing 1 changed file with 310 additions and 0 deletions.
310 changes: 310 additions & 0 deletions aria-practices.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6426,6 +6426,316 @@ <h3>Indicating sort order with <code>aria-sort</code></h3>

</section>

<section id="range_related_properties">
<h2>Communicating Value and Limits for Range Widgets</h2>
<p>
ARIA defines the following roles as range widgets, which means they communicate a value that is typically numeric and constrained to defined limits.
</p>
<ul>
<li><code>meter</code></li>
<li><code>progressbar</code></li>
<li><code>scrollbar</code></li>
<li><code>separator</code> (if focusable)</li>
<li><code>slider</code></li>
<li><code>spinbutton</code></li>
</ul>
<p>
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.
</p>
<p>
This section describes considerations for using the following four properties that communicate characteristics of a range widget:
</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<th><code>aria-valuemin</code></th>
<td>Defines the minimum value allowed by a range widget.</td>
</tr>
<tr>
<th><code>aria-valuemax</code></th>
<td>Defines the maximum value allowed by a range widget.</td>
</tr>
<tr>
<th><code>aria-valuenow</code></th>
<td>Defines the current value of a range widget. This value is a number greater than or equal to <code>aria-valuemin</code> and less than or equal to <code>aria-valuemax</code> (if they are specified).</td>
</tr>
<tr>
<th><code>aria-valuetext</code></th>
<td>If a numeric value is not sufficiently descriptive, this property can define a text description of the current value of a range widget.</td>
</tr>
</tbody>
</table>

<section id="range_related_properties_using_aria-valuemin_aria-valuemax_and_aria-valuenow">
<h3>Using <code>aria-valuemin</code>, <code>aria-valuemax</code> and <code>aria-valuenow</code></h3>
<p>
When the value of a range widget is constrained to known limits, the <code>aria-valuemin</code> and <code>aria-valuemax</code> 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 <code>aria-valuemin</code> to the lowest value allowed for the widget and <code>aria-valuemax</code> to the highest allowed value.
If values for <code>aria-valuemin</code> and <code>aria-valuemax</code> are not set, default values are exposed to assistive technologies unless the widget is a <code>spinbutton</code>, which is the only range widget that does not have default limits.
</p>
<p>
The <code>aria-valuenow</code> property is used to inform assistive technologies of the current value of a range widget.
Set <code>aria-valuenow</code> to the current value of the widget, ensuring the value of <code>aria-valuenow</code> falls within the range defined by <code>aria-valuemin</code> and <code>aria-valuemax</code>.
If the current value of a <code>progressbar</code> or <code>spinbutton</code> is indeterminate or unknown, omit the <code>aria-valuenow</code> property.
The <code>aria-valuenow</code> property is required for the <code>meter</code>, <code>scrollbar</code>, <code>separator</code> (if the element is focusable), and <code>slider</code> roles.
</p>
<p>
The range widget roles have the following default values and requirements for <code>aria-valuemin</code>, <code>aria-valuemax</code> and <code>aria-valuenow</code>.
</p>
<table>
<thead>

<tr>
<th scope="col">Role</th>
<th scope="col"><code>aria-valuemin</code><br>(default)</th>
<th scope="col"><code>aria-valuemax</code><br>(default)</th>
<th scope="col"><code>aria-valuemin</code><br>(required)</th>
<th scope="col"><code>aria-valuemax</code><br>(required)</th>
<th scope="col"><code>aria-valuenow</code><br>(required)</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row"><code>meter</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>progressbar</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<th scope="row"><code>scrollbar</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>separator</code> <small>(if focusable)</small></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>slider</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>spinbutton</code></th>
<td>None</td>
<td>None</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
</tbody>
</table>
</section>

<section id="range_related_properties_using_aria-valuetext">
<h3>Using <code>aria-valuetext</code></h3>

<p>
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,
<code>aria-valuetext</code> is used to surface the text value to assistive technologies.
Only use <code>aria-valuetext</code> when <code>aria-valuenow</code> is not sufficiently meaningful for users because using <code>aria-valuetext</code> will prevent assistive technologies from communicating <code>aria-valuenow</code>.
</p>

<div class="example">
<p>
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.
</p>

<pre><code>
&lt;span id="battery-label">Battery&lt;/span>
&lt;span role="meter" aria-labelledby="battery-label"
aria-valuenow="5"
aria-valuetext="5%, 18 minutes remaining.">
&lt;/span>
</code></pre>
</div>
</section>

<section id="range_related_properties_meter_role">
<h3>Range properties with meter</h3>
<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for elements with role <code>meter</code> 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 <code>aria-valuenow</code> 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 <code>meter</code> role is in the <a href="#meter">meter design pattern</a>.</p>

<p>This example of a meter shows the current Central Processing Unit (CPU) usage. </p>

<pre><code>&lt;span id="cpu_usage_label">CPU usage&lt;/span>
&lt;!-- The CPU usage uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;div role="meter"
aria-valuenow="90"
aria-labelledby="cpu_usage_label"&gt;
&lt;/div&gt;</code></pre>

<p>
The <code>aria-valuetext</code> property can be set to a string that makes the meter value understandable. For example, a CPU usage meter value might be conveyed as <code>aria-valuetext="90% of CPU is being used"</code>.
</p>
<p>Here is another example of a meter that has a range different from the default of 0 for <code>aria-valuemin</code> and 100 for <code>aria-valuemax</code>.</p>

<pre><code>&lt;span id="ph_alkaline_meter_label">Alkaline pH(Power of Hydrogen) Level&lt;/span>
&lt;div role="meter"
aria-valuenow="9"
aria-valuemin="7"
aria-valuemax="14"
aria-labelledby="ph_alkaline_meter_label"&gt;
&lt;/div&gt;</code></pre>
</section>
<section id="range_related_properties_progressbar_role">
<h3>Range properties with progress bars</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>progressbar</code> 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 <code>progressbar</code> if its value is known (e.g. not indeterminate).
If the <code>aria-valuenow</code> property is set, the author needs to make sure it is within the minimum and maximum values.
</p>
<p>Following is an example of a progress bar represented by an SVG.</p>

<pre><code>&lt;div&gt;&lt;span id="loadlabel"&gt;Loading:&lt;/span&gt;
&lt;!-- The progress bar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;span role="progressbar"
aria-labelledby="loadlabel"
aria-valuenow="33" &gt;
&lt;svg width="100" height="10"&gt;
&lt;rect x="0" y="0" height="10" width="100" stroke="black" fill="none"/&gt;
&lt;rect x="0" y="0" height="10" width="33" fill="green" /&gt;
&lt;/svg&gt;
&lt;/span&gt;
&lt;/div&gt;</code></pre>
<p>This progress bar can also be made using the native HTML <code>progress</code> element.</p>

<pre><code>&lt;label for="loadstatus"&gt;Loading:&lt;/label&gt;
&lt;progress id="loadstatus" max="100" value="33"&gt;&lt;/progress&gt;
</code></pre>

<p>To represent an indeterminate progress bar where the value range is unknown, omit the <code>aria-valuenow</code> attribute.</p>

<pre><code>&lt;img role="progressbar" src="spinner.gif" alt="Loading..."&gt;</code></pre>
</section>

<section id="range_related_properties_scrollbar_role">
<h3>Range properties with scrollbars</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>scrollbar</code> role when it's minimum value is not 0 or the maximum value is not 100. The <code>aria-valuenow</code> property is required for <code>scrollbar</code> and the author needs to make sure it is within the minimum and maximum values.
</p>
<p>
<code>aria-valuenow</code> will generally be exposed as a percentage between <code>aria-valuemin</code> and <code>aria-valuemax</code> calculated by assistive technologies.
</p>

<pre><code>&lt;span id="pi-label"&gt;Pi&lt;/div&gt;
&lt;div id="pi"&gt;
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
&lt;/div&gt;
&lt;div class="rail"&gt;
&lt;!-- The scrollbar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;div
class="thumb"
role="scrollbar"
aria-labelledby="pi-label"
aria-controls="pi"
aria-orientation="horizontal"
aria-valuenow="25"&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>


</section>

<section id="range_related_properties_slider_role">
<h3>Range properties with sliders</h3>
<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>slider</code> role when the slider's minimum is not 0 or the maximum value is not 100.
The <code>aria-valuenow</code> property is required for <code>slider</code> role and the author needs to make sure it is within the minimum and maximum values.
A detailed description of the <code>slider</code> role can be found in the <a href="#slider">slider design pattern</a> and <a href="#slidertwothumb">slider (multi-thumb) design pattern</a>.
</p>
<p>
The following example shows a temperature controller.
In this example, <code>aria-valuenow</code> is meaningful to the user, and so <code>aria-valuetext</code> is not used.
</p>
<pre><code>&lt;div class="rail"&gt;
&lt;div id="thumb" role="slider" aria-valuemin="50" aria-valuenow="68" aria-valuemax="100"
aria-label="Temperature (F)" tabindex="0"&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>The slider example above can be made using the HTML <code>&lt;input type="range"></code> element.</p>
<pre><code>&lt;input type="range" min="50" value="68" max="100" aria-label="Temperature (F)"&gt;
</code></pre><p>The following example is a fan control. The <code>aria-valuenow</code> value is "1", which is not meaningful to the user. The <code>aria-valuetext</code> property is used so that assistive technology will surface its value ("low") instead.</p>
<pre><code>&lt;div class="rail"&gt;
&lt;div id="thumb" role="slider" aria-valuemin="0" aria-valuenow="1" aria-valuemax="3"
aria-valuetext="low" aria-label="Fan speed" tabindex="0" &gt;
&lt;/div&gt;
&lt;div class="value"&gt; Off &lt;/div&gt;
&lt;div class="value"&gt; Low &lt;/div&gt;
&lt;div class="value"&gt; Medium &lt;/div&gt;
&lt;div class="value"&gt; High &lt;/div&gt;
&lt;/div&gt;</code></pre>
</section>

<section id="range_related_properties_spinbutton_role">
<h3>Range properties with spin buttons</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties are used only when a <code>spinbutton</code> 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 <code>aria-valuenow</code> property is set only when a <code>spinbutton</code> has a value.
If it is not set, a value is not exposed to assistive technologies for the <code>spinbutton</code>.
<code>aria-valuetext</code> can be used when appropriate.
A detailed description of the <code>spinbutton</code> role can be found in the <a href="#spinbutton">spinbutton design pattern</a>.
</p>

<p>The following example sets the price of paperclips in cents.</p>

<pre><code>&lt;div role="spinbutton" aria-labelledby="price-label" aria-valuenow="50" tabindex="0"&gt;
&lt;button id="lower-price"&gt;Lower&lt;/button&gt;
&lt;button id="raise-price"&gt;Raise&lt;/button&gt;
&lt;span id="price-label"&gt;Price per paperclip: $&lt;/span&gt;&lt;span id="price"&gt;0.50&lt;/span&gt;
&lt;/div&gt;</code></pre>

<p>If there are minimum and maximum allowed values, set the <code>aria-valuemin</code> and <code>aria-valuemax</code> properties.</p>

<pre><code>&lt;div role="spinbutton" aria-labelledby="price-label"
aria-valuemin="1" aria-valuenow="50" aria-valuemax="200" tabindex="0"&gt;
&lt;button id="lower-price"&gt;Lower&lt;/button&gt;
&lt;button id="raise-price"&gt;Raise&lt;/button&gt;
&lt;span id="price-label"&gt;Price per paperclip: $&lt;/span&gt;&lt;span id="price"&gt;0.50&lt;/span&gt;
&lt;/div&gt;</code></pre>

<p>The spin button example above can be made using the native HTML <code>&lt;input type="number"></code> element.</p>

<pre><code>&lt;label&gt;Price per paperclip: $&lt;input type="number" min="0.01" value="0.5" max="2" step="0.01"&gt;&lt;/label&gt;</code></pre>
</section>
</section>

<section id="presentation_role">
<h2>Intentionally Hiding Semantics with the <code>presentation</code> Role</h2>
<p>
Expand Down

0 comments on commit 7efa6e5

Please sign in to comment.