content/patterns/spinbutton/spinbutton-pattern.html - external/github.com/w3c/aria-practices - Git at Google

 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="UTF-8">
     <meta content="width=device-width, initial-scale=1.0" name="viewport">
     <title>Spinbutton Pattern</title>

     <!-- Core JS and CSS shared by all patterns -->
     <link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/base.css">
     <link rel="stylesheet" href="../../shared/css/core.css">
     <script src="../../shared/js/highlight.pack.js"></script>
     <script src="../../shared/js/app.js"></script>
     <script data-skipto="colorTheme:aria; displayOption:popup; containerElement:div" src="../../shared/js/skipto.js"></script>
   </head>
   <body>
     <main>
       <h1>Spinbutton Pattern</h1>

       <section id="about">
         <h2>About This Pattern</h2>
         <p>
           A spinbutton is an input widget that restricts its value to a set or range of discrete values.
           For example, in a widget that enables users to set an alarm, a spinbutton could allow users to select a number from 0 to 59 for the minute of an hour.
         </p>
         <p>
           Spinbuttons often have three components, including a text field that displays the current value, an increase button, and a decrease button.
           The text field is usually the only focusable component because the increase and decrease functions are keyboard accessible via arrow keys.
           Typically, the text field also allows users to directly edit the value.
         </p>
         <p>
           If the range is large, a spinbutton may support changing the value in both small and large steps.
           For instance, in the alarm example, the user may be able to move by 1 minute with <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> and by 10 minutes with <kbd>Page Up</kbd> and <kbd>Page Down</kbd>.
         </p>
       </section>

       <section id="examples">
         <img alt="" src="../../images/pattern-spinbutton.svg">
         <h2>Example</h2>
         <p><a href="examples/datepicker-spinbuttons.html">Date Picker Spin Button Example:</a> Illustrates a date picker made from three spin buttons for day, month, and year.</p>
       </section>

       <section id="keyboard_interaction">
         <h2>Keyboard Interaction</h2>
         <ul>
           <li><kbd>Up Arrow</kbd>: Increases the value.</li>
           <li><kbd>Down Arrow</kbd>: Decreases the value.</li>
           <li><kbd>Home</kbd>: If the spinbutton has a minimum value, sets the value to its minimum.</li>
           <li><kbd>End</kbd>: If the spinbutton has a maximum value, sets the value to its maximum.</li>
           <li><kbd>Page Up</kbd> (Optional): Increases the value by a larger step than <kbd>Up Arrow</kbd>.</li>
           <li><kbd>Page Down</kbd> (Optional): Decreases the value by a larger step than <kbd>Down Arrow</kbd>.</li>
           <li>
             If the spinbutton text field allows directly editing the value, the following keys are supported:
             <ul>
               <li>Standard single line text editing keys appropriate for the device platform (see note below).</li>
               <li>
                 Printable Characters: Type characters in the textbox.
                 Note that many implementations allow only certain characters as part of the value and prevent input of any other characters.
                 For example, an hour-and-minute spinner would allow only integer values from 0 to 59, the colon ':', and the letters 'AM' and 'PM'. Any other character input does not change the contents of the text field nor the value of the spinbutton.
               </li>
             </ul>
           </li>
         </ul>
         <div class="note">
           <h3>Note</h3>
           <ol>
             <li>Focus remains on the text field during operation.</li>
             <li>
               Standard single line text editing keys appropriate for the device platform:
               <ol>
                 <li>include keys for input, cursor movement, selection, and text manipulation.</li>
                 <li>Standard key assignments for editing functions depend on the device operating system.</li>
                 <li>The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the <code>contenteditable</code> HTML attribute.</li>
                 <li><strong>IMPORTANT:</strong> Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.</li>
               </ol>
             </li>
           </ol>
         </div>
       </section>

       <section id="roles_states_properties">
         <h2>WAI-ARIA Roles, States, and Properties</h2>
         <ul>
           <li>
             The focusable element serving as the spinbutton has role <a class="role-reference" href="#spinbutton">spinbutton</a>.
             This is typically an element that supports text input.
           </li>
           <li>The spinbutton element has the <a class="property-reference" href="#aria-valuenow">aria-valuenow</a> property set to a decimal value representing the current value of the spinbutton.</li>
           <li>The spinbutton element has the <a class="property-reference" href="#aria-valuemin">aria-valuemin</a> property set to a decimal value representing the minimum allowed value of the spinbutton if it has a known minimum value.</li>
           <li>The spinbutton element has the <a class="property-reference" href="#aria-valuemax">aria-valuemax</a> property set to a decimal value representing the maximum allowed value of the spinbutton if it has a known maximum value.</li>
           <li>
             If the value of <code>aria-valuenow</code> is not user-friendly, e.g., the day of the week is represented by a number, the <a class="property-reference" href="#aria-valuetext">aria-valuetext</a> property is set on the spinbutton element to a string that makes the spinbutton value understandable, e.g., &quot;Monday&quot;.
           </li>
           <li>
             If the spinbutton has a visible label, it is referenced by <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> on the spinbutton element.
             Otherwise, the spinbutton element has a label provided by <a href="#aria-label" class="property-reference">aria-label</a>.
           </li>
           <li>
             The spinbutton element has <a href="#aria-invalid" class="state-reference">aria-invalid</a> set to <code>true</code> if the value is outside the allowed range.
             Note that most implementations prevent input of invalid values, but in some scenarios, blocking all invalid input may not be practical.
           </li>
         </ul>
       </section>
     </main>
   </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8">
	<meta content="width=device-width, initial-scale=1.0" name="viewport">
	<title>Spinbutton Pattern</title>

	<!-- Core JS and CSS shared by all patterns -->
	<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/base.css">
	<link rel="stylesheet" href="../../shared/css/core.css">
	<script src="../../shared/js/highlight.pack.js"></script>
	<script src="../../shared/js/app.js"></script>
	<script data-skipto="colorTheme:aria; displayOption:popup; containerElement:div" src="../../shared/js/skipto.js"></script>
	</head>
	<body>
	<main>
	<h1>Spinbutton Pattern</h1>

	<section id="about">
	<h2>About This Pattern</h2>
	<p>
	A spinbutton is an input widget that restricts its value to a set or range of discrete values.
	For example, in a widget that enables users to set an alarm, a spinbutton could allow users to select a number from 0 to 59 for the minute of an hour.
	</p>
	<p>
	Spinbuttons often have three components, including a text field that displays the current value, an increase button, and a decrease button.
	The text field is usually the only focusable component because the increase and decrease functions are keyboard accessible via arrow keys.
	Typically, the text field also allows users to directly edit the value.
	</p>
	<p>
	If the range is large, a spinbutton may support changing the value in both small and large steps.
	For instance, in the alarm example, the user may be able to move by 1 minute with <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> and by 10 minutes with <kbd>Page Up</kbd> and <kbd>Page Down</kbd>.
	</p>
	</section>

	<section id="examples">
	<img alt="" src="../../images/pattern-spinbutton.svg">
	<h2>Example</h2>
	<p><a href="examples/datepicker-spinbuttons.html">Date Picker Spin Button Example:</a> Illustrates a date picker made from three spin buttons for day, month, and year.</p>
	</section>

	<section id="keyboard_interaction">
	<h2>Keyboard Interaction</h2>
	<ul>
	<li><kbd>Up Arrow</kbd>: Increases the value.</li>
	<li><kbd>Down Arrow</kbd>: Decreases the value.</li>
	<li><kbd>Home</kbd>: If the spinbutton has a minimum value, sets the value to its minimum.</li>
	<li><kbd>End</kbd>: If the spinbutton has a maximum value, sets the value to its maximum.</li>
	<li><kbd>Page Up</kbd> (Optional): Increases the value by a larger step than <kbd>Up Arrow</kbd>.</li>
	<li><kbd>Page Down</kbd> (Optional): Decreases the value by a larger step than <kbd>Down Arrow</kbd>.</li>
	<li>
	If the spinbutton text field allows directly editing the value, the following keys are supported:
	<ul>
	<li>Standard single line text editing keys appropriate for the device platform (see note below).</li>
	<li>
	Printable Characters: Type characters in the textbox.
	Note that many implementations allow only certain characters as part of the value and prevent input of any other characters.
	For example, an hour-and-minute spinner would allow only integer values from 0 to 59, the colon ':', and the letters 'AM' and 'PM'. Any other character input does not change the contents of the text field nor the value of the spinbutton.
	</li>
	</ul>
	</li>
	</ul>
	<div class="note">
	<h3>Note</h3>
	<ol>
	<li>Focus remains on the text field during operation.</li>
	<li>
	Standard single line text editing keys appropriate for the device platform:
	<ol>
	<li>include keys for input, cursor movement, selection, and text manipulation.</li>
	<li>Standard key assignments for editing functions depend on the device operating system.</li>
	<li>The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the <code>contenteditable</code> HTML attribute.</li>
	<li><strong>IMPORTANT:</strong> Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.</li>
	</ol>
	</li>
	</ol>
	</div>
	</section>

	<section id="roles_states_properties">
	<h2>WAI-ARIA Roles, States, and Properties</h2>
	<ul>
	<li>
	The focusable element serving as the spinbutton has role <a class="role-reference" href="#spinbutton">spinbutton</a>.
	This is typically an element that supports text input.
	</li>
	<li>The spinbutton element has the <a class="property-reference" href="#aria-valuenow">aria-valuenow</a> property set to a decimal value representing the current value of the spinbutton.</li>
	<li>The spinbutton element has the <a class="property-reference" href="#aria-valuemin">aria-valuemin</a> property set to a decimal value representing the minimum allowed value of the spinbutton if it has a known minimum value.</li>
	<li>The spinbutton element has the <a class="property-reference" href="#aria-valuemax">aria-valuemax</a> property set to a decimal value representing the maximum allowed value of the spinbutton if it has a known maximum value.</li>
	<li>
	If the value of <code>aria-valuenow</code> is not user-friendly, e.g., the day of the week is represented by a number, the <a class="property-reference" href="#aria-valuetext">aria-valuetext</a> property is set on the spinbutton element to a string that makes the spinbutton value understandable, e.g., "Monday".
	</li>
	<li>
	If the spinbutton has a visible label, it is referenced by <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> on the spinbutton element.
	Otherwise, the spinbutton element has a label provided by <a href="#aria-label" class="property-reference">aria-label</a>.
	</li>
	<li>
	The spinbutton element has <a href="#aria-invalid" class="state-reference">aria-invalid</a> set to <code>true</code> if the value is outside the allowed range.
	Note that most implementations prevent input of invalid values, but in some scenarios, blocking all invalid input may not be practical.
	</li>
	</ul>
	</section>
	</main>
	</body>
	</html>