Skip to main content
WireKit
Copy for LLM

Toggle Button

A button that stays pressed: bold, italic, mute, pin. One control, two states, aria-pressed doing the talking.

WireKit has three two-state controls and they are not interchangeable:

Use Component
A form setting the user saves ("Email notifications: on") Toggle — a role="switch" with a label
Pick one of several options Segmented Control
A single control that stays pressed Toggle Button

Basic Usage

Click to toggle 
<x-wirekit::row gap="sm" align="center">
    <x-wirekit::toggle-button :pressed="true" self-toggle>Bold</x-wirekit::toggle-button>
    <x-wirekit::toggle-button :pressed="false" self-toggle>Italic</x-wirekit::toggle-button>
</x-wirekit::row>

Click either button: it flips between pressed and unpressed. The pressed state is carried by the surface — filled when pressed, outline when not — so it survives a monochrome or high-contrast rendering. It never depends on a tint alone.

These demos use self-toggle, which lets the button manage its own state so it works with no wiring. In a real app you usually want the controlled form below instead, where the pressed state lives in your component.

In a toolbar

Toggle buttons are what a formatting bar is made of.

A formatting cluster 
<x-wirekit::row gap="sm" align="center">
    <x-wirekit::toggle-button :pressed="true" self-toggle aria-label="Bold">B</x-wirekit::toggle-button>
    <x-wirekit::toggle-button :pressed="false" self-toggle aria-label="Italic">I</x-wirekit::toggle-button>
    <x-wirekit::toggle-button :pressed="false" self-toggle aria-label="Underline">U</x-wirekit::toggle-button>
</x-wirekit::row>

Livewire

The component is controlled: the pressed state lives in your component, not in the button. That is deliberate — the truth about "is this text bold" belongs to the document.

{{-- 1. Bind the state, handle the click — no local JS state to drift --}}
<x-wirekit::toggle-button :pressed="$bold" wire:click="$toggle('bold')" aria-label="Bold">
    B
</x-wirekit::toggle-button>

// 2. One property is the whole state
public bool $bold = false;

Props

Prop Type Default Description
pressed bool false The two-state truth; drives aria-pressed and the surface. Also the initial state in self-toggle mode
selfToggle bool false Let the button flip its own state on click, with no wiring (attribute: self-toggle). Handy for a standalone toolbar; leave it off for the controlled Livewire form above
size string 'md' Forwarded to the underlying button
scope string|null null Scoped personalization name

Everything else — wire:click, aria-label, disabled, classes — passes through to the underlying Button.

Accessibility

  • The control is a real <button type="button"> with aria-pressed — the WAI-ARIA toggle-button pattern. Assistive technology announces "pressed" / "not pressed" without any extra wiring.
  • Never color-only: pressed switches the surface (filled vs outline), so the state is visible in monochrome and high contrast too (WCAG 1.4.1).
  • An icon-only toggle needs its own aria-label — a glyph is not a name.
  • It composes Button, so the focus ring, disabled model and sizes are the same ones used everywhere else.

Keyboard Interaction

Key Action
Tab Focus the button
Enter / Space Toggle the pressed state

Pitfalls

  • Do not use it for a saved setting. That is Toggle, which is a labeled form switch.
  • Do not use it for one-of-many. That is Segmented Control.
  • Do not leave an icon-only toggle unnamed.

Design Tokens

The pressed and unpressed surfaces come from Button's filled and outline surfaces on the neutral intent — so a theme change restyles it with everything else.

Further Reading