Skip to main content

Button

Render actions and links with loading, icons, and semantic roots.

Props
Slots

Anatomy#

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

Usage#

Use Button for commands and explicit navigation. Render a native button for an action on this page. Use as="a" with href for a destination. Use ToggleButton when the control stays pressed.

import { Button } from 'moraine'

export function Example() {
  return <Button>Save</Button>
}

Variant, tone, and size#

variant selects the surface: solid (default), soft, outline, ghost, or link. tone sets the color. It defaults to primary and accepts the shared tones such as neutral, danger, and success. size runs from xs to xl (default md). Inside a ButtonGroup, a button inherits the group’s size, variant, and tone unless it sets its own.

<Button variant="outline" tone="danger" size="sm">
  Delete
</Button>

Press motion#

activeEffect controls the press motion. The default move-down shifts the button down by one pixel. zoom-in scales it down slightly. Both skip the motion when the button has aria-haspopup, so overlay triggers stay still. Use none to disable the motion, or pass a function that receives the rendered element and returns a class string.

<Button activeEffect="zoom-in">Compress</Button>
<Button activeEffect="none">Static</Button>

Loading#

Use loading when application state owns the pending operation. autoLoading is opt-in: when onClick returns a promise, the button loads until the promise settles. A handler that calls event.preventDefault() does not start loading. While loading, the button sets aria-busy and ignores clicks and keyboard activation, but does not apply native disabled, so a focused button keeps its keyboard position. An explicit disabled still uses native disabled semantics where available.

The loading icon replaces leading, or trailing when only trailing is set. With no icons, it is added before the label. Set loadingIcon to change it. children can also be a function that receives { loading }. Declare its parameter even when unused.

<Button loading={saving()}>Save</Button>
<Button autoLoading onClick={() => submit()}>
  {(state) => (state.loading ? 'Saving...' : 'Save')}
</Button>

Icons and polymorphism#

leading and trailing accept icon names, elements, or components. Icon-only buttons need an aria-label or another accessible name. Polymorphic roots without native link semantics receive the button role and keyboard activation; anchors with href keep native link behavior. When disabled is set on such a root, it gets aria-disabled and leaves the tab order. When a custom component forwards its root ref, Moraine resolves native button semantics from the rendered DOM element.

<Button leading="i-lucide:plus">Create</Button>
<Button as="a" href="/docs" trailing="i-lucide:arrow-right">
  Docs
</Button>
<Button size="icon-sm" aria-label="Settings" leading="i-lucide:settings" />

Icon sizes#

Icon-only buttons use the square sizes icon-xs to icon-xl.

<Button size="icon-md" aria-label="Search" leading="i-lucide:search" />

Examples#

Bookmark a checklist item#

Keep an icon-only control labeled. Pair it with a tooltip when the action is otherwise unnamed.

import { Button, Icon, Tooltip } from 'moraine'
import { createSignal } from 'solid-js'

export function IconButtons() {
  const [bookmarked, setBookmarked] = createSignal(false)

  return (
    <div class="flex gap-3 items-center">
      <span class="text-sm">Release checklist</span>
      <Tooltip>
        <Tooltip.Trigger
          as={Button}
          variant="outline"
          size="icon-sm"
          aria-label={bookmarked() ? 'Remove bookmark' : 'Bookmark checklist'}
          onClick={() => setBookmarked((value) => !value)}
        >
          <Icon name={bookmarked() ? 'i-lucide:bookmark-check' : 'i-lucide:bookmark'} />
        </Tooltip.Trigger>
        <Tooltip.Content>{bookmarked() ? 'Remove bookmark' : 'Bookmark checklist'}</Tooltip.Content>
      </Tooltip>
    </div>
  )
}

Pending save#

Drive loading from local state when the request is owned by the page. Use autoLoading when the click handler returns a promise.

import { Button } from 'moraine'
import { createSignal } from 'solid-js'

export function LoadingUsage() {
  const [loading, setLoading] = createSignal(false)

  const handleManual = () => {
    setLoading(true)
    setTimeout(() => setLoading(false), 1200)
  }

  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Button loading={loading()} onClick={handleManual}>
        Controlled Loading
      </Button>
      <Button
        autoLoading
        variant="outline"
        onClick={() => new Promise((resolve) => setTimeout(resolve, 1500))}
      >
        Auto Promise Loading
      </Button>
    </div>
  )
}

Create, navigate, and settings#

Mix a labeled command, a documentation link, and an icon-only settings control. Icon-only buttons must keep an accessible name.

import { Button } from 'moraine'

export function IconsPolymorphism() {
  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Button leading="i-lucide:plus">Create Project</Button>
      <Button variant="outline" trailing="i-lucide:external-link" as="a" href="#polymorphic">
        Documentation Link
      </Button>
      <Button variant="ghost" size="xs" aria-label="Settings" leading="i-lucide:settings" />
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-disabled
Slot: button
Description: Present when the component, slot, or item is disabled.
data-loading
Slot: button
Description: Present when the component or async operation is loading.

Props#

Props for the Button component. Renders a <button> element by default.

Prop