---
title: Button
description: Render actions and links with loading, icons, and semantic roots.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Button

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

## Anatomy

```text
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](https://moraine.subf.dev/components/toggle-button.md) when the
control stays pressed.

```tsx
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](https://moraine.subf.dev/components/button-group.md), a button inherits the group's `size`, `variant`, and `tone`
unless it sets its own.

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

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

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

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

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

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

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

```tsx
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 | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `button` | Present when the component, slot, or item is disabled. |
| `data-loading` | `button` | Present when the component or async operation is loading. |

### Props

Props for the Button component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activeEffect | 'none' \| 'move-down' \| 'zoom-in' \| ((element: HTMLElement) => string) \| undefined | 'move-down' | Press motion while the button is active.<br>`'move-down'` and `'zoom-in'` skip the motion when the root has `aria-haspopup`.<br>Pass a function to return a class string from the rendered element. |
| 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. |
| 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. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon-xs' \| 'icon-sm' \| 'icon-md' \| 'icon-lg' \| 'icon-xl' \| undefined | 'md' | Visual size of the component. |
| tone | Tone \| undefined | 'primary' | Color tone of the component. |
| 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 | 'solid' | Visual treatment of the component. |
| as | T \| undefined | 'button' | Element or component to render as. |
| children | JSX.Element \| Component<ChildrenRenderProps> \| undefined | — | Label content, or a render function receiving `{ loading }`.<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. Empty content renders no<br>label element, which suits icon-only buttons (add an `aria-label`). |
| 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. |

**`children` example**

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

<Button autoLoading onClick={() => fetch('/api/save')}>
  {(state) => (state.loading ? 'Saving...' : 'Save')}
</Button>
```
