- Skip to main content
- Skip to "About this site"

# Toggle

- Documentation
- Questions or comments?

## Purpose

Create an element that toggles elements between on and off states.

Plugin Setup Simple Example Details Elements Grouped Toggle Accordion Persist Toggle State

## Plugin Setup

Adding the `.wb-toggle` CSS class to any element will turn it into a toggle element. The behaviour of this toggle element is then controlled by the `data-toggle` attribute which takes a JavaScript object of properties:

Property | Purpose
--- | ---
`selector` | CSS selector that specifies the elements the toggle element controls. If no CSS selector is supplied, the toggle element controls itself.
`parent` | CSS selector that causes the toggle element to only control elements within a given parent element.
`group` | CSS selector that groups multiple toggle elements together and only allows one of the elements to be open at a time.
`persist` | Causes a toggle element to remember its current state and re-apply it when the page reloads. Supports the following values: 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. Supports the following values: 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. Supports the following values: on: toggle element will only turn elements to the "on" toggle state. off: toggle element will only turn elements to the "off" toggle state.
`state` (v4.0.11+) | Sets the initial state of a toggle element. Supports the following values: off (default): Toggle element initial state is "off" on: Toggle element initial state is "on"
`stateOn` | CSS class that's added to elements when they are toggled on. Defaults to "on".
`stateOff` | CSS class that's added to elements when they are toggled off. Defaults to "off".

For example, the following element will always toggle on elements with the `.foo` CSS class that are contained in a parent with the `.bar` CSS class. In addition, the elements it controls will be toggled on when the page is printed.

    <button type="button" class="wb-toggle" data-toggle='{"type": "on", "selector": ".foo", "parent": ".bar", "print": "on"}'>Turn on</button>

## Simple Example

This simple example shows:

- a group of buttons that control the toggle state of multiple elements, and
- a single element that controls its own toggle state (the last box).

## Details Elements

The toggle plugin can be used to open/close multiple `<details>` elements. By adding the `"print": "on"` setting to the first toggle element, the plugin will also open all details elements when the page is printed.

Note: this example uses the `parent` configuration option to restrict the toggle of details elements to those that are contained in a specified parent element (`#details-element`). By doing this, the grouped toggle and accordion examples below aren't affected by the toggle.

Example 1

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 2

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 3

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

## Grouped Toggle

This parameter restricts grouped toggles to only have one of the elements active at a time much like the grouped checkbox behaviour.

Example 1

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 2

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 3

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

## Accordion

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

### Example

Example 1

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 2

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Example 3

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

### Setup

- Wrap all sections of the accordion in parent element with a unique CSS class or ID. `<div class="accordion">`
- 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 you're using details elements for the accordion sections, the HTML should look like the following once you're 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>

## Persist Toggle State

The following `details` element will remember its toggle state as long as this browser window (or tab) remains open.

Example 1

Example content that provides more details.

Cups of coffee consumed by each delegate
Name | Cups | Type of Coffee | Sugar?
--- | --- | --- | ---
T. Sexton | 10 | Espresso | No
J. Dinnen | 5 | Decaf | Yes

Date modified:
  2015-04-22