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.
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
Shared props
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.