-
Notifications
You must be signed in to change notification settings - Fork 22.5k
/
index.md
182 lines (129 loc) · 7.34 KB
/
index.md
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
---
title: "ARIA: checkbox role"
slug: Web/Accessibility/ARIA/Roles/checkbox_role
page-type: aria-role
---
{{AccessibilitySidebar}}
The `checkbox` role is for checkable interactive controls. Elements containing `role="checkbox"` must also include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute to expose the checkbox's state to assistive technology.
```html
<span
role="checkbox"
aria-checked="false"
tabindex="0"
aria-labelledby="chk1-label"></span>
<label id="chk1-label">Remember my preferences</label>
```
> **Note:** The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native [HTML checkbox of `<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) (with an associated {{HTMLElement('label')}}), which natively provides all the functionality required:
```html
<input type="checkbox" id="chk1-label" name="RememberPreferences" />
<label for="chk1-label">Remember my preferences</label>
```
## Description
The native HTML checkbox ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)) form control had two states ("checked" or "not checked"), with an [`indeterminate`](/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) state settable via JavaScript. Similarly, an element with `role="checkbox"` can expose three states through the `aria-checked` attribute: `true`, `false`, or `mixed`.
Since a checkbox is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to change this. The expected keyboard shortcut for activating a checkbox is the <kbd>Space</kbd> key.
The developer is required to change the value of the `aria-checked` attribute dynamically when the checkbox is activated.
### All descendants are presentational
There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `checkbox`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `checkbox` element as it is a role that does not support semantic children.
For example, consider the following `checkbox` element, which contains a heading.
```html
<div role="checkbox"><h6>Name of my checkbox</h6></div>
```
Because descendants of `checkbox` are presentational, the following code is equivalent:
```html
<div role="checkbox"><h6 role="presentation">Name of my checkbox</h6></div>
```
From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree):
```html
<div role="checkbox">Name of my checkbox</div>
```
### Associated WAI-ARIA Roles, States, and Properties
- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked)
- : The value of `aria-checked` defines the state of a checkbox. This attribute has one of three possible values:
- `true`
- : The checkbox is checked.
- `false`
- : The checkbox is not checked.
- `mixed`
- : The checkbox is partially checked, or indeterminate.
- `tabindex="0"`
- : Used to make it focusable so the assistive technology user can tab to it and start reading right away.
### Keyboard interactions
| Key | Function |
| ---------------- | ---------------------- |
| <kbd>Space</kbd> | Activates the checkbox |
### Required JavaScript
#### Required event handlers
- `onclick`
- : Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user
- `onKeyDown`
- : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user
## Examples
The following example creates an otherwise non-semantic checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element.
### HTML
```html
<span
role="checkbox"
id="chkPref"
aria-checked="false"
onclick="changeCheckbox()"
onKeyDown="changeCheckbox(event.code)"
tabindex="0"
aria-labelledby="chk1-label"></span>
<label
id="chk1-label"
onclick="changeCheckbox()"
onKeyDown="changeCheckbox(event.code)"
>Remember my preferences</label
>
```
### CSS
```css
[role="checkbox"] {
padding: 5px;
}
[role="checkbox"]:focus {
border: 2px solid #0198e1;
}
[aria-checked="true"]::before {
content: "[x]";
}
[aria-checked="false"]::before {
content: "[ ]";
}
```
### JavaScript
```js
function changeCheckbox(code) {
const item = document.getElementById("chkPref");
const checked = item.getAttribute("aria-checked");
if (code && code !== "Space") {
return;
} else if (checked === "true") {
item.setAttribute("aria-checked", "false");
} else {
item.setAttribute("aria-checked", "true");
}
}
```
{{EmbedLiveSample("Examples", 230, 250)}}
## Accessibility concerns
When the `checkbox` role is added to an element, the user agent should do the following:
- Expose the element as having a `checkbox` role in the operating system's accessibility API.
- When the `aria-checked` value changes, send an accessible state changed event.
Assistive technology products should do the following:
- Screen readers should announce the element as a checkbox, and optionally provide instructions on how to activate it.
People implementing checkboxes should do the following:
- Ensure that the checkbox can be reached and interacted with by both keyboard controls and clicks
- Keep the `aria-checked` attribute up to date following user interactions
- Provide styles that indicate when the checkbox has focus
> **Note:** Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may change.
## Best practices
The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML checkbox](/en-US/docs/Web/HTML/Element/input/checkbox) using form control instead of recreating a checkbox's functionality with JavaScript and ARIA.
## See also
- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)
- [ARIA: `radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role)
- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role)
- [ARIA: `menuitemcheckbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role)
- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role)
- [ARIA: `switch` role](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role)
- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role)