Easy
Toggle
State

Basis: defining a trigger

Attribute: data-toggle-class

<button data-toggle-class>…</button>

Here is the basic usage: Adding this attribute on a button will make it toggle the CSS class is-active on it on click. It becomes a trigger.

<button data-toggle-class="is-selected">…</button>

You can specify a class name of your own that you want to toggle instead: Here, by clicking on this trigger, the class is-selected will be toggled on it on click.

<button data-toggle-class="class1 class2 class3">…</button>

You can go further into toggling by filling the attribute with as many classes as you need: Here, a click on the trigger will toggle each class on it.

Toggling only on trigger

Attribute: data-toggle-on-trigger

<button data-toggle-class-on-trigger="class1 class2 class3">…</button>

Since you are able to specify a target, you may want to toggle some classes only on the trigger. Here, each of those three classes will be toggled only on this trigger.

Toggling with a target

You may want to add a target to your trigger.

<button data-toggle-class="class" data-toggle-target="selector">…</button>

This way, the class specified in the attribute data-toggle-class will be toggle on this trigger and on its target, defined by the selector.

Toggling only on target

Attribute: data-toggle-on-target

<button data-toggle-class-on-target="class1 class2 class3" data-toggle-target="selector">…</button>

You may want to toggle some classes only on the target. Here, each of those three classes will be toggled only on this target.

Note that this attribute must be used with one of the targeting attributes.

Toggling combinations

You can combine all toggling attributes, making Easy Toggle State compatible with any CSS framwork.

<button
	data-toggle-class="is-open"
	data-toggle-class-on-trigger="text-white font-bold bg-blue"
	data-toggle-class-on-target="text-gray bg-white"
	data-toggle-target="#plop">
	…
</button>

Here, with this combination, a click on this trigger will toggle:

• the classes is-open, text-white, font-bold, bg-blue on this trigger
• the classes is-open, text-gray, bg-white on the target, the element #plop

Basis: defining a target

Attribute: data-toggle-target

<button data-toggle-class="class" data-toggle-target="selector">…</button>

This is the basics in targeting: the attribute data-toggle-target tells this trigger to look in the whole page for one or several elements to target matching the selector.

This way, a click on the trigger will toggle the class on the trigger itself and on its one or several targets.

The selector value must be a valid CSS selector string, containing one or more selectors to match. Learn more about CSS selectors.

Targeting from the parent

Attribute: data-toggle-target-parent

<button data-toggle-class="class" data-toggle-target-parent="selector">…</button>

Instead of looking in the whole page, you can search for one or several targets matching the selector only inside the trigger’s parent container.

Targeting within the trigger

Attribute: data-toggle-target-self

<button data-toggle-class="class" data-toggle-target-self="selector">…</button>

Instead of looking in the whole page, you can search for one or several targets matching the selector only inside the trigger itself.

See an example with this checkbox.

Targeting the previous sibling element

Attribute: data-toggle-target-previous

<button data-toggle-class="class" data-toggle-target-previous>…</button>

You can target the previous direct sibling element by using data-toggle-target-previous attribute.

Targeting the next sibling element

Attribute: data-toggle-target-next

<button data-toggle-class="class" data-toggle-target-next>…</button>

You can target the next direct sibling element by using data-toggle-target-next attribute.

Active by default

Attribute: data-toggle-is-active

<button data-toggle-class="class" data-toggle-is-active>…</button>

Specify a trigger element and its targets to be active by default. As a consequence, they will be toggled once on initialization.

See an example with tabs.

Grouping triggers

Attribute: data-toggle-group

<button data-toggle-class="class" data-toggle-group="name">…</button>
<button data-toggle-class="class" data-toggle-group="name">…</button>

Specify that a trigger is a part of a group, defined by a name. Only one trigger of a group can be active at a time. Of course, it must be used on at least two triggers to create a group.

They will actually behave like an accordion component.

Attribute: data-toggle-radio-group

<button data-toggle-class="class" data-toggle-radio-group="name">…</button>
<button data-toggle-class="class" data-toggle-radio-group="name">…</button>

