examples/combobox/aria1.1pattern/listbox-combo.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>ARIA 1.1 Combobox with Listbox Popup Examples | WAI-ARIA Authoring Practices 1.1</title>

<!--  Core js and css shared by all examples; do not modify when using this template. -->
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/base.css">
<link rel="stylesheet" href="../../css/core.css">
<script src="../../js/examples.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script src="../../js/app.js"></script>
<script src="../../js/utils.js"></script>

<!--  js and css for this example. -->
<link href="css/combobox-1.1.css" rel="stylesheet">
<script src="js/listbox-combobox.js"></script>
<script src="js/listbox-combo-example.js"></script>
</head>
<body>
  <nav aria-label="Related Links" class="feedback">
    <ul>
      <li><a href="../../../#browser_and_AT_support">Browser and Assistive Technology Support</a></li>
      <li><a href="https://github.com/w3c/aria-practices/issues/new">Report Issue</a></li>
      <li><a href="https://github.com/w3c/aria-practices/projects/7">Related Issues</a></li>
      <li><a href="../../../#combobox">Design Pattern</a></li>
    </ul>
  </nav>
  <main>
    <h1>ARIA 1.1 Combobox with Listbox Popup Examples</h1>
    <p>
      The following three example comboboxes implement the ARIA 1.1 form of the
      <a href="../../../#combobox">combobox design pattern</a>
      using a listbox popup.
      Each of the three comboboxes also demonstrates a different form of the autocomplete behaviors described in the design pattern.
    </p>
    <p>
      In these examples, users can specify the name of a fruit or vegetable by either typing a value in the box or choosing from the list.
      The list becomes available after the textbox contains a character that matches the beginning of the name of one of the items in the list of suggested values.
      Users may type any value in the textbox; this implementation does not limit input to values that are in the list of suggested values.
    </p>
    <p>Similar examples include: </p>
    <ul>
      <li><a href="grid-combo.html">ARIA 1.1 Combobox with Grid Popup</a>: A combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.</li>
      <li><a href="../aria1.0pattern/combobox-autocomplete-both.html">ARIA 1.0 Combobox with Both List and Inline Autocomplete</a>: A combobox that demonstrates the autocomplete behavior known as <q>list with inline autocomplete</q> and uses the ARIA 1.0 implementation pattern.</li>
      <li><a href="../aria1.0pattern/combobox-autocomplete-list.html">ARIA 1.0 Combobox with List Autocomplete</a>: A combobox that demonstrates the autocomplete behavior known as <q>list with manual selection</q> and uses the ARIA 1.0 implementation pattern.</li>
      <li><a href="../aria1.0pattern/combobox-autocomplete-none.html">ARIA 1.0 Combobox Without Autocomplete</a>: A combo box that demonstrates the behavior associated with <code>aria-autocomplete=none</code> and uses the ARIA 1.0 implementation pattern.</li>
    </ul>
  
    <section>
      <h2 id="ex_label">Examples</h2>
      <h3 id="ex1_label">Example 1: List Autocomplete with Manual Selection</h3>
      <div role="separator" id="ex1_start_sep" aria-labelledby="ex1_start_sep ex1_label" aria-label="Start of"></div>
      <div id="ex1">
        <label id="ex1-label" class="combobox-label">
          Choice 1 Fruit or Vegetable
        </label>
        <div class="combobox-wrapper">
          <div role="combobox"
            aria-expanded="false"
            aria-owns="ex1-listbox"
            aria-haspopup="listbox"
            id="ex1-combobox">
            <input type="text"
              aria-autocomplete="list"
              aria-controls="ex1-listbox"
              aria-labelledby="ex1-label"
              id="ex1-input">
          </div>
          <ul
            aria-labelledby="ex1-label"
            role="listbox"
            id="ex1-listbox"
            class="listbox hidden">
          </ul>
        </div>
      </div>
      <div role="separator" id="ex1_end_sep" aria-labelledby="ex1_end_sep ex1_label" aria-label="End of"></div>
      <h4>Notes</h4>
      <p>List autocomplete with manual selection means that:</p>
      <ol>
        <li>
          When the listbox popup is displayed, it contains suggested values that complete or logically correspond to the characters typed in the textbox.
          In this implementation, the values in the listbox have names that start with the characters typed in the textbox.
        </li>
        <li>Users may set the value of the combobox by choosing a value from the list of suggested values.</li>
        <li>If the user does not choose a value from the listbox before moving focus outside the combobox, the value that the user typed, if any, becomes the value of the combobox.</li>
      </ol>
      <h3 id="ex2_label">Example 2: List Autocomplete with Automatic Selection</h3>
      <div role="separator" id="ex2_start_sep" aria-labelledby="ex2_start_sep ex2_label" aria-label="Start of"></div>
      <div id="ex2">
        <label id="ex2-label" class="combobox-label">
          Choice 2 Fruit or Vegetable
        </label>
        <div class="combobox-wrapper">
          <div role="combobox" 
            aria-expanded="false"
            aria-owns="ex2-listbox"
            aria-haspopup="listbox"
            id="ex2-combobox">
            <input type="text"
              aria-autocomplete="list"
              aria-controls="ex2-listbox"
              aria-labelledby="ex2-label"
              id="ex2-input">
          </div>
          <ul
            aria-labelledby="ex2-label"
            role="listbox"
            id="ex2-listbox"
            class="listbox hidden">
          </ul>
        </div>
      </div>
      <div role="separator" id="ex2_end_sep" aria-labelledby="ex2_end_sep ex2_label" aria-label="End of"></div>
      <h4>Notes</h4>
      <p>List autocomplete with automatic selection means that:</p>
      <ol>
        <li>
          When the listbox popup is displayed, it contains suggested values that complete or logically correspond to the characters typed in the textbox.
          In this implementation, the values in the listbox have names that start with the characters typed in the textbox.
        </li>
        <li>The first suggestion is automatically highlighted as selected.</li>
        <li>The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox.</li>
      </ol>
      <h3 id="ex3_label">Example 3: List with Inline Autocomplete</h3>
      <div role="separator" id="ex3_start_sep" aria-labelledby="ex3_start_sep ex3_label" aria-label="Start of"></div>
      <div id="ex3">
        <label id="ex3-label" class="combobox-label">
          Choice 3 Fruit or Vegetable
        </label>
        <div class="combobox-wrapper">
          <div role="combobox"
            aria-expanded="false"
            aria-owns="ex3-listbox"
            aria-haspopup="listbox"
            id="ex3-combobox">
            <input type="text"
              aria-autocomplete="both"
              aria-controls="ex3-listbox"
              aria-labelledby="ex3-label"
              id="ex3-input">
            <div
              class="combobox-dropdown"
              id="ex3-combobox-arrow"
              tabindex="-1"
              role="button"
              aria-label="Show vegetable options">
              <img src="imgs/arrow_drop_down_grey_27x27.png" alt="">
            </div>
          </div>
          <ul
            aria-labelledby="ex3-label"
            role="listbox"
            id="ex3-listbox"
            class="listbox hidden">
          </ul>
        </div>
      </div>
      <div role="separator" id="ex3_end_sep" aria-labelledby="ex3_end_sep ex3_label" aria-label="End of"></div>
      <h4>Notes</h4>
      <p>List with inline autocomplete means that:</p>
      <ol>
        <li>With the exception of one additional feature, this example has the same autocomplete behavior as the previous example that has list with automatic selection.</li>
        <li>The additional feature is that the portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox.</li>
        <li>The inline completion string is visually highlighted and has a selected state.</li>
      </ol>
    </section>

    <section>
      <h2 id="kbd_label">Keyboard Support</h2>
      <p>
      The example comboboxes on this page implement the following keyboard interface. 
        Other variations and options for the keyboard interface are described in the  
        <a href="../../../#combobox_kbd_interaction">Keyboard Interaction section of the combobox design pattern.</a>
      </p>
      <h3 id="kbd_label_textbox">Textbox</h3>
      <table aria-labelledby="kbd_label_textbox kbd_label" class="def">
        <thead>
          <tr>
            <th>Key</th>
            <th>Function</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <th><kbd>Down Arrow</kbd></th>
            <td>
              <ul>
                <li>If the listbox is displayed:
                  <ul>
                    <li>Example 1: Moves focus to the first suggested value.</li>
                    <li>Examples 2 and 3: Moves focus to the second suggested value. Note that the first value is automatically selected.</li>
                  </ul>
                </li>
                <li>If the listbox is not displayed, in example 3 only, opens the listbox and moves focus to the first value.</li>           
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Up Arrow</kbd></th>
            <td>
              <ul>
                <li>If the listbox is displayed, moves focus to the last suggested value.</li>
                <li>If the listbox is not displayed, in example 3 only, opens the listbox and moves focus to the last value.</li>           
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Enter</kbd></th>
            <td>
              <ul>
                <li>Example 1: Does nothing.</li>
                <li>Examples 2 and 3: If the listbox is displayed and the first option is automatically selected:
                  <ul>
                    <li>Sets the textbox value to the content of the selected option.</li>
                    <li>Closes the listbox.</li>
                  </ul>
                </li>
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Escape</kbd></th>
            <td>
              <ul>
                <li>Clears the textbox</li>
                <li>If the listbox is displayed, closes it.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <th>Standard single line text editing keys</th>
            <td>
              <ul>
                <li>Keys used for cursor movement and text manipulation, such as <kbd>Delete</kbd> and <kbd>Shift + Right Arrow</kbd>.</li>
                <li>An HTML <code>input</code> with <code>type=<q>text</q></code> is used for the textbox so the browser will provide platform-specific editing keys.</li>
              </ul>
            </td>
          </tr>
        </tbody>
      </table>
      <h3 id="kbd_label_listbox">Listbox Popup</h3>
      <p>
        <strong>NOTE:</strong> When visual focus is in the listbox, DOM focus remains on the textbox and the value of <code>aria-activedescendant</code> on the textbox is set to a value that refers to the listbox option that is visually indicated as focused.
        Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator.
        For more information about this focus management technique, see 
        <a href="../../../#kbd_focus_activedescendant">Using aria-activedescendant to Manage Focus.</a>
      </p>
      <table aria-labelledby="kbd_label_listbox kbd_label" class="def">
        <thead>
          <tr>
            <th>Key</th>
            <th>Function</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <th><kbd>Enter</kbd></th>
            <td>
              <ul>
                <li>Sets the textbox value to the content of the focused option in the listbox.</li>
                <li>Closes the listbox.</li>
                <li>Sets focus on the textbox.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Escape</kbd></th>
            <td>
              <ul>
                <li>Closes the listbox.</li>
                <li>Sets focus on the textbox.</li>
                <li>Clears the textbox.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Down Arrow</kbd></th>
            <td>
              <ul>
                <li>Moves focus to the next option.</li>
                <li>If focus is on the last option, moves focus to the first option.</li>
                <li>Note: This wrapping behavior is useful when <kbd>Home</kbd> and <kbd>End</kbd> move the editing cursor as described below.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Up Arrow</kbd></th>
            <td>
              <ul>
                <li>Moves focus to the previous option.</li>
                <li>If focus is on the first option, moves focus to the last option.</li>
                <li>Note: This wrapping behavior is useful when <kbd>Home</kbd> and <kbd>End</kbd> move the editing cursor as described below.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <th><kbd>Right Arrow</kbd></th>
            <td>Moves focus to the textbox and moves the editing cursor one character to the right.</td>
          </tr>
          <tr>
            <th><kbd>Left Arrow</kbd></th>
            <td>Moves focus to the textbox and moves the editing cursor one character to the leftt.</td>
          </tr>
          <tr>
            <th><kbd>Home</kbd></th>
            <td>Moves focus to the textbox and places the editing cursor at the beginning of the field.</td>
          </tr>
          <tr>
            <th><kbd>End</kbd></th>
            <td>Moves focus to the textbox and places the editing cursor at the end of the field.</td>
          </tr>
          <tr>
            <th>Printable Characters</th>
            <td>
              <ul>
                <li>Moves focus to the textbox.</li>
                <li>Types the character in the textbox.</li>
              </ul>
            </td>
          </tr>
        </tbody>
      </table>
    </section>

    <section>
      <h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
      <p>
        The example comboboxes on this page implement the following ARIA roles, states, and properties. 
        Information about other ways of applying ARIA roles, states, and properties is available in the    
        <a href="../../../#combobox_roles_states_props">Roles, States, and Properties section of the combobox design pattern.</a>
      </p>
      <h3 id="rps_label_combobox">Combobox Container</h3>
      <table aria-labelledby="rps_label_combobox rps_label" class="data attributes">
        <thead>
          <tr>
            <th scope="col">Role</th>
            <th scope="col">Attribute</th>
            <th scope="col">Element</th>
            <th scope="col">Usage</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <th scope="row">
              <code>combobox</code>
            </th>
            <td></td>
            <td><code>div</code></td>
            <td>
              <ul>
                <li>Identifies the element as a combobox.</li>
                <li>Note: The primary difference between the ARIA 1.0 pattern and the ARIA 1.1 pattern is the placement of the <code>combobox</code> role.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-haspopup=<q>listbox</q></code>
            </th>
            <td><code>div</code></td>
            <td>
              <ul>
                <li>Indicates that the combobox can popup a <code>listbox</code> to suggest values.</li>
                <li>This is the default value for elements with the <code>combobox</code> role.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-owns=<q>IDREF</q></code>
            </th>
            <td><code>div</code></td>
            <td>Identifies the element that serves as the listbox popup.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-expanded=<q>false</q></code>
            </th>
            <td><code>div</code></td>
            <td>Indicates that the popup element <strong>is not</strong> displayed.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-expanded=<q>true</q></code>
            </th>
            <td><code>div</code></td>
            <td>Indicates that the popup element <strong>is</strong> displayed.</td>
          </tr>
        </tbody>
      </table>
      <h3 id="rps_label_textbox">Textbox</h3>
      <table aria-labelledby="rps_label_textbox rps_label" class="data attributes">
        <thead>
          <tr>
            <th scope="col">Role</th>
            <th scope="col">Attribute</th>
            <th scope="col">Element</th>
            <th scope="col">Usage</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-labelledby=<q>IDREF</q></code>
            </th>
            <td><code>input[type="text"]</code></td>
            <td>Provides a label for the textbox element of the combobox.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-autocomplete=<q>list</q></code>
            </th>
            <td><code>input[type="text"]</code></td>
            <td>Examples 1 and 2: Indicates that the autocomplete behavior of the text input is to suggest a list of possible values in a popup and that the suggestions are related to the string that is present in the textbox.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-autocomplete=<q>both</q></code>
            </th>
            <td><code>input[type="text"]</code></td>
            <td>Example 3: Indicates that the autocomplete behavior of the text input is to both show an inline completion string and suggest a list of possible values in a popup where the suggestions are related to the string that is present in the textbox.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-controls=<q>IDREF</q></code>
            </th>
            <td><code>input[type="text"]</code></td>
            <td>
              <ul>
                <li>Identifies the popup element that lists suggested values.</li>
                <li>Note: In the ARIA 1.0 combobox pattern, the textbox uses <code>aria-owns</code> instead of <code>aria-controls</code>.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-activedescendant=<q>IDREF</q></code>
            </th>
            <td><code>input[type="text"]</code></td>
            <td>
              <ul>
                <li>When an option in the listbox is visually indicated as having keyboard focus, refers to that option.</li>
                <li>When navigation keys, such as <kbd>Down Arrow</kbd>, are pressed, the JavaScript changes the value.</li>
                <li>Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the <code>input</code> element.</li>
                <li>
                  For more information about this focus management technique, see 
                  <a href="../../../#kbd_focus_activedescendant">Using aria-activedescendant to Manage Focus.</a>
                </li>
              </ul>
            </td>
          </tr>
        </tbody>
      </table>
      <h3 id="rps_label_listbox">Listbox Popup</h3>
      <table aria-labelledby="rps_label_listbox rps_label" class="data attributes">
        <thead>
          <tr>
            <th scope="col">Role</th>
            <th scope="col">Attribute</th>
            <th scope="col">Element</th>
            <th scope="col">Usage</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <th scope="row">
              <code>listbox</code>
            </th>
            <td></td>
            <td>
              <code>ul</code>
            </td>
            <td>Identifies the <code>ul</code> element as a <code>listbox</code>.</td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-labelledby=<q>IDREF</q></code>
            </th>
            <td><code>ul</code></td>
            <td>Provides a label for the <code>listbox</code> element of the combobox.</td>
          </tr>
          <tr>
            <th scope="row">
              <code>option</code>
            </th>
            <td></td>
            <td><code>li</code></td>
            <td>
              <ul>
                <li>Identifies the element as a <code>listbox</code> <code>option</code>.</li>
                <li>The text content of the element provides the accessible name of the <code>option</code>.</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td></td>
            <th scope="row">
              <code>aria-selected=<q>true</q></code>
            </th>
            <td><code>li</code></td>
            <td>
              <ul>
                <li>Specified on an option in the listbox when it is visually highlighted as selected.</li>
                <li>In example 1, occurs only when an option in the list is referenced by <code>aria-activedescendant</code>.</li>
                <li>In examples 2 and 3, also occurs when focus is in the textbox and the first option is automatically selected.</li>
              </ul>
            </td>
          </tr>
        </tbody>
      </table>
    </section>

    <section>
      <h2>Javascript and CSS Source Code</h2>
      <ul>
        <li>CSS: <a href="css/combobox-1.1.css" type="tex/css">combobox-1.1.css</a></li>
        <li>Javascript: <a href="js/listbox-combobox.js">listbox-combobox.js</a></li>
        <li>Javascript: <a href="js/listbox-combo-example.js">listbox-combo-example.js</a></li>
      </ul>
    </section>

    <section>
      <h2 id="sc_label">HTML Source Code</h2>
      <h3 id="sc1_label">Example 1</h3>
      <div role="separator" id="sc1_start_sep" aria-labelledby="sc1_start_sep sc1_label sc_label" aria-label="Start of"></div>
      <pre><code id="sc1"></code></pre>
      <div role="separator" id="sc1_end_sep" aria-labelledby="sc1_end_sep sc1_label sc_label" aria-label="End of"></div>
      <h3 id="sc2_label">Example 2</h3>
      <div role="separator" id="sc2_start_sep" aria-labelledby="sc2_start_sep sc2_label sc_label" aria-label="Start of"></div>
      <pre><code id="sc2"></code></pre>
      <div role="separator" id="sc2_end_sep" aria-labelledby="sc2_end_sep sc2_label sc_label" aria-label="End of"></div>
      <h3 id="sc3_label">Example 3</h3>
      <div role="separator" id="sc3_start_sep" aria-labelledby="sc3_start_sep sc3_label sc_label" aria-label="Start of"></div>
      <pre><code id="sc3"></code></pre>
      <div role="separator" id="sc3_end_sep" aria-labelledby="sc3_end_sep sc3_label sc_label" aria-label="End of"></div>
      <script>
        sourceCode.add('sc1', 'ex1');
        sourceCode.add('sc2', 'ex2');
        sourceCode.add('sc3', 'ex3');
        sourceCode.make();
      </script>
    </section>
  </main>
  <nav>
    <a href="../../../#combobox">combobox design pattern in WAI-ARIA Authoring Practices 1.1</a>
  </nav>
</body>
</html>