You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>The use of the dynamic <code>aria-expanded</code> attribute on the toggling element is recommended for toggling elements as it will announce that the target of the toggle is “expanded” or “collapsed.” Optionally, the attribute <code>aria-pressed</code> can be used instead to announce that the toggle button is “pressed” or “not pressed”. These attributes provide different feedback to screenreaders and are appropriate for different component types. <code>aria-expanded</code> would be used for patterns such as <ahref="https://inclusive-components.design/collapsible-sections/">
32
46
<strong>collapsible sections</strong>
33
47
</a> and <code>aria-pressed</code> would be used for <ahref="https://inclusive-components.design/toggle-button/">
34
48
<strong>toggle buttons</strong>
35
49
</a> or <strong>switches</strong>. A full list of dynamic and static attributes is described below.</p>
36
50
<p>Placement of the target should follow the toggling element so that it appears next in order on the page for screen readers. For targets that are far apart or appear in a different section of the page, the Anchor Toggle may be more appropriate.</p>
37
-
<p>The Toggle Utility supports having more than one toggle element per toggle target.</p>
51
+
<p>Elements that have aria-hidden set to <code>true</code> should not contain focusable elements. Setting their tabindex to <code>-1</code> will prevent them from being focused on. For convenience, child elements in the target element that have their <code>tabindex</code> set will be toggled.</p>
<p>The Toggle Utility supports having more than one toggle element per toggle target. An example use case is for “close” buttons within dialogue elements.</p>
<p>Attributes such as <code>aria-controls</code>, <code>aria-expanded</code>, and <code>type</code> will help assistive technologies understand the relationship between the toggle element and the toggle target. These three attributes should be considered the bare minimum but they may be interchanged with others based on the use case. Below is an explanation of other possible attributes that can be used with the toggle utility. <em>Static</em> attributes will not change. <em>Dynamic</em> attributes will change when the toggle event is fired.</p>
74
+
<p>Attributes on the Element, Target, and Target Children, such as <code>aria-hidden</code>, <code>aria-controls</code>, <code>aria-expanded</code>, <code>type</code>, and <code>tabindex</code>help assistive technologies understand the relationship between each element and their respective states of visibility. These attributes should be present but they may be interchanged with others based on the use case. Below is an explanation of all attributes that can be used with the toggle utility. <em>Static</em> attributes will not change. <em>Dynamic</em> attributes will change when the toggle event is fired.</p>
<td>Boolean that announces that the toggling element is toggled. Not recommended for use with <code>aria-expanded</code>.</td>
128
+
<td>Boolean that announces that the toggling element is toggled. Not recommended for use with <code>aria-expanded</code>. Commonly used with buttons that act as switches for options that are on or off.</td>
<td>Setting the toggle target’s focusable children’s <code>tabindex</code> attribute to “-1” will prevent them from being focused on when the parent is hidden. See the list below of potentially focusable elements that are supported.</td>
209
+
</tr>
210
+
<tr>
211
+
<td>
212
+
<code>data-toggle-tabindex</code>
213
+
</td>
214
+
<td>
215
+
<em>static</em>
216
+
</td>
217
+
<td>optional</td>
218
+
<td>If an child element has a <code>tabindex</code> that needs to be set when the parent target is visible then the default value can be stored in this data attribute.</td>
<td>A function that will be executed before the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class.</td>
278
+
<td>A function that will be executed before the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class with several values that may be useful in the callback such as the settings, toggle element, toggle target, and initial click event.</td>
<td>A function that will be executed after the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class.</td>
288
+
<td>A function that will be executed after the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class with several values that may be useful in the callback such as the settings, toggle element, toggle target, and initial click event.</td>
The use of the dynamic `aria-expanded` attribute on the toggling element is recommended for toggling elements as it will announce that the target of the toggle is "expanded" or "collapsed." Optionally, the attribute `aria-pressed` can be used instead to announce that the toggle button is "pressed" or "not pressed". These attributes provide different feedback to screenreaders and are appropriate for different component types. `aria-expanded` would be used for patterns such as [**collapsible sections**](https://inclusive-components.design/collapsible-sections/) and `aria-pressed` would be used for [**toggle buttons**](https://inclusive-components.design/toggle-button/) or **switches**. A full list of dynamic and static attributes is described below.
24
38
25
39
Placement of the target should follow the toggling element so that it appears next in order on the page for screen readers. For targets that are far apart or appear in a different section of the page, the Anchor Toggle may be more appropriate.
26
40
27
-
The Toggle Utility supports having more than one toggle element per toggle target.
41
+
Elements that have aria-hidden set to `true` should not contain focusable elements. Setting their tabindex to `-1` will prevent them from being focused on. For convenience, child elements in the target element that have their `tabindex` set will be toggled.
The Toggle Utility supports having more than one toggle element per toggle target. An example use case is for "close" buttons within dialogue elements.
Attributes such as `aria-controls`, `aria-expanded`, and `type` will help assistive technologies understand the relationship between the toggle element and the toggle target. These three attributes should be considered the bare minimum but they may be interchanged with others based on the use case. Below is an explanation of other possible attributes that can be used with the toggle utility. *Static* attributes will not change. *Dynamic* attributes will change when the toggle event is fired.
69
+
Attributes on the Element, Target, and Target Children, such as `aria-hidden`, `aria-controls`, `aria-expanded`, `type`, and `tabindex`help assistive technologies understand the relationship between each element and their respective states of visibility. These attributes should be present but they may be interchanged with others based on the use case. Below is an explanation of all attributes that can be used with the toggle utility. *Static* attributes will not change. *Dynamic* attributes will change when the toggle event is fired.
32
70
33
71
**Toggling Element Attributes**
34
72
35
73
Attribute | State | Importance | Description
36
74
----------------|-----------|---------------|-
37
-
`aria-controls` | *static* | required | ID of the target element. Used by the toggle to select the target element.
75
+
`aria-controls` | *static* | **required** | ID of the target element. Used by the toggle to select the target element.
38
76
`aria-expanded` | *dynamic* | recommended | Boolean that announces that target content is "expanded" or "collapsed" when the toggling element is clicked.
39
77
`type` | *static* | recommended | Setting a `<button>` element type to "button" will distinguish it from other button types, such as "submit" and "reset," but only within `<form>` elements. By default, a `<button>` is the type "submit" within a form.
40
-
`aria-pressed` | *dynamic* | optional | Boolean that announces that the toggling element is toggled. Not recommended for use with `aria-expanded`.
78
+
`aria-pressed` | *dynamic* | optional | Boolean that announces that the toggling element is toggled. Not recommended for use with `aria-expanded`. Commonly used with buttons that act as switches for options that are on or off.
41
79
`role` | *static* | optional | If the toggling element is not a `<button>` element, but looks and behaves like a button (see documentation for the [Button Element](/buttons)), then setting the `role` attribute to "button" is recommended. See [MDN documentation for the "button" role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) for more information
`role` | *static* | optional | Setting the target element's `role` to "region" identifies the target as a significant area. See [MDN documentation for the "region" role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Region_role) for more information.
49
87
`aria-labelledby` | *static* | optional | This is used along with the `role` attribute to label the content of a "region." This can be set to the toggling elements `id` but can also be set to a different elements `id`.
`tabindex` | *dynamic* | recommended | Setting the toggle target's focusable children's `tabindex` attribute to "-1" will prevent them from being focused on when the parent is hidden. See the list below of potentially focusable elements that are supported.
94
+
`data-toggle-tabindex` | *static* | optional | If an child element has a `tabindex` that needs to be set when the parent target is visible then the default value can be stored in this data attribute.
95
+
96
+
**Potentially Focusable Elements**
97
+
98
+
a, button, input, select, textarea, object, embed, form,
`selector` | *string* | optional | Full selector string of the toggle element (this is passed to the `.matches()` method).
58
109
`inactiveClass` | *string/boolean* | optional | Single class name that will be toggled on the toggle and target element when the element is inactive or "collapsed." Pass "false" to skip toggling an inactive class (there is no inactive class for the toggle element).
59
110
`activeClass` | *string/boolean* | optional | Single class name that will be toggled on the target element when the element is active or "expanded." Pass "false" to skip toggling an active class.
60
-
`before` | *function* | optional | A function that will be executed before the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class.
61
-
`after` | *function* | optional | A function that will be executed after the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class.
111
+
`before` | *function* | optional | A function that will be executed before the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class with several values that may be useful in the callback such as the settings, toggle element, toggle target, and initial click event.
112
+
`after` | *function* | optional | A function that will be executed after the toggling element and target classes and attributes are toggled. The function is passed the instance of the toggle class with several values that may be useful in the callback such as the settings, toggle element, toggle target, and initial click event.
0 commit comments