Button
Render actions and links with loading, icons, and semantic roots.
Anatomy#
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.
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.
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.
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.
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.
Icon sizes#
Icon-only buttons use the square sizes icon-xs to icon-xl.
Examples#
Bookmark a checklist item#
Keep an icon-only control labeled. Pair it with a tooltip when the action is otherwise unnamed.
Pending save#
Drive loading from local state when the request is owned by the page. Use autoLoading when the
click handler returns a promise.
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.
API Reference#
Attributes#
data-disableddata-loadingProps#
Props for the Button component. Renders a <button> element by default.