forked from w3c/aria-practices
-
Notifications
You must be signed in to change notification settings - Fork 0
/
aria-practices.html
7330 lines (6869 loc) · 486 KB
/
aria-practices.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
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8">
<title>WAI-ARIA Authoring Practices 1.2</title>
<script src="common/script/resolveReferences.js" class="remove"></script>
<script src="respec-config.js" class="remove"></script>
<script src="common/biblio.js" class="remove"></script>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<link href="common/css/common.css" rel="stylesheet" type="text/css">
</head>
<body>
<section id="abstract">
<p>
This document provides readers with an understanding of how to use <cite><a href="https://www.w3.org/TR/wai-aria-1.2/"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> 1.2</a></cite> [[WAI-ARIA]] to create accessible rich internet applications.
It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties.
This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.
</p>
<p>This document is part of the WAI-ARIA suite described in the <a href="https://www.w3.org/WAI/intro/aria.php">WAI-ARIA Overview</a>.</p>
</section>
<section id="sotd">
<p>
This is an editor's draft by the
<a href="https://www.w3.org/WAI/ARIA/">Accessible Rich Internet Applications Working Group</a>
of the
<a href="https://www.w3.org/WAI/">Web Accessibility Initiative</a>.
It supports the
[[[wai-aria-1.2]]] [[WAI-ARIA-1.2]]
specification, providing detailed advice and examples beyond what would be appropriate to a technical specification but which are important to understand the specification.
</p>
<p> This draft includes only a portion of content planned for WAI-ARIA Authoring Practices 1.2. To see plans for the complete guide, review the <a href="https://github.com/w3c/aria-practices/milestones?direction=asc&sort=due_date&state=open">Authoring Practices Milestone Plan</a>. </p>
<p>
Feedback on the information provided here is essential to the ultimate success of Rich Internet Applications that afford full access to their information and operations.
The Accessible Rich Internet Applications Working Group asks in particular:
</p>
<ul>
<li>Is it clear how to create accessible Rich Internet Applications?</li>
<li>Is the usage of roles, states, and properties clear? </li>
<li>Are the various types of rich Web content covered? </li>
<li>Are considerations beyond the use of WAI-ARIA sufficiently explained? </li>
<li>Is the relationship of this document to the WAI-ARIA specification clear? </li>
<li>Are the <a href="#aria_ex">design patterns</a> clear?</li>
</ul>
<p>
To comment,
<a href="https://github.com/w3c/aria-practices/issues/">file an issue in the <abbr title="World Wide Web Consortium">W3C</abbr> ARIA Practices GitHub repository</a>,
or if that is not possible, send email to
<a href="mailto:[email protected]?subject=Comment%20on%20WAI-ARIA%20Practices%201.2">[email protected]</a>
(<a href="http://lists.w3.org/Archives/Public/public-aria/">comment archive</a>).
</p>
</section>
<section id="intro">
<h2>Introduction</h2>
<p>
The ARIA Authoring Practices Guide (APG) explains how to create accessible web experiences for users of assistive technologies and keyboard interfaces by developing web sites that properly convey accessibility semantics and implement common keyboard conventions.
It also provides guidance on some closely related topics, such as supporting operating system settings for high contrast and reduced motion.
</p>
<p>
Accessibility semantics refer to the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements.
For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned.
To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents an interactive button.
In addition, keyboard accessibility requires the button to be focusable, and keyboard conventions call for pressing <kbd>Enter</kbd> or <kbd>Space</kbd> to activate the button when it is focused.
The APG describes how to convey accessibility semantics and implement keyboard accessibility for many common design patterns, ranging from typical buttons and popup menus to complex tree grids.
It also explains essential practices related to these patterns, such as how to convey web page structure with ARIA landmark regions and effectively utilize the many ways of encoding accessible names.
</p>
<p>
The APG is organized into two major sections: patterns and practices.
Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern.
The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible.
For instance, the practices section on providing accessible names and descriptions gives detailed descriptions of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements.
</p>
<p>
The APG assumes basic understanding of web development, especially of HTML and CSS.
It may be particularly useful to designers and engineers who are working on site design systems and component libraries.
However, it is important to understand that the APG only covers a portion of what is needed to create accessible experiences.
To understand accessibility more broadly, it is advisable to start with the <a href="https://www.w3.org/WAI/fundamentals/">WAI Accessibility Fundamentals</a> and <a href="https://www.w3.org/WAI/design-develop/">WAI Overview of Design and Development</a>.
</p>
<p>
The accessibility semantics used in the APG patterns and described in APG practices are defined in the
<cite><a href="https://www.w3.org/TR/wai-aria-1.2/">WAI-ARIA 1.2 Specification</a></cite>.
That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, such as the meaning of <code>role="button"</code>.
These attributes and other features required to make sites usable by people who rely on assistive technologies or keyboard navigation are not natively included in the languages used to create web sites, such as HTML, JavaScript, CSS, and SVG.
The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts.
The <a href="https://www.w3.org/WAI/intro/aria.php">WAI-ARIA Overview</a>
provides additional background on WAI-ARIA, summarizes those efforts, and lists the other documents included in the WAI-ARIA suite.
</p>
</section>
<section id="read_me_first">
<h2>Read Me First</h2>
<section id="no_aria_better_bad_aria">
<h3>No ARIA is better than Bad ARIA</h3>
<p>
Functionally, ARIA roles, states, and properties are analogous to a CSS for assistive technologies.
For screen reader users, ARIA controls the rendering of their non-visual experience.
Incorrect ARIA misrepresents visual experiences, with potentially devastating effects on their corresponding non-visual experiences.
</p>
<p>Before using ARIA or any of the guidance in this document, please take time to understand the following two essential principles.</p>
<h4>Principle 1: A role is a promise</h4>
<p>This code:</p>
<pre><code>
<div role="button">Place Order</div>
</code> </pre>
<p>
Is a promise that the author of that <code><div></code> has also incorporated JavaScript that provides the keyboard interactions expected for a button.
Unlike HTML input elements, ARIA roles do not cause browsers to provide keyboard behaviors or styling.
</p>
<p>Using a role without fulfilling the promise of that role is similar to making a "Place Order" button that abandons an order and empties the shopping cart.</p>
<p>One of the objectives of this guide is to define expected behaviors for each ARIA role.</p>
<h4>Principle 2: ARIA Can Both Cloak and Enhance, Creating Both Power and Danger</h4>
<p>
The information assistive technologies need about the meaning and purpose of user interface elements is called accessibility semantics.
From the perspective of assistive technologies, ARIA gives authors the ability to dress up HTML and SVG elements with critical accessibility semantics that the assistive technologies would not otherwise be able to reliably derive.
</p>
<p>Some of ARIA is like a cloak; it covers up, or overrides, the original semantics or content.</p>
<pre><code>
<a role="menuitem">Assistive tech users perceive this element as an item in a menu, not a link.</a>
<a aria-label="Assistive tech users can only perceive the contents of this aria-label, not the link text">Link Text</a>
</code></pre>
<p>On the other hand, some uses of ARIA are more like suspenders or belts; they add meaning that provides essential support to the original content.</p>
<pre><code>
<button aria-pressed="false">Mute</button>
</code></pre>
<p>
This is the power of ARIA.
It enables authors to describe nearly any user interface component in ways that assistive technologies can reliably interpret, thus making components accessible to assistive technology users.
</p>
<p>
This is also the danger of ARIA.
Authors can inadvertently override accessibility semantics.
</p>
<pre>
<code>
<table role="log">
<!--
Table that assistive technology users will not perceive as a table.
The log role tells browser this is a log, not a table.
-->
</table>
<ul role="navigation">
<!-- This is a navigation region, not a list. -->
<li><a href="uri1">nav link 1</li>
<li><a href="uri2">nav link 2</li>
<!-- ERROR! Previous list items are not in a list! -->
</ul>
</code>
</pre>
</section>
<section id="browser_and_AT_support">
<h3>Browser and Assistive Technology Support</h3>
<p>
<strong>Testing assistive technology interoperability is essential before using code from this guide in production.</strong>
Because the purpose of this guide is to illustrate appropriate use of ARIA 1.2 as defined in the ARIA specification, the design patterns, reference examples, and sample code intentionally <strong>do not</strong> describe and implement coding techniques for working around problems caused by gaps in support for ARIA 1.2 in browsers and assistive technologies.
It is thus advisable to test implementations thoroughly with each browser and assistive technology combination that is relevant within a target audience.
</p>
<p>
Similarly, JavaScript and CSS in this guide is written to be compatible with the most recent version of Chrome, Firefox, and Safari at the time of writing.
Some JavaScript and CSS may not function correctly in Internet Explorer.
</p>
<p>
Except in cases where the ARIA Working Group and other contributors have overlooked an error,
examples in this guide that do not function well in a particular browser or with a specific assistive technology are demonstrating browser or assistive technology bugs.
Browser and assistive technology developers can thus utilize code in this guide to help assess the quality of their support for ARIA 1.2.
</p>
</section>
<section id="mobile_and_touch_support">
<h3>Mobile and Touch Support</h3>
<p>
Currently, this guide does not indicate which examples are compatible with mobile browsers or touch interfaces.
While some of the examples include specific features that enhance mobile and touch support, some ARIA features are not supported in any mobile browser.
In addition, there is not yet a standardized approach for providing touch interactions that work across mobile browsers.
</p>
<p>More guidance about touch and mobile support is planned for future releases of the guide.</p>
</section>
</section>
<section id="aria_ex">
<h2>Design Patterns and Widgets</h2>
<p>This section demonstrates how to make common rich internet application patterns and widgets accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.</p>
<section class="widget" id="accordion">
<h3>Accordion (Sections With Show/Hide Functionality)</h3>
<p>
An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content.
The headings function as controls that enable users to reveal or hide their associated sections of content.
Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page.
</p>
<p>Terms for understanding accordions include:</p>
<dl>
<dt>Accordion Header:</dt>
<dd>Label for or thumbnail representing a section of content that also serves as a control for showing, and in some implementations, hiding the section of content. </dd>
<dt>Accordion Panel:</dt>
<dd>Section of content associated with an accordion header.</dd>
</dl>
<p>
In some accordions, there are additional elements that are always visible adjacent to the accordion header.
For instance, a menubutton may accompany each accordion header to provide access to actions that apply to that section.
And, in some cases, a snippet of the hidden content may also be visually persistent.
</p>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/accordion/accordion.html">Accordion Example</a>: demonstrates a form divided into three sections using an accordion to show one section at a time. </p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>
<kbd>Enter</kbd> or <kbd>Space</kbd>:
<ul>
<li>
When focus is on the accordion header for a collapsed panel, expands the associated panel.
If the implementation allows only one panel to be expanded, and if another panel is expanded, collapses that panel.
</li>
<li>
When focus is on the accordion header for an expanded panel, collapses the panel if the implementation supports collapsing.
Some implementations require one panel to be expanded at all times and allow only one panel to be expanded; so, they do not support a collapse function.
</li>
</ul>
</li>
<li><kbd>Tab</kbd>: Moves focus to the next focusable element; all focusable elements in the accordion are included in the page <kbd>Tab</kbd> sequence.</li>
<li><kbd>Shift + Tab</kbd>: Moves focus to the previous focusable element; all focusable elements in the accordion are included in the page <kbd>Tab</kbd> sequence.</li>
<li>
<kbd>Down Arrow</kbd> (Optional): If focus is on an accordion header, moves focus to the next accordion header.
If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
</li>
<li>
<kbd>Up Arrow</kbd> (Optional): If focus is on an accordion header, moves focus to the previous accordion header.
If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.
</li>
<li>
<kbd>Home</kbd> (Optional): When focus is on an accordion header, moves focus to the first accordion header.
</li>
<li>
<kbd>End</kbd> (Optional): When focus is on an accordion header, moves focus to the last accordion header.
</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties:</h4>
<ul>
<li>
The title of each accordion header is contained in an element with role <a href="#button" class="role-reference">button</a>.
</li>
<li>
Each accordion header <code>button</code> is wrapped in an element with role <a href="#heading" class="role-reference">heading</a> that has a value set for <a href="#aria-level" class="property-reference">aria-level</a> that is appropriate for the information architecture of the page.
<ul>
<li>If the native host language has an element with an implicit <code>heading</code> and <code>aria-level</code>, such as an HTML heading tag, a native host language element may be used.</li>
<li>
The <code>button</code> element is the only element inside the <code>heading</code> element.
That is, if there are other visually persistent elements, they are not included inside the <code>heading</code> element.
</li>
</ul>
</li>
<li>
If the accordion panel associated with an accordion header is visible, the header <code>button</code> element has <a href="#aria-expanded" class="state-reference">aria-expanded</a> set to <code>true</code>.
If the panel is not visible, <a href="#aria-expanded" class="state-reference">aria-expanded</a> is set to <code>false</code>.
</li>
<li>
The accordion header <code>button</code> element has <a href="#aria-controls" class="property-reference">aria-controls</a> set to the ID of the element containing the accordion panel content.
</li>
<li>
If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header <code>button</code> element has <a href="#aria-disabled" class="state-reference">aria-disabled</a> set to <code>true</code>.
</li>
<li>
Optionally, each element that serves as a container for panel content has role
<a href="#region" class="role-reference">region</a> and
<a href="#aria-labelledby" class="property-reference">aria-labelledby</a>
with a value that refers to the button that controls display of the panel.
<ul>
<li>
Avoid using the <code>region</code> role in circumstances that create landmark region proliferation,
e.g., in an accordion that contains more than approximately 6 panels that can be expanded at the same time.
</li>
<li>
Role <code>region</code> is especially helpful to the perception of structure by screen reader users when panels contain heading elements or a nested accordion.
</li>
</ul>
</li>
</ul>
</section>
</section>
<section class="widget" id="alert">
<h3>Alert</h3>
<p>
An <a class="role-reference" href="#alert">alert</a> is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task.
Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound.
It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes.
</p>
<p>
Because alerts are intended to provide important and potentially time-sensitive information without interfering with the user's ability to continue working,
it is crucial they do not affect keyboard focus.
The <a href="#alertdialog">alert dialog</a> is designed for situations where interrupting work flow is necessary.
</p>
<p>
It is also important to avoid designing alerts that disappear automatically.
An alert that disappears too quickly can lead to failure to meet
<a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-no-exceptions.html">WCAG 2.0 success criterion 2.2.3</a>.
Another critical design consideration is the frequency of interruption caused by alerts.
Frequent interruptions inhibit usability for people with visual and cognitive disabilities, which makes meeting the requirements of
<a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html">WCAG 2.0 success criterion 2.2.4</a>
more difficult.
</p>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/alert/alert.html">Alert Example</a></p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>Not applicable.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>The widget has a role of <a class="role-reference" href="#alert">alert</a>.</p>
</section>
</section>
<section class="widget" id="alertdialog">
<h3>Alert and Message Dialogs</h3>
<p>
An alert dialog is a <a href="#dialog_modal">modal dialog</a> that interrupts the user's workflow to communicate an important message and acquire a response.
Examples include action confirmation prompts and error message confirmations.
The <a href="#alertdialog" class="role-reference">alertdialog</a> role
enables assistive technologies and browsers to distinguish alert dialogs from other dialogs
so they have the option of giving alert dialogs special treatment, such as playing a system alert sound.
</p>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/dialog-modal/alertdialog.html">Alert Dialog Example</a>: A confirmation prompt that demonstrates an alert dialog.</p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>See the keyboard interaction section for the <a href="#dialog_modal">modal dialog pattern</a>.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>
The element that contains all elements of the dialog, including the alert
message and any dialog buttons, has role
<a class="role-reference" href="#alertdialog">alertdialog</a>.
</li>
<li>
The element with role <code>alertdialog</code> has either:
<ul>
<li>
A value for
<a href="#aria-labelledby" class="property-reference">aria-labelledby</a>
that refers to the element containing the title of the dialog if the
dialog has a visible label.
</li>
<li>
A value for
<a href="#aria-label" class="property-reference">aria-label</a>
if the dialog does not have a visible label.
</li>
</ul>
</li>
<li>
The element with role <code>alertdialog</code> has a value set for
<a href="#aria-describedby" class="property-reference">aria-describedby</a>
that refers to the element containing the alert message.
</li>
</ul>
</section>
</section>
<section class="widget" id="breadcrumb">
<h3 class="widget-name">Breadcrumb</h3>
<p>
A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order.
It helps users find their place within a website or web application.
Breadcrumbs are often placed horizontally before a page's main content.
</p>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/breadcrumb/index.html">Breadcrumb design pattern example</a></p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>Not applicable.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>Breadcrumb trail is contained within a navigation landmark region.</li>
<li>The landmark region is labelled via <a href="#aria-label" class="property-reference">aria-label</a> or <a href="#aria-labelledby" class="property-reference">aria-labelledby</a>.</li>
<li>
The link to the current page has <a href="#aria-current" class="property-reference">aria-current</a> set to <code>page</code>.
If the element representing the current page is not a link, aria-current is optional.
</li>
</ul>
</section>
</section>
<section class="widget" id="button">
<h3>Button</h3>
<p>
A <a class="role-reference" href="#button">button</a> is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…".
</p>
<p>In addition to the ordinary button widget, WAI-ARIA supports 2 other types of buttons:</p>
<ul>
<li>
Toggle button: A two-state button that can be either off (not pressed) or on (pressed).
To tell assistive technologies that a button is a toggle button, specify a value for the attribute <a href="#aria-pressed" class="state-reference">aria-pressed</a>.
For example, a button labelled mute in an audio player could indicate that sound is muted by setting the pressed state true.
<strong>Important:</strong> it is critical the label on a toggle does not change when its state changes.
In this example, when the pressed state is true, the label remains "Mute" so a screen reader would say something like "Mute toggle button pressed".
Alternatively, if the design were to call for the button label to change from "Mute" to "Unmute," the aria-pressed attribute would not be needed.
</li>
<li>Menu button: as described in the <a href="#menubutton">menu button pattern</a>, a button is revealed to assistive technologies as a menu button if it has the property <a href="#aria-haspopup" class="property-reference">aria-haspopup</a> set to either <code>menu</code> or <code>true</code>.</li>
</ul>
<p class="note">
The types of actions performed by buttons are distinctly different from the function of a link (see <a href="#link">link pattern</a>).
It is important that both the appearance and role of a widget match the function it provides.
Nevertheless, elements occasionally have the visual style of a link but perform the action of a button.
In such cases, giving the element role <code>button</code> helps assistive technology users understand the function of the element.
However, a better solution is to adjust the visual design so it matches the function and ARIA role.
</p>
<section class="notoc">
<h4>Examples</h4>
<ul>
<li><a href="examples/button/button.html">Button Examples</a>: Examples of clickable HTML <code>div</code> and <code>span</code> elements made into accessible command and toggle buttons.</li>
<li><a href="examples/button/button_idl.html">Button Examples (IDL)</a>: Examples of clickable HTML <code>div</code> and <code>span</code> elements made into accessible command and toggle buttons. This example uses the <a class="specref" href="#idl-interface">IDL Interface</a>.</li>
</ul>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>When the button has focus:</p>
<ul>
<li>
<kbd>Space</kbd>: Activates the button.
</li>
<li>
<kbd>Enter</kbd>: Activates the button.
</li>
<li>
Following button activation, focus is set depending on the type of action the button
performs. For example:
<ul>
<li>
If activating the button opens a dialog, the focus moves inside the dialog. (see
<a href="#dialog_modal">dialog pattern</a>)
</li>
<li>If activating the button closes a dialog, focus typically returns to the
button that opened the dialog unless the function performed in the dialog context
logically leads to a different element. For example, activating a cancel button in a
dialog returns focus to the button that opened the dialog. However, if
the dialog were confirming the action of deleting the page from which it was
opened, the focus would logically move to a new context.</li>
<li>If activating the button does not dismiss the current context, then focus
typically remains on the button after activation, e.g., an Apply or
Recalculate button.</li>
<li>If the button action indicates a context change, such as move to next step in
a wizard or add another search criteria, then it is often appropriate to move focus to
the starting point for that action.</li>
<li>
If the button is activated with a shortcut key, the focus usually remains in
the context from which the shortcut key was activated. For example, if <kbd>Alt
+ U</kbd> were assigned to an "Up" button that moves the currently focused
item in a list one position higher in the list, pressing <kbd>Alt + U</kbd> when the
focus is in the list would not move the focus from the list.
</li>
</ul>
</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The button has role of <a class="role-reference" href="#button">button</a>.</li>
<li>
The <code>button</code> has an accessible label.
By default, the accessible name is computed from any text content inside the button element.
However, it can also be provided with <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> or <a href="#aria-label" class="property-reference">aria-label</a>.
</li>
<li>If a description of the button's function is present, the button element has <a href="#aria-describedby" class="property-reference">aria-describedby</a> set to the ID of the element containing the description.</li>
<li>When the action associated with a button is unavailable, the button has <a class="state-reference" href="#aria-disabled">aria-disabled</a> set to <code>true</code>.</li>
<li>
If the button is a toggle button, it has an <a href="#aria-pressed" class="state-reference">aria-pressed</a> state.
When the button is toggled on, the value of this state is <code>true</code>, and when toggled off, the state is <code>false</code>.
</li>
</ul>
</section>
</section>
<section class="widget" id="carousel">
<h3>Carousel (Slide Show or Image Rotator)</h3>
<p>
A carousel presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides.
Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view.
In some implementations, rotation automatically starts when the page loads, and it may also automatically stop once all the slides have been displayed.
While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common.
</p>
<p>
Ensuring all users can easily control and are not adversely affected by slide rotation is an essential aspect of making carousels accessible.
For instance, the screen reader experience can be confusing and disorienting if slides that are not visible on screen are incorrectly hidden, e.g., displayed off-screen.
Similarly, if slides rotate automatically and a screen reader user is not aware of the rotation, the user may read an element on slide one, execute the screen reader command for next element, and, instead of hearing the next element on slide one, hear an element from slide 2 without any knowledge that the element just announced is from an entirely new context.
</p>
<p>Features needed to provide sufficient rotation control include:</p>
<ul>
<li>Buttons for displaying the previous and next slides.</li>
<li>Optionally, a control, or group of controls, for choosing a specific slide to display. For example, slide picker controls can be marked up as tabs in a tablist with the slide represented by a tabpanel element.</li>
<li>If the carousel can automatically rotate, it also:
<ul>
<li>Has a button for stopping and restarting rotation. This is particularly important for supporting assistive technologies operating in a mode that does not move either keyboard focus or the mouse.</li>
<li>Stops rotating when keyboard focus enters the carousel. It does not restart unless the user explicitly requests it to do so.</li>
<li>Stops rotating whenever the mouse is hovering over the carousel.</li>
</ul>
</li>
</ul>
<section class="notoc">
<h4>Examples</h4>
<ul>
<li><a href="examples/carousel/carousel-1-prev-next.html">Auto-Rotating Image Carousel with Buttons for Slide Control:</a> A basic image carousel that demonstrates the accessibility features necessary for carousels that rotate automatically on page load and also enables users to choose which slide is displayed with buttons for previous and next slide.</li>
<li><a href="examples/carousel/carousel-2-tablist.html">Auto-Rotating Image Carousel with Tabs for Slide Control:</a> An image carousel that demonstrates accessibility features necessary for carousels that rotate automatically on page load and also enables users to choose which slide is displayed with a set of tabs.</li>
</ul>
</section>
<section class="notoc">
<h4>Terms</h4>
<p>The following terms are used to describe components of a carousel.</p>
<dl>
<dt>Slide</dt>
<dd>A single content container within a set of content containers that hold the content to be presented by the carousel.</dd>
<dt>Rotation Control</dt>
<dd>An interactive element that stops and starts automatic slide rotation.</dd>
<dt>Next Slide Control</dt>
<dd>An interactive element, often styled as an arrow, that displays the next slide in the rotation sequence.</dd>
<dt>Previous Slide Control</dt>
<dd>An interactive element, often styled as an arrow, that displays the previous slide in the rotation sequence.</dd>
<dt>Slide Picker Controls</dt>
<dd>A group of elements, often styled as small dots, that enable the user to pick a specific slide in the rotation sequence to display.</dd>
</dl>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li>
If the carousel has an auto-rotate feature, automatic slide rotation stops when any element in the carousel receives keyboard focus.
It does not resume unless the user activates the rotation control.
</li>
<li><kbd>Tab</kbd> and <kbd>Shift + Tab</kbd>: Move focus through the interactive elements of the carousel as specified by the page tab sequence -- scripting for <kbd>Tab</kbd> is not necessary.</li>
<li>
Button elements implement the keyboard interaction defined in the <a href="#button">button pattern</a>.
Note: Activating the rotation control, next slide, and previous slide do not move focus, so users may easily repetitively activate them as many times as desired.
</li>
<li>If present, the rotation control is the first element in the <kbd>Tab</kbd> sequence inside the carousel. It is essential that it precede the rotating content so it can be easily located.</li>
<li>If tab elements are used for slide picker controls, they implement the keyboard interaction defined in the <a href="#tabpanel">Tabs Pattern.</a></li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>This section describes the element composition for three styles of carousels:</p>
<ul>
<li>Basic: Has rotation, previous slide, and next slide controls but no slide picker controls.</li>
<li>Tabbed: Has basic controls plus a single tab stop for slide picker controls implemented using the <a href="#tabpanel">tabs pattern.</a></li>
<li>Grouped: Has basic controls plus a series of tab stops in a group of slide picker controls where each control implements the <a href="#button">button pattern.</a> Because each slide selector button adds an element to the page tab sequence, this style is the least friendly for keyboard users.</li>
</ul>
<h5>Basic carousel elements</h5>
<ul>
<li>
A carousel container element that encompasses all components of the carousel, including both carousel controls and slides,
has either role <a href="#region" class="role-reference">region</a>
or role <a href="#group" class="role-reference">group.</a>
The most appropriate role for the carousel container depends on the information architecture of the page.
See the <a href="#aria_landmark">landmark regions guidance</a> to determine whether the carousel warrants being designated as a landmark region.
</li>
<li>The carousel container has the <a href="#aria-roledescription" class="property-reference">aria-roledescription</a> property set to <code>carousel</code>.</li>
<li>
If the carousel has a visible label, its accessible label is provided by the property
<a href="#aria-labelledby" class="property-reference" >aria-labelledby</a> on the carousel container set to the ID of the element containing the visible label.
Otherwise, an accessible label is provided by the property <a href="#aria-label" class="property-reference">aria-label</a> set on the carousel container.
Note that since the <code>aria-roledescription</code> is set to "carousel", the label does not contain the word "carousel".
</li>
<li>The rotation control, next slide control, and previous slide control are either native button elements (recommended) or implement the <a href="#button">button pattern</a>.</li>
<li>
The rotation control has an accessible label provided by either its inner text or <a href="#aria-label" class="property-reference">aria-label</a>.
The label changes to match the action the button will perform, e.g., "Stop slide rotation" or "Start slide rotation".
A label that changes when the button is activated clearly communicates both that slide content can change automatically and when it is doing so.
Note that since the label changes, the rotation control does not have any states, e.g., <code>aria-pressed</code>, specified.
</li>
<li>Each slide container has role <a href="#group" class="role-reference">group</a> with the property <a href="#aria-roledescription" class="property-reference">aria-roledescription</a> set to <code>slide</code>.</li>
<li>Each slide has an accessible name:
<ul>
<li>
If a slide has a visible label, its accessible label is provided by the property
<a href="#aria-labelledby" class="property-reference" >aria-labelledby</a>
on the slide container set to the ID of the element containing the visible label.
</li>
<li>
Otherwise, an accessible label is provided by the property
<a href="#aria-label" class="property-reference">aria-label</a>
set on the slide container.
</li>
<li>
If unique names that identify the slide content are not available, a number and set size can serve as a meaningful alternative, e.g., "3 of 10".
Note: Normally, including set position and size information in an accessible name is not appropriate.
An exception is helpful in this implementation because group elements do not support <a href="#aria-setsize" class="property-reference">aria-setsize</a> or <a href="#aria-posinset" class="property-reference">aria-posinset</a>.
The tabbed carousel implementation pattern does not have this limitation.
</li>
<li>Note that since the <code>aria-roledescription</code> is set to "slide", the label does not contain the word "slide."</li>
</ul>
</li>
<li>
Optionally, an element wrapping the set of slide elements has <a href="#aria-atomic" class="property-reference">aria-atomic</a> set to <code>false</code>
and <a href="#aria-live" class="property-reference">aria-live</a> set to:
<ul>
<li><code>off</code>: if the carousel is automatically rotating.</li>
<li><code>polite</code>: if the carousel is <strong>NOT</strong> automatically rotating.</li>
</ul>
</li>
</ul>
<h5>Tabbed Carousel Elements</h5>
<p>The structure of a tabbed carousel is the same as a basic carousel except that:</p>
<ul>
<li>
Each slide container has role <a href="#tabpanel" class="role-reference">tabpanel</a> in lieu of <code>group</code>,
and it does not have the <code>aria-roledescription</code> property.
</li>
<li>It has slide picker controls implemented using the <a href="#tabpanel">tabs pattern</a> where:
<ul>
<li>Each control is a <code>tab</code> element, so activating a tab displays the slide associated with that tab.</li>
<li>The accessible name of each <code>tab</code> indicates which slide it will display by including the name or number of the slide, e.g., "Slide 3". Slide names are preferable if each slide has a unique name.</li>
<li>The set of controls is grouped in a <code>tablist</code> element with an accessible name provided by the value of <a href="#aria-label" class="property-reference">aria-label</a> that identifies the purpose of the tabs, e.g., "Choose slide to display."</li>
<li>The <code>tab</code>, <code>tablist</code>, and <code>tabpanel</code> implement the properties specified in the <a href="#tabpanel">tabs pattern</a>.</li>
</ul>
</li>
</ul>
<h5>Grouped Carousel Elements</h5>
<p>A grouped carousel has the same structure as a basic carousel, but it also includes slide picker controls where:</p>
<ul>
<li>The set of slide picker controls is contained in an element with role <a href="#group" class="role-reference">group</a>.</li>
<li>The group containing the picker controls has an accessible label provided by the value of <a href="#aria-label" class="property-reference">aria-label</a> that identifies the purpose of the controls, e.g., "Choose slide to display."</li>
<li>Each picker control is a native button element (recommended) or implements the <a href="#button">button pattern.</a></li>
<li>
The accessible name of each picker button matches the name of the slide it displays.
One technique for accomplishing this is to set <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> to a value that references the slide <code>group</code> element.
</li>
<li>
The picker button representing the currently displayed slide has the property <a href="#aria-disabled" class="property-reference">aria-disabled</a> set to <code>true</code>.
Note: <code>aria-disabled</code> is preferable to the HTML <code>disabled</code> attribute because this is a circumstance where screen reader users benefit from the disabled button being included in the page <kbd>Tab</kbd> sequence.
</li>
</ul>
</section>
</section>
<section class="widget" id="checkbox">
<h3>Checkbox</h3>
<p>WAI-ARIA supports two types of <a href="#checkbox" class="role-reference">checkbox</a> widgets:</p>
<ol>
<li>Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.</li>
<li>Tri-state: This type of checkbox supports an additional third state known as partially checked.</li>
</ol>
<p>
One common use of a tri-state checkbox can be found in software installers where a single tri-state checkbox is used to represent and control the state of an entire group of install options.
And, each option in the group can be individually turned on or off with a dual state checkbox.
</p>
<ul>
<li>If all options in the group are checked, the overall state is represented by the tri-state checkbox displaying as checked.</li>
<li>If some of the options in the group are checked, the overall state is represented with the tri-state checkbox displaying as partially checked.</li>
<li>If none of the options in the group are checked, the overall state of the group is represented with the tri-state checkbox displaying as not checked.</li>
</ul>
<p>The user can use the tri-state checkbox to change all options in the group with a single action:</p>
<ul>
<li>Checking the overall checkbox checks all options in the group.</li>
<li>Unchecking the overall checkbox will uncheck all options in the group.</li>
<li>
And, In some implementations, the system may remember which options were checked the last time the overall status was partially checked.
If this feature is provided, activating the overall checkbox a third time recreates that partially checked state where only some options in the group are checked.
</li>
</ul>
<section class="notoc">
<h4>Examples</h4>
<ul>
<li>
<a href="examples/checkbox/checkbox.html">Checkbox (Two-State) Example</a>: Demonstrates a simple 2-state checkbox.
</li>
<li>
<a href="examples/checkbox/checkbox-mixed.html">Checkbox (Mixed-State) Example</a>:
Demonstrates a checkbox that uses the mixed value for aria-checked to reflect and control checked states within a group of two-state HTML checkboxes contained in an HTML <code>fieldset</code>.
</li>
</ul>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>When the checkbox has focus, pressing the <kbd>Space</kbd> key changes the state of the checkbox.</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The checkbox has role <a href="#checkbox" class="role-reference">checkbox</a>.</li>
<li>
The checkbox has an accessible label provided by one of the following:
<ul>
<li>Visible text content contained within the element with role <code>checkbox</code>.</li>
<li>A visible label referenced by the value of <a href="#aria-labelledby" class="property-reference" >aria-labelledby</a> set on the element with role <code>checkbox</code>.</li>
<li><a href="#aria-label" class="property-reference">aria-label</a> set on the element with role <code>checkbox</code>.</li>
</ul>
</li>
<li>When checked, the checkbox element has state <a href="#aria-checked" class="state-reference" >aria-checked</a> set to <code>true</code>.</li>
<li>When not checked, it has state <a href="#aria-checked" class="state-reference" >aria-checked</a> set to <code>false</code>.</li>
<li>When partially checked, it has state <a href="#aria-checked" class="state-reference" >aria-checked</a> set to <code>mixed</code>.</li>
<li>If a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role <a href="#group" class="role-reference" >group</a> that has the property <a href="#aria-labelledby" class="property-reference" >aria-labelledby</a> set to the ID of the element containing the label.</li>
<li>If the presentation includes additional descriptive static text relevant to a checkbox or checkbox group, the checkbox or checkbox group has the property <a href="#aria-describedby" class="property-reference">aria-describedby</a> set to the ID of the element containing the description.</li>
</ul>
</section>
</section>
<section class="widget" id="combobox">
<h3>Combobox</h3>
<p>
A <a href="#combobox" class="role-reference">combobox</a> is an input widget with an associated popup that enables users to select a value for the combobox from a collection of possible values.
In some implementations, the popup presents allowed values, while in other implementations, the popup presents suggested values, and users may either select one of the suggestions or type a value.
The popup may be a <a href="#Listbox">listbox</a>,
<a href="#grid">grid</a>,
<a href="#TreeView">tree</a>, or
<a href="#dialog_modal">dialog.</a>
Many implementations also include a third optional element -- a graphical <q>Open</q> button adjacent to the combobox, which indicates availability of the popup.
Activating the <q>Open</q> button displays the popup if suggestions are available.
</p>
<p>
The combobox pattern supports several optional behaviors.
The one that most shapes interaction is text input.
Some comboboxes allow users to type and edit text in the combobox and others do not.
If a combobox does not support text input, it is referred to as select-only, meaning the only way users can set a value is by selecting a value in the popup.
For example, in some browsers, an HTML <code>select</code> element with <code>size="1"</code> is presented to assistive technologies as a combobox.
Alternatively, if a combobox supports text input, it is referred to as editable.
An editable combobox may either allow users to input any arbitrary value, or it may restrict its value to a discrete set of allowed values, in which case typing input serves to filter suggestions presented in the popup.
</p>
<p>The popup is hidden by default, i.e., the default state is collapsed. The conditions that trigger expansion -- display of the popup --are specific to each implementation. Some possible conditions that trigger expansion include:</p>
<ul>
<li>It is displayed when the <kbd>Down Arrow</kbd> key is pressed or the <q>Open</q> button is activated. Optionally, if the combobox is editable and contains a string that does not match an allowed value, expansion does not occur.</li>
<li>It is displayed when the combobox receives focus even if the combobox is editable and empty.</li>
<li>If the combobox is editable, the popup is displayed only if a certain number of characters are typed in the combobox and those characters match some portion of one of the suggested values.</li>
</ul>
<p>Combobox widgets are useful for acquiring user input in either of two scenarios:</p>
<ol>
<li>
The value must be one of a predefined set of allowed values, e.g., a location field must contain a valid location name.
Note that the listbox and menu button patterns are also useful in this scenario; differences between combobox and alternative patterns are described below.
</li>
<li>
An arbitrary value is allowed, but it is advantageous to suggest possible values to users.
For example, a search field may suggest similar or previous searches to save the user time.
</li>
</ol>
<p>
The nature of possible values presented by a popup and the way they are presented is called the autocomplete behavior.
Comboboxes can have one of four forms of autocomplete:
</p>
<ol>
<li>
<strong>No autocomplete:</strong> The combobox is editable, and when the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the combobox.
For example, the popup suggests a set of recently entered values, and the suggestions do not change as the user types.
</li>
<li>
<strong>List autocomplete with manual selection:</strong> When the popup is triggered, it presents suggested values. If the combobox is editable, the suggested values complete or logically correspond to the characters typed in the combobox.
The character string the user has typed will become the value of the combobox unless the user selects a value in the popup.
</li>
<li>
<strong>List autocomplete with automatic selection:</strong> The combobox is editable, and when the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the combobox,
and the first suggestion is automatically highlighted as selected.
The automatically selected suggestion becomes the value of the combobox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the combobox.
</li>
<li>
<strong>List with inline autocomplete:</strong> This is the same as list with automatic selection with one additional feature.
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 combobox.
The inline completion string is visually highlighted and has a selected state.
</li>
</ol>
<p>
If a combobox is editable and has any form of list autocomplete, the popup may appear and disappear as the user types.
For example, if the user types a two character string that triggers five suggestions to be displayed but then types a third character that forms a string that does not have any matching suggestions,
the popup may close and, if present, the inline completion string disappears.
</p>
<p>
Two other widgets that are also visually compact and enable users to make a single choice from a set of discrete choices are <a href="#Listbox">listbox</a> and <a href="#menubutton">menu button</a>.
One feature that distinguishes combobox from both listbox and menu button is that the user's choice can be presented as a value in an editable field, which gives users the ability to select some or all of the value for copying to the clipboard.
Comboboxes and menu buttons can be implemented so users can explore the set of allowed choices without losing a previously made choice.
That is, users can navigate the set of available choices in a combobox popup or menu and then press <kbd>escape</kbd>, which closes the popup or menu without changing previous input.
In contrast, navigating among options in a single-select listbox immediately changes its value, and <kbd>Escape</kbd> does not provide an undo mechanism.
Comboboxes and listboxes can be marked as required with <code>aria-required="true"</code>, and they have an accessible name that is distinct from their value.
Thus, when assistive technology users focus either a combobox or listbox in its default state, they can perceive both a name and value for the widget.
However, a menu button cannot be marked required, and while it has an accessible name, it does not have a value so is not suitable for conveying the user's choice in its collapsed state.
</p>
<section class="notoc">
<h4>Examples</h4>
<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="examples/combobox/combobox-autocomplete-both.html">Editable Combobox with Both List and Inline Autocomplete</a>: An editable combobox that demonstrates the autocomplete behavior known as <q>list with inline autocomplete</q>.</li>
<li><a href="examples/combobox/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="examples/combobox/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="examples/combobox/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>
<li><a href="examples/combobox/combobox-datepicker.html">Date Picker Combobox</a>: An editable date input combobox that opens a dialog containing a calendar grid and buttons for navigating by month and year.</li>
</ul>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Tab</kbd>: The combobox is in the page <kbd>Tab</kbd> sequence.</li>
<li>Note: The popup indicator icon or button (if present), the popup, and the popup descendants are excluded from the page <kbd>Tab</kbd> sequence. </li>
</ul>
<h5>Combobox Keyboard Interaction</h5>
<p>When focus is in the combobox:</p>
<ul>
<li><kbd>Down Arrow</kbd>: If the popup is available, moves focus into the popup:
<ul>
<li>If the autocomplete behavior automatically selected a suggestion before <kbd>Down Arrow</kbd> was pressed, focus is placed on the suggestion following the automatically selected suggestion.</li>
<li>Otherwise, places focus on the first focusable element in the popup.</li>
</ul>
</li>
<li><kbd>Up Arrow</kbd> (Optional): If the popup is available, places focus on the last focusable element in the popup.</li>
<li><kbd>Escape</kbd>: Dismisses the popup if it is visible. Optionally, if the popup is hidden before <kbd>Escape</kbd> is pressed, clears the combobox.</li>
<li>
<kbd>Enter</kbd>: If the combobox is editable and an autocomplete suggestion is selected in the popup, accepts the suggestion either by placing the input cursor at the end of the accepted value in the combobox or by performing a default action on the value.
For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the combobox so the user can add another recipient.
</li>
<li>Printable Characters:
<ul>
<li>If the combobox is editable, type characters in the combobox. Note that some implementations may regard certain characters as invalid and prevent their input.</li>
<li>If the combobox is not editable, optionally moves focus to a value that starts with the typed characters.</li>
</ul>
</li>
<li>If the combobox is editable, it supports standard single line text editing keys appropriate for the device platform (see note below).</li>
<li><kbd>Alt + Down Arrow</kbd> (Optional): If the popup is available but not displayed, displays the popup without moving focus.</li>
<li><kbd>Alt + Up Arrow</kbd> (Optional): If the popup is displayed:
<ul>
<li>If the popup contains focus, returns focus to the combobox.</li>
<li>Closes the popup.</li>
</ul>
</li>
</ul>
<div class="note">
<p>Standard single line text editing keys appropriate for the device platform:</p>
<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> Ensure JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.</li>
</ol>
</div>
<h5>Listbox Popup Keyboard Interaction</h5>
<p>When focus is in a listbox popup:</p>
<ul>
<li><kbd>Enter</kbd>: Accepts the focused option in the listbox by closing the popup, placing the accepted value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the combobox. Optionally, if the combobox is editable, clears the contents of the combobox.</li>
<li><kbd>Down Arrow</kbd>: Moves focus to and selects the next option. If focus is on the last option, either returns focus to the combobox or does nothing.</li>
<li><kbd>Up Arrow</kbd>: Moves focus to and selects the previous option. If focus is on the first option, either returns focus to the combobox or does nothing.</li>
<li>
<kbd>Right Arrow</kbd>: If the combobox is editable, returns focus to the combobox without closing the popup and moves the input cursor one character to the right.
If the input cursor is on the right-most character, the cursor does not move.
</li>
<li>
<kbd>Left Arrow</kbd>: If the combobox is editable, returns focus to the combobox without closing the popup and moves the input cursor one character to the left.
If the input cursor is on the left-most character, the cursor does not move.
</li>
<li><kbd>Home</kbd> (Optional): Either moves focus to and selects the first option or, if the combobox is editable, returns focus to the combobox and places the cursor on the first character.</li>
<li><kbd>End</kbd> (Optional): Either moves focus to the last option or, if the combobox is editable, returns focus to the combobox and places the cursor after the last character.</li>
<li>Any printable character:
<ul>
<li>If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.</li>
<li>Otherwise, moves focus to the next option with a name that starts with the characters typed.</li>
</ul>
</li>
<li><kbd>Backspace</kbd> (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</li>
</ul>
<ol class="note">
<li>DOM Focus is maintained on the combobox and the assistive technology focus is moved within the listbox using <code>aria-activedescendant</code> as described in <a href="#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant.</a></li>
<li>Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the combobox value.</li>
</ol>
<h5>Grid Popup Keyboard Interaction</h5>
<p>
In a grid popup, each suggested value may be represented by either a single cell or an entire row.
See notes below for how this aspect of grid design effects the keyboard interaction design and the way that selection moves in response to focus movements.
</p>
<ul>
<li><kbd>Enter</kbd>: Accepts the currently selected suggested value by closing the popup, placing the selected value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the combobox. Optionally, if the combobox is editable, clears the contents of the combobox.</li>
<li>
<kbd>Right Arrow</kbd>: Moves focus one cell to the right.
Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row.
If focus is on the last cell in the grid, either does nothing or returns focus to the combobox.
</li>
<li>
<kbd>Left Arrow</kbd>: Moves focus one cell to the left.
Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row.
If focus is on the first cell in the grid, either does nothing or returns focus to the combobox.
</li>
<li>
<kbd>Down Arrow</kbd>: Moves focus one cell down.
If focus is in the last row of the grid, either does nothing or returns focus to the combobox.
</li>
<li>
<kbd>Up Arrow</kbd>: Moves focus one cell up.
If focus is in the first row of the grid, either does nothing or returns focus to the combobox.
</li>
<li>
<kbd>Page Down</kbd> (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows.
If focus is in the last row of the grid, focus does not move.
</li>
<li>
<kbd>Page Up</kbd> (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows.
If focus is in the first row of the grid, focus does not move.
</li>
<li><kbd>Home</kbd> (Optional): <strong>Either:</strong>
<ul>
<li> Moves focus to the first cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the first cell in the grid.</li>
<li>If the combobox is editable, returns focus to the combobox and places the cursor on the first character.</li>
</ul>
</li>
<li><kbd>End</kbd> (Optional): <strong>Either:</strong>
<ul>
<li> Moves focus to the last cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the last cell in the grid.</li>
<li>If the combobox is editable, returns focus to the combobox and places the cursor after the last character.</li>
</ul>
</li>
<li><kbd>Control + Home</kbd> (optional): moves focus to the first row.</li>
<li><kbd>Control + End</kbd> (Optional): moves focus to the last row.</li>
<li>Any printable character: If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.</li>
<li><kbd>Backspace</kbd> (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</li>
</ul>
<ol class="note">
<li>DOM Focus is maintained on the combobox and the assistive technology focus is moved within the grid using <code>aria-activedescendant</code> as described in <a href="#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant.</a></li>
<li>The grid allows only one suggested value to be selected at a time for the combobox value.</li>
<li>In a grid popup, each suggested value may be represented by either a single cell or an entire row. This aspect of design effects focus and selection movement:
<ol>
<li>If every cell contains a different suggested value:
<ul>
<li>Selection follows focus so that the cell containing focus is selected.</li>
<li>Horizontal arrow key navigation typically wraps from one row to another.</li>
<li>Vertical arrow key navigation typically wraps from one column to another.</li>
</ul>
</li>
<li>If all cells in a row contain information about the same suggested value:
<ul>
<li>Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.</li>
<li>Horizontal key navigation may wrap from one row to another.</li>
<li>Vertical arrow key navigation <strong>does not</strong> wrap from one column to another.</li>
</ul>
</li>
</ol>
</li>
</ol>
<h5>Tree Popup Keyboard Interaction</h5>
<p>
In some implementations of tree popups, some or all parent nodes may serve as suggestion category labels so may not be selectable values.
See notes below for how this aspect of the design effects the way selection moves in response to focus movements.
</p>
<p>When focus is in a vertically oriented tree popup:</p>
<ul>
<li><kbd>Enter</kbd>: Accepts the currently selected suggested value by closing the popup, placing the selected value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the combobox. Optionally, clears the contents of the combobox.</li>
<li><kbd>Right arrow</kbd>:
<ul>
<li>When focus is on a closed node, opens the node; focus and selection do not move.</li>
<li>When focus is on a open node, moves focus to the first child node and selects it if it is selectable.</li>
<li>When focus is on an end node, does nothing.</li>
</ul>
</li>
<li><kbd>Left arrow</kbd>:
<ul>
<li>When focus is on an open node, closes the node.</li>
<li>When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node and selects it if it is selectable.</li>
<li>When focus is on a root node that is also either an end node or a closed node, does nothing.</li>
</ul>
</li>
<li><kbd>Down Arrow</kbd>: Moves focus to the next node that is focusable without opening or closing a node and selects it if it is selectable.</li>
<li><kbd>Up Arrow</kbd>: Moves focus to the previous node that is focusable without opening or closing a node and selects it if it is selectable.</li>
<li><kbd>Home</kbd>: Moves focus to the first focusable node in the tree without opening or closing a node and selects it if it is selectable.</li>
<li><kbd>End</kbd>: Moves focus to the last focusable node in the tree without opening or closing a node and selects it if it is selectable.</li>
<li>Any printable character:
<ul>
<li>If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.</li>
<li>Otherwise, moves focus to the next suggested value with a name that starts with the characters typed.</li>
</ul>
</li>