Actions

Button

The base clickable action element, with size/color/variant options and optional icon/link behavior.

vue

<UiButton />

Options

One block per prop — what it does, and what it looks like set.

Size

size is the size of the button.

To

to swaps the underlying element for a NuxtLink — an internal path is routed client-side, an absolute URL renders as a plain anchor.

Internal route External URL

Setting both to and disabled renders a plain <button>, not a NuxtLink — disabled links can't be prevented from navigating any other way.

Target

target is only meaningful alongside to, where the button renders as a real link. Set it to _blank to open in a new tab.

New tab

Variant

variant is four levels of emphasis: solid for the primary action on a page, subtle beside it, soft where a full fill would be too loud, and ghost for the quietest actions — a toolbar icon button, say.

Color

color themes the button across every variant. Keep it tied to meaning rather than decoration: error on the button that deletes something, neutral for everything that just navigates.

solid

subtle

soft

ghost

Icon

icon renders before the label — or on its own, which is what a ghost icon button in a toolbar wants.

Omit the default slot (no text) to get a square icon-only button automatically; passing slot content switches it to a padded, non-square layout.

Disabled

disabled disables interaction with the button.

Loading

loading swaps the icon for a spinner — or, with no icon, lays one over the label — disables the button and sets aria-busy. The label stays put, so the button never changes width.

loading (and loadingAuto while its Promise runs) also disables the button, so a to button renders as a plain <button> for the duration, the same as disabled does.

Loading icon

loadingIcon replaces the spinner. Any icon other than the self-animating loader gets spun for you.

Loading auto

loadingAuto watches the Promise your @click handler returns and shows the loading state until it settles — no busy ref of your own, and a second click while it runs is ignored.

loadingAuto only sees a Promise that the @click handler itself returns — an async function works, a handler that starts a request and returns nothing doesn't.

API Reference

Generated from the component's source — props, slots and emits as the component actually declares them.

Props

Prop

Type

Default

Description

size

"sm" | "md" | "lg"

'md'

The size of the button.

to

string

—

Renders the button as a NuxtLink pointing to this route/URL.

target

string

—

The target attribute for the link (e.g. '_blank').

variant

"solid" | "subtle" | "soft" | "ghost"

'subtle'

The visual style of the button.

color

'neutral'

The color theme of the button.

icon

string

—

Name of the icon displayed inside the button.

disabled

boolean

false

Disables interaction with the button.

loading

boolean

false

Shows a spinner in place of the icon (or over the label when there is no icon), disables the button and sets `aria-busy`. The label stays, so the button keeps its width.

loadingIcon

string

'loader'

Name of the icon shown while loading. An icon other than the self-animating `loader` is spun with `animate-spin`.

loadingAuto

boolean

false

Sets `loading` automatically while the Promise returned by the `@click` handler is pending, so the caller needs no busy ref of its own. Also ignores clicks until it settles.

Slots

Slot

default

Types

type Variant = "solid" | "subtle" | "soft" | "ghost";

type Color = "neutral" | "primary" | "secondary" | "success" | "error" | "warning" | "info" | "pending";

type ClickHandler = (event: MouseEvent) => unknown;