# Button · HeroUI

> A clickable button component with multiple variants and states

- Page: https://jiguang132.com/systems/heroui/docs/components/button
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

```tsx
import { Button } from '@heroui/react';
```

### Usage


> Example `button-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Variants


> Example `button-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### With Icons


> Example `button-with-icons`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Icon Only


> Example `button-icon-only`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Loading


> Example `button-loading`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Loading State


> Example `button-loading-state`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Sizes


> Example `button-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Full Width


> Example `button-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Disabled State


> Example `button-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Social Buttons


> Example `button-social`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Custom Render Function


> Example `button-custom-render-function`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


## Styling

### Passing Tailwind CSS classes

```tsx
import { Button } from '@heroui/react';

function CustomButton() {
  return (
    <Button className="bg-purple-500 text-white hover:bg-purple-600">
      Purple Button
    </Button>
  );
}
```

### Customizing the component classes

To customize the Button component classes, you can use the `@layer components` directive.
  
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .button {
    @apply bg-purple-500 text-white hover:bg-purple-600;
  }

  .button--icon-only {
    @apply rounded-lg bg-blue-500;
  }
}
```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### Adding custom variants

You can extend HeroUI components by wrapping them and adding your own custom variants.


> Example `button-custom-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### Adding Ripple Effect

The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).


> Example `button-ripple-effect`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button


### CSS Classes

The Button component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)):

#### Base & Size Classes
- `.button` - Base button styles
- `.button--sm` - Small size variant
- `.button--md` - Medium size variant
- `.button--lg` - Large size variant

#### Variant Classes
- `.button--primary`
- `.button--secondary`
- `.button--tertiary`
- `.button--outline`
- `.button--ghost`
- `.button--danger`

#### Modifier Classes
- `.button--icon-only`
- `.button--icon-only.button--sm`
- `.button--icon-only.button--lg`

### Interactive States

The button supports both CSS pseudo-classes and data attributes for flexibility:

- **Hover**: `:hover` or `[data-hovered="true"]`
- **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
- **Pending**: `[data-pending]` (no pointer events during loading)

## API Reference

### Button Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `fullWidth` | `boolean` | `false` | Whether the button should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
| `isPending` | `boolean` | `false` | Whether the button is in a loading state |
| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | Overrides the default DOM element with a custom render function.|

### ButtonRenderProps

When using the render prop pattern, these values are provided:

| Prop | Type | Description |
|------|------|-------------|
| `isPending` | `boolean` | Whether the button is in a loading state |
| `isPressed` | `boolean` | Whether the button is currently pressed |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isFocused` | `boolean` | Whether the button is focused |
| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
| `isDisabled` | `boolean` | Whether the button is disabled |

---

Index of all JGuang resources: https://jiguang132.com/llms.txt