/
index.html
14022 lines (13938 loc) · 777 KB
/
index.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>Accessible Rich Internet Applications (WAI-ARIA) 1.3</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<link href="common/css/common.css" rel="stylesheet" type="text/css"/>
<script class="remove" src="common/script/aria.js"></script>
<script src="common/script/resolveReferences.js" class="remove"></script>
<script class="remove">
var respecConfig = {
github: "w3c/aria",
doJsonLd: true,
// specification status (e.g., WD, LC, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
//crEnd: "2012-04-30",
//perEnd: "2013-07-23",
//publishDate: "2013-08-22",
// the specifications short name, as in https://www.w3.org/TR/short-name/
shortName: "wai-aria-1.2",
// if you wish the publication date to be other than today, set this
//publishDate: "2014-12-11",
copyrightStart: "2013",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
//previousPublishDate: "2014-06-12",
//previousMaturity: "WD",
prevRecURI: "https://www.w3.org/TR/wai-aria-1.1/",
//previousDiffURI: "https://www.w3.org/TR/2014/REC-wai-aria-20140320/",
// if there a publicly available Editors Draft, this is the link
edDraftURI: "https://w3c.github.io/aria/",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2012-02-21",
// editors, add as many as you like
// only "name" is required
editors: [
{
name: "James Nurthen",
company: "Adobe",
companyURL: "https://www.adobe.com/",
w3cid: 37155
},
{
name: "Michael Cooper",
company: "W3C",
companyURL: "http://www.w3.org",
w3cid: 34017
},
{
name: "Peter Krautzberger",
company: "krautzource UG",
companyURL: "https://www.krautzource.com",
w3cid: 60398
}
],
formerEditors: [
{
name: "Joanmarie Diggs",
company: "Igalia, S.L.",
companyURL: "https://www.igalia.com",
w3cid: 68182
},
{
name: "Shane McCarron",
company: "Spec-Ops",
companyURL: "https://www.spec-ops.io",
w3cid: 89030,
note: "Editor until 2018"
},
{
name: "Richard Schwerdtfeger",
company: "Knowbility",
companyURL: "https://www.knowbility.org/",
w3cid: 2460,
note: "Editor until October 2017"
},
{
name: "James Craig",
company: "Apple Inc.",
companyURL: "https://www.apple.com/accessibility",
w3cid: 42459,
note: "Editor until May 2016"
}
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
//authors: [
// { name: "Your Name", url: "http://example.org/",
// company: "Your Company", companyURI: "http://example.com/" },
//],
/*
alternateFormats: [
{ uri: 'aria-diff.html', label: "Diff from Previous Recommendation" } ,
{ uri: 'aria.ps', label: "PostScript version" },
{ uri: 'aria.pdf', label: "PDF version" }
],
*/
// errata: 'http://www.w3.org/2010/02/rdfa/errata.html',
// name of the WG
group: "aria",
maxTocLevel: 4,
// Spec URLs
ariaSpecURLs: {
"ED": "",
"WD" : "",
"CR": "",
"REC": ""
},
accNameURLs: {
"ED": "https://w3c.github.io/accname/",
"WD" : "https://www.w3.org/TR/accname-1.2/",
"FPWD": "https://www.w3.org/TR/accname-1.2/",
"CR" : "https://www.w3.org/TR/accname-1.2/",
"REC": "https://www.w3.org/TR/accname-1.2/"
},
coreMappingURLs: {
"ED": "https://w3c.github.io/core-aam/",
"WD" : "https://www.w3.org/TR/core-aam-1.2/",
"FPWD": "https://www.w3.org/TR/core-aam-1.2/",
"CR": "https://www.w3.org/TR/core-aam-1.2/",
"REC": "https://www.w3.org/TR/core-aam-1.2/"
},
practicesURLs: {
"ED": "https://w3c.github.io/aria-practices/",
"WD" : "https://www.w3.org/TR/wai-aria-practices-1.2/",
"FPWD": "https://www.w3.org/TR/wai-aria-practices-1.2/",
"CR": "https://www.w3.org/TR/wai-aria-practices-1.2/",
"REC": "https://www.w3.org/TR/wai-aria-practices-1.2/"
},
preProcess: [ linkCrossReferences ],
postProcess: [ ariaAttributeReferences ],
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML"],
definitionMap: []
};
</script>
<script src="common/biblio.js" class="remove"></script>
</head>
<body>
<section id="abstract">
<p>Accessibility of web content requires semantic information about widgets, structures, and behaviors, in order to allow assistive technologies to convey appropriate information to persons with disabilities. This specification provides an ontology of roles, states, and properties that define accessible user interface elements and can be used to improve the accessibility and interoperability of web content and applications. These semantics are designed to allow an author to properly convey user interface behaviors and structural information to assistive technologies in document-level markup. This version adds features new since WAI-ARIA 1.1 [[wai-aria-1.1]] to improve interoperability with assistive technologies to form a more consistent accessibility model for [[HTML]] and [[SVG2]]. This specification complements both [[HTML]] and [[SVG2]].</p>
<p>This document is part of the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> suite described in the <a href="http://www.w3.org/WAI/intro/aria.php"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Overview</a>.</p>
</section>
<section id="sotd">
<p>The Accessible Rich Internet Applications Working Group seeks feedback on any aspect of the specification. When submitting feedback, please consider issues in the context of the companion documents. To comment, <a href="https://github.com/w3c/aria/issues/new">file an issue in the <abbr title="World Wide Web Consortium">W3C</abbr> ARIA GitHub repository</a>. If this is not feasible, send email to <a href="mailto:public-aria@w3.org?subject=Comment%20on%20WAI-ARIA%201.2">public-aria@w3.org</a> (<a href="http://lists.w3.org/Archives/Public/public-aria/">comment archive</a>). In-progress updates to the document may be viewed in the <a href="http://w3c.github.io/aria/">publicly visible editors' draft</a>.</p>
</section>
<section class="informative" id="introduction" data-cite="dom">
<h1>Introduction</h1>
<p>The goals of this specification include:</p>
<ul>
<li>expanding the accessibility information that may be supplied by the author;</li>
<li>requiring that supporting host languages provide full keyboard support that may be implemented in a device-independent way, for example, by telephones, handheld devices, e-book readers, and televisions;</li>
<li>improving the accessibility of dynamic content generated by scripts; and</li>
<li>providing for interoperability with <a>assistive technologies</a>.</li>
</ul>
<p>WAI-ARIA is a technical specification that provides a framework to improve the accessibility and interoperability of web content and applications. This document is primarily for developers creating custom widgets and other web application components. Please see the <a href="http://www.w3.org/WAI/intro/aria">WAI-ARIA Overview</a> for links to related documents for other audiences, such as <cite><a href="" class="practices"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</a></cite> [[WAI-ARIA-PRACTICES-1.2]] that introduces developers to the accessibility problems that WAI-ARIA is intended to solve, the fundamental concepts, and the technical approach of WAI-ARIA.</p>
<p>This document currently handles two aspects of <a>roles</a>: user interface functionality and structural <a>relationships</a>. For more information and use cases, see <cite><a href="" class="practices"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</a></cite> [[WAI-ARIA-PRACTICES-1.2]] for the use of roles in making interactive content accessible.</p>
<p>Roles defined by this specification are designed to support the roles used by platform <a>accessibility <abbr title="Application Programing Interfaces">APIs</abbr></a>. Declaration of these roles on elements within dynamic web content is intended to support interoperability between the web content and assistive technologies that utilize <a>accessibility <abbr title="Application Programing Interfaces">APIs</abbr></a>.</p>
<p>The schema to support this standard has been designed to be extensible so that custom roles can be created by extending base roles. This allows [=user agents=] to support at least the base role, and user agents that support the custom role can provide enhanced access. Note that much of this could be formalized in [[XMLSCHEMA11-2]]. However, being able to define similarities between roles, such as <a href="#baseConcept">baseConcepts</a> and more descriptive definitions, would not be available in <abbr title="Extensible Markup Language Schema Datatypes">XSD</abbr>.</p>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> 1.2 is a member of the <a href="https://www.w3.org/WAI/intro/aria"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> 1.2 suite</a> that defines how to expose semantics of WAI-ARIA and other web content languages to <a>accessibility <abbr title="Application Programing Interfaces">APIs</abbr></a>.
</p>
<section class="section" id="intro_ria_accessibility">
<h2>Rich Internet Application Accessibility</h2>
<p>The domain of web accessibility defines how to make web content usable by persons with disabilities. Persons with certain types of disabilities use <a>assistive technologies</a> (<abbr title="Assistive Technologies">AT</abbr>) to interact with content. Assistive technologies can transform the presentation of content into a format more suitable to the user, and can allow the user to interact in different ways. For example, the user may need to, or choose to, interact with a slider widget via arrow keys, instead of dragging and dropping with a mouse. In order to accomplish this effectively, the software needs to understand the <a>semantics</a> of the content. Semantics is the science of meaning; in this case, used to assign roles, states, and properties that apply to user interface and content elements as a human would understand. For instance, if a paragraph is semantically identified as such, assistive technologies can interact with it as a unit separable from the rest of the content, knowing the exact boundaries of that paragraph. An adjustable range slider or collapsible list (a.k.a. a tree <a>widget</a>) are more complex examples, in which various parts of the widget have semantics that need to be properly identified for assistive technologies to support effective interaction.</p>
<p>New technologies often overlook semantics required for accessibility, and new authoring practices often misuse the intended semantics of those technologies. [=Elements=] that have one defined meaning in the language are used with a different meaning intended to be understood by the user.</p>
<p>For example, web application developers create collapsible tree widgets in HTML using CSS and JavaScript even though HTML has no semantic <code>tree</code> element. To a non-disabled user, it may look and act like a collapsible tree widget, but without appropriate semantics, the tree widget may not be <a>perceivable</a> to, or <a>operable</a> by, a person with a disability because assistive technologies may not recognize the role. Similarly, web application developers create interactive button widgets in SVG using JavaScript even though SVG has no semantic <code>button</code> element. To a non-disabled user, it may look and act like a button widget, but without appropriate semantics, the button widget may not be <a>perceivable</a> to, or <a>operable</a> by, a person with a disability because assistive technologies may not recognize the role.</p>
<p>The incorporation of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is a way for an author to provide proper semantics for custom widgets to make these widgets accessible, usable, and interoperable with assistive technologies. This specification identifies the types of widgets and structures that are commonly recognized by accessibility products, by providing an <a>ontology</a> of corresponding <a>roles</a> that can be attached to content. This allows elements with a given role to be understood as a particular widget or structural type regardless of any semantics inherited from the implementing host language. Roles are a common property of platform <a>accessibility <abbr title="Application Programing Interfaces">APIs</abbr></a> which assistive technologies use to provide the user with effective presentation and interaction.</p>
<p>The Roles Model includes interaction <a>widgets</a> and elements denoting document structure. The Roles Model describes inheritance and details the [=attributes=] each role supports. Information about mapping of roles to accessibility <abbr title="Application Programing Interfaces">APIs</abbr> is provided by the <cite><a href="" class="core-mapping">Core Accessibility API Mappings</a></cite> [[CORE-AAM-1.2]].</p>
<p>Roles are element types and will not change with time or user actions. Role information is used by assistive technologies, through interaction with the user agent, to provide normal processing of the specified element type.</p>
<p>States and properties are used to declare important attributes of an element that affect and describe interaction. They enable the <a>user agent</a> and operating system to properly handle the element even when the attributes are dynamically changed by client-side scripts. For example, alternative input and output technology, such as screen readers and speech dictation software, need to be able to recognize and effectively manipulate and communicate various interaction states (e.g., disabled, checked) to the user.</p>
<p>While it is possible for assistive technologies to access these properties directly through the <cite><a href="https://www.w3.org/TR/dom/">Document Object Model</a></cite> [[DOM]], the preferred mechanism is for the user agent to map the states and properties to the accessibility <abbr title="Application Programing Interfaces">API</abbr> of the operating system. See the <cite><a href="" class="core-mapping">Core Accessibility API Mappings</a></cite> [[CORE-AAM-1.2]] and the <cite><a href="" class="accname">Accessible Name and Description Computation</a></cite> [[ACCNAME-1.2]] for details.</p>
<p id="desc_contractmodel">Figure 1.0 illustrates the relationship between user agents (e.g., browsers), accessibility APIs, and assistive technologies. It describes the "contract" provided by the user agent to assistive technologies, which includes typical accessibility information found in the accessibility <abbr title="Application Programing Interfaces">API</abbr> for many of our accessible platforms for GUIs (role, state, selection, <a>event</a> notification, <a>relationship</a> information, and descriptions). The DOM, usually HTML, acts as the data model and view in a typical model-view-controller relationship, and JavaScript acts as the controller by manipulating the style and content of the displayed data. The user agent conveys relevant information to the operating system's accessibility API, which can be used by any assistive technologies, such as screen readers.</p>
<div class="image">
<p><img alt="The contract model with accessibility APIs" height="389" id="contractmodel" src="img/accessibleelement.png" width="723"/></p>
<p class="img-caption">Figure 1: The contract model with accessibility <abbr title="Application Programing Interfaces">APIs</abbr></p>
</div>
<p>For more information see <cite><a href="" class="practices"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</a></cite> for the use of roles in making interactive content accessible.</p>
<p>Users of alternate input devices need <a>keyboard accessible</a> content. The new semantics, when combined with the recommended keyboard interactions provided in <cite><a href="" class="practices"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</a></cite>, will allow alternate input solutions to facilitate command and control via an alternate input solution.</p>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> introduces navigational <a>landmarks</a> through its Roles Model and the <abbr title="Extensible Hypertext Markup Language">XHTML</abbr> role landmarks, which can help persons with dexterity and vision impairments by providing for improved keyboard navigation. <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> may also be used to assist persons with cognitive learning disabilities. The additional semantics allow authors to restructure and substitute alternative content as needed.</p>
<p><a>Assistive technologies</a> need the ability to support alternative inputs by getting and setting the current value of <a>widget</a> states and properties. Assistive technologies also need to determine what <a>objects</a> are selected and manage widgets that allow multiple selections, such as list boxes and grids.</p>
<p>Speech-based command and control systems can benefit from <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> semantics like the <code>role</code> attribute to assist in conveying audio information to the user. For example, upon encountering an element with a role of <rref>menu</rref> with child elements of role <rref>menuitem</rref> each containing text content representing a different flavor, a speech system might state to the user, "Select one of three choices: chocolate, strawberry, or vanilla."</p>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is intended to be used as a supplement for native language semantics, not a replacement. When the host language provides a feature that provides equivalent accessibility to the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> feature, use the host language feature. <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> should only be used in cases where the host language lacks the needed <a>role</a>, <a>state</a>, and [=ARIA/property=] indicators. Use a host language feature that is as similar as possible to the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> feature, then refine the meaning by adding <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>. For instance, a multi-selectable grid could be implemented as a table, and then <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> used to clarify that it is an interactive grid, not just a static data table. This allows for the best possible fallback for user agents that do not support <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> and preserves the integrity of the host language semantics.</p>
</section>
<section id="target-audience">
<h2>Target Audience</h2>
<p>This specification defines the basic model for <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>, including roles, states, properties, and values. It impacts several audiences:</p>
<ul>
<li>[=user agents=] that process content containing <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> features;</li>
<li><a>Assistive technologies</a> that present content in special ways to user with disabilities;</li>
<li>Authors who create content;</li>
<li>Authoring tools that help authors create conforming content; and</li>
<li>Conformance checkers that verify appropriate use of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>.</li>
</ul>
<p>Each conformance requirement indicates the audience to which it applies.</p>
<p>Although this specification is applicable to the above audiences, it is not specifically targeted to, nor is it intended to be the sole source of information for, any of these audiences. The following documents provide important supporting information:</p>
<ul>
<li>[[[WAI-ARIA-PRACTICES-1.2]]] addresses authoring recommendations for HTML, and is also of interest to developers of authoring tools and conformance checkers.</li>
<li>[[[CORE-AAM-1.2]]]</cite> addresses developers of [=user agents=] and <a class="termref">assistive technologies</a>.</li>
<li>[[[ACCNAME-1.2]]] also addresses developers of [=user agents=] and <a class="termref">assistive technologies</a>.</li>
</ul>
</section>
<section id="ua-support">
<h2>User Agent Support</h2>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> relies on user agent support for its features in two ways:</p>
<ul>
<li>Mainstream [=user agents=] use <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> to alter how host language features are exposed to <a>accessibility APIs</a> in order to improve accessibility. The mechanism for this is defined in the <cite><a href="" class="core-mapping">Core Accessibility API Mappings</a></cite>.</li>
<li><a>Assistive technologies</a> use the enhanced information available in an accessibility API, or uses the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> markup directly via the <abbr title="Document Object Model">DOM</abbr>, to convey semantic and interaction information to the user.</li>
</ul>
<p>Aside from using <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> markup to improve what is exposed to accessibility APIs, user agents behave as they would natively. Assistive technologies react to the extra information in the accessibility API as they already do for the same information on non-web content. User agents that are not assistive technologies, however, need do nothing beyond providing appropriate updates to the accessibility API.</p>
<p>The <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> specification neither requires nor forbids user agents from enhancing native presentation and interaction behaviors on the basis of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> markup. Mainstream user agents might expose <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> navigational landmarks (for example, as a dialog box or through a keyboard command) with the intention to facilitate navigation for all users. User agents are encouraged to maximize their usefulness to users, including users without disabilities. </p>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is intended to provide missing semantics so that the intent of the author may be conveyed to assistive technologies. Generally, authors using <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> will provide the appropriate presentation and interaction features. Over time, host languages may add <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> equivalents, such as new form controls, that are implemented as standard accessible user interface controls by the user agent. This allows authors to use them instead of custom <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> enabled user interface components. In this case the user agent would support the native host language feature. Developers of host languages that implement <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> are advised to continue supporting <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> semantics when they do not adversely conflict with implicit host language semantics, as <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> semantics more clearly reflect the intent of the author if the host language features are inadequate to meet the author's needs.</p>
</section>
<section id="co-evolution">
<h2>Co-Evolution of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> and Host Languages</h2>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is intended to augment semantics in supporting languages like [[HTML]] and [[SVG2]], or to be used as an accessibility enhancement technology in other markup-based languages that do not explicitly include support for ARIA. It clarifies semantics to assistive technologies when authors create new types of objects, via style and script, that are not yet directly supported by the language of the page, because the invention of new types of objects is faster than standardized support for them appears in web languages.</p>
<p>It is not appropriate to create objects with style and script when the host language provides a semantic element for that type of object. While <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> can improve the accessibility of these objects, accessibility is best provided by allowing the user agent to handle the object natively. For example, it's better to use an <code>h1</code> element in HTML than to use the <rref>heading</rref> role on a <code>div</code> element.</p>
<p>It is expected that, over time, host languages will evolve to provide semantics for objects that currently can only be declared with <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>. This is natural and desirable, as one goal of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is to help stimulate the emergence of more semantic and accessible markup. When native semantics for a given feature become available, it is appropriate for authors to use the native feature and stop using <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> for that feature. Legacy content may continue to use <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>, however, so the need for user agents to support <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> remains.</p>
<p>While specific features of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> may lose importance over time, the general possibility of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> to add semantics to web pages is expected to be a persistent need. Host languages may not implement all the semantics <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> provides, and various host languages may implement different subsets of the features. New types of objects are continually being developed, and one goal of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> is to provide a way to make such objects accessible, because web authoring practices often advance faster than host language standards. In this way, <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> and host languages both evolve together but at different rates.</p>
<p>Some host languages exist to create semantics for features other than the user interface. For example, SVG expresses the semantics behind production of graphical objects, not of user interface components that those objects may represent. Host languages might, by design, not provide native semantics that map to <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> features. In these cases, <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> could be adopted as a long-term approach to add semantic information to user interface components.</p>
</section>
<section id="authoring_practices">
<h2>Authoring Practices</h2>
<section id="authoring_tools">
<h3>Authoring Tools</h3>
<p>Many of the requirements in the definitions of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>roles</a>, <a>states</a>, and [=ARIA/properties=] can be checked automatically during the development process, similar to other quality control processes used for validating code. To assist authors who are creating custom widgets, authoring tools may compare widget roles, states, and properties to those supported in <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> as well as those supported in related and cross-referenced roles, states, and properties. Authoring tools may notify authors of errors in widget design patterns, and may also prompt developers for information that cannot be determined from context alone. For example, a scripting library can determine the labels for the tree items in a tree view, but would need to prompt the author to label the entire tree. To help authors visualize a logical accessibility structure, an authoring environment might provide an outline view of a web resource based on the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> markup.</p>
<p>In both HTML and SVG, <code>tabindex</code> is an important way browsers support keyboard <a href="#host_general_focus">focus navigation</a> for implementations of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr>; authoring and debugging tools may check to make sure <code>tabindex</code> values are properly set. For example, error conditions may include cases where more than one treeitem in a tree has a <code>tabindex</code> value greater than or equal to 0, where <code>tabindex</code> is not set on any treeitem, or where <pref>aria-activedescendant</pref> is not defined when the element with the role tree has a <code>tabindex</code> value of greater than or equal to 0.</p>
</section>
<section id="authoring_testing">
<h3>Testing Practices and Tools</h3>
<p>The accessibility of interactive content cannot be confirmed by static checks alone. Developers of interactive content should test for device-independent access to <a>widgets</a> and applications, and should verify accessibility <abbr title="application programing interface">API</abbr> access to all content and changes during user interaction.</p>
</section>
</section>
<section id="at_support">
<h2>Assistive Technologies</h2>
<p>Programmatic access to accessibility semantics is essential for assistive technologies. Most assistive technologies interact with user agents, like other applications, through a recognized accessibility API. Perceivable objects in the user interface are exposed to assistive technologies as accessible objects, defined by the accessibility API interfaces. To do this properly, accessibility information – role, states, properties as well as contextual information – needs to be accurately conveyed to the assistive technologies through the accessibility API. When a state change occurs, the user agent provides the appropriate event notification to the accessibility API. Contextual information, in many host languages like HTML, can be determined from the <abbr title="Document Object Model">DOM</abbr> itself as it provides a contextual tree hierarchy.</p>
<p>While some assistive technologies interact with these accessibility APIs, others may access the content directly from the <abbr title="Document Object Model">DOM</abbr>. These technologies can restructure, simplify, style, or reflow the content to help a different set of users. Common use cases for these types of adaptations may be the aging population, persons with cognitive impairments, or persons in environments that interfere with use of their tools. For example, the availability of regional navigational landmarks may allow for a mobile device adaptation that shows only portions of the content at any one time based on its semantics. This could reduce the amount of information the user needs to process at any one time. In other situations it may be appropriate to replace a custom user interface control with something that is easier to navigate with a keyboard, or touch screen device.</p>
</section>
</section>
<section class="informative" id="terms" data-cite="dom">
<h1>Important Terms</h1>
<div>
<p>While some terms are defined in place, the following definitions are used throughout this document. </p>
<dl class="termlist">
<dt><dfn data-export="">Accessibility <abbr title="Application Programming Interface">API</abbr></dfn></dt>
<dd>
<p>Operating systems and other platforms provide a set of interfaces that expose information about <a class="termref">objects</a> and <a class="termref">events</a> to <a>assistive technologies</a>. Assistive technologies use these interfaces to get information about and interact with those <a class="termref">widgets</a>. Examples of accessibility APIs are <a href="https://docs.microsoft.com/en-us/windows/win32/winauto/microsoft-active-accessibility">Microsoft Active Accessibility</a> [[MSAA]], <a href="https://docs.microsoft.com/en-us/windows/win32/winauto/entry-uiauto-win32">Microsoft User Interface Automation</a> [[UI-AUTOMATION]], <abbr title="Microsoft Active Accessibility">MSAA</abbr> with <cite><a href="https://docs.microsoft.com/en-us/windows/win32/winauto/iaccessibleex"><abbr title="User Interface Automation">UIA</abbr> Express</a></cite> [[UIA-EXPRESS]], the
<a href="https://developer.apple.com/documentation/appkit/nsaccessibility">Mac <abbr title="OS Ten">OS X</abbr> Accessibility Protocol</a> [[AXAPI]], the <cite><a href="https://developer.gnome.org/atk/unstable/">Linux/Unix Accessibility Toolkit</a></cite> [[ATK]] and <cite><a href="https://developer.gnome.org/libatspi/stable/">Assistive Technology Service Provider Interface</a></cite> [[AT-SPI]], and <a href="https://wiki.linuxfoundation.org/accessibility/iaccessible2/start">IAccessible2</a> [[IAccessible2]].</p>
</dd>
<dt><dfn data-export="">Accessible object</dfn></dt>
<dd data-cite="dom">
<p>A [=nodes|node=] in the <a class="termref">accessibility tree</a> of a platform <a>accessibility <abbr title="application programming interface">API</abbr></a>. Accessible objects expose various <a class="termref">states</a>, [=ARIA/properties=], and <a class="termref">events</a> for use by <a>assistive technologies</a>. In the context of markup languages (e.g., HTML and SVG) in general, and of WAI-ARIA in particular, markup [=elements=] and their [=attributes=] are represented as accessible objects. </p>
</dd>
<dt><dfn data-export="">Assistive Technologies</dfn></dt>
<dd><p>Hardware and/or software that:</p>
<ul>
<li>relies on services provided by a <a>user agent</a> to retrieve and render Web content </li>
<li>works with a user agent or web content itself through the use of APIs, and</li>
<li>provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities</li>
</ul>
<p>This definition may differ from that used in other documents.</p>
<p>Examples of assistive technologies that are important in the context
of this document include the following:</p>
<ul>
<li>screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;</li>
<li>screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;</li>
<li>text-to-speech software, which is used to convert text into synthetic speech;</li>
<li>speech recognition software, which is used to allow spoken control and dictation;</li>
<li>alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;</li>
<li>alternate pointing devices, which are used to simulate mouse pointing and clicking.</li>
</ul>
</dd>
<dt><dfn data-local-lt="deprecate|deprecation">Deprecated</dfn></dt>
<dd>
<p>A deprecated <a class="termref" href="#dfn-role">role</a>, <a class="termref" href="#dfn-state">state</a>, or <a class="termref" href="#dfn-property">property</a> is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> specification. [=user agents=] are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, see <a href="#deprecated" class="specref">Deprecated Requirements</a> in the Conformance section.</p>
</dd>
<dt><dfn>Defines</dfn></dt>
<dd>
<p>Used in an attribute description to denote that the value <a href="#propcharacteristic_value">type</a> is an <a href="#valuetype_integer">integer</a>, <a href="#valuetype_number">number</a>, or <a href="#valuetype_string">string</a>.</p>
<p>Related Terms: <a>Identifies</a>, <a>Indicates</a></p>
</dd>
<dt><dfn data-local-lt="desktop focus">Desktop focus event</dfn></dt>
<dd>
<p>Event from/to the host operating system via the accessibility <abbr title="application programming interface">API</abbr>, notifying of a change of input focus.</p>
</dd>
<dt><dfn>Event</dfn></dt>
<dd>
<p>A programmatic message used to communicate discrete changes in the <a>state</a> of an <a>object</a> to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.</p>
</dd>
<dt><dfn>Expose</dfn></dt><!--Not used-->
<dd>
<p>Translated to platform-specific <a class="termref">accessibility APIs</a> as defined in the <a href="" class="core-mapping">Core Accessibility API Mappings</a>.</p>
</dd>
<dt><dfn>Graphical Document</dfn></dt>
<dd>
<p>A document containing graphic representations with user-navigable parts. Charts, maps, diagrams, blueprints, and dashboards are examples of graphical documents. A graphical document is composed using any combination of symbols, images, text, and graphic primitives (shapes such as circles, points, lines, paths, rectangles, etc).</p>
</dd>
<dt><dfn data-dfn-for="element" data-export="">Hidden</dfn></dt>
<dd>
<p>Indicates that the <a>element</a> is excluded from the accessibility tree and therefore not exposed to accessibility APIs.<p>
<p>Related: <a href="#tree_exclusion">Excluding Elements in the Accessibility Tree</a>, [=element/hidden from all users=], <sref>aria-hidden</sref>.<p>
<dt><dfn data-dfn-for="element" data-lt="hide from all users" data-export="">Hidden From All Users</dfn></dt>
<dd>
<p>Indicates that the <a>element</a> is not visible, <a>perceivable</a>, or interactive to <em>any</em> user. Note that an <a>element</a> can be [=element/hidden=] but not [=element/hidden from all users=] by using <code>aria-hidden</code>.</p>
<p>Related: <a href="#tree_exclusion">Excluding Elements in the Accessibility Tree</a>, [=element/hidden=], <sref>aria-hidden</sref>.<p>
</dd>
<dt><dfn>Identifies</dfn></dt>
<dd>
<p>Used in an attribute description to denote that the value <a href="#propcharacteristic_value">type</a> is an <a href="#valuetype_idref">ID reference</a> (identifying a single element) or <a href="#valuetype_idref_list">ID reference list</a> (identifying one or more elements).</p>
<p>Related Terms: <a>Defines</a>, <a>Indicates</a></p>
</dd>
<dt><dfn>Indicates</dfn></dt>
<dd>
<p>Used in an attribute description to denote that the value <a href="#propcharacteristic_value">type</a> is a named token or otherwise token-like, including the Boolean-like <a href="#valuetype_true-false">true/false</a>, <a href="#valuetype_true-false-undefined">true/false/undefined</a>, <a href="#valuetype_tristate">tristate (true/false/mixed)</a>, a single named <a href="#valuetype_token">token</a>, or a <a href="#valuetype_token_list">token list</a>.</p>
<p>Related Terms: <a>Defines</a>, <a>Identifies</a></p>
</dd>
<dt><dfn>Keyboard Accessible</dfn></dt>
<dd>
<p>Accessible to the user using a keyboard or <a>assistive technologies</a> that mimic keyboard input, such as a sip and puff tube. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#keyboard-accessible"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Guideline 2.1: Make all functionality available from a keyboard</a></cite> [[WCAG21]].</p>
</dd>
<dt><dfn>Landmark</dfn></dt>
<dd>
<p>A type of region on a page to which the user may want quick access. Content in such a region is different from that of other regions on the page and relevant to a specific user purpose, such as navigating, searching, perusing the primary content, etc.</p>
</dd>
<dt><dfn data-export="">Live Region</dfn></dt>
<dd>
<p>Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere. These regions are not always updated as a result of a user interaction. Examples of live regions include a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and process them: aria-live, aria-relevant, aria-atomic, and aria-busy.</p>
</dd>
<dt><dfn data-export="">Managed State</dfn></dt>
<dd>
<p><a>Accessibility API</a> <a>state</a> that is controlled by the user agent, such as focus and selection. These are contrasted with "unmanaged states" that are typically controlled by the author. Nevertheless, authors can override some managed states, such as aria-posinset and aria-setsize. Many managed states have corresponding CSS pseudo-classes, such as :focus, and pseudo-elements, such as ::selection, that are also updated by the user agent.</p>
</dd>
<dt><dfn>Nemeth Braille</dfn></dt>
<dd>
<p>The Nemeth Braille Code for Mathematics is a braille code for encoding mathematical and scientific notation. See <cite><a href="https://en.wikipedia.org/wiki/Nemeth_Braille">Nemeth Braille on Wikipedia</a>.</cite></p>
</dd>
<dt><dfn>Object</dfn></dt>
<dd>
<p>In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more [=elements=], and rendered by [=user agents=].</p>
In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an <a>accessibility <abbr title="Application Programming Interfaces">API</abbr></a> may represent one or more DOM objects. <a class="termref">Accessibility APIs</a> have defined interfaces that are distinct from DOM interfaces.</dd>
<dt><dfn>Ontology</dfn></dt>
<dd>
<p>A description of the characteristics of classes and how they relate to each other.</p>
</dd>
<dt><dfn>Operable</dfn></dt>
<dd>
<p>Usable by users in ways they can control. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#operable"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Principle 2: Content must be operable</a></cite> [[WCAG21]]. See <a>Keyboard Accessible</a>.</p>
</dd>
<dt><dfn data-export="" data-dfn-for="ARIA" data-local-lt="owned|owned element's">Owned Element</dfn></dt>
<dd>
<p>An 'owned element' is any <abbr title="Document Object Model">DOM</abbr> descendant of the <a>element</a>, any element specified as a child via <pref>aria-owns</pref>, or any <abbr title="Document Object Model">DOM</abbr> descendant of the owned child.</p>
</dd>
<dt><dfn data-local-lt="owning">Owning Element</dfn></dt><!--Not used-->
<dd>
<p>An 'owning element' is any <abbr title="Document Object Model">DOM</abbr> ancestor of the <a>element</a>, or any element with an <pref>aria-owns</pref> attribute which references the ID of the element. </p>
</dd>
<dt><dfn data-export="">Perceivable</dfn></dt>
<dd>
<p>Presentable to users in ways they can sense. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#perceivable"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Principle 1: Content must be perceivable</a></cite> [[WCAG21]].</p>
</dd>
<dt><dfn data-export="" data-dfn-for="ARIA">Property</dfn></dt>
<dd>
<p>[=attributes=] that are essential to the nature of a given <a>object</a>, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, <pref>aria-multiline</pref>) are less likely to change than <a class="termref" href="#dfn-state">states</a>, but note that the frequency of change difference is not a rule. A few properties, such as <pref>aria-activedescendant</pref>, <pref>aria-valuenow</pref>, and <pref>aria-valuetext</pref> are expected to change often. See <a class="specref" href="#statevsprop">clarification of states versus properties</a>.</p>
</dd>
<dt><dfn data-export="">Relationship</dfn></dt>
<dd>
<p>A connection between two distinct things. Relationships may be of various types to indicate which <a>object</a> labels another, controls another, etc.</p>
</dd>
<dt><dfn data-export="">Role</dfn></dt>
<dd>
<p>Main indicator of type. <!-- (removing, vague) The object's role is the class of <a class="termref">objects</a> of which it is a member. --> This <a class="termref" data-lt="semantics">semantic</a> association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.</p>
</dd>
<dt><dfn data-export="" data-local-lt="semantically">Semantics</dfn></dt>
<dd>
<p>The meaning of something as understood by a human, defined in a way that computers can process a representation of an <a>object</a>, such as [=elements=] and [=attributes=], and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.</p>
</dd>
<dt><dfn data-export="">State</dfn></dt>
<dd>
<p>A state is a dynamic <a class="termref" href="#dfn-property">property</a> expressing characteristics of an <a>object</a> that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities. See <a class="specref" href="#statevsprop">clarification of states versus properties</a>.</p>
</dd>
<dt><dfn>Target Element</dfn></dt>
<dd>
<p>An element specified in a <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> relation. For example, in <code> <div aria-controls=”elem1”></code>, where <code>“elem1”</code> is the ID for the target element.</p>
</dd>
<dt><dfn data-lt="unicode braille">Unicode Braille Patterns</dfn></dt>
<dd>
<p>In Unicode, braille is represented in a block called Braille Patterns (U+2800..U+28FF). The block contains all 256 possible patterns of an 8-dot braille cell; this includes the complete 6-dot cell range which is represented by U+2800..U+283F. In all braille systems, the braille pattern dots-0 (U+2800) is used to represent a space or the lack of content; it is also called a blank Braille pattern. See <cite><a href="https://en.wikipedia.org/wiki/Braille_Patterns">Braille Patterns on Wikipedia</a>.</cite></p>
</dd>
<dt><dfn data-export="">Widget</dfn></dt>
<dd>
<p>Discrete user interface <a class="termref" href="#dfn-object">object</a> with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).</p>
</dd>
</dl>
</div>
</section>
<section class="normative override" id="conformance">
<h2>Conformance</h2>
<p>The main content of Accessible Rich Internet Applications is normative and defines requirements that impact conformance claims. Introductory material, appendices, sections marked as "non-normative" and their subsections, diagrams, examples, and notes are informative (non-normative). Non-normative material provides advisory information to help interpret the guidelines but does not create requirements that impact a conformance claim.</p>
<p>Normative sections provide requirements that [=user agents=] must follow for an implementation to conform to this specification. The keywords <em class="rfc2119">MUST</em>, <em class="rfc2119">MUST NOT</em>, <em class="rfc2119">REQUIRED</em>, <em class="rfc2119">SHALL</em>, <em class="rfc2119">SHALL NOT</em>, <em class="rfc2119">SHOULD</em>, <em class="rfc2119">RECOMMENDED</em>, <em class="rfc2119">MAY</em>, and <em class="rfc2119">OPTIONAL</em> in this document are to be interpreted as described in <cite><a href="http://www.rfc-editor.org/rfc/rfc2119.txt">Keywords for use in RFCs to indicate requirement levels</a></cite> [[!RFC2119]]. RFC-2119 keywords are formatted in uppercase and contained in an element with <code>class="rfc2119"</code>. When the keywords shown above are used, but do not share this format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usages are avoided in this specification.</p>
<p>Normative sections provide requirements that authors, user agents and assistive technologies MUST follow for an implementation to conform to this specification.</p>
<p>Non-normative (informative) sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.</p>
<section id="ua_noninterference">
<h2>Non-interference with the Host Language</h2>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> processing by the <a>user agent</a> MUST NOT interfere with the normal operation of the built-in features of the host language.</p>
<p>If a CSS selector includes a WAI-ARIA attribute (e.g., <code class="highlight lang-css">input[aria-invalid="true"]</code>), user agents MUST update the visual display of any elements matching (or no longer matching) the selector any time the attribute is added/changed/removed in the <abbr title="Document Object Model">DOM</abbr>. The user agent MAY alter the mapping of the host language features into an <a>accessibility <abbr title="Application Programing Interface">API</abbr></a>, but the user agent MUST NOT alter the <abbr title="Document Object Model">DOM</abbr> in order to remap <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> markup into host language features.</p>
</section>
<section id="ua_dom">
<h2>All <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> in <abbr title="Document Object Model">DOM</abbr></h2>
<p>A conforming <a>user agent</a> which implements a document object model that does not conform to the W3C DOM specification MUST include the content attribute for role and its <a href="#roles_categorization">WAI-ARIA role values</a>, as well as the <a href="#states_and_properties">WAI-ARIA States and Properties</a> in the DOM as specified by the author, even though processing may affect how the elements are exposed to accessibility APIs. Doing so ensures that each role attribute and all <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> states and properties, including their values, are in the document in an unmodified form so other tools, such as assistive technologies, can access them. A conforming W3C <abbr title="Document Object Model">DOM</abbr> meets this criterion.</p>
</section>
<section id="ua_domchanges">
<h2>Assistive Technology Notifications Communicated to Web Applications</h2>
<p><a>Assistive technologies</a>, such as speech recognition systems and alternate input devices for users with mobility impairments, require the ability to control a web application in a device-independent way. <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>states</a> and [=ARIA/properties=] reflect the current state of rich internet application components. The ability for assistive technologies to notify web applications of necessary changes is essential because it allows these alternative input solutions to control an application without being dependent on the standard input device which the user is unable to effectively control directly.</p>
<p>User agents MUST provide a method to notify the web application when a change occurs to states or properties in the system accessibility API. Likewise, web application authors SHOULD update the web application accordingly when notified of a change request from the user agent or assistive technology.</p>
</section>
<section id="conformance_checkers">
<h2>Conformance Checkers</h2>
<p>Any application or script verifying document conformance or validity SHOULD include a test for all of the normative author requirements in this specification. If testing for a given requirement, conformance checkers MUST issue an error if an author "MUST" requirement isn't met, and MUST issue a warning if an author "SHOULD" requirement isn't met.</p>
</section>
<section id="deprecated">
<!-- Deprecated requirements should begin with <p><em>This requirement is <a href="#deprecated">deprecated</a>.</em></p> -->
<h2>Deprecated Requirements</h2>
<p>As the technology evolves, sometimes new ways to meet a use case become available, that work better than a feature that was previously defined. But because of existing implementation of the older feature, that feature cannot be removed from the conformance model without rendering formerly conforming content non-conforming. In this case, the older feature is marked as "deprecated". This indicates that the feature is allowed in the conformance model and expected to be supported by user agents, but it is recommended that authors do not use it for new content. In future versions of the specification, if the feature is no longer widely used, the feature could be removed and no longer expected to be supported by user agents.</p>
</section>
</section>
<section class="normative" id="usage" data-cite="dom">
<h1>Using <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr></h1>
<p>Complex web applications become inaccessible when <a>assistive technologies</a> cannot determine the <a>semantics</a> behind portions of a document or when the user is unable to effectively navigate to all parts of it in a usable way (see <cite><a href="" class="practices"><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</a></cite>). <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> divides the semantics into <a>roles</a> (the type defining a user interface element) and <a>states</a> and [=ARIA/properties=] supported by the roles.</p>
<p>Authors need to associate [=elements=] in the document to a WAI-ARIA role and the appropriate states and properties (aria-* [=attributes=]) during its life-cycle, unless the elements already have the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantics</a> for states and properties. In these instances the equivalent host language states and properties take precedence to avoid a conflict while the role attribute will take precedence over the implicit role of the host language element.</p>
<section id="introroles" class="normative">
<h2><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Roles</h2>
<p>A <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>role</a> is set on an <a>element</a> using a <code>role</code> <a>attribute</a>, similar to the <code>role</code> attribute defined in <cite><a href="https://www.w3.org/TR/role-attribute/">Role Attribute</a></cite> [[ROLE-ATTRIBUTE]].</p>
<pre class="example highlight"><li role="menuitem">Open file…</li></pre>
<p>The definition of each role in the model provides the following information :</p>
<ul>
<li>an informative description of the role;</li>
<li>hierarchical information about related roles (e.g., a <rref>searchbox</rref> is a type of <rref>textbox</rref>);</li>
<li>context of the role (e.g., a <rref>listitem</rref> is contained inside a <rref>list</rref>);</li>
<li>references to related concepts in other specifications;</li>
<li>supported <a>states</a> and [=ARIA/properties=] for each role (e.g., a <rref>checkbox</rref> supports being checked via <sref>aria-checked</sref>).</li>
</ul>
<p>Attaching a role gives <a>assistive technologies</a> information about how to handle each element. When <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> roles override host language semantics, there are no changes in the <abbr title="Document Object Model">DOM</abbr>, only in the <a class="termref">accessibility tree</a>.</p>
<p>User agents MUST use the first token in the sequence of tokens in the <code>role</code> <a>attribute</a> value that matches the name of any non-abstract <abbr title="Accessible Internet Application">WAI-ARIA</abbr> <a>role</a>. Refer to the section on <a href="#host_general_role">`role` attribute implementation in Host Languages</a> for further details.</p>
</section>
<section id="introstates">
<h2><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> States and Properties</h2>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> provides a collection of accessibility <a>states</a> and [=ARIA/properties=] which are used to support platform <a>accessibility <abbr title="Application Programing Interfaces">APIs</abbr></a> on various operating system platforms. <a>Assistive technologies</a> may access this information through an exposed <a>user agent</a> DOM or through a mapping to the platform accessibility <abbr title="Application Programing Interfaces">API</abbr>. When combined with <a>roles</a>, the user agent can supply the assistive technologies with user interface information to convey to the user at any time. Changes in states or properties will result in a notification to assistive technologies, which could alert the user that a change has occurred.</p>
<p>In the following example, a list item (<code>html:li</code>) has been used to create a checkable menu item, and JavaScript <a>events</a> will capture mouse and keyboard events to toggle the value of <sref>aria-checked</sref>. A role is used to make the behavior of this simple <a>widget</a> known to the user agent. [=attribute|Attributes=] that change with user actions (such as <sref>aria-checked</sref>) are defined in the <a href="#states_and_properties">states and properties</a> section.</p>
<pre class="example highlight"><li role="menuitemcheckbox" aria-checked="true">Sort by Last Modified</li></pre>
<p>Some accessibility states, called <em><a>managed states</a></em>, are controlled by the user agent. Examples of managed state include keyboard focus and selection. Managed states often have corresponding <abbr title="Cascading Style Sheets">CSS</abbr> pseudo-classes (such as <code>:focus</code> and <code>::selection</code>) to define style changes. In contrast, the states in this specification are typically controlled by the author and are called <em>unmanaged states.</em> Some states are managed by the user agent, such as <pref>aria-posinset</pref> and <pref>aria-setsize</pref>, but the author can override them if the <abbr title="Document Object Model">DOM</abbr> is incomplete and would cause the user agent calculation to be incorrect. User agents map both managed and unmanaged states to the platform accessibility <abbr title="Application Programing Interfaces">APIs</abbr>.</p>
<p>Most modern user agents support <cite><a href="https://www.w3.org/TR/css3-selectors/#attribute-selectors"><abbr title="Cascading Style Sheets">CSS</abbr> attribute selectors</a></cite> ([[CSS3-SELECTORS]]), and can allow the author to create <abbr title="User Interface">UI</abbr> changes based on <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> attribute information, reducing the amount of scripts necessary to achieve equivalent functionality. In the following example, a <abbr title="Cascading Style Sheets">CSS</abbr> selector is used to determine whether or not the text is bold and an image of a check mark is shown, based on the value of the <sref>aria-checked</sref> attribute.</p>
<pre class="example highlight lang-css">[aria-checked="true"] { font-weight: bold; }
[aria-checked="true"]::before { background-image: url(checked.gif); }</pre>
<p>If CSS is not used to toggle the visual representation of the check mark, the author could include additional markup and scripts to manage an image that represents whether or not the <rref>menuitemcheckbox</rref> is checked.</p>
<pre class="example highlight"><li role="menuitemcheckbox" aria-checked="true">
<img src="checked.gif" alt="">
<span class="comment"><!-- note: additional scripts required to toggle image source --></span>
Sort by Last Modified
</li></pre>
</section>
<section id="managingfocus" class="normative">
<h2>Managing Focus and Supporting Keyboard Navigation</h2>
<p>When using standard <abbr title="Hypertext Markup Language">HTML</abbr> interactive elements and simple <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>widgets</a>, application developers can manipulate the tab order or associate keyboard shortcuts with elements in the document.</p>
<p><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> includes a number of "managing container" widgets, also known as "composite" widgets. When appropriate, the container is responsible for tracking the last descendant that was active (the default is usually the first item in the container). It is essential that a container maintain a usable and consistent strategy when focus leaves a container and is then later refocused. While there may be exceptions, it is recommended that when a previously focused container is refocused, the active descendant be the same element as the active descendant when the container was last focused. Exceptions include cases where the contents of a container widget have changed, and widgets like a menubar where the user expects to always return to the first item when focus leaves the menu bar. For example, if the second item of a tree group was the active descendant when the user tabbed out of the tree group, then the second item of the tree group remains the active descendant when the tree group gets focus again. The user may also activate the container by clicking on one of the descendants within it. When the container or its active descendant has focus, the user may navigate through the container by pressing additional keys, such as the arrow keys, to change the currently active descendant. Any additional press of the main navigation key (generally the <kbd>TAB</kbd> key) will move out of the container to the next widget.</p>
<p>Usable keyboard navigation in a rich internet application is different from the tabbing paradigm among interactive elements, such as links and form controls, in a static document. In rich internet applications, the user tabs to significantly complex <a class="termref">widgets</a>, such as a menu or spreadsheet, and uses the arrow keys to navigate within the widget. The changes that <abbr title="accessible rich internet applications">WAI-ARIA</abbr> introduces to keyboard navigation make this enhanced accessibility possible. In <abbr title="accessible rich internet applications">WAI-ARIA</abbr>, any element can be keyboard focusable. In addition to host language mechanisms such as <code>tabindex</code>, <pref>aria-activedescendant</pref> provides another mechanism for keyboard operation. Most other aspects of <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> widget development depend on keyboard navigation functioning properly.</p>
<p>
When implementing <pref>aria-activedescendant</pref> as described below, the user agent keeps the <abbr title="Document Object Model">DOM</abbr> focus on the container element or on an input element that controls the container element.
However, the user agent communicates <a>desktop focus events</a> and states to the assistive technology as if the element referenced by <pref>aria-activedescendant</pref> has focus.
User agents are not expected to validate that the active descendant is a descendant of the container element.
It is the responsibility of the user agent to ensure that keyboard events are processed at the <a>element</a> that has <abbr title="Document Object Model">DOM</abbr> focus.
Any keyboard events directed at the active descendant bubble up to the <abbr title="Document Object Model">DOM</abbr> element with focus for processing.
</p>
<section id="managingfocus_authors">
<h3>Information for Authors</h3>
<p>If the author removes the element with focus, the author SHOULD move focus to a logical element. Similarly, authors SHOULD not scroll the element with focus off screen unless the user performed a scrolling action.</p>
<p>Authors SHOULD ensure that all interactive [=elements=] are focusable and that all parts of composite widgets are either focusable or have a documented alternative method to achieve their function.</p>
<p>Authors MUST manage focus on the following container roles:</p>
<ul>
<li><rref>grid</rref></li>
<li><rref>listbox</rref></li>
<li><rref>menu</rref></li>
<li><rref>menubar</rref></li>
<li><rref>radiogroup</rref></li>
<li><rref>tree</rref></li>
<li><rref>treegrid</rref></li>
<li><rref>tablist</rref></li>
</ul>
<p>User agents that support <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> expand the usage of host language mechanisms such as <code>tabindex</code>, <code>focus</code>, and <code>blur</code> to allow them on all [=elements=]. Where the host language supports it, authors MAY add any element such as a <code>div</code>, <code>span</code>, or <code>img</code> to the default tab order by setting <code>tabindex="0"</code>. In addition, any item with <code>tabindex</code> equal to a negative integer is focusable via script or a mouse click, but is not part of the default tab order. This is supported in both [[HTML]] and [[SVG2]].</p>
<p>
Authors MAY use <pref>aria-activedescendant</pref> to inform <a>assistive technologies</a> which descendant of a <rref>widget</rref> element is treated as having keyboard focus in the user interface if the role of the widget element supports <code>aria-activedescendant</code>.
This is often a more convenient way of providing keyboard navigation within widgets, such as a <rref>listbox</rref>, where the widget occupies only one stop in the page <kbd>Tab</kbd> sequence and other keys, typically arrow keys, are used to focus elements inside the widget.
</p>
<p>Typically, the author will use host language <a>semantics</a> to put the widget in the <kbd>Tab</kbd> sequence (e.g., <code>tabindex="0"</code> in <abbr title="Hypertext Markup Language">HTML</abbr>) and <code>aria-activedescendant</code> to point to the ID of the currently active descendant. The author, not the user agent, is responsible for styling the currently active descendant to show it has keyboard focus. The author cannot use <code>:<span class="css-selector">focus</span></code> to style the currently active descendant since the actual focus is on the container.</p>
<p>More information on managing focus can be found in the <a href="#keyboard" class="practices">Developing a Keyboard Interface</a> section of the <cite><abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Authoring Practices</cite>.</p>
</section>
<section id="managingfocus_useragents">
<h3>Information for User Agents</h3>
<p>The user agent MUST do the following to implement <pref>aria-activedescendant</pref>:</p>
<ol>
<li>Implement the host language method for keyboard navigation so that widgets that support <code>aria-activedescendant</code> may be included in the tab order.</li>
<li>For platforms that expose <a>desktop focus</a> or <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a> focus separately from <abbr title="Document Object Model">DOM</abbr> focus, do not expose the focused state in the accessibility <abbr title="application programming interface">API</abbr> for any element when it has <abbr title="Document Object Model">DOM</abbr> focus and also has <pref>aria-activedescendant</pref> which points to a valid <a href="#valuetype_idref">ID reference</a>.</li>
<li>When the <pref>aria-activedescendant</pref> attribute changes on an element that currently has <abbr title="Document Object Model">DOM</abbr> focus, remove the focused state from the previously focused object and fire an accessibility <abbr title="application programming interface">API</abbr> <a>desktop focus event</a> on the new element referenced by <code>aria-activedescendant</code>. If <pref>aria-activedescendant</pref> is cleared or does not point to an element in the current document, fire a desktop focus event for the <a>object</a> that had the attribute change.</li>
<li>Apply the following accessibility <abbr title="Application Programming Interface">API</abbr> states to any element with an ID attribute that can be referenced by an element with both an <pref>aria-activedescendant</pref> attribute and has <abbr title="Document Object Model">DOM</abbr> focus. There are two ways an element can be referenced by <pref>aria-activedescendant</pref>. One way is when it is [=ARIA/owned=] by an element with <pref>aria-activedescendant</pref> and the other is when it is [=ARIA/owned=] by an element that is controlled by an element with role of <rref>combobox</rref>, <rref>textbox</rref> or <rref>searchbox</rref> with an <pref>aria-activedescendant</pref> attribute:
<ol>
<li>Focusable, if the element also has a <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> <a class="termref">role</a>. The element needs to be focusable because it could be referenced by the <pref>aria-activedescendant</pref> attribute. Native elements that have no <a class="termref">role</a> attribute do not need to be checked; their native semantics determine the focusable state.</li>
<li>Focused, whenever the element is the target of the <pref>aria-activedescendant</pref> attribute and the element with the <pref>aria-activedescendant</pref> attribute has <abbr title="Document Object Model">DOM</abbr> focus.</li>
</ol>
</li>
</ol>
<p>When an assistive technology uses its platform's accessibility <abbr title="Application Programming Interfaces">API</abbr> to request a change of focus, user agents MUST do the following:</p>
<ol>
<li>Remove the platform's focused state from the previously focused object.</li>
<li>Set the <abbr title="Document Object Model">DOM</abbr> focus:
<ol>
<li>If the <a class="termref">element</a> can take <abbr title="Document Object Model">DOM</abbr> focus, the <a class="termref">user agent</a> MUST set the <abbr title="Document Object Model">DOM</abbr> focus to it.</li>
<li>Otherwise, if the element being focused has an ID and the ID is referenced by the <pref>aria-activedescendant</pref> attribute of an element that is focusable, the user agent MUST set <abbr title="Document Object Model">DOM</abbr> focus to the element that has the <pref>aria-activedescendant</pref> attribute.
<p class="note">An element with an ID can be referenced when it is [=ARIA/owned=] by a container element that has the <pref>aria-activedescendant</pref> attribute or by a container element that is controlled by an element that has the <pref>aria-activedescendant</pref> attribute (e.g. see <rref>combobox</rref>). Otherwise the <pref>aria-activedescendant</pref> attribute reference indicates an author error.</p>
<p class="note">The inability to set <abbr title="Document Object Model">DOM</abbr> focus to the containing element indicates an author error.</p>
</li>
<li>Otherwise, the user agent MAY attempt to set <abbr title="Document Object Model">DOM</abbr> focus to the child element itself.</li>
</ol>
</li>
<li>If the element being focused has an ID and is [=ARIA/owned=] by either a container element with both an <code>aria-activedescendant</code> attribute and has <abbr title="Document Object Model">DOM</abbr> focus, or by a container element that is controlled by an element with both an <pref>aria-activedescendant</pref> attribute and has <abbr title="Document Object Model">DOM</abbr> focus, the user agent MUST set the accessibility <abbr title="Application Programming Interface">API</abbr> focused state and fire an accessibility <abbr title="Application Programming Interface">API</abbr> focus <a>event</a> on the element identified by the value of <code>aria-activedescendant</code>.</li>
</ol>
</section>
</section>
</section>
<section class="normative" id="roles">
<h1>The Roles Model</h1>
<p>This section defines <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>roles</a> and describes their characteristics and properties.</p>
<p>The roles, their characteristics, the states and properties they support, and specification of how they may be used in markup, shall be considered normative.</p>
<p>In order to reflect the content in the DOM, user agents SHOULD map the role attribute to the appropriate value in the implemented accessibility API, and user agents SHOULD update the mapping when the role attribute changes.</p>
<section id="relationshipsconcepts">
<h2>Relationships Between Concepts</h2>
<p>The Roles Model uses the following relationships to relate <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> roles to each other and to concepts from other specifications, such as HTML.</p>
<section id="superclassrole">
<h3>Superclass Role</h3>
<p>The <a>role</a> that the current subclassed role extends in the Roles Model. This extension causes all the states and properties of the superclass role to propagate to the subclass role. Other than well known stable specifications, inheritance may be restricted to items defined inside this specification, so that external items cannot be changed and affect inherited classes.</p>
</section>
<section id="subclassroles">
<h3>Subclass Roles</h3>
<p>Informative list of <a>roles</a> for which this role is the superclass. This is provided to facilitate reading of the specification but adds no new information.</p>
</section>
<section id="relatedConcept">
<h3>Related Concepts</h3>
<p>Informative data about a similar or related idea from other specifications. Concepts that are related are not necessarily identical. Related concepts do not inherit properties from each other. Hence if the definition of one concept changes, the properties, behavior, and definition of its related concept is not affected.</p>
<p>For example, a progress bar is like a status indicator. Therefore, the <rref>progressbar</rref> <a>widget</a> has a related concept which includes <rref>status</rref>. However, if the definition of <rref>status</rref> is modified, the definition of a <rref>progressbar</rref> is not affected.</p>
</section>
<section id="baseConcept">
<h3>Base Concept</h3>
<p>Informative data about <a>objects</a> that are considered prototypes for the <a>role</a>. Base concept is similar to type, but without inheritance of limitations and properties. Base concepts are designed as a substitute for inheritance for external concepts. A base concept is like a <a href="#relatedConcept">related concept</a> except that the base concept is almost identical to the role definition.</p>
<p>For example, the <rref>checkbox</rref> defined in this document has similar functionality and anticipated behavior to a <code><input type="checkbox"></code> defined in [[HTML]]. Therefore, a <rref>checkbox</rref> has an [[HTML]] <code>checkbox</code> as a <code>baseConcept</code>. However, if the original [[HTML]] checkbox baseConcept definition is modified, the definition of a <rref>checkbox</rref> in this document will not be affected, because there is no actual inheritance of the respective type.</p>
</section>
</section>
<section id="Properties">
<h2>Characteristics of Roles</h2>
<p>Roles are defined and described by their characteristics. Characteristics define the structural function of a role, such as what a role is, concepts behind it, and what instances the role can or must contain. In the case of <a>widgets</a> this also includes how it interacts with the <a>user agent</a> based on mapping to <abbr title="Hypertext Markup Language">HTML</abbr> forms. States and properties from <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> that are supported by the role are also indicated.</p>
<p>Roles define the following characteristics. </p>
<section id="isAbstract">
<h3>Abstract Roles</h3>
<dl class="runin">
<dt>Values</dt>
<dd>Boolean</dd>
</dl>
<p>Abstract <a>roles</a> are the foundation upon which all other <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> roles are built. Content authors MUST NOT use abstract roles because they are not implemented in the <abbr title="application programing interface">API</abbr> binding. User agents MUST NOT map abstract roles to the standard role mechanism of the accessibility API. Abstract roles are provided to help with the following:</p>
<ol>
<li>Organize the Roles Model and provide roles with a meaning in the context of known concepts.</li>
<li>Streamline the addition of roles that include necessary features.</li>
</ol>
</section>
<section id="requiredState">
<h3>Required States and Properties</h3>
<p><a>States</a> and [=ARIA/properties=] specifically required for the <a>role</a> and subclass roles. Content authors MUST provide a non-empty <span>value</span> for required states and properties. Content authors MUST NOT use the value <code>undefined</code> for required states and properties, unless <code>undefined</code> is an explicitly-supported value of that state or property.</p>
<p>When an <a>object</a> inherits from multiple ancestors and one ancestor indicates that property is supported while another ancestor indicates that it is required, the property is required in the inheriting object.</p>
<p class="note">A host language attribute with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="supportedState">
<h3>Supported States and Properties</h3>
<p><a>States</a> and [=ARIA/properties=] specifically applicable to the <a>role</a> and child roles. Content authors MAY provide <span>values</span> for supported states and properties, but need not in cases where default values are sufficient. [=user agents=] MUST map all supported states and properties for the role to an accessibility API. If the state or property is undefined and it has a default value for the role, [=user agents=] SHOULD expose the default value.</p>
<p class="note">A host language attribute with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="inheritedattributes">
<h3>Inherited States and Properties</h3>
<p>Informative list of properties that are inherited by a <a>role</a> from superclass roles. <a>States</a> and [=ARIA/properties=] are inherited from superclass roles in the Roles Model, not from ancestor [=elements=] in the <abbr title="Document Object Model">DOM</abbr> tree. These properties are not explicitly defined on the role, as the inheritance of properties is automatic. This information is provided to facilitate reading of the specification. The set of supported states and properties combined with inherited states and properties forms the full set of states and properties supported by the role.</p>
</section>
<section id="prohibitedattributes">
<h3>Prohibited States and Properties</h3>
<p>List of states and properties that are prohibited on a <a>role</a>. Authors MUST NOT specify a prohibited state or property.</p>
<p class="note">A host language attribute with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> would also prohibit a state or property in this section. </p>
</section>
<section id="mustContain">
<h3>Required Owned Elements</h3>
<p>Any <a>element</a> that will be [=ARIA/owned=] by the element with this <a>role</a>. For example, an element with the role <rref>list</rref> will own at least one element with the role <rref>listitem</rref>.</p>
<p>When multiple roles are specified as <em>required owned elements</em> for a role, at least one instance of one required [=ARIA/owned=] element is expected. This specification does <em>not</em> require an instance of each of the listed owned roles. For example, a <code>menu</code> should have at least one instance of a <code>menuitem</code>, <code>menuitemcheckbox</code>, <em>or</em> <code>menuitemradio</code>. The <code>menu</code> role does not require one instance of each. </p>
<p>There may be times that required [=ARIA/owned=] elements are missing, for example, while editing or while loading a data set. When a widget is missing <em>required owned elements</em> due to script execution or loading, authors MUST mark a containing element with <sref>aria-busy</sref> equal to <code>true</code>. For example, until a page is fully initialized and complete, an author could mark the document element as busy.</p>
<p class="note">A role that has 'required owned elements' does not imply the reverse relationship. While processing of a role may be incomplete without elements of given roles present as descendants, elements with roles in this list do not always have to be found within elements of the given role. See <a href="#scope">required context role</a> for requirements about the context where elements of a given role will be contained.</p>
<p class="note">An element with a <a href="#subclassroles">subclass role</a> of the 'required owned element' does not fulfill this requirement. For example, the <rref>listbox</rref> role requires ownership of an element using the <rref>option</rref> or <rref>group</rref> role. Although the <rref>group</rref> role is the superclass of <rref>row</rref>, adding an [=ARIA/owned=] element with a role of <rref>row</rref> will not fulfill the requirement that <rref>listbox</rref> owns an <rref>option</rref> or a <rref>group</rref>.</p>
<p class="note">An element with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="scope">
<h3>Required Context Role</h3>
<p>The required context role defines the owning container where this <a>role</a> is allowed. If a role has a required context, authors MUST ensure that an element with the role is contained inside (or [=ARIA/owned=] by) an element with the required context role. For example, an element with role <code>listitem</code> is only meaningful when contained inside (or [=ARIA/owned=] by) an element with role <code>list</code>.</p>
<p class="note">A role that has 'required context role' does not imply the reverse relationship. While an element with the given role needs to appear within an element of the listed role(s) in order to be meaningful, elements of the listed roles do not always need descendant elements of the given role in order to be meaningful. See <a href="#mustContain">required owned elements</a> for requirements about elements that require presence of a given descendant to be processed properly.</p>
<p class="note">An element with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="namecalculation">
<h3>Accessible Name Calculation</h3>
<dl class="runin">
<dt>Values</dt>
<dd>One of the following values:
<ol>
<li>author: name comes from values provided by the author in explicit markup features such as the <pref>aria-label</pref> attribute, the <pref>aria-labelledby</pref> attribute, or the host language labeling mechanism, such as the <code>alt</code> or <code>title</code> attributes in <abbr title="Hypertext Markup Language">HTML</abbr>, with HTML <code>title</code> attribute having the lowest precedence for specifying a text alternative.</li>
<li>contents: name comes from the text value of the <a>element</a> node. Although this may be allowed in addition to "author" in some <a>roles</a>, this is used in content only if higher priority "author" features are not provided. Priority is defined by the <a href="#mapping_additional_nd_te" class="accname">accessible name and description computation</a> algorithm [[ACCNAME-1.2]].</li>
<li>prohibited: the element does not support name from author. Authors MUST NOT use the <pref>aria-label</pref> or <pref>aria-labelledby</pref> attributes to name the element.</li>
</ol>
</dd>
</dl>
<section id="namecomputation">
<h4>Name Computation</h4>
<p><a href="#mapping_additional_nd_name" class="accname">Name Computation</a> is defined in the Accessible Name and Description specification.</p>
</section>
<section id="descriptioncomputation">
<h4>Description Computation</h4>
<p><a href="#mapping_additional_nd_description" class="accname">Description Computation</a> is defined in the Accessible Name and Description specification.</p>
</section>
<section id="textalternativecomputation">
<h4>Accessible Name and Description Computation</h4>
<p><a href="#mapping_additional_nd_te" class="accname">Accessible Name and Description Computation</a> is defined in the Accessible Name and Description specification.</p>
</section>
<section id="namefromauthor">
<h4>Roles Supporting Name from Author</h4>
<div id="index_fromauthor">
</div>
</section>
<section id="namefromcontent">
<h4>Roles Supporting Name from Content</h4>
<div id="index_fromcontent">
</div>
</section>
<section id="namefromprohibited">
<h4>Roles which cannot be named (Name prohibited)</h4>
<div id="index_fromprohibited">
</div>
</section>
</section>
<section id="childrenArePresentational">
<h3>Presentational Children</h3>
<dl class="runin">
<dt>Values</dt>
<dd>
<p>Boolean (<code>true</code> | <code>false</code>)</p>
</dd>
</dl>
<p>The <abbr title="Document Object Model">DOM</abbr> descendants are presentational. [=user agents=] SHOULD NOT expose descendants of this <a>element</a> through the platform <a>accessibility <abbr title="Application Programing Interface">API</abbr></a>. If [=user agents=] do not hide the descendant nodes, some information may be read twice.</p>
</section>
<section id="implictValueForRole">
<h3>Implicit Value for Role</h3>
<p>Many states and properties have default values. Occasionally, the default value when used on a given role should be different from the usual default. Roles that require a state or property to have a non-standard default value indicate this in the "Implicit Value for Role". This is expressed in the form "Default for <code>state or property name</code> is <code>new default value</code>". Roles that define this have the new default value for the state or property if the author does not provide an explicit value.</p>
</section>
</section>
<section id="roles_categorization">
<h2>Categorization of Roles</h2>
<p>To support the current user scenario, this specification categorizes <a>roles</a> that define user interface <a>widgets</a> (sliders, tree controls, etc.) and those that define page structure (sections, navigation, etc.). Note that some assistive technologies provide special modes of interaction for regions marked with role <code>application</code> or <code>document</code>.</p>
<p>A visual description of the relationships among roles is available in the <a href="https://www.w3.org/WAI/ARIA/1.2/class-diagram/">ARIA 1.2 Class Diagram</a>.</p>
<p>Roles are categorized as follows:</p>
<ol>
<li><a href="#abstract_roles">Abstract Roles</a></li>
<li><a href="#widget_roles">Widget Roles</a></li>
<li><a href="#document_structure_roles">Document Structure Roles</a></li>
<li><a href="#landmark_roles">Landmark Roles</a></li>
<li><a href="#live_region_roles">Live Region Roles</a></li>
<li><a href="#window_roles">Window Roles</a></li>
</ol>
<section id="abstract_roles">
<h3>Abstract Roles</h3>
<p>The following <a>roles</a> are used to support the WAI-ARIA Roles Model for the purpose of defining general role concepts.</p>
<p>Abstract roles are used for the ontology. Authors MUST NOT use abstract roles in content.</p>
<ul>
<li><rref>command</rref></li>
<li><rref>composite</rref></li>
<li><rref>input</rref></li>
<li><rref>landmark</rref></li>
<li><rref>range</rref></li>
<li><rref>roletype</rref></li>
<li><rref>section</rref></li>
<li><rref>sectionhead</rref></li>
<li><rref>select</rref></li>
<li><rref>structure</rref></li>
<li><rref>widget</rref></li>
<li><rref>window</rref></li>
</ul>
</section>
<section id="widget_roles">
<h3>Widget Roles</h3>
<p>The following roles act as standalone user interface widgets or as part of larger, composite widgets.</p>
<ul>
<li><rref>button</rref></li>
<li><rref>checkbox</rref></li>
<li><rref>gridcell</rref></li>
<li><rref>link</rref></li>
<li><rref>menuitem</rref></li>
<li><rref>menuitemcheckbox</rref></li>
<li><rref>menuitemradio</rref></li>
<li><rref>option</rref></li>
<!-- FIXME: This is commented out because the ARIA Working Group agreed to move the password role to ARIA 2.0,
but we've not branched for 1.1 yet. Once we have branched, this section should be deleted from the 1.1
branch and uncommented for the master branch (pending discussion and consensus).
<li><rref>password</rref></li>
-->
<li><rref>progressbar</rref></li>
<li><rref>radio</rref></li>
<li><rref>scrollbar</rref></li>
<li><rref>searchbox</rref></li>
<li><rref>separator</rref> (when focusable)</li>
<li><rref>slider</rref></li>
<li><rref>spinbutton</rref></li>
<li><rref>switch</rref></li>
<li><rref>tab</rref></li>
<li><rref>tabpanel</rref></li>
<li><rref>textbox</rref></li>
<li><rref>treeitem</rref></li>
</ul>
<p>The following roles act as composite user interface widgets. These roles typically act as containers that manage other, contained widgets.</p>
<ul>
<li><rref>combobox</rref></li>
<li><rref>grid</rref></li>
<li><rref>listbox</rref></li>
<li><rref>menu</rref></li>
<li><rref>menubar</rref></li>
<li><rref>radiogroup</rref></li>
<li><rref>tablist</rref></li>
<li><rref>tree</rref></li>
<li><rref>treegrid</rref></li>
</ul>
</section>
<section id="document_structure_roles">
<h3>Document Structure Roles</h3>
<p>The following <a>roles</a> describe structures that organize content in a page. Document structures are not usually interactive.</p>
<ul>
<li><rref>application</rref></li>
<li><rref>article</rref></li>
<li><rref>associationlist</rref></li>
<li><rref>associationlistitemkey</rref></li>
<li><rref>associationlistitemvalue</rref></li>
<li><rref>blockquote</rref></li>
<li><rref>caption</rref></li>
<li><rref>cell</rref></li>
<li><rref>code</rref></li>
<li><rref>columnheader</rref></li>
<li><rref>comment</rref></li>
<li><rref>definition</rref></li>
<li><rref>deletion</rref></li>
<li><rref>directory</rref></li>
<li><rref>document</rref></li>
<li><rref>emphasis</rref></li>
<li><rref>feed</rref></li>
<li><rref>figure</rref></li>
<li><rref>generic</rref></li>
<li><rref>group</rref></li>
<li><rref>heading</rref></li>
<li><rref>img</rref></li>
<li><rref>insertion</rref></li>
<li><rref>list</rref></li>
<li><rref>listitem</rref></li>
<li><rref>mark</rref></li>
<li><rref>math</rref></li>
<li><rref>meter</rref></li>
<li><rref>none</rref></li>
<li><rref>note</rref></li>
<li><rref>paragraph</rref></li>
<li><rref>presentation</rref></li>
<li><rref>row</rref></li>
<li><rref>rowgroup</rref></li>
<li><rref>rowheader</rref></li>
<li><rref>separator</rref> (when not focusable)</li>
<li><rref>strong</rref></li>
<li><rref>subscript</rref></li>
<li><rref>suggestion</rref></li>
<li><rref>superscript</rref></li>
<li><rref>table</rref></li>
<li><rref>term</rref></li>
<li><rref>time</rref></li>
<!-- FIXME: This is commented out because the ARIA Working Group agreed to move the text role to ARIA 2.0,
but we've not branched for 1.1 yet. Once we have branched, this entire section should be deleted from
the 1.1 branch and uncommented for the master branch.
<li><rref>text</rref></li>
-->
<li><rref>toolbar</rref></li>
<li><rref>tooltip</rref></li>
</ul>
</section>
<section id="landmark_roles">
<h3>Landmark Roles</h3>
<p>The following <a>roles</a> are regions of the page intended as navigational <a>landmarks</a>. All of these roles inherit from the <code>landmark</code> base type and all are imported from the <cite><a href="https://www.w3.org/TR/role-attribute/#s_role_module_attributes">Role Attribute</a></cite> [[ROLE-ATTRIBUTE]]. The roles are included here in order to make them clearly part of the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Roles Model.</p>
<ul>
<li><rref>banner</rref></li>
<li><rref>complementary</rref></li>
<li><rref>contentinfo</rref></li>
<li><rref>form</rref></li>
<li><rref>main</rref></li>
<li><rref>navigation</rref></li>
<li><rref>region</rref></li>
<li><rref>search</rref></li>
</ul>
</section>
<section id="live_region_roles">
<h3>Live Region Roles</h3>
<p>The following <a>roles</a> are <a>live regions</a> and may be modified by <a href="#attrs_liveregions">live region attributes</a>.</p>
<ul>
<li><rref>alert</rref></li>
<li><rref>log</rref></li>
<li><rref>marquee</rref></li>
<li><rref>status</rref></li>
<li><rref>timer</rref></li>
</ul>
</section>
<section id="window_roles">
<h3>Window Roles</h3>
<p>The following <a>roles</a> act as windows within the browser or application.</p>
<ul>
<li><rref>alertdialog</rref></li>
<li><rref>dialog</rref></li>
</ul>
</section>
</section>
<section id="role_definitions" data-cite="dom">
<h2>Definition of Roles</h2>
<p>Below is an alphabetical list of <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> <a>roles</a> to be used by authors.</p>
<p>Abstract roles are used for the ontology. Authors MUST NOT use abstract roles in content.</p>
<p id="index_role">Placeholder for compact list of roles</p>
<div class="role" id="alert">
<rdef>alert</rdef>
<div class="role-description">
<p>A type of <a>live region</a> with important, and usually time-sensitive, information. See related <rref>alertdialog</rref> and <rref>status</rref>.</p>
<p>Alerts are used to convey messages that may be immediately important to users. In the case of audio warnings, alerts provide an accessible alternative for hearing-impaired users. The <code>alert</code> <a>role</a> is applied to the element containing the alert message. An <code>alert</code> is a specialized form of the <rref>status</rref> role, which is processed as an atomic <a>live region</a>.</p>
<p>Alerts are assertive live regions, which means they cause immediate notification for assistive technology users. If the operating system allows, the <a>user agent</a> SHOULD fire a system alert <a>event</a> through the accessibility API when the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> alert is created.</p>
<p>Neither authors nor user agents are required to set or manage focus to an alert in order for it to be processed. Since alerts are not required to receive focus, authors SHOULD NOT require users to close an alert. If an author desires focus to move to a message when it is conveyed, the author SHOULD use <rref>alertdialog</rref> instead of <code>alert</code>.</p>
<p>Elements with the role <code>alert</code> have an implicit <pref>aria-live</pref> value of <code>assertive</code>, and an implicit <pref>aria-atomic</pref> value of <code>true</code>.</p>
</div>
<table class="role-features">
<caption>Characteristics:</caption>
<thead>
<tr>
<th scope="col">Characteristic</th>
<th scope="col">Value</th>
</tr>
</thead>
<tbody>
<tr>
<th class="role-abstract-head" scope="row">Is Abstract:</th>
<td class="role-abstract"> </td>
</tr>
<tr>
<th class="role-parent-head" scope="row">Superclass Role:</th>
<td class="role-parent"><rref>section</rref></td>
</tr>
<tr>
<th class="role-children-head" scope="row">Subclass Roles:</th>
<td class="role-children">Placeholder</td>
</tr>
<tr>
<th class="role-base-head" scope="row">Base Concept:</th>
<td class="role-base"> </td>
</tr>
<tr>
<th class="role-related-head" scope="row">Related Concepts:</th>
<td class="role-related"> </td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Context Role:</th>
<td class="role-scope"> </td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Required Owned Elements:</th>
<td class="role-mustcontain"> </td>
</tr>
<tr>
<th class="role-required-properties-head">Required States and Properties:</th>
<td class="role-required-properties"> </td>
</tr>
<tr>
<th class="role-properties-head" scope="row">Supported States and Properties:</th>
<td class="role-properties"> </td>
</tr>
<tr>
<th class="role-inherited-head" scope="row">Inherited States and Properties:</th>
<td class="role-inherited">Placeholder</td>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
<td class="role-namerequired"> </td>
</tr>
<tr>
<th class="role-namerequired-inherited-head" scope="row">Inherits Name Required:</th>
<td class="role-namerequired-inherited"> </td>
</tr>
<tr>
<th class="role-childpresentational-head" scope="row">Children Presentational:</th>
<td class="role-childpresentational"> </td>
</tr>
<tr>
<th class="role-presentational-inherited-head" scope="row">Inherits Presentational:</th>
<td class="role-presentational-inherited"> </td>
</tr>
<tr>
<th class="implicit-values-head">Implicit Value for Role:</th>
<td class="implicit-values">
Default for <pref>aria-live</pref> is <code class="default">assertive</code>.<br/>
Default for <pref>aria-atomic</pref> is <code class="default">true</code>.
</td>
</tr>
</tbody>
</table>
</div>
<div class="role" id="alertdialog">
<rdef>alertdialog</rdef>
<div class="role-description">
<p>A type of dialog that contains an alert message, where initial focus goes to an <a>element</a> within the dialog. See related <rref>alert</rref> and <rref>dialog</rref>.</p>
<p>Alert dialogs are used to convey messages to alert the user. The <code>alertdialog</code> <a>role</a> goes on the [=nodes|node=] containing both the alert message and the rest of the dialog. Content authors SHOULD make alert dialogs modal by ensuring that, while the <code>alertdialog</code> is shown, keyboard and mouse interactions only operate within the dialog. See <pref>aria-modal</pref>.</p>
<p>Unlike <rref>alert</rref>, <code>alertdialog</code> can receive a response from the user. For example, to confirm that the user understands the alert being generated. When the alert dialog is displayed, authors SHOULD set focus to an active element within the alert dialog, such as a form control or confirmation button. The <a>user agent</a> SHOULD fire a system alert <a>event</a> through the accessibility API when the alert is created, provided one is specified by the intended <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a>.</p>
<p>Authors SHOULD use <pref>aria-describedby</pref> on an <code>alertdialog</code> to reference the alert message element in the dialog. If they do not, an <a>assistive technology</a> can resort to its internal recovery mechanism to determine the contents of the alert message.</p>
</div>
<table class="role-features">
<caption>Characteristics:</caption>
<thead>
<tr>
<th scope="col">Characteristic</th>
<th scope="col">Value</th>
</tr>
</thead>
<tbody>
<tr>
<th class="role-abstract-head" scope="row">Is Abstract:</th>
<td class="role-abstract"> </td>
</tr>
<tr>
<th class="role-parent-head" scope="row">Superclass Role:</th>
<td class="role-parent">
<ul>
<li><rref>alert</rref></li>
<li><rref>dialog</rref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-children-head" scope="row">Subclass Roles:</th>
<td class="role-children">Placeholder</td>
</tr>
<tr>
<th class="role-base-head" scope="row">Base Concept:</th>
<td class="role-base"> </td>
</tr>
<tr>
<th class="role-related-head" scope="row">Related Concepts:</th>
<td class="role-related"> </td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Context Role:</th>
<td class="role-scope"> </td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Required Owned Elements:</th>
<td class="role-mustcontain"> </td>
</tr>
<tr>
<th class="role-required-properties-head">Required States and Properties:</th>
<td class="role-required-properties"> </td>
</tr>
<tr>
<th class="role-properties-head" scope="row">Supported States and Properties:</th>
<td class="role-properties"> </td>
</tr>
<tr>
<th class="role-inherited-head" scope="row">Inherited States and Properties:</th>
<td class="role-inherited">Placeholder</td>
</tr>
<tr>
<th class="role-namefrom-head" scope="row">Name From:</th>
<td class="role-namefrom">author</td>
</tr>
<tr>
<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
<td class="role-namerequired">True</td>