Skip to content

Soracom

Design System
Home Design System Elements Autocomplete

Autocomplete

A container for an input and menu used as an autocomplete/type-ahead for the input.

stable dark-mode
This component requires Javascript for certain functionality, and implementing W3C WAI-ARIA accessibility recommendations

Overview 

The autocomplete component is a container for a ds-input and ds-autocomplete__list used as the menu. This component only provides styling and does not provide any javascript required to implement auto-complete functionality.

Options 

Basic usage 

Basic usage 
<div class="ds-autocomplete">
  <div class="ds-input">
    <input type="text" name="test-field">
  </div>
  <ul class="ds-autocomplete__list">
    <li>Anorith</li>
    <li>Arbok</li>
    <li>Arcanine</li>
    <li>Bulbasaur</li>
    <li>Butterfree</li>
    <li>Caterpie</li>
    <li>Charizard</li>
    <li>Charmander</li>
    <li>Charmeleon</li>
    <li>Squirtle</li>
    <li>Venusaur</li>
    <li>Wartortle</li>
  </ul>
</div>
  • Anorith
  • Arbok
  • Arcanine
  • Bulbasaur
  • Butterfree
  • Caterpie
  • Charizard
  • Charmander
  • Charmeleon
  • Squirtle
  • Venusaur
  • Wartortle
<div class="ds-autocomplete">
  <div class="ds-input">
    <input type="text" name="test-field">
  </div>
  <ul class="ds-autocomplete__list">
    <li>Anorith</li>
    <li>Arbok</li>
    <li>Arcanine</li>
    <li>Bulbasaur</li>
    <li>Butterfree</li>
    <li>Caterpie</li>
    <li>Charizard</li>
    <li>Charmander</li>
    <li>Charmeleon</li>
    <li>Squirtle</li>
    <li>Venusaur</li>
    <li>Wartortle</li>
  </ul>
</div>

Input Icons 

See ds-input icons.

List icons 

See ds-menu icons.

List descriptions 

See ds-menu descriptions

Accessibility 

Role and ARIA attributes 

Recommendations for implementing ds-autocomplete to meet W3C WAI-ARIA guidelines are as follows:

Autocomplete container (div)  

<div class="ds-autocomplete"
  role="combobox"
  aria-haspopup="listbox"
  aria-expanded="true|false"
  aria-owns="[ID]">
  ...
</div>
Element Attribute Required Type Description
<div> role="combobox" Required Static Indicates the div is a combobox
aria-haspopup="listbox" Required Static Indicates the div can open an autocomplete list
aria-owns="[ID]" Required Static Refers to the ID of the autocomplete list
aria-expanded="true|false" Required Dynamic 1. Set to true when the list is open
2. Removed or set to false when the list is closed

Autocomplete textbox (input)  

<div class="ds-input">
  <input type="text"
    id="[ID]"
    aria-autocomplete="list"
    aria-controls="[ID]"
    aria-activedescendant="[ID]">
</div>
Element Attribute Required Type Description
<input type="text"> id="[ID]" Required Static Unique ID
aria-autocomplete="list" Required Static Indicates the input is related to an autocomplete list
aria-controls="[ID]" Required Static Refers to the ID of the autocomplete list
aria-activedescendant="[ID]" Required Static Refers to the ID of the focused item in the autocomplete list

Autocomplete list (ul)  

<ul class="ds-autocomplete__list"
  role="listbox"
  aria-labelledby="[ID]">
  <li
    id="[ID]"
    role="option"
    aria-selected="true|false">
    ...
  </li>
</ul>
Element Attribute Required Type Description
<ul> role="listbox" Required Static Indicates the element is an autocomplete list
aria-labelledby="[ID]" _Optional_ Static ID of an associated label element
<li> id="[ID]" Required Static Unique ID
role="option" Required Static Indicates the element is an autocomplete list option
aria-selected="true|false" Required Dynamic 1. Indicates when the option is selected
2. Related to the text inputs aria-activedescendant

Keyboard access 

The following keyboard controls must be implemented to provide accessible keyboard access.

Autocomplete textbox (input): 

Default browser support for entering and editing text inputs applies, such as delete, left/right arrow.

Key Required Support Description
Enter Required Javascript 1. If a list item is selected, sets the value of the textbox to the selected option.
2. Closes the autocomplete list.
Escape Required Javascript 1. Closes the autocomplete list.
2. Clears the textbox.
Down Arrow Required Javascript 1. If no list item is focused, moves focus to the first list item.
2. If a list item is focused, moves to the next item.
3. If the last item is focused, moves to the first list item.
Up Arrow Required Javascript 1. If no list item is focused, moves focus to the last list item.
2. If a list item is focused, moves to the previous item.
3. If the first item is focused, moves to the last list item.
Printable Characters Required Javascript 1. Types the character in the textbox.
2. Filters the items in the Autocomplete list.
3. Selects the first matching item.

Autocomplete list (ul): 

