Skip to content

Button ​

Triggers an action; choose it over a link when the result happens on this page. Use as="a" or asChild with a router link for navigation that should look like a button.

Usage ​

vue
<Button variant="primary" @click="save">Save</Button>

Props ​

PropTypeDefaultNotes
variant'primary' | 'danger' | 'secondary' | 'outline' | 'ghost' | 'link''secondary'
size'md' | 'sm' | 'lg''md'Height from control-*
disabledbooleanfalse
loadingbooleanfalseA spinner shows over the content, which stays in place; clicks are blocked
type'button' | 'submit' | 'reset''button'Ignored when not rendering a button
asAsTag | Component'button'The element or component this component should render as. Can be overwritten by asChild.
asChildbooleanfalseMerge onto the child element, which brings its own content: set type on a child button, and show progress inside the child when loading
classstringnoneMerged last

Slots ​

SlotContent
defaultLabel
leadingIcon before the label
trailingIcon after the label

An icon-only button puts the icon in default and must set aria-label.

Events ​

EventPayloadWhen
——None of its own; native events such as click pass through.

Tokens ​

TokenFalls back toControls
--h-button-radius--h-radius-mdCorner radius

States ​

default, hover, focus-visible, active, disabled, loading; each for all six variants and three sizes. Icon-only. With leading and trailing icons.

Keyboard ​

KeyAction
Enter, SpaceActivate

Accessibility ​

  • loading sets aria-busy="true" and aria-disabled="true", and keeps the button focusable.
  • disabled uses the native attribute on button, aria-disabled and tabindex="-1" on other elements. A disabled or loading as="a" link drops its href and keeps role="link"; while loading it stays in the tab order. With asChild or a router component (to), remove the link yourself while disabled.
  • Focus ring uses ring, ring-width, ring-offset.
  • The width does not change when loading toggles.
  • Loading looks busy, not disabled: it keeps full opacity.
  • Clicks on a disabled or loading button don't reach its parent.
  • Focus stays visible in forced-colors mode.

Do ​

vue
<Button variant="primary" :loading="saving" @click="save">Save</Button>
<Button variant="ghost" @click="cancel">Cancel</Button>

Do not ​

vue
<!-- Two primary buttons in one view: the user cannot tell the main action. -->
<Button variant="primary">Save</Button>
<Button variant="primary">Publish</Button>