Toggle

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

Questions or comments?

Purpose

Allows an element to toggle elements between on and off states. The element that is toggled records its current state using a ".on" or ".off" CSS class. The accordion option implements the WAI-ARIA accordion design pattern.

Use when

Do not use when

Working example

English example

French example

How to implement

Toggle self

This is the most basic use of the plugin. It allows an element to toggle itself on and off when clicked.

  1. Add the wb-toggle CSS class to an element.
<button type="button" class="wb-toggle">Toggle</button>

Toggle other elements

A toggle element can be setup to control the on/off toggle state of other elements. Any elements that match the CSS selector specified by the data-toggle attribute will have their on/off state changed when the toggle element is clicked.

  1. Add the wb-toggle CSS class to the toggle element.
  2. Using the data-toggle attribute, specify the CSS selector of the elements that will have their states toggled.
<button type="button" class="wb-toggle" data-toggle="{'selector': '.otherElements'}">Toggle</button>

Toggle configuration

This example expands on Toggle other elements by using the plugin's configuration options.

  1. Add the wb-toggle CSS class to the toggle element.
  2. Using the data-toggle data attribute, specify
    • the CSS selector of the elements that will have their states toggled,
    • the CSS selector of the parent these elements must exist in,
    • that toggle is "on" only,
    • that elements should be toggled "on" when the page is printed, and
    • that the toggle state should be saved between page loads using sessionStorage.
<button type="button" class="wb-toggle" data-toggle="{
	'selector': '.otherElements',
	'parent': '#parentElement',
	'type': 'on',
	'print': 'on',
	'persist': 'session'}">Toggle</button>

Grouped Toggle

This option causes a group of elements to only allow one of the elements to be active ("on") at a time, much like a tabbed interface.

  1. Add the wb-toggle CSS class to the toggle elements.
  2. Using the data-toggle attribute, specify the element(s) the toggle element will control, and the group CSS selector.

The following shows a completed example for button elements that toggle open details elements:

<button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle1", "group": ".grouped", "type": "on"}'>Example 1</button>
<button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle2", "group": ".grouped", "type": "on"}'>Example 2</button>

<details id="toggle1" class="grouped">
	<!-- content -->
</details>
<details id="toggle2" class="grouped">
	<!-- content -->
</details>

Accordion

The group toggle feature of the plugin can also be used to create an accordion.

  1. Wrap all sections of the accordion in parent element with a unique CSS class or ID. <div class="accordion">
  2. For each accordion section:
    • Add the wb-toggle class and data-toggle attribute to the element the user will click to open/close the section.
    • Add the tgl-tab class to the element that shows the section's heading.
    • Wrap the content in a <div class="tgl-panel"> element.

If details elements are used for the accordion sections, the HTML should look like the following once finished:

<div class="accordion">

   <!-- Accordion section 1 -->
   <details class="acc-group">
      <summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Section 1's heading</summary>
      <div class="tgl-panel">
         <!-- Section 1's content -->
      </div>
   </details>

   <!-- Accordion section 2 -->
   <details class="acc-group">
      <summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Section 2's heading</summary>
      <div class="tgl-panel">
         <!-- Section 2's content -->
      </div>
   </details>

</div>

Configuration options

All configuration options of the plugin are controlled by the data-toggle attribute:

Option Description How to configure Values
selector CSS selector that specifies the elements the toggle element controls. If no CSS selector is supplied, the toggle element controls itself. Specify the CSS selector. All elements to be toggled should match this selector.[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'selector': '.cssSelector'}">
None (default):
Toggle element toggles itself.
String:
CSS selector. All elements that match this selector will be toggled when the toggle element is clicked.
parent CSS selector that causes the toggle element to only control elements within a given parent element. Specify the CSS selector. When a toggle element is clicked, it will only toggle elements that are children of this selector.[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'parent': '.parentCssSelector'}">
None (default):
No parent element restriction.
String:
CSS selector. When a toggle element is clicked, it will only toggle the elements that are children of this selector.
group CSS selector that groups multiple toggle elements together and only allows one of the elements to be open at a time. Specify the CSS group selector. All elements to be toggled should match this selector.[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'group': '.groupCssSelector'}">
None (default):
No grouping behaviour.
String:
CSS selector. When a toggle element is clicked, all other elements that match this selector will be closed.
persist Causes a toggle element to remember its current state and re-apply it when the page reloads. Supports persistence. Only "session" and "local" are supported:[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'persist': 'session'}">
None (default):
Element will not change state for printing.
"session":
Toggle state will persist until the user closes their browser window or tab.
"local":
Toggle state will persist even after the browser window or tab is closed.
print Causes a toggle element to turn the elements it controls on or off when the page is printed. Specify the print behaviour. Only "on" or "off" are supported:[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'print': 'on'}">
None (default):
Element will not change state for printing.
"on":
Elements will be set to "on" toggle state for printing.
"off":
Elements will be set to "off" toggle state for printing.
type Causes a toggle element to only turn the elements it controls on or off. Specify the type. Only "on" or "off" are supported:[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'type': 'on'}">
None (default):
Toggle element will alternate back and forth between states (on and off)
"on":
Toggle element will only turn elements it controls on.
"off":
Toggle element will only turn elements it controls off.
stateOn CSS class that's added to elements when they are toggled on. Specify a CSS class name without the leading "."[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'stateOn': 'cssClass'}">
None (default):
Defaults to "on"
String:
CSS class name
stateOff CSS class that's added to elements when they are toggled off. Specify a CSS class name without the leading "."[{htmlmin-lb}]
<span class="wb-toggle" data-toggle="{'stateOff': 'cssClass'}">
None (default):
Defaults to "off"
String:
CSS class name

Events

Document the public events that can be used by implementers or developers.

Event Trigger What it does
wb-init.wb-toggle Triggered manually (e.g., $( ".wb-toggle" ).trigger( "wb-init.wb-toggle" );). Used to manually initialize the Toggle plugin. Note: the toggle plugin will be initialized automatically unless the element is added after the page has already loaded.
wb-ready.wb-toggle (v4.0.5+) Triggered automatically after a toggle initializes. Used to identify which toggle was initialized (target of the event) 
$( document ).on( "wb-ready.wb-toggle", ".wb-toggle", function( event ) {
});
$( ".wb-toggle" ).on( "wb-ready.wb-toggle", function( event ) {
});
toggle.wb-toggle Triggered manually and automatically by plugin (e.g., $( ".wb-toggle" ).trigger( "toggle.wb-toggle" );). Causes a toggle element to change the toggle state of the elements it controls. Normally triggered by clicking on the toggle element. When triggering this event manually, the data-toggle attribute must be passed as the second argument:[{htmlmin-lb}]
// Get a reference to the toggle element and its settings
var $toggler = $( ".wb-toggle" );
    settings = $toggler.data( "toggle" );

// Trigger the toggle event
$toggler.trigger( "toggle.wb-toggle", settings );
wb-ready.wb (v4.0.5+) Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing. 
$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

Toggle plugin source code on GitHub.

Date modified: