Skip to main content

Patterns

Toggle

The Toggle utility uses JavaScript to expand and collapse elements based on user interaction. This will toggle dynamic aria attributes as well as dynamic classes on both the toggling element and target of the toggle. The class "hidden" will be toggled on the target element and the class "active" will be toggled on the toggling element and target element. The target is selected using the static aria-controls attribute by its id.

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 and aria-pressed would be used for toggle buttons or switches. A full list of dynamic and static attributes is described in the the usage section.

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 (the "Menu" and "Close Menu" links of this site are an example).

Targeted toggle element
<button aria-controls="toggle-target" aria-expanded="true" class="btn btn-primary mb-3" data-js="toggle" type="button">Toggle</button>
<div aria-hidden="false" class="bg-color-blue-light p-4 text-center active" id="toggle-target">Targeted toggle element</div>

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.

Toggle and Jump to Target
<a class="inline-block mb-3" data-js="toggle" href="#anchor-target">Toggle and Jump to Target</a>
<section aria-hidden="true" class="bg-color-blue-light p-4 hidden text-center" id="anchor-target">Targeted toggle element</section>

Adding hidden:fadeInUp animated to the target element will animate the opacity and position target element.

<button aria-controls="toggle-target-fade-in-up" aria-expanded="false" class="btn btn-primary mb-3" data-js="toggle" type="button">Fade In Up</button>
<div aria-hidden="true" class="bg-color-blue-light p-4 text-center hidden hidden:fadeInUp animated" id="toggle-target-fade-in-up">Targeted toggle element</div>

Adding hidden:overflow animated to the target element will animate the max-height property of the target element.

<button aria-controls="toggle-target-overflow" aria-expanded="false" class="btn btn-primary mb-3" data-js="toggle" type="button">Overflow</button>
<div aria-hidden="true" class="bg-color-blue-light w-full text-center hidden hidden:overflow animated" id="toggle-target-overflow">
  <div class="p-4">Targeted toggle element</div>
</div>

This is a combination of the "overflow" and "fade in up" animations. Adding 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.

<button aria-controls="toggle-target-overflow-fade-in-up" aria-expanded="false" class="btn btn-primary mb-3" data-js="toggle" type="button">Overflow Fade In Up</button>
<div aria-hidden="true" class="bg-color-blue-light w-full text-center hidden hidden:overflowFadeInUp animated" id="toggle-target-overflow-fade-in-up">
  <div class="p-4 animated">Targeted toggle element</div>
</div>

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 Element 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.

Global Script

To use the Toggle Utility in the global ACCESS NYC Patterns script use the following code:

<!-- Global Script -->
<script src="dist/scripts/AccessNyc.js"></script>

<script>
  var access = new AccessNyc();
  var toggle = access.toggle();
</script>

This function will instantiate the Toggle Utility (with provided options) and attach the event listener to the body of the document. The event will listen for clicks on elements with the matching selector [data-js='toggle'] (see markup details in the examples above). Below is an advanced configuration that passes a custom selector to the instantiated method (see the next section for all of the configuration options):

var toggle = access.toggle({
  selector: '#my-selector'
});

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.

Cherry-picked Module Import

The ES6, CommonJS, and IFFE modules all require importing and object instantiation in your main script. The methods and configurations described above will work with the dedicated module.

// ES6
import Toggle from '@nycopportunity/patterns-framework/src/utilities/toggle/toggle';

// CommonJS
let Toggle = require('@nycopportunity/patterns-framework/dist/utilities/toggle/toggle.common');

<!-- IFFE -->
<script src="@nycopportunity/patterns-framework/dist/utilities/toggle/toggle.iffe.js"></script>

new Toggle();

Note: The Icon Utility source and distribution scripts in the ACCESS NYC Patterns has been deprecated and moved to the NYCO Patterns Framework. Install the @nycopportunity/patterns-framework module to use this script.

Polyfills

The script uses the Element.prototype.matches, Element.prototype.removes, Nodelist.prototype.forEach methods which require polyfills for IE11 support. See the "Polyfills" section in the Installation docs for recommendations.