Key Required Support Description
Enter Required Javascript 1. If a list item is selected, sets the value of the textbox to the selected option.
2. Closes the autocomplete list.
3. Move focus to the textbox.
Escape Required Javascript 1. Closes the autocomplete list.
2. Clears the textbox.
3. Sets focus to the textbox.
Down Arrow Required Javascript 1. Moves to the next item.
2. If the last item is selected, moves to the first list item.
Up Arrow Required Javascript 1. Moves to the previous item.
2. If the first item is selected, moves to the last list item.
Left Arrow Required Javascript 1. Move focus to the textbox.
2. Moves cursor one character to left.
Right Arrow Required Javascript 1. Move focus to the textbox.
2. Moves cursor one character to right.
Home Required Javascript 1. Move focus to the textbox.
2. Moves cursor to beginning of the textbox.
end Required Javascript 1. Move focus to the textbox.
2. Moves cursor to end of the textbox.
Printable Characters Required Javascript 1. Move focus to the textbox.
2. Types the character in the textbox.

Examples 

Used within ds-field, with label and --addon 
<div class="ds-field">
  <label for="example-1" class="ds-text --label">Field test</label>
  <div class="ds-autocomplete" role="combobox" aria-haspopup="listbox" aria-owns="example-1-list">
    <div class="ds-input">
      <input type="text" name="example-1-input" id="example-1-input" aria-autocomplete="list" aria-controls="example-1-list">
    </div>
    <ul id="example-1-list" class="ds-autocomplete__list">
      <li role="option" id="option-anorith">Anorith</li>
      <li role="option" id="option-arbok">Arbok</li>
      <li role="option" id="option-arcanine">Arcanine</li>
      <li role="option" id="option-bulbasaur">Bulbasaur</li>
      <li role="option" id="option-butterfree">Butterfree</li>
      <li role="option" id="option-caterpie">Caterpie</li>
      <li role="option" id="option-charizard">Charizard</li>
      <li role="option" id="option-charmander">Charmander</li>
      <li role="option" id="option-charmeleon">Charmeleon</li>
      <li role="option" id="option-squirtle">Squirtle</li>
      <li role="option" id="option-venusaur">Venusaur</li>
      <li role="option" id="option-wartortle">Wartortle</li>
    </ul>
  </div>
</div>
  • Anorith
  • Arbok
  • Arcanine
  • Bulbasaur
  • Butterfree
  • Caterpie
  • Charizard
  • Charmander
  • Charmeleon
  • Squirtle
  • Venusaur
  • Wartortle
<div class="ds-field">
  <label for="example-1" class="ds-text --label">Field test</label>
  <div class="ds-autocomplete" role="combobox" aria-haspopup="listbox" aria-owns="example-1-list">
    <div class="ds-input">
      <input type="text" name="example-1-input" id="example-1-input" aria-autocomplete="list" aria-controls="example-1-list">
    </div>
    <ul id="example-1-list" class="ds-autocomplete__list">
      <li role="option" id="option-anorith">Anorith</li>
      <li role="option" id="option-arbok">Arbok</li>
      <li role="option" id="option-arcanine">Arcanine</li>
      <li role="option" id="option-bulbasaur">Bulbasaur</li>
      <li role="option" id="option-butterfree">Butterfree</li>
      <li role="option" id="option-caterpie">Caterpie</li>
      <li role="option" id="option-charizard">Charizard</li>
      <li role="option" id="option-charmander">Charmander</li>
      <li role="option" id="option-charmeleon">Charmeleon</li>
      <li role="option" id="option-squirtle">Squirtle</li>
      <li role="option" id="option-venusaur">Venusaur</li>
      <li role="option" id="option-wartortle">Wartortle</li>
    </ul>
  </div>
</div>
Autocomplete list with rich content 
<div class="ds-autocomplete">
  <div class="ds-input">
    <input type="text" name="test-field">
  </div>
  <ul class="ds-autocomplete__list">
    <li data-ds-value="019281919281">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 019281919281</dt>
        <dd>
          <div>My SIM</div>
          <div class="ds-text --small --success --icon-online">Online</div>
        </dd>
      </dl>
    </li>
    <li data-ds-value="9381273784832">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 9381273784832</dt>
        <dd>
          <div>My Other SIM</div>
          <div class="ds-text --small --alert --icon-online">Offline</div>
        </dd>
      </dl>
    </li>
    <li data-ds-value="9381273784719">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 9381273784719</dt>
        <dd>
          <div>My Other SIM</div>
          <div class="ds-text --small --alert --icon-online">Offline</div>
        </dd>
      </dl>
    </li>
  </ul>
</div>
  • Sim ID: 019281919281
    My SIM
    Online
  • Sim ID: 9381273784832
    My Other SIM
    Offline
  • Sim ID: 9381273784719
    My Other SIM
    Offline
<div class="ds-autocomplete">
  <div class="ds-input">
    <input type="text" name="test-field">
  </div>
  <ul class="ds-autocomplete__list">
    <li data-ds-value="019281919281">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 019281919281</dt>
        <dd>
          <div>My SIM</div>
          <div class="ds-text --small --success --icon-online">Online</div>
        </dd>
      </dl>
    </li>
    <li data-ds-value="9381273784832">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 9381273784832</dt>
        <dd>
          <div>My Other SIM</div>
          <div class="ds-text --small --alert --icon-online">Offline</div>
        </dd>
      </dl>
    </li>
    <li data-ds-value="9381273784719">
      <dl class="ds-details--vertical">
        <dt>Sim ID: 9381273784719</dt>
        <dd>
          <div>My Other SIM</div>
          <div class="ds-text --small --alert --icon-online">Offline</div>
        </dd>
      </dl>
    </li>
  </ul>
</div>
Copyright © 2015-2022 Soracom, Inc.
Last page update: February 10, 2022
a548abf0