Toggle
Demonstration
This region is the target element. This link is a potentially focusable element.
Code
The Toggle utility shows or hides targeted regions based on user interaction. Dynamic ARIA attributes and classes on both the toggling element and target of the toggle are used to provide screen reader support.
For button toggling elements, the aria-controls attribute is used to find the target region by its ID. For a elements, the href attribute is used to find the target region by its ID.
The class hidden will be added to the target region when it is hidden. The class active will be added to both the toggling element and target region when the element is visible.
Potentially focusable elements in the target region will have their tabindex toggled to allow or prevent them from receiving focus. If the target region is hidden before the page loads, the tabindex for these elements need to be set to -1. Elements that can be selected by the following strings will have their tabindex toggled.
'a', 'button', 'input', 'select', 'textarea', 'object', 'embed', 'form', 'fieldset', 'legend', 'label', 'area', 'audio', 'video', 'iframe', 'svg', 'details', 'table', '[tabindex]', '[contenteditable]', '[usemap]'
The use of the aria-expanded attribute on the toggling element is recommended to announce the visibility of the target region. 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 and aria-pressed would be used for toggle buttons or switches.
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.
The Toggle utility supports having more than one toggle element per toggle target.
Demonstration
Code
The anchor toggle uses an anchor in the href to jump to the target element. While anchor toggles are an appropriate use case for target elements that are further away from the toggling element, it should be used sparingly as anchor links can make the navigation of content more difficult. Always use descriptive text in the link such as “Jump to” to describe what the behavior of the link will be.
Anchor target regions will have their tabindex attribute set to -1 to shift focus from the toggle element to the target element.
Demonstration
Code
Adding the class hidden:fadeInUp animated to the target element will animate the opacity and position target element.
The animation will be disabled by devices using the prefers-reduced-motion
@media query.
Demonstration
Code
Adding the class hidden:overflow animated to the target element will animate the max-height property of the target element.
The animation will be disabled by devices using the prefers-reduced-motion
@media query.
Demonstration
Code
This is a combination of the “overflow” and “fade in up” animations. Adding the class hidden:overflowFadeInUp will animate the max-height property of the parent element. Adding animated to any immediate (.parent > .child) children of the parent will animate the opacity property fo the child.
The animation will be disabled by devices using the prefers-reduced-motion
@media query.
Global Script
The Toggle toggle requires JavaScript for functionality. It uses the Patterns Scripts, Toggle Utility to properly set ARIA and Class attributes on the toggle and target elements. To use the Toggle through the global script use the following code:
<script src="@nycopportunity/standard/dist/js/default.js"></script> <script> var Standard = new Default(); Standard.toggle(); </script>
This will instantiate the Theme toggling element and attach event listeners to the body. It optionally accepts an object with settings for the Patterns Scripts, Toggle Utility, described below.
Module Import
The Toggle Utility source exists in the Patterns Scripts utility library, which is a dependency of this library. This method allows the specification of each theme object and a callback function that will be triggered after the theme is toggled.
import Toggle from '@nycopportunity/pttrn-scripts/src/toggle/toggle'; new Toggle();
The Toggle instance optionally accepts an object with settings described below and in the Patterns Scripts, Toggle Utility documentation.
Attributes
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.
Toggling Element Attributes
| Attribute | State | Importance | Description |
|---|---|---|---|
aria-controls
|
static | required | ID of the target element. Used by the toggle to select the target element. |
aria-expanded
|
dynamic | recommended | Boolean that announces that target content is “expanded” or “collapsed” when the toggling element is clicked. |
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. |
aria-pressed
|
dynamic | optional | Boolean that announces that the toggling element is toggled. Not recommended for use with aria-expanded. |
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), then setting the role attribute to “button” is recommended. See MDN documentation for the “button” role for more information |
Target Region Attributes
| Attribute | State | Importance | Description |
|---|---|---|---|
aria-hidden
|
dynamic | recommended | Boolean that hides the content of the target element when “collapsed.” |
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 for more information. |
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. |
Configuration
The Toggle Utility accepts an object {} with the following properties:
| Option | Type | Importance | Description |
|---|---|---|---|
selector
|
string | optional | Full selector string of the toggle element (this is passed to the .matches() method). |
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). |
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. |
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. |
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. |