-
Notifications
You must be signed in to change notification settings - Fork 376
/
Copy pathcombobox-autocomplete-both.html
527 lines (519 loc) · 23.7 KB
/
combobox-autocomplete-both.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Editable Combobox With Both List and Inline Autocomplete Example | WAI-ARIA Authoring Practices 1.2</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 type="text/javascript" src="../js/examples.js"></script>
<script type="text/javascript" src="../js/highlight.pack.js"></script>
<script type="text/javascript" src="../js/app.js"></script>
<!-- js and css for this example. -->
<link rel="stylesheet" href="css/combobox-autocomplete.css">
<script type="text/javascript" src="js/combobox-autocomplete.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>Editable Combobox With Both List and Inline Autocomplete Example</h1>
<p>
The below combobox for choosing the name of a US state or territory demonstrates the
<a href="../../#combobox">design pattern for combobox.</a>
The design pattern describes four types of autocomplete behavior.
This example illustrates the autocomplete behavior referred to in the pattern as list with inline completion.
If the user types one or more characters in the edit box and the typed characters match the beginning of the name of one or more states or territories,
a listbox popup appears containing the matching names, and the first match is automatically selected.
In addition, 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.
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.
Note that this implementation enables users to input the name of a state or territory, but it does not prevent input of any other arbitrary value.
</p>
<p>Similar examples include:</p>
<ul>
<li><a href="examples/combobox/combobox-select-only.html">Select-Only Combobox</a>: A single-select combobox with no text input that is functionally similar to an HTML <code>select</code> element.</li>
<li><a href="combobox-autocomplete-list.html">Editable Combobox with List Autocomplete</a>: An editable combobox that demonstrates the autocomplete behavior known as <q>list with manual selection</q>.</li>
<li><a href="combobox-autocomplete-none.html">Editable Combobox Without Autocomplete</a>: An editable combobox that demonstrates the behavior associated with <code>aria-autocomplete=none</code>.</li>
<li><a href="grid-combo.html">Editable Combobox with Grid Popup</a>: An editable combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.</li>
</ul>
<section>
<h2 id="ex_label">Example</h2>
<div role="separator" id="ex_start_sep" aria-labelledby="ex_start_sep ex_label" aria-label="Start of"></div>
<div id="ex1">
<label for="cb1-input">State</label>
<div class="combobox combobox-list">
<div class="group">
<input id="cb1-input" class="cb_edit" type="text" role="combobox" aria-autocomplete="both"
aria-expanded="false" aria-controls="cb1-listbox">
<button type="button" id="cb1-button" aria-label="States" aria-expanded="false" aria-controls="cb1-listbox" tabindex="-1">
<span class="arrow">
<svg width="18" height="16" aria-hidden="true" focusable="false">
<polygon class="outline" points="1,4 17,4 9,15"></polygon>
<polygon class="arrow" points="3,5 15,5 9,13"></polygon>
</svg>
</span>
</button>
</div>
<ul id="cb1-listbox" role="listbox" aria-label="States">
<li id="lb1-al" role="option">Alabama</li>
<li id="lb1-ak" role="option">Alaska</li>
<li id="lb1-as" role="option">American Samoa</li>
<li id="lb1-az" role="option">Arizona</li>
<li id="lb1-ar" role="option">Arkansas</li>
<li id="lb1-ca" role="option">California</li>
<li id="lb1-co" role="option">Colorado</li>
<li id="lb1-ct" role="option">Connecticut</li>
<li id="lb1-de" role="option">Delaware</li>
<li id="lb1-dc" role="option">District of Columbia</li>
<li id="lb1-fl" role="option">Florida</li>
<li id="lb1-ga" role="option">Georgia</li>
<li id="lb1-gm" role="option">Guam</li>
<li id="lb1-hi" role="option">Hawaii</li>
<li id="lb1-id" role="option">Idaho</li>
<li id="lb1-il" role="option">Illinois</li>
<li id="lb1-in" role="option">Indiana</li>
<li id="lb1-ia" role="option">Iowa</li>
<li id="lb1-ks" role="option">Kansas</li>
<li id="lb1-ky" role="option">Kentucky</li>
<li id="lb1-la" role="option">Louisiana</li>
<li id="lb1-me" role="option">Maine</li>
<li id="lb1-md" role="option">Maryland</li>
<li id="lb1-ma" role="option">Massachusetts</li>
<li id="lb1-mi" role="option">Michigan</li>
<li id="lb1-mn" role="option">Minnesota</li>
<li id="lb1-ms" role="option">Mississippi</li>
<li id="lb1-mo" role="option">Missouri</li>
<li id="lb1-mt" role="option">Montana</li>
<li id="lb1-ne" role="option">Nebraska</li>
<li id="lb1-nv" role="option">Nevada</li>
<li id="lb1-nh" role="option">New Hampshire</li>
<li id="lb1-nj" role="option">New Jersey</li>
<li id="lb1-nm" role="option">New Mexico</li>
<li id="lb1-ny" role="option">New York</li>
<li id="lb1-nc" role="option">North Carolina</li>
<li id="lb1-nd" role="option">North Dakota</li>
<li id="lb1-mp" role="option">Northern Marianas Islands</li>
<li id="lb1-oh" role="option">Ohio</li>
<li id="lb1-ok" role="option">Oklahoma</li>
<li id="lb1-or" role="option">Oregon</li>
<li id="lb1-pa" role="option">Pennsylvania</li>
<li id="lb1-pr" role="option">Puerto Rico</li>
<li id="lb1-ri" role="option">Rhode Island</li>
<li id="lb1-sc" role="option">South Carolina</li>
<li id="lb1-sd" role="option">South Dakota</li>
<li id="lb1-tn" role="option">Tennessee</li>
<li id="lb1-tx" role="option">Texas</li>
<li id="lb1-ut" role="option">Utah</li>
<li id="lb1-ve" role="option">Vermont</li>
<li id="lb1-va" role="option">Virginia</li>
<li id="lb1-vi" role="option">Virgin Islands</li>
<li id="lb1-wa" role="option">Washington</li>
<li id="lb1-wv" role="option">West Virginia</li>
<li id="lb1-wi" role="option">Wisconsin</li>
<li id="lb1-wy" role="option">Wyoming</li>
</ul>
</div>
</div>
<div role="separator" id="ex_end_sep" aria-labelledby="ex_end_sep ex_label" aria-label="End of"></div>
</section>
<section>
<h2 id="kbd_label">Keyboard Support</h2>
<p>
The example combobox on this page implements 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 data-test-id="textbox-key-down-arrow">
<th><kbd>Down Arrow</kbd></th>
<td>
<ul>
<li>If the listbox is displayed and a suggestion is selected, moves visual focus to the next suggested value.</li>
<li>If the textbox is empty and the listbox is not displayed, opens the listbox and moves visual focus to the first option.</li>
<li>In both cases DOM focus remains on the textbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="textbox-key-alt-down-arrow">
<th><kbd>Alt + Down Arrow</kbd></th>
<td>
Opens the listbox without moving focus or changing selection.
</td>
</tr>
<tr data-test-id="textbox-key-up-arrow">
<th><kbd>Up Arrow</kbd></th>
<td>
<ul>
<li>If the listbox is displayed and a suggestion is selected, moves visual focus to the last suggested value.</li>
<li>If the textbox is empty, first opens the listbox if it is not already displayed and then moves visual focus to the last option.</li>
<li>In both cases DOM focus remains on the textbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="textbox-key-enter">
<th><kbd>Enter</kbd></th>
<td>
<ul>
<li>Sets the textbox value to the content of the selected option.</li>
<li>Closes the listbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="textbox-key-escape">
<th><kbd>Escape</kbd></th>
<td>
<ul>
<li>If the listbox is displayed, closes it.</li>
<li>If the listbox is not displayed, clears the textbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="standard-single-line-editing-keys">
<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="text"</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 data-test-id="listbox-key-enter">
<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 visual focus on the textbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="listbox-key-escape">
<th><kbd>Escape</kbd></th>
<td>
<ul>
<li>Closes the listbox.</li>
<li>Sets visual focus on the textbox.</li>
</ul>
</td>
</tr>
<tr data-test-id="listbox-key-down-arrow">
<th><kbd>Down Arrow</kbd></th>
<td>
<ul>
<li>Moves visual focus to the next option.</li>
<li>If visual focus is on the last option, moves visual 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 data-test-id="listbox-key-up-arrow">
<th><kbd>Up Arrow</kbd></th>
<td>
<ul>
<li>Moves visual focus to the previous option.</li>
<li>If visual focus is on the first option, moves visual 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 data-test-id="listbox-key-right-arrow">
<th><kbd>Right Arrow</kbd></th>
<td>Moves visual focus to the textbox and moves the editing cursor one character to the right.</td>
</tr>
<tr data-test-id="listbox-key-left-arrow">
<th><kbd>Left Arrow</kbd></th>
<td>Moves visual focus to the textbox and moves the editing cursor one character to the left.</td>
</tr>
<tr data-test-id="listbox-key-home">
<th><kbd>Home</kbd></th>
<td>Moves visual focus to the textbox and places the editing cursor at the beginning of the field.</td>
</tr>
<tr data-test-id="listbox-key-end">
<th><kbd>End</kbd></th>
<td>Moves visual focus to the textbox and places the editing cursor at the end of the field.</td>
</tr>
<tr data-test-id="listbox-characters">
<th>Printable Characters</th>
<td>
<ul>
<li>Moves visual focus to the textbox.</li>
<li>Types the character in the textbox.</li>
<li>Options in the listbox are filtered based on characters in the textbox.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3 id="kbd_label_button">Button</h3>
<p>
The button has been removed from the tab sequence of the page, but is still important to assistive technologies for mobile devices that use touch events to open the list of options.
</p>
</section>
<section>
<h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
<p>
The example combobox on this page implements 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_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 data-test-id="combobox-role">
<th scope="row">
<code>combobox</code>
</th>
<td></td>
<td><code>input[type="text"]</code></td>
<td>Identifies the input as a combobox.</td>
</tr>
<tr data-test-id="combobox-aria-autocomplete">
<td></td>
<th scope="row">
<code>aria-autocomplete="both"</code>
</th>
<td><code>input[type="text"]</code></td>
<td>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 data-test-id="combobox-aria-controls">
<td></td>
<th scope="row">
<code>aria-controls="#IDREF"</code>
</th>
<td><code>input[type="text"]</code></td>
<td>Identifies the element that serves as the popup.</td>
</tr>
<tr data-test-id="combobox-aria-expanded">
<td></td>
<th scope="row">
<code>aria-expanded="false"</code>
</th>
<td><code>input[type="text"]</code></td>
<td>Indicates that the popup element <strong>is not</strong> displayed.</td>
</tr>
<tr data-test-id="combobox-aria-expanded">
<td></td>
<th scope="row">
<code>aria-expanded="true"</code>
</th>
<td><code>input[type="text"]</code></td>
<td>Indicates that the popup element <strong>is</strong> displayed.</td>
</tr>
<tr data-test-id="combobox-id">
<td></td>
<th scope="row">
<code>id="string"</code>
</th>
<td><code>input[type="text"]</code></td>
<td>
<ul>
<li>Referenced by <code>for</code> attribute of <code>label</code> element to provide an accessible name.</li>
<li>Recommended naming method for HTML input elements because clicking label focuses input.</li>
</ul>
</td>
</tr>
<tr data-test-id="combobox-aria-activedescendant">
<td></td>
<th scope="row">
<code>aria-activedescendant="IDREF"</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 data-test-id="listbox-role">
<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 data-test-id="listbox-aria-label">
<td></td>
<th scope="row">
<code>aria-label="States"</code>
</th>
<td><code>ul</code></td>
<td>Provides a label for the <code>listbox</code>.</td>
</tr>
<tr data-test-id="option-role">
<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 data-test-id="option-aria-selected">
<td></td>
<th scope="row">
<code>aria-selected="true"</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>Occurs when an option in the list is referenced by <code>aria-activedescendant</code> and when focus is in the textbox and the first option is automatically selected.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3 id="rps_label_button">Button</h3>
<table aria-labelledby="rps_label_button 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 data-test-id="button-tabindex">
<td></td>
<th scope="row">
<code>tabindex="-1"</code>
</th>
<td><code>button</code></td>
<td>Removes the button from the tab sequence of the page because its function is redundant with the keyboard operation of the combobox.</td>
</tr>
<tr data-test-id="button-aria-label">
<td></td>
<th scope="row">
<code>aria-label="States"</code>
</th>
<td><code>button</code></td>
<td>Provides a label for the <code>button</code>.</td>
</tr>
<tr data-test-id="button-aria-controls">
<td></td>
<th scope="row">
<code>aria-controls="#IDREF"</code>
</th>
<td><code>button</code></td>
<td>Identifies the element that serves as the popup.</td>
</tr>
<tr data-test-id="button-aria-expanded">
<td></td>
<th scope="row">
<code>aria-expanded="false"</code>
</th>
<td><code>button</code></td>
<td>Indicates that the popup element <strong>is not</strong> displayed.</td>
</tr>
<tr data-test-id="button-aria-expanded">
<td></td>
<th scope="row">
<code>aria-expanded="true"</code>
</th>
<td><code>button</code></td>
<td>Indicates that the popup element <strong>is</strong> displayed.</td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>Javascript and CSS Source Code</h2>
<ul>
<li>
CSS:
<a href="css/combobox-autocomplete.css" type="text/css">combobox-autocomplete.css</a>
</li>
<li>
Javascript:
<a href="js/combobox-autocomplete.js" type="text/javascript">combobox-autocomplete.js</a>
</li>
</ul>
</section>
<section>
<h2 id="sc1_label">HTML Source Code</h2>
<div role="separator" id="sc1_start_sep" aria-labelledby="sc1_start_sep sc1_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" aria-label="End of"></div>
<!--
The following script will show the reader the HTML source for the example that is in the div with ID 'ex1'.
It renders the HTML in the preceding pre element with ID 'sc1'.
-->
<script>
sourceCode.add('sc1', 'ex1');
sourceCode.make();
</script>
</section>
</main>
<nav>
<a href="../../#combobox">Combobox Design Pattern in WAI-ARIA Authoring Practices 1.2</a>
</nav>
</body>
</html>