---
title: ToggleButton
description: Toggle a persistent state with independently configured off and on
  button variants.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# ToggleButton

> Toggle a persistent state with independently configured off and on button variants.

## Anatomy

```text
ToggleButton [component; slot=root; <button>]
├── leading [slot]
├── label [slot]
└── trailing [slot]
```

## Usage

Use ToggleButton for persistent on/off actions such as bold formatting or bookmarking. It renders a
native button and exposes its state through `aria-pressed`. Use [Button](https://moraine.subf.dev/components/button.md) for a
one-shot command. Join several toggles with [ButtonGroup](https://moraine.subf.dev/components/button-group.md) for layout only;
the group does not coordinate selection.

```tsx
import { ToggleButton } from 'moraine'

export function Example() {
  return (
    <ToggleButton variant="ghost" activeVariant="soft" leading="i-lucide:bold">
      Bold
    </ToggleButton>
  )
}
```

### Off and on variants

`variant` sets the unpressed appearance and `activeVariant` sets the pressed appearance. Both
accept all Button variants, and the defaults are `ghost` and `soft`. `tone` and `activeTone` pick
the color the same way (both default to `neutral`). Changing a variant does not reset the pressed
state. The `link` variant only changes appearance; ToggleButton still renders a button that
toggles, not a link.

```tsx
<ToggleButton variant="outline" activeVariant="solid">
  Pin
</ToggleButton>
```

### Controlled and uncontrolled state

Use `defaultPressed` to initialize an uncontrolled button. Pass `pressed` and `onPressedChange` when
application state owns the value. Controlled activation reports the requested next value and waits
for the caller to update `pressed`. `onPressedChange` does not fire for programmatic changes to
`pressed`.

Your `onClick` runs before the toggle. Calling `event.preventDefault()` cancels both the state
change and `onPressedChange`.

```tsx
<ToggleButton pressed={pinned()} onPressedChange={setPinned} leading="i-lucide:pin">
  Pin conversation
</ToggleButton>
```

### Icons and accessible names

Keep the accessible name stable while toggling. Use `aria-label` for icon-only buttons;
`aria-pressed` then reports the on or off state. Disabled and loading buttons suppress activation.

Children can be a render function that receives reactive `pressed` and `loading` values. Use it to
style the content from the pressed state without remounting the button's children. Declare the
function's parameter even when you do not use it; a zero-argument function is called as an
accessor and is not mounted as a component.

```tsx
<ToggleButton size="icon-md" leading="i-lucide:bold" aria-label="Bold" />
<ToggleButton size="icon-md" aria-label="Bookmark">
  {(state) => <Icon name="i-lucide:bookmark" class={state.pressed ? 'fill-current' : undefined} />}
</ToggleButton>
```

### Async actions

`autoLoading` follows a Promise returned by `onClick` and blocks repeated activation until it
settles. The state changes immediately after an uncancelled click, including when the Promise later
rejects; it is not automatically rolled back. Handle request errors in your async handler. To update
only after success, use controlled `pressed` and update it after the request completes.

```tsx
<ToggleButton autoLoading onClick={() => bookmark()} leading="i-lucide:bookmark">
  Bookmark
</ToggleButton>
```

### Theme and groups

Configure `toggleButton.defaultVariants` to choose the default off and on appearances and size.
Button's theme still supplies the underlying variant styles; `toggleButton.base`, `classes`, and
`styles` add component-specific presentation. Instance styling follows the standard root and slot
override rules.

Inside ButtonGroup, ToggleButton inherits the group's size and variant. The group's tone sets both
the unpressed `tone` and the pressed `activeTone`. Its pressed variant comes from its own
configuration. Any prop set on the ToggleButton overrides the inherited value.

The root uses `data-slot="toggle-button"` and exposes `data-pressed` while pressed. The leading,
label, and trailing elements retain the corresponding `button-*` data-slot names.

```tsx
<ButtonGroup size="sm" variant="ghost" aria-label="Text formatting">
  <ToggleButton leading="i-lucide:bold" aria-label="Bold formatting" />
  <ToggleButton leading="i-lucide:italic" aria-label="Italic formatting" />
</ButtonGroup>
```

## Examples

### Pin a conversation

Own `pressed` when another control on the page must reset the same flag.

```tsx
import { Button, ToggleButton } from 'moraine'
import { createSignal } from 'solid-js'

export function Controlled() {
  const [pressed, setPressed] = createSignal(false)
  return (
    <div class="space-y-3">
      <div class="flex flex-wrap gap-3 items-center">
        <ToggleButton pressed={pressed()} onPressedChange={setPressed} leading="i-lucide:pin">
          Pin conversation
        </ToggleButton>
        <Button variant="outline" size="sm" onClick={() => setPressed(false)}>
          Reset
        </Button>
      </div>
      <p class="text-sm text-muted-foreground">
        Conversation: <output aria-live="polite">{pressed() ? 'Pinned' : 'Unpinned'}</output>
      </p>
    </div>
  )
}
```

### Toggle formatting and a bookmark

Keep `aria-label` stable on icon-only toggles. Use a child render function when the glyph itself
should change with `pressed`.

```tsx
import { Icon, ToggleButton } from 'moraine'

export function Icons() {
  return (
    <div class="flex gap-3 items-center">
      <ToggleButton size="icon-md" leading="i-lucide:bold" aria-label="Bold" />
      <ToggleButton size="icon-md" leading="i-lucide:italic" aria-label="Italic" defaultPressed />
      <ToggleButton size="icon-md" aria-label="Bookmark" variant="outline" activeVariant="solid">
        {(state) => (
          <Icon
            name="i-lucide:bookmark"
            class={state.pressed ? 'fill-current' : undefined}
            aria-hidden="true"
          />
        )}
      </ToggleButton>
    </div>
  )
}
```

### Turn on notifications in a toolbar

Theme defaults can set size and variants for a page region. ButtonGroup only joins the formatting
toggles visually.

```tsx
import { ButtonGroup, MoraineProvider, ToggleButton } from 'moraine'
import { defineTheme } from 'moraine/theme'

const theme = defineTheme({
  toggleButton: {
    defaultVariants: { variant: 'outline', activeVariant: 'solid', size: 'sm' },
  },
})

export function Theme() {
  return (
    <MoraineProvider theme={theme}>
      <div class="flex flex-wrap gap-4 items-center">
        <ToggleButton leading="i-lucide:bell">Notifications</ToggleButton>
        <ToggleButton leading="i-lucide:mail" activeVariant="soft" defaultPressed>
          Email updates
        </ToggleButton>
        <ButtonGroup size="sm" variant="ghost" aria-label="Text formatting">
          <ToggleButton leading="i-lucide:bold" aria-label="Bold formatting" />
          <ToggleButton leading="i-lucide:italic" aria-label="Italic formatting" />
        </ButtonGroup>
      </div>
    </MoraineProvider>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-pressed` | `toggle-button` | Present while the button or toggle is pressed. |

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activeTone | Tone \| undefined | 'neutral' | Color tone while pressed. |
| activeVariant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'soft' | Visual treatment while pressed. |
| autoLoading | boolean \| undefined | false | Shows loading automatically from the `onClick` handler: when it returns a promise (for example<br>an `async` function), the button is loading until the promise settles, whether it resolves or<br>rejects. A handler that calls `event.preventDefault()` does not trigger loading. |
| defaultPressed | boolean \| undefined | false | Initial uncontrolled toggle state. |
| disabled | boolean \| undefined | — | Disables the button, including non-button roots set with `as` (those get `aria-disabled`<br>and are removed from the tab order). Clicks and Enter/Space activation are ignored while<br>disabled. |
| leading | IconT.Name \| undefined | — | Name of an icon rendered before the label. Replaced by the loading icon while loading. |
| loading | boolean \| undefined | false | Shows the loading indicator. While loading the button sets `aria-busy`, ignores clicks and<br>keyboard activation, and stays focusable. Combine with `autoLoading` to also show loading<br>while an async click handler is pending. |
| loadingIcon | IconT.Name \| undefined | 'icon-loading' | Name of the icon shown while loading. It replaces the `leading` icon, or the `trailing` icon<br>when only `trailing` is set; with no icons it is added before the label. |
| onPressedChange | ((pressed: boolean) => void) \| undefined | — | Called with the new pressed state when the user activates the button, unless an `onClick`<br>handler calls `event.preventDefault()`. It does not fire for programmatic changes to `pressed`. |
| pressed | boolean \| undefined | — | Controlled pressed state. Leave it `undefined` for uncontrolled usage; when set, clicks only call `onPressedChange` and the button follows what you pass back. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon-xs' \| 'icon-sm' \| 'icon-md' \| 'icon-lg' \| 'icon-xl' \| undefined | 'md' | Button size, including icon-only sizes. |
| tone | Tone \| undefined | 'neutral' | Color tone while unpressed. |
| trailing | IconT.Name \| undefined | — | Name of an icon rendered after the label. It is replaced by the loading icon only when no<br>`leading` icon is set. |
| variant | 'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link' \| undefined | 'ghost' | Visual treatment while unpressed. |
| as | T \| undefined | 'button' | Element or component to render as. |
| children | JSX.Element \| Component<ChildrenRenderProps> \| undefined | — | Content or render function receiving reactive toggle and loading states.<br>A render function must declare its parameter, even when unused. A zero-argument<br>function is called as an accessor and is not mounted as a component. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |
