Toggle pattern

Toggle

The toggle pattern wires ARIA and visibility state for show/hide interactions. It powers every other context, so getting comfortable with toggle unlocks the entire toolkit. The Contexts guide shows how dialog, tooltip, and upcoming composites layer additional semantics on top of this foundation.

Behavior highlights

• Adds aria-expanded and aria-controls to triggers.
• Generates IDs when missing and links targets with aria-labelledby.
• Hides targets by default and removes hidden when opened.
• Emits lifecycle events (automagica11y:ready, automagica11y:toggle, automagica11y:toggle:opened, automagica11y:toggle:closed).
• Normalizes truthiness so active, open, true, and on all map to the open state.

Attribute reference

Attribute reference

Attribute	Type	Allowed values	Default	Description
data-automagica11y-toggle	string | Selector	CSS selector, typically an #id	None	Identifies the target surface to show or hide.
data-automagica11y-trigger-class-[state]	string | string[]	Any truthiness token (open, expanded, active, shown, true, on...)	automagic-toggle-open / automagic-toggle-closed	Maps classes onto the trigger for truthy/falsy states.
data-automagica11y-target-class-[state]	string | string[]	Any truthiness token	None	Applies classes to the target element during each state.
data-automagica11y-animate	`target` | `trigger` | Selector	`target`, `trigger`, or any CSS selector	`target`	Opt into the built-in animate lifecycle so close transitions wait for CSS to finish.

Keyboard support

• Space/Enter toggle the target for non-button triggers (buttons work out of the box).
• Focus stays on the trigger when toggling so keyboard users keep context.
• Non-button triggers receive role="button" and tabindex="0" automatically.

Events

Event	Detail payload
automagica11y:ready	{ trigger, target, targets } once initialization completes.
automagica11y:toggle	{ trigger, target, targets, expanded } on every state change.
automagica11y:toggle:opened	{ trigger, target, targets } after an open transition completes.
automagica11y:toggle:closed	{ trigger, target, targets } after a close transition completes.

Demo

Toggle playground

Truthiness-aware classes and lifecycle events.

View source

Toggle content

Inspect events

Open your devtools console and listen for automagica11y:toggle to react to each state change.

Coverage plan

1. Add a live demo combining toggle with data-automagica11y-context="menu" once menu semantics ship.
2. Document how grouped toggles (data-automagica11y-group) coordinate state across triggers.
3. Provide recipes showing how the animate lifecycle and announce plugin extend toggle events.

Track plan progress in Core modules and the Examples roadmap.