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
<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
Input Icons
See ds-input icons.
List icons
See ds-menu icons.
List 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 |
Required | Static | Indicates the input is related to an autocomplete list | |
aria-controls |
Required | Static | Refers to the ID of the autocomplete list | |
aria-activedescendant |
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 |
Required | Static | Indicates the element is an autocomplete list |
aria-labelledby |
_Optional_ | Static | ID of an associated label element |
|
<li> |
id |
Required | Static | Unique ID |
role |
Required | Static | Indicates the element is an autocomplete list option | |
aria-selected |
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
<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-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
-
- Sim ID: 9381273784832
-
My Other SIM
-
- Sim ID: 9381273784719
-
My Other SIM