Button
A clickable button component with multiple variants and states
Usage
import { Button } from '@heroui/react';Examples
Variants
Sizes
With Icons
Icon Only
Loading
Loading State
Full Width
Disabled State
Social Buttons
Render Function
Adding custom variants
You can extend HeroUI components by wrapping them and adding your own custom variants.
Adding Ripple Effect
The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses m3-ripple.
Customization
Tailwind CSS
Global CSS
To customize the Button component classes, you can use the @layer components directive.
Learn more.
@layer components {
.button {
@apply bg-purple-500 text-white hover:bg-purple-600;
}
.button--icon-only {
@apply rounded-lg bg-blue-500;
}
}Styling Reference
HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.
CSS Classes
The Button component uses these CSS classes (View source styles):
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:
:hoveror[data-hovered="true"] - Active/Pressed:
:activeor[data-pressed="true"](includes scale transform) - Focus:
:focus-visibleor[data-focus-visible="true"](shows focus ring) - Disabled:
:disabledor[aria-disabled="true"](reduced opacity, no pointer events) - Pending:
[data-pending](no pointer events during loading)
API Reference
Button
| 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. |
Render Props
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 |
