# Button primitive (/components/primitives/button)



Use the button primitive to build a custom button pattern. It provides Luke UI button styles and
React Aria button behaviour. You own the child layout and loading treatment. For ordinary
application actions, use [`Button`](/components/actions/button).

apps/docs/src/examples/button-primitive/basic.tsx

```tsx
import { Button } from '@luke-ui/react/primitives/button';

export default () => {
	return <Button tone="accent">Save</Button>;
};
```

## Composition [#composition]

Use the primitive when you need custom children, render-prop children, or your own loading layout.
`Button` wraps its label for truncation, adds start and end content slots, and supplies a pending
spinner. The primitive does not.

## Appearance and size [#appearance-and-size]

Use `tone` and `appearance` to set visual emphasis. Use `size` to match nearby controls. Set
`isBlock` when the button should take up its container's inline size. The primitive renders a native
`<button>` by default and accepts the React Aria button API.

## Pending [#pending]

Set `isPending` to prevent another press. The control stays focusable and shows the muted pending
treatment. The primitive does not add a spinner or replace its children. Add a clear busy cue in
your custom content. Set `isDisabled` when the action cannot receive focus or respond to presses.

## Accessibility [#accessibility]

Give the button an accessible name through its visible text or an appropriate ARIA label. Keep the
name stable when possible. If a custom pending treatment changes the action's meaning, update the
name to reflect that state.

## API [#api]

<ComponentPropsTable
  id="type-table-button.tsx-ButtonProps"
  type="{
  &#x22;id&#x22;: &#x22;button.tsx-ButtonProps&#x22;,
  &#x22;name&#x22;: &#x22;ButtonProps&#x22;,
  &#x22;description&#x22;: &#x22;Props for the button primitive.&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;render&#x22;,
      &#x22;description&#x22;: &#x22;Overrides the default DOM element with a custom render function.\nThis allows rendering existing components with built-in styles and behaviors\nsuch as router links, animation libraries, and pre-styled components.\n\nRequirements:\n\n- You must render the expected element type (e.g. if `<button>` is expected, you cannot render an\n  `<a>`).\n- Only a single root DOM element can be rendered (no fragments).\n- You must pass through props and ref to the underlying DOM element, merging with your own prop\n  as appropriate.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;DOMRenderFunction<\&#x22;button\&#x22;, ButtonRenderProps> | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;DOMRenderFunction<\&#x22;button\&#x22;, object>&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;autoFocus&#x22;,
      &#x22;description&#x22;: &#x22;Whether the element should receive focus on render.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;id&#x22;,
      &#x22;description&#x22;: &#x22;The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;slot&#x22;,
      &#x22;description&#x22;: &#x22;A slot name for the component. Slots allow the component to receive props from a parent\ncomponent. An explicit `null` value indicates that the local props completely override all\nprops received from a parent.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | null | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-describedby&#x22;,
      &#x22;description&#x22;: &#x22;Identifies the element (or elements) that describes the object.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-details&#x22;,
      &#x22;description&#x22;: &#x22;Identifies the element (or elements) that provide a detailed, extended description for the\nobject.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-label&#x22;,
      &#x22;description&#x22;: &#x22;Defines a string value that labels the current element.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-labelledby&#x22;,
      &#x22;description&#x22;: &#x22;Identifies the element (or elements) that labels the current element.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;children&#x22;,
      &#x22;description&#x22;: &#x22;The children of the component. A function may be provided to alter the children based on\ncomponent state.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ChildrenOrFunction<ButtonRenderProps>&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;ChildrenOrFunction<object>&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onFocus&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when the element receives focus.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: React.FocusEvent<Element, Element>) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onBlur&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when the element loses focus.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: React.FocusEvent<Element, Element>) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onKeyDown&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a key is pressed.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: KeyboardEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onKeyUp&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a key is released.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: KeyboardEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onHoverStart&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a hover interaction starts.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: HoverEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onHoverEnd&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a hover interaction ends.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: HoverEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onHoverChange&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when the hover state changes.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((isHovering: boolean) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onPressStart&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a press interaction starts.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: PressEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onPressEnd&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a press interaction ends, either\nover the target or when the pointer leaves the target.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: PressEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onPressChange&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when the press state changes.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((isPressed: boolean) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onPressUp&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when a press is released over the target, regardless of\nwhether it started on the target or not.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: PressEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onFocusChange&#x22;,
      &#x22;description&#x22;: &#x22;Handler that is called when the element's focus status changes.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((isFocused: boolean) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;isPending&#x22;,
      &#x22;description&#x22;: &#x22;Whether the button is in a pending state. This disables press and hover events\nwhile retaining focusability, and announces the pending state to screen readers.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;appearance&#x22;,
      &#x22;description&#x22;: &#x22;Visual emphasis.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;'solid'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;\&#x22;subtle\&#x22; | \&#x22;solid\&#x22; | \&#x22;ghost\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;isBlock&#x22;,
      &#x22;description&#x22;: &#x22;Whether the button takes up the full inline size of its container.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;false&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;size&#x22;,
      &#x22;description&#x22;: &#x22;Sets the button size.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;'medium'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;\&#x22;medium\&#x22; | \&#x22;small\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;tone&#x22;,
      &#x22;description&#x22;: &#x22;Visual tone. Controls colour scheme.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;'neutral'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;\&#x22;neutral\&#x22; | \&#x22;accent\&#x22; | \&#x22;danger\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;isDisabled&#x22;,
      &#x22;description&#x22;: &#x22;Whether the button is disabled. Disabled buttons can't be focused or pressed.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;false&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;onPress&#x22;,
      &#x22;description&#x22;: &#x22;Press handler. Called on click, Enter, or Space.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((e: PressEvent) => void) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;type&#x22;,
      &#x22;description&#x22;: &#x22;HTML button type.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;reset\&#x22; | \&#x22;button\&#x22; | \&#x22;submit\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;deprecated&#x22;: false,
      &#x22;description&#x22;: &#x22;`ButtonProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.&#x22;,
      &#x22;name&#x22;: &#x22;__nativePropsForwarding&#x22;,
      &#x22;required&#x22;: true,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;&#x22;
    }
  ]
}"
/>