Specify that they are a part of a radio group, defined by a name. Only one trigger of a radio group can be active at a time. Of course, it must be used on at least two triggers to create a group.

Unlike a simple group as seen above, as soon as a trigger of a radio group has been activated, this radio group will always keep one trigger active. It will actually behave like radio buttons or tabs component.

Note that a trigger of a radio grouped can’t have data-toggle-outside^[?] or data-toggle-escape^[?] behavior.

Toggle on another event

Attribute: data-toggle-event

<button data-toggle-class="class" data-toggle-event="event">…</button>

Specify another event to toggle the trigger instead of the click event used by default. For example, mouseover.

See an example with a tooltip.

Toggle off when outside

Attribute: data-toggle-outside

<button data-toggle-class="class" data-toggle-outside>…</button>

When a trigger is active, specify to toggle off this trigger when you click again outside of it. If you use the data-toggle-event^[?] attribute too on the trigger, the event used is the same.

Note that this attribute does not work on an element with data-toggle-radio-group^[?].

See an example with a dropdown.

Attribute: data-toggle-outside-event

<button
		data-toggle-class="class"
		data-toggle-outside
		data-toggle-outside-event="event">
		…
</button>

When using data-toggle-outside^[?] attribute, add this attribute to use a different event to toggle off outside of the trigger.

Note that this attribute only works when used in addition of data-toggle-outside^[?] attribute.

See an example with a tooltip.

Keyboard support

Attribute: data-toggle-escape

<button data-toggle-class="class" data-toggle-escape>…</button>

Specify that you can press the escape key to toggle off the trigger when it is already active.

Note that this attribute does not work on an element with data-toggle-radio-group^[?].

See an example with a collapsible panel.

Attribute: data-toggle-arrows

<button data-toggle-class="class" data-toggle-arrows data-toggle-group="name">…</button>
<button data-toggle-class="class" data-toggle-arrows data-toggle-group="name">…</button>

Used with a group attribute, specify that as soon as a trigger is focused, you can navigate through the triggers of the same group with arrows ↑ → ↓ ←, home and end keys.

Remember that this attribute must be used with data-toggle-group^[?] or data-toggle-radio-group^[?].

See an example with radio buttons.

Targeting a modal

Attribute: data-toggle-modal

<button data-toggle-class="class" data-toggle-modal>…</button>

Specify that the target is a modal, such as a dialog or a lightbox. This way, when the target is active (open), the focus is trapped inside this target until you close it. This means tabbing will only focus on focusable elements inside this target, leaving anything else outside be out of scope.

Be very careful when using this feature. A focus trap can be very annoying (and an accessibility fault) when used in a wrong way, so be sure your target is a modal component.

Closing button

Attribute: data-toggle-trigger-off

<button data-toggle-class="class" data-toggle-target="#plop">…</button>

<div id="plop">
	<button data-toggle-trigger-off="#plop">…</button>
</div>

This attribute is meant to be used on an element inside a target. By doing so, it enables this element to toggle the related trigger back off when it is active. For example, a close button inside a dialog or a lightbox.

Fill this attribute with a CSS selector matching that target element.

Remember that this attribute must be used on an element placed inside a target element.

API using the bundle (locally or from CDN)

window.easyToggleState();

window.easyToggleState.unbind( Node || NodeList );

window.easyToggleState.unbindAll();

window.easyToggleState.isActive( Node );

API using ES modules

import initialize from "easy-toggle-state";
initialize();

import { unbind } from "easy-toggle-state";
unbind( Node || NodeList );

import { unbindAll } from "easy-toggle-state";
unbindAll();

import { isActive } from "easy-toggle-state";
isActive( Node );

Hooks

You can also add some hooks: each trigger and target element fires a toggleBefore event before and a toggleAfter event after toggling its state, so you can add event listeners on these events, and test the active state.

For example:

document.querySelector("#myTrigger").addEventListener("toggleAfter", event => {
	console.log(`Active: ${window.easyToggleState.isActive(event.target)}`);
}, false);