Skip to content
flyingsalmon

Button

A button triggers one action on the current page and shows that action's busyness itself.

Installation

npx shadcn@latest add @flyingsalmon/button

Usage

import { Button } from '@/components/ui/button'

export function ButtonUsage({ onSave }: { onSave: () => void }) {
  return <Button onClick={onSave}>Save trip</Button>
}

Examples

Variants

Default is the one primary action on a view; outline and secondary sit beside it, ghost lives inside dense rows, and destructive marks the action that removes something.

Sizes

Default and small match the two field heights, so a button lines up with the input beside it.

Leading icon

The icon prop fills the slot before the label. There is no trailing slot, because a trailing icon reads as a menu or a link.

Icon only

A square size renders no label, so every icon-only button carries an aria-label.

Loading

Press either button. The spinner takes the leading slot and the label stays, so the button never hides what it is doing.

Disabled

A disabled button dims and leaves the tab order. Use it for an action that cannot run yet, never for one that is running.

Submit in a form

Rename the trip. Only the submit button says type="submit"; Reset stays a plain button and never posts the form. The new name lands on the trip itself.

Lisbon long weekend

Brian Nguyen and two travellers

Guidelines

When to use

  • To run an action on the current page: save a trip, send an invite, open a dialog, delete a place.
  • To submit a form, as the last control in its actions row.

When not to use

  • Use Text link to take the traveller to another page. A link navigates and a button acts, and browsers give links their own keyboard and context-menu behaviour.
  • Use Switch for a setting that is on or off, because the switch shows its state and a button does not.
  • Use Toggle group to pick one option from a small set, because the group shows which option is chosen.
  • Use Dropdown menu for more than two secondary actions on one item, so the row keeps one visible action and the rest wait in a menu.

Do and don’t

  • Do
    Give each view, card, dialog footer, and alert one default button. The alternative beside it is outline, and a quiet extra action is ghost.The filled orange button is where the eye lands first. Two of them make the traveller choose before they act, and the step down to outline and ghost tells them which action matters.
  • Do
    Name the outcome in the label, such as "Book both flights", and add the cost when the action spends something: "Book both flights · 240 euros".The traveller knows what will happen and what it takes from them before they press, so nobody reads the surrounding copy to find out.
  • Do
    Put the outline Cancel on the left of a dialog or form footer and the one default action on the right.The eye reads the row to its end and lands on the action that finishes the task. Cancel always sits in the same place, so leaving never needs reading.
  • Don’t
    Show success or failure on the button.The result belongs to the thing that changed: the trip updates, the field shows its error, or a notice links back when nothing is on screen.
  • Don’t
    Grey out a button while its action runs.The button shows its own busyness with a spinner beside its label, keeps focus, and ignores repeat presses. A greyed-out button drops focus mid-action and looks broken.
  • Don’t
    Hide a button whose action cannot run yet. Leave it visible but disabled, with a line beside it that says what is missing.The traveller sees where the task ends and learns what to do next, instead of hunting for a button that is not there.
  • Don’t
    Show a destructive button before the traveller has asked to remove something.Red belongs to the step that confirms a removal. As the first button on a view it shouts louder than the work and invites a slip.

Accessibility

KeyDescription
TabMoves focus to the button. A loading button stays in the tab order; a disabled one leaves it.
EnterSpaceRuns the action. A loading button ignores both, including form submission.

A loading button sets aria-busy and keeps its label as its accessible name; the spinner is hidden from screen readers, so the wait is announced once. The focus ring appears on keyboard focus only, so a mouse click never leaves one behind. An icon-only button needs an aria-label, because it renders no text.

API

Button

Also takes every <button> attribute. There is no asChild: a button is always a <button>.

PropTypeDefaultDescription
variantButtonVariantButtonVariant.DefaultDefault, Outline, Secondary, Ghost, or Destructive.
sizeButtonSizeButtonSize.DefaultDefault and Small carry a label. Icon and IconSmall are square. FieldIcon and FieldIconSmall are square buttons for inside a field box.
iconReactNode–The leading icon. On a square size it is the whole content; children work too.
loadingbooleanfalseSwaps the leading slot for a spinner, sets aria-busy, and ignores presses while keeping focus. Set it, not disabled, while the action runs: disabled drops keyboard focus mid-action.
type"button" | "submit" | "reset""button"Set "submit" on the one button that submits its form. Cancel and Reset beside it keep "button", so they never post the form.
disabledbooleanfalseDims the button and removes it from the tab order.

  • Text link

    The control for navigation, where a button would act.
  • Form

    Lays out fields, the actions row, and the result slot.
  • Dropdown menu

    Holds the secondary actions a row has no room for.
  • Spinner

    The indicator a loading button shows in its slot.