Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
data-toggle
Click-to-flip-attribute upscale. Toggles a boolean attribute, ARIA two-state value, custom on/off value, or CSS class on a target — the catch-all for the recurring 'change state' pattern that doesn't have a native primitive.
Overview
The data-toggle attribute upscales a <button> with click-to-flip-attribute behavior. Three modes are auto-detected from the spec, plus a class:name shorthand. aria-controls and aria-pressed / aria-expanded are wired automatically where it makes sense.
Three modes (auto-detected)
1. Boolean attributes
Standard boolean HTML attrs (hidden, disabled, open, checked, readonly, …). Toggles attribute presence: absent ↔ present.
HTML
<button data-toggle="hidden" data-toggle-target="#sidebar">Toggle sidebar</button><aside id="sidebar">...</aside>2. ARIA two-state
aria-pressed, aria-expanded, aria-selected, aria-checked always carry the string "true" or "false". Toggle flips between them.
HTML
<button data-toggle="aria-pressed">🔇 Mute</button>With no data-toggle-target, the button toggles the attribute on itself.
3. Custom on/off cycle
Anything else — typically data-state — cycles between two values supplied via data-toggle-on and data-toggle-off. Defaults to "true" / "false".
HTML
<button data-toggle="data-state" data-toggle-target="#tray" data-toggle-on="open" data-toggle-off="closed"> Toggle tray</button><div id="tray" data-state="closed">...</div>4. Class shorthand
Prefix the spec with class: to toggle a CSS class instead of an attribute.
HTML
<button data-toggle="class:expanded" data-toggle-target="#card">Toggle</button><article id="card">...</article>Attributes
| Attribute | Default | Notes |
|---|---|---|
data-toggle | — | Attribute name to flip, OR class:name. |
data-toggle-target | self | CSS selector for the target. Omit for self-toggling. |
data-toggle-on | "true" | "On" value for custom mode. Set to "open" to enable aria-expanded auto-wiring. |
data-toggle-off | "false" | "Off" value for custom mode. |
Events
The button emits toggle:change after each click.
JS
btn.addEventListener('toggle:change', (e) => { const { spec, value, present, target } = e.detail; // spec: "hidden" | "data-state" | "class:expanded" | ... // present: true if attr/class is now applied // value: the new attribute value (for non-boolean / non-class modes)});Accessibility
- aria-controls — set on the button to the target's id when the target is external (not self).
- aria-pressed — reflected on the button when self-toggling a boolean attribute (e.g. a "Mute" toggle).
- aria-expanded — reflected on the button when the target has
[popover], OR whendata-toggle-on="open"is set on adata-statetoggle (a common disclosure pattern). - Native button — keyboard activation (Enter / Space) just works.
When to reach for native instead
Several other primitives cover overlapping shapes — pick the one closest to your use case:
| If you want to… | Use |
|---|---|
| Open a popover | Native popovertarget (no JS needed) |
| Invoke a registered command (close, open, …) on a target | Native commandfor (WICG; works with <dialog>, [popover], custom-defined commands). VB wires this via data-command. |
| Show / hide based on a form-field value | data-show-when / data-hide-when |
| Toggle a checkbox styled as a switch | data-switch on <input type="checkbox"> |
| Reveal masked content | data-spoiler |
Animate a <details> | data-accordion |
| Anything else — flip arbitrary attribute / class on a target | This attribute. |