forked from w3c/aria-practices
-
Notifications
You must be signed in to change notification settings - Fork 0
/
aria-practices.html
3310 lines (2958 loc) · 206 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>
<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="http://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="http://www.w3.org/WAI/intro/aria.php">WAI-ARIA Overview</a>.</p>
</section>
<section id="sotd"></section>
<section id="intro">
<h2>Introduction</h2>
<p>This section is <em>informative.</em></p>
<p>
WAI-ARIA Authoring Practices is a guide to understanding how to use WAI-ARIA to create an accessible Rich Internet Application.
It describes recommended WAI-ARIA usage patterns and provides an introduction to the concepts behind them.
</p>
<p>
This guide is one part of a suite of resources that support the WAI-ARIA specification.
The WAI-ARIA suite fills accessibility gaps identified by the [[WAI-ARIA-ROADMAP]].
</p>
<p>
As explained in <a href="#ariaBackground">Background on WAI-ARIA</a>, 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, with a focus on the WAI-ARIA specifications.
For an introduction to WAI-ARIA, see the <a href="http://www.w3.org/WAI/intro/aria.php">Accessible Rich Internet Applications Suite (WAI-ARIA) Overview</a>.
</p>
<p>
With the understanding many prefer to learn from examples, the guide begins with a section that demonstrates how to make common widgets accessible with descriptions of expected behaviors supported by working code.
Where it is helpful to do so, the examples refer to detailed explanations of supporting concepts in subsequent sections.
The sections that follow the examples first provide background that helps build understanding of how WAI-ARIA works and how it fits into the larger web technology picture.
Next, the guide covers general steps for building an accessible widget using WAI-ARIA, JavaScript, and CSS, including detailed guidance on how to make rich internet applications keyboard accessible.
The scope then widens to include the full application, addressing the page layout and structural semantics critical to enabling a usable experience with assistive technologies on pages containing both rich applications and rich documents.
It includes guidance on dynamic document management, use of WAI-ARIA Form properties, and the creation of WAI-ARIA-enabled alerts and dialogs.
</p>
</section>
<section id="aria_ex">
<h2>Design Patterns and Widgets</h2>
<p>This section demonstrates how to make common rich internet application widgets and patterns accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.</p>
<p class="note">
Although users of Mac OS X are familiar with using the <kbd>Command</kbd> key instead of the <kbd>Control</kbd> key, the <kbd>Command</kbd> key is typically reserved for desktop applications and OS-level integration.
Until device and platform independence can be addressed in WAI-ARIA 2.0, the primary <kbd>Control</kbd> modifier key for WAI-ARIA widget interaction is specified as <kbd>Control</kbd> on all platforms, including Mac OS X.
</p>
<section id="aria_ex_widget">
<h3>Generally Applicable Keyboard Recommendations </h3>
<p>The following keyboard conventions are applicable to many of the patterns described in subsequent sections.</p>
<ul>
<li><kbd>Shift + F10</kbd> opens associated context menu</li>
<li><kbd>Control + C</kbd> Copies to clipboard </li>
<li><kbd>Control + V</kbd> Pastes from clipboard </li>
<li><kbd>Control + X</kbd> Copies to clipboard and cuts </li>
<li><kbd>Control + Z</kbd> undo last action</li>
<li><kbd>Control + Y</kbd> Redo action</li>
</ul>
</section>
<section class="widget" id="accordion">
<h3>Accordion (Sections With Show/Hide Functionality)</h3>
<p>
An accordion is a vertically stacked set of elements, such as labels or thumbnails, that allow the user to toggle the display of sections of content.
Each labeling element can be expanded or collapsed to reveal or hide its associated 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>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>
Each accordion header is contained in an element with role <a href="#button" class="role-reference">button</a>.
The button label is the label for the associated accordion panel.
</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.
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.
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>
<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>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p><a href="examples/accordion/accordion1.html">Accordion Example</a>: demonstrates a form divided into three sections using an accordion to show one ssection at a time. </p>
</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="http://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="http://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>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 class="notoc">
<h4>Example</h4>
<p><a href="examples/alert/index.html">Alert Example</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>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 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>
<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>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 class="notoc">
<h4>Example</h4>
<p><a href="examples/breadcrumb/index.html">Breadcrumb design pattern example</a></p>
</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 <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>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 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>
<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>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, preferably provided by a visible label associated using <a href="#aria-labelledby" class="property-reference" >aria-labelledby</a>.</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 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>
<section class="widget" id="combobox">
<h3>Combo Box</h3>
<p>Drafting this section is <a href="https://github.com/w3c/aria-practices/issues/31">issue 31</a>. </p>
</section>
<section class="widget" id="dialog_modal">
<h3>Dialog (Modal)</h3>
<p>
Work on this section is in progress. Provide feedback in
<a href="https://github.com/w3c/aria-practices/issues/42">issue 42.</a>
</p>
<p>
A <a href="#dialog" class="role-reference">dialog</a> is a window overlayed on either the primary window or another dialog window.
Like non-modal dialogs, modal dialogs have their own tab sequence, i.e., <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> do not move focus outside the dialog.
However, the window under a modal dialog is typically inert; users cannot interact with content outside the dialog window.
So, unlike non-modal dialogs, a modal dialog does 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>Keyboard Interaction</h4>
<ul>
<li><kbd>Tab</kbd>:
<ul>
<li>Moves focus to the next focusable element inside the dialog.</li>
<li>If focus is on the last element, moves focus to the first focusable element inside the dialog. </li>
</ul>
</li>
<li><kbd>Shift + Tab</kbd>:
<ul>
<li>Moves focus to the previous focusable element inside the dialog.</li>
<li>If focus is on the first element, moves focus to the last focusable 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 is typically set on the first focusable element.
</li>
<li>
When a dialog closes, focus returns to the element that had focus before the dialog was invoked.
This is often the control that opened the dialog.
</li>
</ol>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The element that serves as the dialog container has a role of <a href="#dialog" class="role-reference">dialog</a>.</li>
<li>The dialog has either:
<ul>
<li>The <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> property set to refer to the visible dialog title.</li>
<li>A label specified with <a href="#aria-label" class="property-reference">aria-label</a>.</li>
</ul>
</li>
<li>
The <a href="#aria-describedby" class="property-reference">aria-describedby</a> property can be set on the
element with the <code>dialog</code> role to indicate which
element or elements in the dialog contain content that describes the primary purpose or message of the dialog.
Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.
</li>
</ul>
</section>
<section class="notoc">
<h4>Example</h4>
<p>
Work to develop a dialog example is tracked by
<a href="https://github.com/w3c/aria-practices/issues/103">issue 103.</a>
</p>
</section>
</section>
<section class="widget" id="dialog_nonmodal">
<h3>Dialog (Non-Modal)</h3>
<p>Drafting content for this section is tracked by <a href="https://github.com/w3c/aria-practices/issues/59">issue 59</a>. </p>
</section>
<section class="widget" id="grid">
<h3>Grids : Interactive Tabular Data and Layout Containers</h3>
<p>
A <a href="#grid" class="role-reference">grid</a> widget is a container that enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, <kbd>Home</kbd> , and <kbd>End</kbd>.
As a generic container widget that offers flexible keyboard navigation, it can serve a wide variety of needs.
It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.
While ARIA properties and assistive technologies use row and column nomenclature when describing and presenting the logical structure of elements with the <code>grid</code> role, using the <code>grid</code> role on an element does not necessarily imply that its visual presentation is tabular.
</p>
<p>When presenting content that is tabular, consider the following factors when choosing between implementing this <code>grid</code> patern or the <a href="#table">table</a> pattern.</p>
<ul>
<li>
A <code>grid</code> is a composite widget so it:
<ul>
<li>Always contains multiple focusable elements. </li>
<li>Has only one focusable element in the page tab sequence.</li>
<li>Requires the author to provide code that <a href="#kbd_general_within">manages focus movement inside it</a>.</li>
</ul>
</li>
<li>All focusable elements contained in a table are included in the page tab sequence. </li>
</ul>
<p>
Uses of the <code>grid</code> pattern broadly fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids).
Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design.
To address these factors, the following two sections describe separate keyboard interaction patterns for data and layout grids.
</p>
<section id="dataGrid" class="notoc">
<h4>Data Grids For Presenting Tabular Information</h4>
<p>
A <code>grid</code> can be used to present tabular information that has column titles, row titles, or both.
The <code>grid</code> pattern is particularly useful if the tabular information is editable or interactive.
For example, when data elements are links to more information, rather than presenting them in a static table and including the links in the tab sequence, implementing the <code>grid</code> pattern provides users with intuitive and efficient keyboard navigation of the grid contents as well as a shorter tab sequence for the page.
A <code>grid</code> may also offer functions, such as cell content editing, selection, cut, copy, and paste.
</p>
<p>
In a grid that presents tabular data, every cell contains a focusable element or is itself focusable, regardless of whether the cell content is editable or interactive.
There is one exception: if column or row header cells do not provide functions, such as sort or filter, they do not need to be focusable. One reason this is important is that screen readers need to be in their application reading mode, rather than their document reading mode, while the user is interacting with the grid.
While in application reading mode, a screen reader user can only discover focusable elements and content that labels focusable elements.
So, a screen reader user may unknowningly overlook elements contained in a grid that are either not focusable or not used to label a column or row.
A more detailed description of this topic with examples is available in the section describing <a href="#ScreenReaderModes">screen reader document and application reading modes</a>.
</p>
<section class="notoc">
<h5>Keyboard Interaction For Data Grids</h5>
<p>
The following keys provide grid navigation by moving focus among cells of the grid.
These key commands are available by default after an element in the grid receives focus.
</p>
<ul>
<li>
<kbd>Right Arrow</kbd>: Moves focus one cell to the right.
If focus is on the right-most cell in the row, focus does not move.
</li>
<li><kbd>Left Arrow</kbd>: Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move.</li>
<li><kbd>Down Arrow</kbd>: Moves focus one cell down. If focus is on the bottom cell in the column, focus does not move.</li>
<li><kbd>Up Arrow</kbd>: Moves focus one cell Up. If focus is on the top cell in the column, focus does not move.</li>
<li><kbd>Page Down</kbd>: 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>: 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>: moves focus to the first cell in the row that contains focus.</li>
<li><kbd>End</kbd>: moves focus to the last cell in the row that contains focus.</li>
<li><kbd>Control + Home</kbd>: moves focus to the first cell in the first row.</li>
<li><kbd>Control + End</kbd>: moves focus to the last cell in the last row.</li>
</ul>
<ul class="note">
<li>
When the above grid navigation keys move focus, whether the focus is set on an element inside the cell or the grid cell depends on cell content.
See <a href="#gridNav_focus">Whether to Focus on a Cell or an Element Inside It</a>.
</li>
<li>
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell.
If this functionality is needed, see <a href="#gridNav_inside">Editing and Navigating Inside a Cell</a>.
</li>
<li>If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as <kbd>control + End</kbd>, may move focus to the last row in the DOM rather than the last available row in the back-end data.</li>
</ul>
<p>If a grid supports selection of cells, rows, or columns, the following keys are commonly used for these functions.</p>
<ul>
<li><kbd>Control + Space</kbd>: selects the column that contains the focus.</li>
<li><kbd>Shift + Space</kbd>: Selects the row that contains the focus. If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.</li>
<li><kbd>Control + A</kbd>: Selects all cells.</li>
<li><kbd>Shift + Right Arrow</kbd>: Extends selection one cell to the right.</li>
<li><kbd>Shift + Left Arrow</kbd>: Extends selection one cell to the left.</li>
<li><kbd>Shift + Down Arrow</kbd>: Extends selection one cell down.</li>
<li><kbd>Shift + Up Arrow</kbd>: Extends selection one cell Up.</li>
</ul>
<p class="note">See <a href="#aria_ex_widget">Global Recommendations</a> for cut, copy and paste key assignments.</p>
</section>
</section>
<section id="layoutGrid" class="notoc">
<h4>Layout Grids for Grouping Widgets</h4>
<p>
The <code>grid</code> pattern can be used to group a set of interactive elements, such as links, buttons, or checkboxes.
Since only one element in the entire grid is included in the tab sequence, grouping with a grid can dramatically reduce the number of tab stops on a page.
This is especially valuable if scrolling through a list of elements dynamically loads more of those elements from a large data set, such as in a continuous list of suggested products on a shopping site.
If elements in a list like this were in the tab sequence, keyboard users are effectively trapped in the list.
If any elements in the group also have associated elements that appear on hover, the <code>grid</code> pattern is also useful for providing keyboard access to those contextual elements of the user interface.
</p>
<p>
Unlike grids used to present data, A <code>grid</code> used for layout does not necessarily have header cells for labeling rows or columns and might contain only a single row or a single column.
Even if it has multiple rows and columns, it may present a single, logically homogenous set of elements.
For example, a list of recipients for a message may be a grid where each cell contains a link that represents a recipient.
The grid may initially have a single row but then wrap into multiple rows as recipients are added.
In such circumstances, grid navigation keys may also wrap so the user can read the list from beginning to end by pressing either <kbd>Right Arrow</kbd> or <kbd>Down Arrow</kbd>.
While This type of focus movement wrapping can be very helpful in a layout grid, it would be disorienting if used in a data grid, especially for users of assistive technologies.
</p>
<p>
Because arrow keys are used to move focus inside of a <code>grid</code>, a <code>grid</code> is both easier to build and use if the components it contains do not require the arrow keys to operate.
If a cell contains an element like a <a href="#Listbox">listbox</a>, then an extra key command to focus and activate the listbox is needed as well as a command for restoring the grid navigation functionality.
Aproaches to supporting this need are described in the section on <a href="#gridNav_inside">Editing and Navigating Inside a Cell</a>.
</p>
<section class="notoc">
<h5>Keyboard Interaction For Layout Grids</h5>
<p>
The following keys provide grid navigation by moving focus among cells of the grid.
These key commands are available by default after an element in the grid receives focus.
</p>
<ul>
<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, focus does not move.
</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, focus does not move.
</li>
<li>
<kbd>Down Arrow</kbd>: Moves focus one cell down.
Optionally, if focus is on the bottom cell in the column, focus may move to the top cell in the following column.
If focus is on the last cell in the grid, focus does not move.
</li>
<li>
<kbd>Up Arrow</kbd>: Moves focus one cell up.
Optionally, if focus is on the top cell in the column, focus may move to the bottom cell in the previous column.
If focus is on the first cell in the grid, focus does not move.
</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>: moves focus to the first cell in the row that contains focus.
Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the first cell in the grid.
</li>
<li>
<kbd>End</kbd>: moves focus to the last cell in the row that contains focus.
Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the last cell in the grid.
</li>
<li><kbd>Control + Home</kbd> (optional): moves focus to the first cell in the first row.</li>
<li><kbd>Control + End</kbd> (Optional): moves focus to the last cell in the last row.</li>
</ul>
<ul class="note">
<li>
When the above grid navigation keys move focus, whether the focus is sett on an element inside the cell or the grid cell depends on cell content.
See <a href="#gridNav_focus">Whether to Focus on a Cell or an Element Inside It</a>.
</li>
<li>
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell.
If this functionality is needed, see <a href="#gridNav_inside">Editing and Navigating Inside a Cell</a>.
</li>
<li>If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as <kbd>control + End</kbd>, may move focus to the last row in the DOM rather than the last available row in the back-end data.</li>
</ul>
<p>It would be unusual for a layout grid to provide functions that require cell selection. If it did, though, the following keys are commonly used for these functions.</p>
<ul>
<li><kbd>Control + Space</kbd>: selects the column that contains the focus.</li>
<li>
<kbd>Shift + Space</kbd>: Selects the row that contains the focus.
If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
</li>
<li><kbd>Control + A</kbd>: Selects all cells.</li>
<li><kbd>Shift + Right Arrow</kbd>: Extends selection one cell to the right.</li>
<li><kbd>Shift + Left Arrow</kbd>: Extends selection one cell to the left.</li>
<li><kbd>Shift + Down Arrow</kbd>: Extends selection one cell down.</li>
<li><kbd>Shift + Up Arrow</kbd>: Extends selection one cell Up.</li>
</ul>
<p class="note">See <a href="#aria_ex_widget">Global Recommendations</a> for cut, copy and paste key assignments.</p>
</section>
</section>
<section id="gridNav" class="notoc">
<h4>Keyboard Interaction - Setting Focus and Navigating Inside Cells</h4>
<p>This section describes two important aspects of keyboard interaction design shared by both data and layout grid patterns:</p>
<ol>
<li>Choosing whether a cell or an element inside a cell receives focus in response to grid navigation key events.</li>
<li>Enabling grid navigation keys to be used to interact with elements inside of a cell.</li>
</ol>
<section id="gridNav_focus" class="notoc">
<h5>Whether to Focus on a Cell Or an Element Inside IT</h5>
<p>
For assistive technology users, the quality of experience when navigating a grid heavily depends on both what a cell contains and on where keyboard focus is set.
For example, if a cell contains a button and a grid navigation key places focus on the cell instead of the button, screen readers announce the button label but do not tell users a button is present.
</p>
<p>There are two optimal cell design and focus behavior combinations: </p>
<ol>
<li>
A cell contains one widget whose operation does not require arrow keys and grid navigation keys set focus on that widget.
Examples of such widgets include link, button, menubutton, toggle button, radio button (not radio group), switch, and checkbox.
</li>
<li>A cell contains text or a single graphic and grid navigation keys set focus on the cell.</li>
</ol>
<p>
While any combination of widgets, text, and graphics may be included in a single cell, grids that do not follow one of these two cell design and focus movement patterns add complexity for authors or users or both.
The reference implementations included in the example section below demonstrate some strategies for making other cell designs as accessible as possible, but the most widely accessible experiences are likely to come by applying the above two patterns.
</p>
</section>
<section id="gridNav_inside" class="notoc">
<h5>Editing and Navigating Inside a Cell</h5>
<p>
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to perform actions like operate a combobox or move an editing caret inside of a cell. The user may need keys that are used for grid navigation to operate
elements inside a cell if a cell contains:
</p>
<ol>
<li>Editable content.</li>
<li>Multiple widgets.</li>
<li>A widget that utilizes arrow keys in its interaction model, such as a radio group or slider.</li>
</ol>
<p>Following are common keyboard conventions for disabling and restoring grid navigation functions. </p>
<ul>
<li>
<kbd>Enter</kbd>: Disables grid navigation and:
<ul>
<li>If the cell contains editable content, places focus in an input field, such as a <a href="#textbox" class="role-reference">textbox</a>. If the input is a single-line text field, a subsequent press of <kbd>Enter</kbd> may either restore grid navigation
functions or move focus to an input field in a neighboring cell.</li>
<li>If the cell contains one or more widgets, places focus on the first widget. </li>
</ul>
</li>
<li>
<kbd>F2</kbd>:
<ul>
<li>If the cell contains editable content, places focus in an input field, such as a <a href="#textbox" class="role-reference">textbox</a>. A subsequent press of <kbd>F2</kbd> restores grid navigation functions. </li>
<li>If the cell contains one or more widgets, places focus on the first widget. A subsequent press of <kbd>F2</kbd> restores grid navigation functions. </li>
</ul>
</li>
<li>Alphanumeric keys: If the cell contains editable content, places focus in an input field, such as a <a href="#textbox" class="role-reference">textbox</a>. </li>
</ul>
<p>When grid navigation is disabled, conventional changes to navigation behaviors include: </p>
<ul>
<li><kbd>Escape</kbd>: restores grid navigation. If content was being edited, it may also undo edits.</li>
<li>
<kbd>Right Arrow</kbd> or <kbd>Down Arrow</kbd>: If the cell contains multiple widgets, moves focus to the next widget inside the cell, optionally wrapping to the first widget if focus is on the last widget.
Otherwise, passes the key event to the focused widget.
</li>
<li>
<kbd>Left Arrow</kbd> or <kbd>Up Arrow</kbd>: If the cell contains multiple widgets, moves focus to the previous widget inside the cell, optionally wrapping to the first widget if focus is on the last widget.
Otherwise, passes the key event to the focused widget.
</li>
<li>
<kbd>Tab</kbd>: moves focus to the next widget in the grid.
Optionally, the focus movement may wrap inside a single cell or within the grid itself.
</li>
<li>
<kbd>Shift + Tab</kbd>: moves focus to the previous widget in the grid.
Optionally, the focus movement may wrap inside a single cell or within the grid itself.
</li>
</ul>
</section>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The grid container has role <a href="#grid" class="role-reference">grid</a>. </li>
<li>Each row container has role <a href="#row" class="role-reference">row</a> and is either a DOM descendant of or owned by the <code>grid</code> element or an element with role <a href="#rowgroup" class="role-reference">rowgroup</a>. </li>
<li>Each cell is either a DOM descendant of or owned by a <code>row</code> element and has one of the following roles:
<ul>
<li><a href="#columnheader" class="role-reference">columnheader</a> if the cell contains a title or header information for the column.</li>
<li><a href="#rowheader" class="role-reference">rowheader</a> if the cell contains title or header information for the row.</li>
<li><a href="#gridcell" class="role-reference">gridcell</a> if the cell does not contain column or row header information.</li>
</ul>
</li>
<li>
If there is an element in the user interface that serves as a label for the grid, <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> is set on the grid element with a value that refers to the labeling element.
Otherwise, a label is specified for the grid element using <a href="#aria-label" class="property-reference">aria-label</a>.
</li>
<li>If the grid has a caption or description, <a href="#aria-describedby" class="property-reference">aria-describedby</a> is set on the grid element with a value refering to the element containing the description.</li>
<li>If the grid provides sort functions, <a href="#aria-sort" class="property-reference">aria-sort</a> is set to an appropriate value on the header cell element for the sorted column or row as described in the section on <a href="#gridAndTableProperties">grid and table properties</a>. </li>
<li>If the grid supports selection, when a cell or row is selected, the selected element has <a href="#aria-selected" class="state-reference">aria-selected</a> set <code>true</code>. </li>
<li>
If the grid provides content editing functionality and contains cells that may have edit capabilities disabled in certain conditions, <a href="#aria-readonly" class="state-reference">aria-readonly</a> may be set <code>true</code> on cells where editing is disabled.
If edit functions are disabled for all cells, <code>aria-readonly</code> may be set <code>true</code> on the grid element.
Grids that do not provide editing functions do not include the <code>aria-readonly</code> attribute on any of their elements.
</li>
<li>
If there are conditions where some rows or columns are hidden or not present in the DOM, e.g., data is dynamically loaded when scrolling or the grid provides functions for hiding rows or columns, the following properties are applied as described in the section on <a href="#gridAndTableProperties">grid and table properties</a>.
<ul>
<li><a href="#aria-colcount" class="property-reference">aria-colcount</a> or <a href="#aria-rowcount" class="property-reference">aria-rowcount</a> is set to the total number of columns or rows, respectively. </li>
<li><a href="#aria-colindex" class="property-reference">aria-colindex</a> or <a href="#aria-rowindex" class="property-reference">aria-rowindex</a> is set to the position of a cell within a row or column, respectively. </li>
</ul>
</li>
<li>If the grid includes cells that span multiple rows or multiple columns, and if the <code>grid</code> role is NOT applied to an HTML <code>table</code> element, then <a href="#aria-rowspan" class="property-reference">aria-rowspan</a> or <a href="#aria-colspan" class="property-reference">aria-colspan</a> is applied as described in <a href="#gridAndTableProperties">grid and table properties</a>.</li>
</ul>
<ul class="note">
<li>
If the element with the <code>grid</code> role is an HTML <code>table</code> element, then it is not necessary to use ARIA roles for rows and cells because the HTML elements have implied ARIA semantics.
For example, an HTML <code><TR></code> has an implied ARIA role of <code>row</code>.
A <code>grid</code> built from an HTML <code>table</code> that includes cells that span multiple rows or columns must use HTML <code>rowspan</code> and <code>colspan</code> and must not use <code>aria-rowspan</code> or <code>aria-colspan</code>.
</li>
<li>
If rows or cells are included in a grid via <a href="#aria-owns" class="property-reference">aria-owns</a>, they will be presented to assistive technologies after the DOM descendants of the <code>grid</code> element unless the DOM descendants are also included in the <code>aria-owns</code> attribute.
See using aria-owns for a detailed explaination.
</li>
</ul>
<p class="note">Editor's Note - Guidance for aria-owns has not yet been created. A link to it will be added above once created.</p>
</section>
<section class="notoc">
<h4>Examples</h4>
<ul>
<li><a href="examples/grid/LayoutGrids.html">Layout Grid Examples</a>: Three example implementations of grids that are used to lay out widgets, including a collection of navigation links, a message recipients list, and a set of search results.</li>
<li><a href="examples/grid/dataGrids.html">Data Grid Examples</a>: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.</li>
<li><a href="examples/grid/advancedDataGrid.html">Advanced Data Grid Example</a>: Example of a grid with behaviors and features similar to a typical spreadsheet, including cell and row selection.</li>
</ul>
</section>
</section>
<section class="widget" id="link">
<h3>Link</h3>
<p>
A <a href="#link" class="role-reference">link</a> widget provides an interactive reference to a resource.
The target resource can be either external or local, i.e., either outside or within the current page or application.
</p>
<p class="note">
Authors are strongly encouraged to use a native host language link element, such as an HTML
<code><A></code> element with an <code>href</code> attribute. As with other WAI-ARIA
widget roles, applying the link role to an element will not cause browsers to enhance the
element with standard link behaviors, such as navigation to the link target or context menu
actions.
When using the <code>link</code> role, providing these features of the element is the author's responsibility.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<ul>
<li><kbd>Enter</kbd>: Executes the link and moves focus to the link target.</li>
<li><kbd>Shift + F10</kbd>: Opens the link's context menu.</li>
</ul>
</section>
<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<p>
The element containing the link text or graphic has role of <a href="#link" class="role-reference">link</a>.
</p>
</section>
<section class="notoc">
<h4>Examples</h4>
<p><a href="examples/link/link.html">Link Examples</a>: Link widgets constructed from HTML <code>span</code> and <code>div</code> elements.</p>
</section>
</section>
<section class="widget" id="Listbox">
<h3>Listbox</h3>
<p>
A <a href="#listbox" class="role-reference">listbox</a> widget presents a list of options and allows a user to select one or more of them.
A listbox that allows a single option to be chosen is a single-select listbox; one that allows multiple options to be selected is a multi-select listbox.
</p>
<p>
When screen readers present a listbox, they may render the name, state, and position of each option in the list.
The name of an option is a string calculated by the browser, typically from the content of the option element.
As a flat string, the name does not contain any semantic information.
Thus, if an option contains a semantic element, such as a heading, screen reader users will not have access to the semantics.
In addition, the interaction model conveyed by the listbox role to assistive technologies does not support interacting with elements inside of an option.
Because of these traits of the listbox widget, it does not provide an accessible way to present a list of interactive elements, such as links, buttons, or checkboxes.
To present a list of interactive elements, see the <a href="#grid">grid</a> pattern.
</p>
<p>
Avoiding very long option names facilitates understandability and perceivability for screen reader users.
The entire name of an option is spoken as a single unit of speech when the option is read.
When too much information is spoken as the result of a single key press, it is difficult to understand.
Long names inhibit perception by increasing the impact of interrupted speech because users typically have to re-read the entire option.
And, if the user does not understand what is spoken, reading the name by character, word, or phrase may be a difficult operation for many screen reader users in the context of a listbox widget.
</p>
<p>
Sets of options where each option name starts with the same word or phrase can also significantly degrade usability for keyboard and screen reader users.
Scrolling through the list to find a specific option becomes inordinately time consuming for a screen reader user who must listen to that word or phrase repeated before hearing what is unique about each option.
For example, if a listbox for choosing a city were to contain options where each city name were preceded by a country name, and if many cities were listed for each country, a screen reader user would have to listen to the country name before hearing each city name.
In such a scenario, it would be better to have 2 list boxes, one for country and one for city.
</p>
<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>For a vertically oriented listbox:</p>
<ul>
<li> When a single-select listbox receives focus:
<ul>
<li>If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.</li>
<li>If an option is selected before the listbox receives focus, focus is set on the selected option. </li>
</ul>
</li>
<li>When a multi-select listbox receives focus:
<ul>
<li>If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state.</li>
<li>If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected.</li>
</ul>
</li>
<li><kbd>Down Arrow</kbd>: Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.</li>
<li><kbd>Up Arrow</kbd>: Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.</li>
<li><kbd>Home</kbd> (Optional): Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.</li>
<li><kbd>End</kbd> (Optional): Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.</li>
<li>Type-ahead is recommended for all listboxes, especially those with more than seven options:
<ul>
<li>Type a character: focus moves to the next item with a name that starts with the typed character.</li>
<li>Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.</li>
</ul>
</li>
<li><strong>Multiple Selection</strong>:
Authors may implement either of two interaction models to support multiple selection:
a recommended model that does not require the user to hold a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd>, while navigating the list
or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states.
<ul>
<li>Recommended selection model -- holding modifier keys is not necessary:
<ul>
<li><kbd>Space</kbd>: changes the selection state of the focused option .</li>
<li><kbd>Shift + Down Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the next option.</li>
<li><kbd>Shift + Up Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the previous option.</li>
<li><kbd>Shift + Space</kbd> (Optional): Selects contiguous items from the most recently selected item to the focused item.</li>
<li><kbd>Control + Shift + Home</kbd> (Optional): Selects the focused option and all options up to the first option.</li>
<li><kbd>Control + Shift + End</kbd> (Optional): Selects the focused option and all options down to the last option.</li>
<li><kbd>Control + A</kbd> (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.</li>
</ul>
</li>
<li>Alternative selection model -- moving focus without holding a <kbd>Shift</kbd> or <kbd>Control</kbd> modifier unselects all selected nodes except the focused node:
<ul>
<li><kbd>Shift + Down Arrow</kbd>: Moves focus to and toggles the selection state of the next option.</li>
<li><kbd>Shift + Up Arrow</kbd>: Moves focus to and toggles the selection state of the previous option.</li>
<li><kbd>Control + Down Arrow</kbd>: Moves focus to the next option without changing its selection state.</li>
<li><kbd>Control + Up Arrow</kbd>: Moves focus to the previous option without changing its selection state.</li>