---
title: Button
description: Used to trigger actions or events.
npm: '@cerberus-design/react'
source: 'components/button'
recipe: 'button.ts'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage


```tsx


export function BasicDemo() {
  return <Button>Default</Button>
}
```


### With Icon

To display an icon, use the `ButtonParts` API.


```tsx
'use client'




export function IconDemo() {
  return (
    <Button>
      With icon
      <Button.Icon>
        <ArrowDownRight />
      </Button.Icon>
    </Button>
  )
}
```


> **Note:** When using the pending prop, the icon will be replaced with a spinner.

## Pending

To display a loading state, use the `ButtonParts.Icon` and set the `pending` prop to `true`.


```tsx
'use client'



export function PendingDemo() {
  return (
    <Button pending>
      <Button.Icon />
      Pending
    </Button>
  )
}
```


## Shapes

Use the `shape` prop to set the shape of the button. The `Button` component comes in three shapes: `default`, `sharp` and `rounded`.


```tsx



export function ShapesDemo() {
  return (
    <HStack>
      <Button shape="default">Default</Button>
      <Button shape="sharp">Sharp</Button>
      <Button shape="rounded">Rounded</Button>
    </HStack>
  )
}
```


## Usage

Use the `usage` prop to set the usage style of the button. The `Button` component comes in three usage styles: `filled`, `outlined`, and `ghost`.


```tsx



export function UsageDemo() {
  return (
    <HStack>
      <Button usage="filled">Filled</Button>
      <Button usage="outlined">Outlined</Button>
      <Button usage="outlined-subtle">Outlined Subtle</Button>
      <Button usage="ghost">Ghost</Button>
    </HStack>
  )
}
```


## Sizes

Use the `size` prop to change the Button size. The options are `xs` up to `2xl`.


```tsx




const sizes = (recipesSpec.data.find((r) => r.name === 'button')?.variants.size ??
  []) as ButtonProps['size'][]

export function SizeDemo() {
  return (
    <HStack>
      <For each={sizes}>
        {(size) => (
          <Button key={size} size={size}>
            {size}
          </Button>
        )}
      </For>
    </HStack>
  )
}
```


## Group

You can group buttons together using the `ButtonGroup` component.


```tsx


export function GroupDemo() {
  return (
    <ButtonGroup>
      <Button>Button 1</Button>
      <Button>Button 2</Button>
      <Button>Button 3</Button>
    </ButtonGroup>
  )
}
```


### Attached Button Group

You can create an attached button group by setting the `layout` prop to `attached`.


```tsx




export function AttachedDemo() {
  return (
    <HStack justify="center" w="full">
      <ButtonGroup layout="attached">
        <Button>Main action</Button>
        <IconButton ariaLabel="View options" shape="square" usage="filled">
          <ChevronDown />
        </IconButton>
      </ButtonGroup>

      <ButtonGroup layout="attached">
        <Button usage="outlined">Main action</Button>
        <IconButton ariaLabel="View options" shape="square" usage="outlined">
          <ChevronDown />
        </IconButton>
      </ButtonGroup>
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the button.

| Component   | Description                               |
| ----------- | ----------------------------------------- |
| Button.Root | The context provider for the Button parts |
| Button.Icon | The icon/spinner of the button            |


```tsx


export function CustomDemo() {
  return (
    <Button
      bgColor="danger.bg.initial"
      color="danger.text.initial"
      rounded="md"
      transform="skew(-10deg)"
      _hover={{
        bgColor: 'black',
        color: 'yellow',
      }}
    >
      Cerberus Forever
    </Button>
  )
}
```


## Global Customization

To enable global customization, you can modify the `theme` configuration in your `panda.config.ts` file. For example, to customize the button component globally:


```tsx


export default createCerberusConfig({
  // ...
  theme: {
    extend: {
      recipes: {
        button: {
          defaultVariants: {
            shape: 'default',
          },
        },
      },
    },
  },
})
```

<br />

This change will set the default shape variant of all buttons to `default`.

## API

### Props

The `Button` component is an abstraction of the primitives and accepts the following props:

| Name      | Default  | Description                                                                                                                          |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `palette` | `action` | The color palette (any of the Cerberus palettes) of the button.                                                                      |
| `usage`   | `filled` | The style treatment of the button.                                                                                                   |
| `shape`   | `sharp`  | The shape of the button.                                                                                                             |
| `size`    | `lg`     | The size of the Button.                                                                                                              |
| `pending` | `false`  | The loading state of the button. When a button has an `Icon` it will replace it with a spinner. When not, is shows a disabled state. |
| `asChild` |          | Render the Button as the child component.                                                                                            |

#### ButtonGroup Props

| Name   | Default   | Description                                                                                           |
| ------ | --------- | ----------------------------------------------------------------------------------------------------- |
| layout | `default` | The layout of the button group. Can be `default` or `attached`.                                       |
| shape  | `sharp`   | The shape of the buttons in the group. Should match the `shape` prop of the `Button` components used. |