Skip to content
Browse documentation
whisk/ui

Button

Trigger a clear user action.

Overview

Button triggers an action in the current context. It provides semantic variants, native button behavior, and a host-owned loading presentation.

Coming from another library?
Use loading, startElement, and endElement, not isLoading, leftIcon, or rightIcon. asChild requires exactly one element child, and iconOnly requires aria-label or aria-labelledby.

Use when

The user performs an in-place action.

Use instead

Use Link for inline navigation in text. Use Button asChild with an <a> when a navigation action needs button styling, such as a primary call to action.

Usage

import { Button } from "@smoothie-framework/whisk-react";

<Button variant="primary">Save changes</Button>

Examples

Variants

Match the treatment to the action's importance. Use destructive only for destructive outcomes.

import { Button, StackRow } from "@smoothie-framework/whisk-react";

<StackRow gap={3} wrap>
  <Button variant="primary">Save changes</Button>
  <Button variant="secondary">Preview</Button>
  <Button variant="outline">Cancel</Button>
  <Button variant="ghost">Learn more</Button>
  <Button variant="destructive">Delete project</Button>
  <Button variant="ghostDestructive">Remove</Button>
</StackRow>

Sizes

Match the button size to the surrounding interface density.

import { Button, StackRow } from "@smoothie-framework/whisk-react";

<StackRow align="center" gap={3} wrap>
  <Button size="sm">Small</Button>
  <Button size="md">Medium</Button>
  <Button size="lg">Large</Button>
</StackRow>

Icons

Use iconOnly with an accessible name. Start and end icons are decorative because the visible label names the action.

import { ArrowRightIcon, DownloadIcon } from "@smoothie-framework/whisk-react/icons";
import { Button, StackRow } from "@smoothie-framework/whisk-react";

<StackRow gap={3} wrap>
  <Button iconOnly aria-label="Download report">
    <DownloadIcon />
  </Button>
  <Button startElement={<DownloadIcon />}>Download</Button>
  <Button endElement={<ArrowRightIcon />}>Continue</Button>
  <Button startElement={<DownloadIcon />} endElement={<ArrowRightIcon />}>
    Export report
  </Button>
</StackRow>

Disabled

A disabled Button uses native disabled state and cannot receive focus, so this adjacent hint is visual context. Keep a prerequisite available in the surrounding form or status copy.

Add a report title before publishing.

import { Button, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack gap={2} align="start">
  <Button disabled>Publish report</Button>
  <Text color="subtle">
    Add a report title before publishing.
  </Text>
</Stack>

Loading

loading blocks activation while the host owns the pending operation. loadingText can replace the visible label.

import { Button } from "@smoothie-framework/whisk-react";

<Button loading loadingText="Saving changes">
  Save changes
</Button>

Async loading

Keep the button width stable while an action moves from pending to complete.

import { useState } from "react";
import { Button } from "@smoothie-framework/whisk-react";

export function SaveButton() {
  const [status, setStatus] = useState<"idle" | "loading" | "done">("idle");

  return (
    <Button
      width={44}
      loading={status === "loading"}
      loadingText="Saving changes"
      onClick={() => {
        setStatus("loading");
        setTimeout(() => {
          setStatus("done");
          setTimeout(() => setStatus("idle"), 1500);
        }, 800);
      }}
    >
      {status === "done" ? "Saved" : "Save changes"}
    </Button>
  );
}

Spinner placement

Place the loading indicator before or after the label without changing the action name.

import { Button, StackRow } from "@smoothie-framework/whisk-react";

<StackRow gap={3} wrap>
  <Button loading spinnerPlacement="start">Saving</Button>
  <Button loading spinnerPlacement="end">Saving</Button>
</StackRow>

Custom spinner

Pass spinner when the pending indicator needs a different appearance.

import { Button, Spinner } from "@smoothie-framework/whisk-react";

<Button
  loading
  loadingText="Uploading file"
  spinner={<Spinner size="md" label="In progress" />}
>
  Upload file
</Button>

Full width

Use fullWidth when the action should fill its containing width.

import { Button } from "@smoothie-framework/whisk-react";

<Button fullWidth>Continue</Button>

As link

Use asChild when the action navigates and the underlying element must remain a link.

import { Button } from "@smoothie-framework/whisk-react";

<Button asChild>
  <a href="/docs/framework/whisk-ui/get-started">Get started</a>
</Button>

Form submit

Button defaults to type="button". Set type="submit" only for the form action, and keep Cancel as a button.

import { Box, Button, StackRow } from "@smoothie-framework/whisk-react";

<Box as="form" onSubmit={(event) => event.preventDefault()}>
  <StackRow gap={3} wrap>
    <Button type="submit">Save project</Button>
    <Button type="button" variant="ghost">Cancel</Button>
  </StackRow>
</Box>

RTL

Start and end positions follow writing direction, but directional icons do not mirror automatically.

import { ArrowLeftIcon } from "@smoothie-framework/whisk-react/icons";
import { Box, Button } from "@smoothie-framework/whisk-react";

<Box dir="rtl">
  <Button endElement={<ArrowLeftIcon />}>
    متابعة
  </Button>
</Box>

For a compact set of related actions, use ButtonGroup.

Props

Component props

PropTypeDefaultDescription
variantprimary | secondary | outline | ghost | destructive | ghostDestructiveprimaryChoose the semantic action treatment.
sizesm | md | lgmdChoose the action density.
typebutton | submit | resetbuttonChoose native form behavior. Set submit explicitly for a form's submit action.
disabledbooleanfalsePrevent native activation and remove the button from the Tab order.
loadingbooleanfalsePrevent activation, set aria-busy, and show a pending indicator. The application owns the operation.
loadingTextReactNodenoneReplace the visible label while loading.
spinnerReactNodeSpinnerReplace the pending indicator.
spinnerPlacementstart | endstartPlace the pending indicator before or after the visible label.
spinnerSizexs | sm | md | lg | xlsmSet the default Spinner size when spinner is not provided.
startElementReactNodenoneAdd decorative, non-interactive content before the visible label.
endElementReactNodenoneAdd decorative, non-interactive content after the visible label.
iconOnlybooleanfalseRender an icon-only button. Requires a nonempty aria-label or aria-labelledby.
fullWidthbooleanfalseMake the button fill its containing width.

Shared props

PropSupportedNotes
as / asChildYesChoose the button host with as, or merge Button presentation into exactly one element child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered button or child host.
refYesForwards to the rendered button or child host.
Native HTML attributesYesNative button attributes are forwarded, except props Button owns for its behavior and accessibility state.

Accessibility

Button renders a native button by default, so Enter and Space activate it. Use a specific visible label, or supply a nonempty aria-label or aria-labelledby for iconOnly. Decorative startElement, endElement, and spinner content are hidden from assistive technology. When loading, use loadingText to announce the pending state; otherwise, the button retains its visible label. Do not communicate an unavailable or destructive action through color alone.

Content guidance

Start with a specific verb and name the outcome, especially for destructive actions.

DoDon't
Save changes, Delete projectSubmit, OK, Click here