-
Notifications
You must be signed in to change notification settings - Fork 304
/
aria-practices.html
4622 lines (4281 loc) · 297 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 xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<meta charset="utf-8" />
<title>WAI-ARIA Authoring Practices 1.1</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script src="common/script/resolveReferences.js" class="remove"></script>
<script src="common/biblio.js" class="remove"></script>
<script src="respec-config.js" 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.1/"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> 1.1</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
<a href="" class="specref">WAI-ARIA 1.1</a> [<cite><a href="#bib-WAI-ARIA" class="bibref">WAI-ARIA</a></cite>]
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.1. 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:public-aria@w3.org?subject=Comment%20on%20WAI-ARIA%20Practices%201.1">public-aria@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/public-aria/">comment archive</a>).
</p>
</section>
<section id="intro">
<h2>Introduction</h2>
<p>This section is <em>informative.</em></p>
<p>
WAI-ARIA Authoring Practices is a guide for understanding how to use
<cite><a href="https://www.w3.org/TR/wai-aria-1.1/">WAI-ARIA 1.1</a></cite> to create an accessible Rich Internet Application.
It provides guidance on the appropriate application of WAI-ARIA, describes recommended WAI-ARIA usage patterns, and explains concepts behind them.
</p>
<p>
Languages used to create rich and dynamic web sites, e.g., HTML, JavaScript, CSS, and SVG, do not natively include all the features required to make sites usable by people who use assistive technologies (AT) or who rely on keyboard navigation.
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>
<p>
After a brief <q>Read Me First</q> section, the guide begins with ARIA implementation patterns for common widgets that both enumerate expected behaviors and demonstrate those behaviors with working code.
The implementation patterns and examples refer to detailed explanations of supporting concepts in subsequent guidance sections.
The guidance sections cover more general topics such as use of ARIA landmarks, practices for keyboard interfaces, grid and table properties, and the effects of role <code>presentation</code>.
</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>Principal 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.1 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.1 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, Internet Explorer, and Safari at the time of writing.
In particular, some JavaScript and CSS may not function correctly in Internet Explorer version 10 or earlier.
</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.1.
</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>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>
<li>
<kbd>Control + Page Down</kbd> (Optional): If focus is inside an accordion
panel or on an accordion header, moves focus to the next accordion header.
If focus is in the last accordion header or panel, either does nothing or
moves focus to the first accordion header.
</li>
<li>
<kbd>Control + Page Up</kbd> (Optional): If focus is inside an accordion panel, moves focus to the header for that panel.
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>
</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/index.html">Alert Example</a></p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>An alert (WAI-ARIA live region) does not require any keyboard interaction.</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>
Developing an example implementation of this pattern is <a href="https://github.com/w3c/aria-practices/issues/101">issue 101</a>.
</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 title.
</li>
<li>
A value for
<a href="#aria-label" class="property-reference">aria-label</a>
if the dialog does not have a visible title.
</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 labeled 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 labeled 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>
<p><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.</p>
</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="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-1/checkbox-1.html">Simple Two-State Checkbox Example</a>: Demonstrates a simple 2-state checkbox.
</li>
<li>
<a href="examples/checkbox/checkbox-2/checkbox-2.html">Tri-State Checkbox Example</a>:
Demonstrates how to make a widget that uses the <code>mixed</code> value for <code>aria-checked</code> and group collection of checkboxes with a field set.
</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>Combo Box</h3>
<p>
A <a href="#combobox" class="role-reference">combobox</a> is a widget made up of the combination of two distinct elements:
1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox.
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 button adjacent to the textbox, indicating the availability of the popup.
Activating the button displays the popup if suggestions are available.
</p>
<p>The popup is hidden by default, and the conditions that trigger its display are specific to each implementation. Some possible popup display conditions include:</p>
<ul>
<li>It is displayed only if a certain number of characters are typed in the textbox and those characters match some portion of one of the suggested values.</li>
<li>It is displayed as soon as the textbox is focused, even if the textbox is empty.</li>
<li>It is displayed when the <kbd>Down Arrow</kbd> key is pressed or the <q>show</q> button is activated, possibly with a dependency on the content of the textbox.</li>
<li>It is displayed if the value of the textbox is altered in a way that creates one or more partial matches to a suggested value.</li>
</ul>
<p>Combobox widgets are useful for setting the value of a single-line textbox in one of two types of scenarios:</p>
<ol>
<li>
The value for the textbox must be chosen from 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>
The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user,
e.g., a search field may suggest similar or previous searches to save the user time.
</li>
</ol>
<p>
The nature of the suggested values and the way the suggestions are presented is called the autocomplete behavior.
Comboboxes can have one of four forms of autocomplete:
</p>
<ol>
<li>
<strong>No autocomplete:</strong> When the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the textbox.
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 that complete or logically correspond to the characters typed in the textbox.
The character string the user has typed will become the value of the textbox unless the user selects a value in the popup.
</li>
<li>
<strong>List autocomplete with automatic selection:</strong> When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox,
and the first suggestion is automatically highlighted as selected.
The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox.
</li>
<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 textbox.
The inline completion string is visually highlighted and has a selected state.
</li>
</ol>
<p>
With 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>
When constructing a widget that is both visually compact and enables users to choose one value from a set of discrete values, often either a <a href="#Listbox">listbox</a> or <a href="#menubutton">menu button</a> is simpler to implement and use.
One feature of combobox that distinguishes it from both listbox and menu button is that the value of the combobox is presented in an edit field.
Thus, the combobox gives users one function that both listbox and menu button lack, namely the ability to select some or all of the value for copying to the clipboard.
One feature that distinguishes both combobox and menu button widgets from listbox widgets is their ability to provide an undo mechanism.
In many implementations, users can navigate the set of allowed values in a combobox or menu and then decide to revert to the value the widget had before navigating by pressing <kbd>escape</kbd>.
In contrast, navigating a listbox immediately changes its value, and escape does not provide an undo mechanism.
</p>
<p class="note">
The options for a combobox to popup a grid, tree, or dialog were introduced in ARIA 1.1.
Changes made in the ARIA 1.1 specification also add support for a code pattern that enables assistive technologies to present the textbox and popup as separately perceivable elements.
both ARIA 1.0 and 1.1 patterns are described in the following sections.
While using the ARIA 1.1 pattern is recommended as soon as assistive technology support is sufficient,
there are no plans to deprecate the ARIA 1.0 pattern.
</p>
<section class="notoc">
<h4>Examples</h4>
<ul>
<li><a href="examples/combobox/aria1.1pattern/listbox-combo.html">Examples of ARIA 1.1 Combobox with Listbox Popup</a>: Comboboxes that demonstrate the various forms of autocomplete behavior using a listbox popup and use the ARIA 1.1 implementation pattern.</li>
<li><a href="examples/combobox/aria1.1pattern/grid-combo.html">Example of ARIA 1.1 Combobox with Grid Popup</a>: A combobox that presents suggestions in a grid, enabling users to navigate descriptive information about each suggestion.</li>
<li><a href="examples/combobox/aria1.0pattern/combobox-autocomplete-both.html">ARIA 1.0 Combobox with Both List and Inline Autocomplete</a>: A combobox that demonstrates the autocomplete behavior known as <q>list with inline autocomplete</q> and uses the ARIA 1.0 implementation pattern.</li>
<li><a href="examples/combobox/aria1.0pattern/combobox-autocomplete-list.html">ARIA 1.0 Combobox with List Autocomplete</a>: A combobox that demonstrates the autocomplete behavior known as <q>list with manual selection</q> and uses the ARIA 1.0 implementation pattern.</li>
<li><a href="examples/combobox/aria1.0pattern/combobox-autocomplete-none.html">ARIA 1.0 Combobox Without Autocomplete</a>: A combo box that demonstrates the behavior associated with <code>aria-autocomplete=none</code> and uses the ARIA 1.0 implementation pattern.</li>
</ul>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Tab</kbd>: The textbox 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>Textbox Keyboard Interaction</h5>
<p>When focus is in the textbox:</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, clears the textbox.</li>
<li>
<kbd>Enter</kbd>: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox 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 textbox so the user can add another recipient.
</li>
<li>Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.</li>
<li>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:
<ol>
<li>If the popup contains focus, returns focus to the textbox.</li>
<li>Closes the popup.</li>
</ol>
</li>
</ul>
<p class="note">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> Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.</li>
</ol>
<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 and placing the accepted value in the textbox with the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.</li>
<li>
<kbd>Right Arrow</kbd>: Returns focus to the textbox 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>: Returns focus to the textbox 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>Any printable character: Returns the focus to the textbox without closing the popup and types the character.</li>
<li><kbd>Backspace</kbd> (Optional): Returns focus to the textbox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</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 textbox 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 textbox or does nothing.</li>
<li><kbd>Home</kbd> (Optional): Either moves focus to and selects the first option or returns focus to the textbox and places the cursor on the first character.</li>
<li><kbd>End</kbd> (Optional): Either moves focus to the last option or returns focus to the textbox and places the cursor after the last character.</li>
</ul>
<ol class="note">
<li>DOM Focus is maintained on the combobox textbox 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 textbox 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 and placing the selected value in the textbox with the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.</li>
<li>Any printable character: Returns the focus to the textbox without closing the popup and types the character.</li>
<li><kbd>Backspace</kbd> (Optional): Returns focus to the textbox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</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 textbox.
</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 textbox.
</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 textbox.
</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 textbox.
</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>Returns focus to the textbox 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>Returns focus to the textbox 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>
</ul>
<ol class="note">
<li>DOM Focus is maintained on the combobox textbox 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 textbox 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 and placing the selected value in the textbox with the input cursor at the end of the value.</li>
<li><kbd>Escape</kbd>: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.</li>
<li>Any printable character: Returns the focus to the textbox without closing the popup and types the character.</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 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 node in the tree that is focusable without opening a node and selects it if it is selectable.</li>
</ul>
<ol class="note">
<li>DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the tree using <code>aria-activedescendant</code> as described in <a href="#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant.</a></li>
<li>The tree allows only one suggested value to be selected at a time for the textbox value.</li>
<li>
In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values.
If focus moves to a node that is not a selectable value, either:
<ul>
<li>The previously selected node, if any, remains selected until focus moves to a node that is selectable.</li>
<li>There is no selected value.</li>
<li>In either case, focus is visually distinct from selection so users can readily see if a value is selected or not.</li>
</ul>
</li>
<li>If the nodes in a tree are arranged horizontally:
<ol>
<li><kbd>Down Arrow</kbd> performs as <kbd>Right Arrow</kbd> is described above, and vice versa.</li>
<li><kbd>Up Arrow</kbd> performs as <kbd>Left Arrow</kbd> is described above, and vice versa.</li>
</ol>
</li>
</ol>
<h5>Dialog Popup Keyboard Interaction</h5>
<p>When focus is in a dialog popup:</p>
<ul>
<li>There are two ways to close the popup and return focus to the textbox:
<ol>
<li>Perform an action in the dialog, such as activate a button, that specifies a value for the textbox.</li>
<li>
Cancel out of the dialog, e.g., press <kbd>Escape</kbd> or activate the cancel button in the dialog.
Canceling either returns focus to the text box without changing the textbox value or returns focus to the textbox and clears the textbox.
</li>
</ol>
</li>
<li>The dialog implements the keyboard interaction defined in the <a href="#dialog_modal">modal dialog pattern.</a></li>
</ul>
<p class="note">
Unlike other combobox popups, dialogs do not support <code>aria-activedescendant</code> so DOM focus moves into the dialog from the textbox.
</p>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>
The role, state, and property guidance where the ARIA 1.1 and ARIA 1.0 patterns differ is listed first.
The subsequent guidance applies to both patterns.
</p>
<ul>
<li>In a combobox implementing the ARIA 1.1 pattern:
<ul>
<li>The element that serves as the combobox container has role <a href="#combobox" class="role-reference">combobox</a>.</li>
<li>The element with role <code>combobox</code> contains or owns a textbox element that has either role <a href="#textbox" class="role-reference">textbox</a> or role <a href="#searchbox" class="role-reference">searchbox</a>.</li>
<li>When the combobox popup is visible, the combobox element contains or owns an element that has role <a href="#listbox" class="role-reference">listbox</a>, <a href="#tree" class="role-reference">tree</a>, <a href="#grid" class="role-reference">grid</a>, or <a href="#dialog" class="role-reference">dialog</a>.</li>
<li>
If the combobox popup has a role other than <code>listbox</code>, the element with role <code>combobox</code> has <a href="#aria-haspopup" class="property-reference">aria-haspopup</a> set to a value that corresponds to the popup type.
That is, <code>aria-haspopup</code> is set to <code>grid</code>, <code>tree</code>, or <code>dialog</code>.
Note that elements with role <code>combobox</code> have an implicit <code>aria-haspopup</code> value of <code>listbox</code>.
</li>
<li>When the combobox popup is visible, the textbox element has <a href="#aria-controls" class="property-reference">aria-controls</a> set to a value that refers to the combobox popup element.</li>
</ul>
</li>
<li>In a combobox implementing the ARIA 1.0 pattern:
<ul>
<li>The element that serves as the textbox has role <a href="#combobox" class="role-reference">combobox</a>.</li>
<li>When the combobox popup is visible, the element with role combobox has <a href="#aria-owns" class="property-reference">aria-owns</a> set to a value that refers to an element with role <a href="#listbox" class="role-reference">listbox</a>.</li>
<li>
the element with role <code>combobox</code> has a value for <a href="#aria-haspopup" class="property-reference">aria-haspopup</a> of <code>listbox</code>.
Note that elements with role <code>combobox</code> have an implicit <code>aria-haspopup</code> value of <code>listbox</code>.
</li>
</ul>
</li>
<li>
The textbox element has a value for <a href="#aria-multiline" class="property-reference">aria-multiline</a> of <code>false</code>.
Note that the default value of <code>aria-multiline</code> is <code>false</code>.
</li>
<li>
When the combobox popup is not visible, the element with role <code>combobox</code> has <a href="#aria-expanded" class="state-reference">aria-expanded</a> set to <code>false</code>.
When the popup element is visible, <code>aria-expanded</code> is set to <code>true</code>.
Note that elements with role <code>combobox</code> have a default value for <code>aria-expanded</code> of <code>false</code>.
</li>
<li>When a combobox receives focus, DOM focus is placed on the textbox element.</li>
<li>When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has <a href="#aria-activedescendant" class="property-reference">aria-activedescendant</a> set to a value that refers to the focused element within the popup.</li>
<li>In a combobox with a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the <code>option</code>, <code>gridcell</code>, <code>row</code>, or <code>treeitem</code> containing that value has <a href="#aria-selected" class="state-reference">aria-selected</a> set to <code>true</code>.</li>
<li>
If the combobox has a visible label, the element with role combobox has <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> set to a value that refers to the labeling element.
Otherwise, the combobox element has a label provided by <a href="#aria-label" class="property-reference">aria-label</a>.
</li>
<li>The textbox element has <a href="#aria-autocomplete" class="property-reference">aria-autocomplete</a> set to a value that corresponds to its autocomplete behavior:
<ul>
<li><code>none</code>: When the popup is displayed, the suggested values it contains are the same regardless of the characters typed in the textbox.</li>
<li><code>list</code>: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.</li>
<li>
<code>both</code>: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
In addition, the portion of the selected suggestion that has not been typed by the user, known as the <q>completion string</q>, appears inline after the input cursor in the textbox.
The inline completion string is visually highlighted and has a selected state.
</li>
</ul>
</li>
</ul>
<ol class="note">
<li>When referring to the roles, states, and properties documentation for the below list of patterns used for popups, keep in mind that a combobox is a single-select widget where selection always follows focus in the popup.</li>
<li>The roles, states, and properties for popup elements are defined in their respective design patterns:
<ul>
<li><a href="#listbox_roles_states_props">Listbox Roles, States, and Properties</a></li>
<li><a href="#grid_roles_states_props">Grid Roles, States, and Properties</a></li>
<li><a href="#tree_roles_states_props">Tree Roles, States, and Properties</a></li>
<li><a href="#dialog_roles_states_props">Dialog Roles, States, and Properties</a></li>
</ul>
</li>
</ol>
</section>
</section>
<section class="widget" id="dialog_modal">
<h3>Dialog (Modal)</h3>
<p>
A <a href="#dialog" class="role-reference">dialog</a> is a window overlayed on either the primary window or another dialog window.
Windows under a modal dialog are inert.
That is, users cannot interact with content outside an active dialog window.
Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern,
and in some implementations, attempts to interact with the inert content cause the dialog to close.
</p>
<p>
Like non-modal dialogs, modal dialogs contain their tab sequence.
That is, <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> do not move focus outside the dialog.
However, unlike most non-modal dialogs, modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog.
</p>
<p>
The <a href="#alertdialog" class="role-reference">alertdialog</a> role is a special-case dialog role
designed specifically for dialogs that divert users' attention to a brief, important message.
Its usage is described in the <a href="#alertdialog">alert dialog design pattern.</a>
</p>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/dialog-modal/dialog.html">Modal Dialog Example</a></p>
</section>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>In the following description, the term <q>tabbable element</q> refers to any element with a <code>tabindex</code> value of zero or greater. Note that values greater than 0 are strongly discouraged.</p>
<ul>
<li>When a dialog opens, focus moves to an element inside the dialog. See notes below regarding initial focus placement.</li>
<li><kbd>Tab</kbd>:
<ul>
<li>Moves focus to the next tabbable element inside the dialog.</li>
<li>If focus is on the last tabbable element inside the dialog, moves focus to the first tabbable element inside the dialog. </li>
</ul>
</li>
<li><kbd>Shift + Tab</kbd>:
<ul>
<li>Moves focus to the previous tabbable element inside the dialog.</li>
<li>If focus is on the first tabbable element inside the dialog, moves focus to the last tabbable element inside the dialog.</li>
</ul>
</li>
<li><kbd>Escape</kbd>: Closes the dialog.</li>
</ul>
<ol class="note">
<li> When a dialog opens, focus placement depends on the nature and size of the content.
<ul>
<li>In all circumstances, focus moves to an element contained in the dialog.</li>
<li>Unless a condition where doing otherwise is advisable, focus is initially set on the first focusable element.</li>
<li>
If content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view,
it is advisable to add <code>tabindex=<q>-1</q></code> to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.
</li>
<li>
If a dialog contains the final step in a process that is not easily reversible, such as deleting data or completing a financial transaction,
it may be advisable to set focus on the least destructive action, especially if undoing the action is difficult or impossible.
The <a href="#alertdialog">Alert Dialog Pattern</a> is often employed in such circumstances.
</li>
<li>
If a dialog is limited to interactions that either provide additional information or continue processing,
it may be advisable to set focus to the element that is likely to be most frequently used, such as an <q>OK</q> or <q>Continue</q> button.
</li>
</ul>
</li>
<li>
When a dialog closes, focus returns to the element that invoked the dialog unless either:
<ul>
<li>The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.</li>
<li>The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice:
<ol>
<li>It is very unlikely users need to immediately re-invoke the dialog.</li>
<li>The task completed in the dialog is directly related to a subsequent step in the work flow.</li>
</ol>
For example, a grid has an associated toolbar with a button for adding rows.
the Add Rows button opens a dialog that prompts for the number of rows.
After the dialog closes, focus is placed in the first cell of the first new row.
</li>
</ul>
</li>
<li>It is strongly recommended that the tab sequence of all dialogs include a visible element with role <code>button</code> that closes the dialog, such as a close icon or cancel button.</li>
</ol>