Button

Buttons allow users to perform actions and choose with a single tap.

Installation

npx nextui-cli@latest add button

No need to install this package if @nextui-org/react is already installed globally.

NextUI exports 2 button-related components:

Pass the isLoading prop to display a Spinner component inside the button.

You can also customize the loading spinner by passing the a custom component to the spinner prop.

You can add icons to the Button by passing the startContent or endContent props.

You can also display a button without text by passing the isIconOnly prop and the desired icon as children.

You can customize the Button component by passing custom Tailwind CSS classes to the component slots.

Custom class names will override the default ones thanks to Tailwind Merge library. It means that you don't need to worry about class conflicts.

You can also use the useButton hook to create your own button component.

The ButtonGroup component also accepts the isDisabled prop to disable all buttons inside it.

A common use case for the ButtonGroup component is to display a group of two buttons one for the selected value and another for the dropdown.

See the Dropdown component for more details.

Button has the following attributes on the base element:

data-hover: When the button is being hovered. Based on useHover
data-focus: When the button is being focused. Based on useFocusRing.
data-focus-visible: When the button is being focused with the keyboard. Based on useFocusRing.
data-disabled: When the button is disabled. Based on isDisabled prop.
data-pressed: When the button is pressed. Based on usePress
data-loading: When the button is loading. Based on isLoading prop.

We recommend to read this blog post about the complexities of building buttons that work well across devices and interaction methods.

Attribute	Type	Description	Default
children	`ReactNode`	The content to display in the button.	-
variant	`solid` \| `bordered` \| `light` \| `flat` \| `faded` \| `shadow` \| `ghost`	The button appearance style.	`solid`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The button color theme.	`default`
size	`sm` \| `md` \| `lg`	The button size.	`md`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The button border radius.	-
startContent	`ReactNode`	The button start content.	-
endContent	`ReactNode`	The button end content.	-
spinner	`ReactNode`	Spinner to display when loading.	-
spinnerPlacement	`start` \| `end`	The spinner placement.	`start`
fullWidth	`boolean`	Whether the button should take the full width of its parent.	`false`
isIconOnly	`boolean`	Whether the button should have the same width and height.	`false`
isDisabled	`boolean`	Whether the button is disabled.	`false`
isLoading	`boolean`	Whether the button is loading.	`false`
disableRipple	`boolean`	Whether the button should display a ripple effect on press.	`false`
disableAnimation	`boolean`	Whether the button should display animations.	`false`

Attribute	Type	Description
onPress	`(e: PressEvent) => void`	Handler called when the press is released over the target.
onPressStart	`(e: PressEvent) => void`	Handler called when a press interaction starts.
onPressEnd	`(e: PressEvent) => void`	Handler called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange	`(isPressed: boolean) => void`	Handler called when the press state changes.
onPressUp	`(e: PressEvent) => void`	Handler called when a press is released over the target, regardless of whether it started on the target or not.
onKeyDown	`(e: KeyboardEvent) => void`	Handler called when a key is pressed.
onKeyUp	`(e: KeyboardEvent) => void`	Handler called when a key is released.
onClick	`MouseEventHandler`	The native button click event handler (Deprecated) use onPress instead.

Attribute	Type	Description	Default
children	`ReactNode` \| `ReactNode[]`	The buttons to display.	-
variant	`solid` \| `bordered` \| `light` \| `flat` \| `faded` \| `shadow` \| `ghost`	The buttons appearance style.	`solid`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The buttons color theme.	`default`
size	`sm` \| `md` \| `lg`	The buttons size.	`md`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The buttons border radius.	`xl`
fullWidth	`boolean`	Whether the buttons should take the full width.	`false`
isDisabled	`boolean`	Whether the buttons are disabled.	`false`