Button
The Button is an action element with color, variant and size options, plus
disabled, loading, iconOnly, toggle, menu and block states. It's written
once as a .uf.tsx component and compiled to all seven frameworks.
Here it is in the framework you picked in the Framework select:
import { IButton } from "@inkline/react";
export function Actions() {
return <IButton label="Save" color="primary" />;
}
Pick another in the Framework select to compare them.
Variants
The Button has six style variants, set with variant, and nine colours, set with
color:
<IButton label="Solid" variant="solid" />
<IButton label="Outline" variant="outline" />
<IButton label="Soft" variant="soft" />
<IButton label="Subtle" variant="subtle" />
<IButton label="Ghost" variant="ghost" />
<IButton label="Link" variant="link" />
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Button text content. The default slot takes precedence. |
color | primary | secondary | success | info | warning | error | light | dark | neutral | neutral | Color variant. |
variant | solid | outline | soft | subtle | ghost | link | solid | Style variant. |
size | xs | sm | md | lg | xl | md | Size variant. |
type | button | submit | reset | button | Native button type. |
disabled | boolean | false | Disables the button and takes it out of the tab order. |
focusableWhenDisabled | boolean | false | Keeps a disabled button in the tab order, with aria-disabled. |
loading | boolean | false | Shows a spinner and blocks activation. The button keeps its focus and its name. |
loadingLabel | string | "Loading" | Announced to screen readers when loading starts. |
iconOnly | boolean | false | Shows only the leading icon. The label is visually hidden and still names the button. |
block | boolean | false | Renders a full-width button. |
id | string | — | The native button's id. |
ariaLabel | string | — | The native button's aria-label. |
ariaDescribedby | string | — | The native button's aria-describedby. |
ariaPressed | boolean | — | The native button's aria-pressed, for a toggle button. |
ariaExpanded | boolean | — | The native button's aria-expanded, for a button that opens a menu or a dialog. |
ariaHaspopup | true | menu | listbox | tree | grid | dialog | — | The native button's aria-haspopup. |
ariaControls | string | — | The native button's aria-controls. |
A prop you leave unset renders no attribute, so a Button without ariaPressed
isn't a toggle.
Slots
| Slot | Holds |
|---|---|
default | The label, in place of label. |
leading | An icon before the label, which is also the icon of an icon-only button. |
trailing | An icon after the label. An icon-only button doesn't show it. |
Both icon slots are hidden from assistive technology, since the label names the button.
Events
| Event | Payload | Fires |
|---|---|---|
click | none | When the native button is clicked, unless it's disabled or loading. |
Listen with onClick in React and Solid, @click in Vue, onclick in Svelte,
onClick$ in Qwik and (ufClick) in Angular. Astro renders on the server, so
nothing listens there. click carries no event object: to call
preventDefault() or read the modifier keys, listen to click on an element
around the button, where the native event still bubbles.
Accessibility
The Button renders a native <button>, so it gets its role, focus, Enter,
Space and form submission from the browser. A few states need a word more:
- Icon-only buttons. Give an
iconOnlybutton alabelanyway. It's visually hidden, but it names the button, so a screen reader says "Delete" rather than nothing. - Disabled buttons.
disabledtakes the button out of the tab order, so people can't find it to learn why it's disabled. WithfocusableWhenDisabled, it stays in the tab order witharia-disabled="true", and a click,EnterorSpacedoes nothing. - Loading. A loading button keeps its focus and its name, blocks its own
click and its form's submission, and announces
loadingLabelin a polite live region outside the button. The spinner is hidden from assistive technology. Screen readers only announce changes to a live region that's already in the page, as the Open Components reference notes, so the button adds the region when it's focused or pressed, before its click. A button that starts loading without either, like one your code sets loading on page load, may not be announced the first time. - Toggle and menu buttons. Set
ariaPressedon a button that turns something on and off, andariaHaspopup,ariaExpandedandariaControlson one that opens a menu.
Until the page runs its code, a loading button and a focusable disabled one render natively disabled, so they can't submit a form before the page is ready. On Astro, which runs no client code, they stay that way: they can't be focused, and nothing is announced.
The Button shows its variant, colour and size in data-variant, data-color
and data-size, and its icon-only and loading states in data-icon-only and
data-loading, so your CSS can target them.
Composition
IButton is a styled wrapper around a headless base, IButtonBase, which
carries the behavior and none of the styling. Import the base from
@inkline/<framework>/headless when you want the button's mechanics under your
own CSS — see
Your first component.