Use Toggle Button

<jangle-toggle-button> switches one persistent boolean action on or off. Keep the visible label unchanged between states: “Bold” stays “Bold” when selected. Use Button for a momentary command, and a form control when the value must participate in form submission.

Add a toggle

Configure package access, then load the theme and registration:

import '@jangle-ui/tokens/tokens.css';
import '@jangle-ui/components/toggle-button/register';

<jangle-toggle-button id="bold" icon="bold">Bold</jangle-toggle-button>
<p id="preview">Make room for a better idea.</p>

const toggle = document.querySelector('#bold');
const preview = document.querySelector('#preview');

toggle.addEventListener('jangle-toggle-change', (event) => {
  preview.style.fontWeight = event.detail.pressed
    ? 'var(--jangle-typography-font-weight-strong)'
    : 'var(--jangle-typography-font-weight-normal)';
});

The component toggles its own pressed state after an uncanceled native click and reports { pressed: boolean } after the new state renders. The event bubbles and crosses shadow boundaries. Use this event for application effects; the native click occurs before the state commits. Cancel the original click with preventDefault() to prevent the toggle. Setting toggle.pressed from application state updates the control silently without emitting another change event.

Appearance and availability

The default is medium, unpressed, with theme-controlled corners. Off uses neutral-subtle; on uses brand-subtle with a persistent inset border. This component has one selection recipe, not separate intent, treatment, or tone choices. size="sm|md|lg" chooses the complete 32, 40, or 48px minimum-height recipe. Long labels wrap and grow the target. An optional icon is decorative. Text mode requires visible text; mixed state is not supported.

For a familiar icon-only action, set icon-only and provide both an icon and a stable localized accessible label:

<jangle-toggle-button icon-only icon="volume-x" label="Mute" size="sm"></jangle-toggle-button>

The label is an accessible name, not a tooltip. Icon-only mode uses square 24, 32, 40, or 48px targets for xs, sm, md, or lg; radius="full" makes them circular. Use larger targets for touch-heavy interfaces. It has the same pressed state and change event as text mode. Do not provide slot content in icon-only mode. A text-mode size="xs" request normalizes the property and attribute to md and emits a diagnostic. Set icon-only and size="xs" together when switching to an extra-small icon control.

radius="none" removes rounding; full retains pill corners under every shape profile. default uses --jangle-toggle-button-radius when configured, otherwise the theme's medium radius. Use context="inverse" only on an application-owned inverse surface.

disabled makes activation unavailable, removes the native control from Tab order, and retains its pressed state. Disabled fieldsets are respected. Toggle Button never submits a value or resets its state with a form. Applications own persistence, operation outcomes, and any subsequent focus movement. Enter and Space activate the native control; its stable name and aria-pressed expose the state without an extra live announcement.

Independent toggles can sit in Button Group, but that does not create exclusive selection or a toolbar. See Toggle Button in Storybook for the working example and complete API.