Button

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


Installation

npx nextui-cli@latest add button
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

NextUI exports 2 button-related components:

  • Button: The main component to display a button.
  • ButtonGroup: A wrapper component to display a group of buttons.

Usage

Disabled

Sizes

Radius

Colors

Variants

Loading

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.

With Icons

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

Icon Only

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

Custom Styles

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.

Custom Implementation

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

Button Group

Group Disabled

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

Group Use case

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.

Data Attributes

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.

Accessibility

  • Button has role of button.
  • Keyboard event support for Space and Enter keys.
  • Mouse and touch event handling, and press state management.
  • Keyboard focus management and cross browser normalization.

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

API

Button Props

AttributeTypeDescriptionDefault
childrenReactNodeThe content to display in the button.-
variantsolid | bordered | light | flat | faded | shadow | ghostThe button appearance style.solid
colordefault | primary | secondary | success | warning | dangerThe button color theme.default
sizesm | md | lgThe button size.md
radiusnone | sm | md | lg | fullThe button border radius.-
startContentReactNodeThe button start content.-
endContentReactNodeThe button end content.-
spinnerReactNodeSpinner to display when loading.-
spinnerPlacementstart | endThe spinner placement.start
fullWidthbooleanWhether the button should take the full width of its parent.false
isIconOnlybooleanWhether the button should have the same width and height.false
isDisabledbooleanWhether the button is disabled.false
isLoadingbooleanWhether the button is loading.false
disableRipplebooleanWhether the button should display a ripple effect on press.false
disableAnimationbooleanWhether the button should display animations.false

Button Events

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

Button Group Props

AttributeTypeDescriptionDefault
childrenReactNode | ReactNode[]The buttons to display.-
variantsolid | bordered | light | flat | faded | shadow | ghostThe buttons appearance style.solid
colordefault | primary | secondary | success | warning | dangerThe buttons color theme.default
sizesm | md | lgThe buttons size.md
radiusnone | sm | md | lg | fullThe buttons border radius.xl
fullWidthbooleanWhether the buttons should take the full width.false
isDisabledbooleanWhether the buttons are disabled.false