Skip to main content

ToggleButton

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

Props
Slots

Anatomy#

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 for a one-shot command. Join several toggles with ButtonGroup for layout only; the group does not coordinate selection.

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.

<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.

<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.

<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.

<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.

<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.

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.

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.

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
data-pressed
Slot: toggle-button
Description: Present while the button or toggle is pressed.

Props#

Renders a <button> element by default.

Prop