# Button (/components/actions/button)
`Button` triggers an action, such as saving a form, opening a dialog, or deleting an item. Use
[`Link`](/components/actions/link) when the interaction takes someone to another URL or route.
apps/docs/src/examples/button/basic.tsx
```tsx
import { Button } from '@luke-ui/react/button';
export default () => {
return ;
};
```
## Best practices [#best-practices]
| Guidance | Practices |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| Do | Use `Button` for an action, such as saving, submitting, or opening a dialog. |
| Do | Use [`Link`](/components/actions/link) with an `href` when the interaction navigates to another URL or route. |
| Don't | Navigate from a `Button`. It loses native link semantics and browser link behaviours. |
## Size [#size]
`medium` is the default size. Use `small` in dense toolbars, tables, and other compact interfaces.
Keep related controls at the same size.
apps/docs/src/examples/button/sizes.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { Comparison, ComparisonItem } from '#docs/comparison';
export default () => {
return (
);
};
```
## Appearance [#appearance]
Use `appearance` to set a button's visual weight. `solid` is the default. Choose `subtle` or `ghost`
for secondary actions that should recede beside the main action. Appearance sets emphasis. Use
`tone` to communicate intent.
apps/docs/src/examples/button/appearance.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { Comparison, ComparisonItem } from '#docs/comparison';
export default () => {
return (
);
};
```
## Tone [#tone]
Use `tone` to communicate intent. `neutral` is the default, `accent` identifies a primary action,
and `danger` marks a destructive one. Tone and appearance are independent, so every combination is
available.
apps/docs/src/examples/button/tones.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { Comparison, ComparisonItem } from '#docs/comparison';
export default () => {
return (
);
};
```
## Block layout [#block-layout]
Set `isBlock` when the button should fill the inline size of its container. A typical case is a
primary action at the end of a narrow form or panel.
```tsx
```
## Content slots [#content-slots]
Use `startContent` or `endContent` for non-interactive adornments beside the label, such as an icon,
badge, count, or keyboard hint. Nested interactive controls are unsupported. `Button` sizes nested
icons for you, so an `Icon` needs no `size` prop. Pass one only to override it. Use
[`IconButton`](/components/actions/icon-button) only when the icon is familiar without a text label.
apps/docs/src/examples/button/content-slots.tsx
```tsx
import { Box } from '@luke-ui/react/box';
import { Button } from '@luke-ui/react/button';
import { Icon } from '@luke-ui/react/icon';
import { Kbd } from '@luke-ui/react/kbd';
export default () => {
return (
}>Add item
);
};
```
## Pending and Actions [#pending-and-actions]
`onPress` handles the interaction. `pressAction` performs the resulting operation. When both are
set, `onPress` runs first, then `pressAction`.
Prefer a native form Action when the operation is a form submission. Pass the form’s pending state
to `Button`. This example uses React’s
[`useActionState`](https://react.dev/reference/react/useActionState).
apps/docs/src/examples/button/form-action.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { useActionState } from 'react';
export default () => {
const [, formAction, isPending] = useActionState(save, null);
return (
);
};
async function save(_state: null, _formData: FormData) {
await new Promise((resolve) => {
setTimeout(resolve, 1200);
});
return null;
}
```
Use `pressAction` for Button-owned operations that are not form submissions. Combining `pressAction`
with `type="submit"` is usually the wrong pattern, because both paths may run.
`pressAction` creates pending state automatically. Explicit `isPending` shows a spinner immediately.
An Action-owned spinner waits briefly so a fast Action never flashes one.
apps/docs/src/examples/button/pending.tsx
```tsx
import { Button } from '@luke-ui/react/button';
export default () => {
return ;
};
async function save() {
await new Promise((resolve) => {
setTimeout(resolve, 1200);
});
}
```
Set `isPending` for externally owned pending state, such as a parent mutation or router transition.
Pending buttons stay focusable and ignore further presses.
apps/docs/src/examples/button/external-pending.tsx
```tsx
import { Button } from '@luke-ui/react/button';
export default () => {
return ;
};
```
Unexpected failures from `pressAction` use React’s normal Action and Error Boundary behaviour.
Handle expected domain errors inside the Action.
apps/docs/src/examples/button/action-error.tsx
```tsx
import { Box } from '@luke-ui/react/box';
import { Button } from '@luke-ui/react/button';
import { Text } from '@luke-ui/react/text';
import type { FallbackProps } from 'react-error-boundary';
import { ErrorBoundary } from 'react-error-boundary';
export default () => {
return (
);
};
async function save() {
await new Promise((resolve) => {
setTimeout(resolve, 400);
});
throw new Error('Could not save changes');
}
function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
const message = error instanceof Error ? error.message : 'Something went wrong';
return (
{message}
);
}
```
## Disabled [#disabled]
Set `isDisabled` only when the action is unavailable. Disabled buttons cannot receive focus or
respond to presses.
apps/docs/src/examples/button/disabled.tsx
```tsx
import { Button } from '@luke-ui/react/button';
export default () => {
return ;
};
```
## Accessibility [#accessibility]
The visible label provides the accessible name, so most buttons do not need `aria-label`. Write a
label that describes the action, such as “Save changes” or “Delete account”, rather than a vague
label such as “OK”.
The spinner is hidden from assistive technology. Pending state is announced through the button’s
pending semantics, so the label does not need to change while pending.
## Related components [#related-components]
`Button` is the normal component for application UI. It wraps its label for truncation, provides
content slots, and supplies the pending spinner. Use the
[button primitive](/components/primitives/button) when you need to own the child layout or loading
treatment.
## API [#api]