www.heroui.com/docs/

Public Link
Created by:
****ad@vlad.studio
Starting URLs:
https://www.heroui.com/docs/guide/introduction
CSS Selector:
.mdx
Crawl Prefixes:
https://www.heroui.com/docs/
Exclude Patterns:
https://www.heroui.com/docs/api-references/
## Page: https://www.heroui.com/docs/guide/introduction

# Introduction

Welcome to the HeroUI documentation!

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

![HeroUI banner](/_next/image?url=%2Fheroui-banner.png&w=1920&q=100)

## What is HeroUI?

HeroUI is a UI library for React that helps you build beautiful and accessible user interfaces. Created on top of Tailwind CSS and React Aria.

HeroUI's primary goal is to streamline the development process, offering a beautiful and adaptable system design for an enhanced user experience.

* * *

## FAQ

### Is HeroUI a copy-paste library?

No, HeroUI is not a copy-paste library. All components are available through `npm` and can be installed individually or as a whole package.

### How is HeroUI different from TailwindCSS?

*   **TailwindCSS**:
    
    Tailwind CSS is a CSS Framework that provides atomic CSS classes to help you style components, leaving you to handle lots of other things like accessibility, component composition, keyboard navigation, style overrides, etc.
    
*   **HeroUI**:
    
    HeroUI is a UI library for React that combines the power of TailwindCSS with React Aria to provide complete components (logic and styles) for building accessible and customizable user interfaces. Since HeroUI uses TailwindCSS as its style engine, you can use all TailwindCSS classes within your HeroUI components, ensuring optimal compiled CSS size.
    

### How is HeroUI different from TailwindCSS components libraries?

TailwindCSS components libraries such as TailwindUI, Flowbite, or Preline, just to name a few, only offer a curated selection of TailwindCSS classes to style your components. They don't provide any React specific components, logic, props, composition, or accessibility features.  

In contrast to these libraries, HeroUI is a complete UI library that provides a set of accessible and customizable components, hooks, and utilities.

### How HeroUI deals with TailwindCSS classes conflicts?

We created a TailwindCSS utility library called tailwind-variants that automatically handles TailwindCSS class conflicts. This ensures your custom classes will consistently override the default ones, eliminating any duplication.

### Does HeroUI use runtime CSS?

No. As HeroUI uses TailwindCSS as its style engine, it generates CSS at build time, eliminating the need for runtime CSS. This means that HeroUI is fully compatible with the latest React and Next.js versions.

### Does HeroUI support TypeScript?

Yes, HeroUI is written in TypeScript and has full support for it.

### Can I use HeroUI with other front-end frameworks or libraries, such as Vue or Angular?

No, HeroUI is specifically designed for React as it is built on top of React Aria. However, you can still use the HeroUI components styling part with other frameworks or libraries.

### Why does HeroUI use Framer Motion?

We use Framer Motion to animate some components due to the complexity of the animations and their physics-based nature. Framer Motion allows us to handle these animations in a more straightforward and performant way. In addition, it is well tested and production ready.

* * *

## Community

We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!

X

For announcements, tips and general information.

Discord

To get involved in the community, ask questions and share tips.

Github

To report bugs, request features and contribute to the project.

## Contributing

PRs on **HeroUI** are always welcome, please see our contribution guidelines to learn how you can contribute to this project.

---

## Page: https://www.heroui.com/docs/components/accordion

# Accordion

Accordion display a list of high-level options that can expand/collapse to reveal more information.

Storybook@heroui/accordionSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 2 accordion-related components:

*   **Accordion**: The main component to display a list of accordion items.
*   **AccordionItem**: The item component to display a single accordion item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### With Subtitle

Preview

Code

Open in Chat

### Expand multiple items

If you set `selectionMode` to `multiple`, then the `Accordion` will allow multiple items to be expanded at the same time.

Preview

Code

Open in Chat

### Compact

If you set `isCompact` to `true`, the `Accordion` will be displayed in a compact style.

Preview

Code

Open in Chat

### Variants

Accordion has 4 variants: `light`, `shadow`, `bordered` and `splitted`.

#### Light variant

Preview

Code

Open in Chat

#### Shadow variant

Preview

Code

Open in Chat

#### Bordered variant

Preview

Code

Open in Chat

#### Splitted variant

Preview

Code

Open in Chat

### Default expanded keys

If you want to expand some items by default, you can set the `defaultExpandedKeys` property to an array of keys.

Preview

Code

Open in Chat

### Disabled keys

If you want to disable some items, you can set the `disabledKeys` property to an array of keys.

Preview

Code

Open in Chat

### Start content

If you want to display some content before the accordion items, you can set the `startContent` property.

Preview

Code

Open in Chat

### Custom Indicator

Accordion items have a property called `indicator`. You can use it to customize the open/close indicator.

Preview

Code

Open in Chat

The indicator can be also a `function`, which receives the `isOpen`, `isDisabled` and the default `indicator` as parameters.

Preview

Code

Open in Chat

### Custom Motion

Accordion offers a `motionProps` property to customize the `enter` / `exit` animation.

Preview

Code

Open in Chat

> Learn more about Framer motion variants here.

### Controlled

Accordion is a controlled component, which means you need to control the `selectedKeys` property by yourself.

Preview

Code

Open in Chat

## Accordion Item Slots

*   **base**: The accordion item wrapper.
*   **heading**: The accordion item heading. It contains the `indicator` and the `title`.
*   **trigger**: The button that open/close the accordion item.
*   **titleWrapper**: The wrapper of the `title` and `subtitle`.
*   **title**: The accordion item title.
*   **subtitle**: The accordion item subtitle.
*   **startContent**: The content before the accordion item.
*   **indicator**: The element that indicates the open/close state of the accordion item.
*   **content**: The accordion item content.

### Custom Accordion Styles

You can customize the accordion and accordion items styles by using any of the following properties:

*   `className`: The class name of the accordion. Modify the accordion wrapper styles.(Accordion)
*   `itemClasses`: The class names of the accordion items. Modify all accordion items styles at once. (Accordion)
*   `classNames`: The class names of the accordion items. Modify each accordion item styles separately. (AccordionItem)

Here's an example of how to customize the accordion styles:

Preview

Code

Open in Chat

## Data Attributes

`AccordionItem` has the following attributes on the `base` element:

*   **data-open**: Whether the accordion item is open.
*   **data-disabled**: When the accordion item is disabled.
*   **data-hover**: When the accordion item is being hovered. Based on useHover.
*   **data-focus**: When the accordion item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the accordion item is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the accordion item is disabled. Based on `isDisabled` prop.
*   **data-pressed**: When the accordion item is pressed. Based on usePress.

## Accessibility

*   Keyboard event support for Space, Enter, Arrow Up, Arrow Down and Home / End keys.
*   Keyboard focus management and cross browser normalization.
*   `aria-expanded` attribute for the accordion item.
*   `aria-disabled` attribute for the accordion item.
*   `aria-controls` attribute for the accordion item.

## API

### Accordion Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode | ReactNode[]   ` |  |
| `variant`

 | `   light | shadow | bordered | splitted   ` | `"light"` |
| `selectionMode`

 | `   none | single | multiple   ` |  |
| `selectionBehavior`

 | `   toggle | replace   ` | `"toggle"` |
| `isCompact`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `showDivider`

 | `   boolean   ` | `true` |
| `dividerProps`

 | `   DividerProps   ` |  |
| `hideIndicator`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `disableIndicatorAnimation`

 | `   boolean   ` | `false` |
| `disallowEmptySelection`

 | `   boolean   ` | `false` |
| `keepContentMounted`

 | `   boolean   ` | `false` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `motionProps`

 | `   MotionProps   ` |  |
| `disabledKeys`

 | `   React.Key[]   ` |  |
| `itemClasses`

 | `   AccordionItemClassnames   ` |  |
| `selectedKeys`

 | `   all | React.Key[]   ` |  |
| `defaultSelectedKeys`

 | `   all | React.Key[]   ` |  |

### Accordion Events

| Prop | Type | Default |
| --- | --- | --- |
| `onSelectionChange`
 | `   (keys: "all" | Set<React.Key>) => any   ` |  |

### Accordion Item Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `title`

 | `   ReactNode   ` |  |
| `subtitle`

 | `   ReactNode   ` |  |
| `indicator`

 | `   IndicatorProps   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `motionProps`

 | `   MotionProps   ` |  |
| `isCompact`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `keepContentMounted`

 | `   boolean   ` | `false` |
| `hideIndicator`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `disableIndicatorAnimation`

 | `   boolean   ` | `false` |
| `HeadingComponent`

 | `   React.ElementType   ` | `"h2"` |
| `classNames`

 | `   AccordionItemClassnames   ` |  |

### Accordion Item Events

| Prop | Type | Default |
| --- | --- | --- |
| `onFocus`
 | `   (e: FocusEvent) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onPress`

 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |
| `onClick`

 | `   MouseEventHandler   ` |  |

* * *

### Types

#### Accordion Item Indicator Props

### Accordion Item classNames

#### Motion Props

---

## Page: https://www.heroui.com/docs/guide/figma

# Figma Kit

HeroUI components recreated in Figma. It includes components, colors, and typography from the HeroUI design system.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

Open in Figma

## What is HeroUI Figma Kit?

HeroUI Figma Kit is a comprehensive design resource that contains the foundation of the HeroUI design system. It helps designers and developers create consistent and beautiful user interfaces using our component library.

> This file is still in development and will be continuously updated.

* * *

## FAQ

### How can I access the Figma Kit?

You can access the HeroUI Figma Kit by clicking the "Open in Figma" button above. The kit is free and available to anyone with a Figma account.

### Is the Figma Kit kept up to date with the component library?

Yes, we strive to keep the Figma Kit synchronized with our component library. However, as noted above, the kit is still in development and continuously being updated.

### Can I use the Figma Kit for my projects?

Yes, you can use the HeroUI Figma Kit for both personal and commercial projects. We encourage you to use it as a starting point for your designs.

### Are the components in the Figma Kit responsive?

The components in the Figma Kit are designed with responsiveness in mind, matching the behavior of our React components. You can find examples of different viewport sizes and component states.

---

## Page: https://www.heroui.com/docs/guide/design-principles

# Design Principles

The development of HeroUI has been guided by a set of specific design and API principles. These principles serve as the foundation for our library and play a crucial role in ensuring the efficiency, effectiveness, and user-friendliness of the components we offer.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

### Simplicity and Usability

Simplicity is the ultimate sophistication. At HeroUI, we believe in delivering simple and intuitive components. Our design process centers around the user, ensuring that we deliver tools that are easy to understand, configure, and implement, regardless of a developer's expertise level.

### Modular Design

Each component in HeroUI is designed as a standalone module. This modular approach allows developers to import and use only what they need, leading to lighter applications and faster load times.

### Customization and Flexibility

HeroUI is designed with customization at its core. Whether it's theming or overriding styles, we provide developers with comprehensive control over the aesthetics of the components. Our integration with the TailwindCSS and Tailwind Variants library and simplifies the customization process and enables an extensive range of design possibilities.

### Consistent API

HeroUI maintains a consistent API across all components. We've ensured that common attributes function identically across different components, allowing developers to anticipate component behavior and thus reducing the learning curve.

### Accessibility

We are committed to ensuring that our components are accessible to all users. In the development of HeroUI, accessibility standards and guidelines have been adhered to, ensuring our components work effectively with assistive technologies. For further information on how to make your web applications more accessible, refer to React Spectrum.

### Component Slots

To provide maximum flexibility, many HeroUI components have `slots`, allowing developers to inject custom styles or content in specific areas of a component. Each slot can be individually styled, offering granular control over the appearance and behavior of the component.

Through these principles, we aim to make HeroUI an effective, efficient, and enjoyable tool for developers to use. As we continue to expand and enhance HeroUI, these guiding principles will remain central to our design and development processes.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

---

## Page: https://www.heroui.com/docs/guide/installation

# Installation

Requirements:

*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Automatic Installation

Using the CLI is now the easiest way to start a HeroUI project. You can initialize your project and add components directly via the CLI:

### Installation

Execute one of the following commands in your terminal:

npm

yarn

pnpm

bun

### Initialization and Starting the App

Initialize the project by using the `init` command.

You will be prompted to configure your project:

Install the dependencies to start the local server:

npm

yarn

pnpm

bun

Start the local server:

npm

yarn

pnpm

bun

### Adding the Components

Once your HeroUI project is ready to develop, you can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

## Manual Installation

If you prefer not to use the CLI, you may try either global installation or individual installation to set up HeroUI in your project:

### Global Installation

The easiest way to get started with HeroUI is to use the global installation, which means that all the components are imported from a single package.

Follow the steps below to install all HeroUI components:

#### Install Packages

To install HeroUI, run one of the following commands in your terminal:

npm

yarn

pnpm

bun

#### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

#### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

#### Provider Setup

It is essential to add the `HeroUIProvider` at the `root` of your application.

### Individual Installation

HeroUI is also available as individual packages. You can install each package separately. This is useful if you want to reduce the size of your CSS bundle as it will only include styles for the components you're actually using.

> **Note**: JavaScript bundle size will not change due to tree shaking support in HeroUI.

Follow the steps below to install each package separately:

#### Install Core Packages

Although you can install each package separately, you need to install the core packages first to ensure that all components work correctly.

Run one of the following commands in your terminal to install the core packages:

npm

yarn

pnpm

bun

#### Install Component

Now, let's install the component you want to use. For example, if you want to use the Button component, you need to run one of the following commands in your terminal:

npm

yarn

pnpm

bun

#### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

#### Tailwind CSS Setup

TailwindCSS setup changes a bit when you use individual packages. You only need to add the styles of the components you're using to your `tailwind.config.js` file. For example, for the Button component, you need to add the following code to your `tailwind.config.js` file:

#### Provider Setup

It is essential to add the `HeroUIProvider` at the `root` of your application.

#### Use the Component

Now, you can use the component you installed in your application:

## Framework Guides

HeroUI is compatible with your preferred framework. We have compiled comprehensive, step-by-step tutorials for the following frameworks:

Next.js

Vite

Remix

Astro

---

## Page: https://www.heroui.com/docs/guide/cli

# CLI

The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to `add`, `remove`, or `upgrade` individual components, assess the health of your project, and more.

## Installation

Requirements:

*   Node.js version 18.17.x or later

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

### Global Installation

To install the `CLI` globally, execute one of the following commands in your terminal:

npm

yarn

pnpm

bun

### Without Installation

Alternatively, you can use the `CLI` without a global installation by running the following command:

npm

yarn

pnpm

bun

## Quick Start

Once the `CLI` is installed, run the following command to display available commands:

This will produce the following help output:

## init

Initialize a new HeroUI project using the `init` command. This sets up your project with the necessary configurations.

You will be prompted to configure your project:

Install the dependencies to start the local server:

npm

yarn

pnpm

bun

Start the local server:

npm

yarn

pnpm

bun

## add

Add components to your HeroUI project with the add command. This command manages component dependencies and updates your project configurations.

Without specifying a specific component:

You will be prompted to select the components you wish to add:

To add a specific component:

You will see an output confirming the addition of the component:

## upgrade

Upgrade all the HeroUI components within your project.

Upgrade specific HeroUI components within your project using the upgrade command to ensure they are up to date.

You will be asked to confirm the upgrade:

Upon confirmation, the command will execute and provide an output similar to:

## remove

Remove components from your HeroUI project with the remove command. This helps in managing the project's component structure and dependencies.

A confirmation prompt will be displayed:

Following confirmation, the output will indicate successful removal:

## list

List all installed HeroUI components in your project with the list command. This provides a clear overview of what is currently included in your project.

The output will detail each component:

## doctor

Diagnose and resolve issues within your project using the doctor command. This ensures your project's health and proper configuration.

Depending on your project's status, you might see:

Or, if issues are detected:

## env

Display detailed information about your project's environment settings using the env command. This includes system, dependencies, and configuration details.

The output will reflect your current environment setup:

## API Reference

Explore the complete CLI commands and features in the API References.

For updates and source code, visit the GitHub Repository.

---

## Page: https://www.heroui.com/docs/guide/routing

# Routing

HeroUI Components such as Tabs, Listbox, Dropdown and many others offer the flexibility to be rendered as **HTML links**.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Introduction

By default, links perform native browser navigation when they are interacted with. However, many apps and frameworks use client side routers to avoid a full page reload when navigating between pages.

The `HeroUIProvider` component configures all HeroUI components within it to navigate using the client side router you provide.

Set this up once in the `root` of your app, and any HeroUI component with the `href` prop will automatically navigate using your router.

## HeroUIProvider Setup

The `HeroUIProvider` component accepts `navigate` and `useHref` props. `navigate` is a router function for client-side navigation, while `useHref` optionally converts router hrefs to native HTML hrefs. Here's the pattern:

> **Note**: Framework-specific examples are shown below.

### Router Options

All `HeroUI` link components accept a `routerOptions` prop that passes options to the router's navigate function for controlling behavior like scrolling and history navigation.

When using TypeScript, you can configure the RouterConfig type globally so that all link components have auto complete and type safety using a type provided by your router.

## Next.js

#### App Router

Go to your `app/providers.tsx` or `app/providers.jsx` (create it if it doesn't exist) and add the `useRouter` hook from `next/navigation`, it returns a router object that can be used to perform navigation.

> Check the Next.js docs for more details.

#### Add the `useRouter`

#### Add Provider to Root

Now, Go to your `root` layout page and wrap it with the `HeroUIProvider`:

> **Note**: Skip this step if you already set up the `HeroUIProvider` in your app.

#### Next.js Base Path (Optional)

If you are using the Next.js basePath setting, you'll need to configure an environment variable to access it.

Then, provide a custom `useHref` function to prepend it to the href for all links.

### Pages Router

Go to pages`/_app.js` or `pages/_app.tsx` (create it if it doesn't exist) and add the`useRouter` hook from `next/router`, it returns a router object that can be used to perform navigation.

When using the basePath configuration option, provide a `useHref` option to the router passed to Provider to prepend it to links automatically.

## React Router

Use the `useNavigate` hook from `react-router-dom` to get the `navigate` function for routing. The `useHref` hook can be used with React Router's `basename` option.

Make sure to place the component using these hooks inside `BrowserRouter` and keep `<Routes>` within `HeroUIProvider`. Here's how to set it up in your App component:

Ensure that the component that calls `useNavigate` and renders `HeroUIProvider` is inside the router component (e.g. `BrowserRouter`) so that it has access to React Router's internal context. The React Router `<Routes>` element should also be defined inside `HeroUIProvider` so that links inside the rendered routes have access to the router.

## Remix

Remix uses React Router under the hood, so the same `useNavigate` and `useHref` hook described above also works in Remix apps. `HeroUIProvider` should be rendered at the `root` of each page that includes HeroUI components, or in `app/root.tsx` to add it to all pages. See the Remix docs for more details.

## TanStack

To use TanStack Router with HeroUI, render HeroUI's RouterProvider inside your root route. Use `router.navigate` in the `navigate` prop, and `router.buildLocation` in the `useHref` prop.

## Usage examples

Now that you have set up the `HeroUIProvider` in your app, you can use the `href` prop in the `Tabs`, `Listbox` and `Dropdown` items to navigate between pages.

The Link component will also use the `navigate` function from the `HeroUIProvider` to navigate between pages.

> For more information about routing in React Aria, visit the React Aria Routing Guide.

---

## Page: https://www.heroui.com/docs/guide/forms

# Forms

HeroUI provides form components with built-in validation and styling to help users input and submit data effectively.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

Preview

Code

## Labels and help text

Accessible forms start with clear, descriptive labels for each field. All HeroUI form components support labeling using the Label component, which is automatically associated with the field via the id and for attributes on your behalf.

In addition, HeroUI components support help text, which associates additional context with a field such as a **description** or **error message**. The label and help text are announced by assistive technology such as screen readers when the user focuses the field.

Most fields should have a visible label. In rare exceptions, the `aria-label` or `aria-labelledby` attribute must be provided instead to identify the element to screen readers.

## Submitting data

How you submit form data depends on your framework, application, and server. By default, **HTML** forms are submitted via a full-page refresh in the browser. You can call `preventDefault` in the `onSubmit` event to handle form data submission via an API.

Frameworks like Next.js, Remix, and React Router provide their own ways to handle form submission.

#### Uncontrolled forms

A simple way to get form data is to use the browser's FormData API during the `onSubmit` event. You can send this data to a backend API or convert it into a JavaScript object using Object.fromEntries. Each field should have a `name` prop to identify it, and the values will be serialized as strings by the browser.

#### Controlled forms

HeroUI form components are uncontrolled by default, but if you need to manage state in real-time, you can use the `useState` hook to make the component controlled.

#### Customizing error messages

By default, error messages are provided by the browser. You can customize these messages by providing a function to the `errorMessage` prop.

> **Note**: The default error messages are localized by the browser based on the browser/operating system language settings. The locale setting in HeroUI Provider does not affect validation errors.

## Validation

Form validation is crucial for ensuring that users enter the correct data. HeroUI supports native HTML constraint validation and allows for custom validation and real-time validation.

#### Built-in validation

HeroUI form components support native HTML validation attributes like `isRequired` and `minLength`. These constraints are checked by the browser when the user commits changes (e.g., on blur) or submits the form. You can display validation errors with custom styles instead of the browser's default UI.

To enable ARIA validation, set `validationBehavior="aria"`. When`validationBehavior="aria"` is set, fields are only marked as required or invalid for assistive technologies, without preventing form submission. You can change the form defaults for your entire app using HeroUI Provider.

Supported constraints include:

*   `isRequired` indicates that a field must have a value before the form can be submitted.
*   `minValue` and `maxValue` specify the minimum and maximum value in a date picker or number input.
*   `minLength` and `maxLength` specify the minimum and length of text input.
*   `pattern` provides a custom regular expression that a text input must conform to.
*   `type="email"` and `type="url"` provide built-in validation for email addresses and URLs.

See each component's documentation for more details on the supported validation props.

#### Custom validation

In addition to built-in constraints, you can provide a function to the `validate` prop to support custom validation.

#### Realtime validation

If you want to display validation errors while the user is typing, you can control the field value and use the `isInvalid` prop along with the `errorMessage` prop.

Use `validationBehavior="aria"` to allow form submission even when fields are invalid, while maintaining accessibility.

#### Server validation

Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. HeroUI allows you to display server-side validation errors by using the `validationErrors` prop in the `Form` component. This prop should be an object where each key is the field `name` and the value is the error message.

#### Schema validation

HeroUI supports errors from schema validation libraries like Zod. You can use Zod's `flatten` method to get error messages for each field and return them as part of the server response.

### React Server Actions

Server Actions that allows seamless form submission to the server and retrieval of results. The useActionState hook can be used to get the result of server actions (such as errors) after submitting a form.

### Remix

Remix actions handle form submissions on the server. You can use the useSubmit hook to submit form data to the server and the useActionData hook to retrieve validation errors from the server.

## Form libraries

In most cases, the built-in validation features of HeroUI are sufficient. However, if you're building more complex forms or integrating HeroUI components into an existing form, you can use a form library like React Hook Form or Formik.

#### React Hook Form

You can integrate HeroUI components using Controller. Controller allows you to manage field values and validation errors, and reflect the validation result in HeroUI components.

> For more information about forms in HeroUI, visit the React Aria Forms Guide.

---

## Page: https://www.heroui.com/docs/guide/tailwind-v4

# Tailwind v4

TailwindCSS v4 is now available in Beta! This guide will help you migrate your existing TailwindCSS v4 project to HeroUI. The demonstration is available at https://beta.heroui.com/.

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Migration Steps

1.  Follow the official Tailwind v4 upgrade guide
2.  Install the `beta` version of HeroUI

CLI

npm

yarn

pnpm

bun

3.  Configure HeroUI with the new Tailwind v4 syntax

### Update CSS Import

#### Without `tailwind.config.js`

Since Tailwind v4 favors a CSS-first approach, `tailwind.config.js` will not be required.

Create `hero.ts` file

Update your main css file

#### With `tailwind.config.js`

In Tailwind v4, `tailwind.config.js` is still supported for backward compatibility. If you still need to use it, you can load it explicity as below.

### Update PostCSS Configuration

### Update Vite Configuration (Vite Projects Only)

## Verification

After migration, verify that:

1.  Your styles are being applied correctly
2.  The build process completes without errors
3.  HeroUI components render as expected

> Make sure to check the Tailwind v4 documentation for any breaking changes that might affect your existing styles.

## Need Help?

If you encounter any issues during migration, please:

*   Join our Discord community
*   Open an issue on our GitHub repository

---

## Page: https://www.heroui.com/docs/guide/nextui-to-heroui

# NextUI to HeroUI

HeroUI is the new identity for NextUI, bringing the same powerful components and features you love under a new name. This guide will help you migrate your existing NextUI project to HeroUI.

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Automatic Migration (Recommended)

The easiest way to migrate your NextUI project to HeroUI is using our official codemod:

### Run Migration

Execute the codemod in your project directory:

npm

yarn

pnpm

bun

> **Note:** If you're using a monorepo, run the codemod from the root directory

This will automatically:

*   Update all package names from `@nextui-org/*` to `@heroui/*`
*   Rename component imports and references
*   Update TailwindCSS configuration
*   Transform provider components
*   Adjust any NextUI-specific utilities or hooks
*   Update `.npmrc` file pnpm only

### Install Dependencies

After running the codemod, install the new dependencies:

npm

yarn

pnpm

bun

## Manual Migration

If you prefer to migrate manually, follow these steps:

### Update Dependencies

Replace NextUI packages with their HeroUI equivalents:

npm

yarn

pnpm

bun

### Update TailwindCSS Configuration

Update your `tailwind.config.js`:

### Update Provider Component

Replace the NextUI provider with HeroUI's provider:

### Update Imports

Update all component imports to use the new package name:

### Individual Packages

If you're using individual packages, update each package name:

### Npmrc Pnpm Only

If you are using pnpm, you need to update your .npmrc file to use the new package name:

## Verification

After migration, verify that:

1.  All components render correctly
2.  Theme customizations are preserved
3.  No NextUI imports remain in your codebase
4.  Your application builds without errors

> The functionality and API of all components remain the same - only the package names and imports have changed.

## Troubleshooting

If you encounter issues during migration, try these steps:

### NPM Users

If you're using `npm`, you may need to:

1.  Delete your `node_modules` folder
2.  Delete your `package-lock.json` file
3.  Reinstall all packages with `npm install`

### Package.json Check

Ensure that no `@nextui-org` packages remain in your `package.json` dependencies or devDependencies.

### Need Help?

Join our Discord community in the **#nextui-to-heroui** channel https://discord.gg/9b6yyZKmH4 - our team is happy to help!

* * *

If you encounter any issues during migration, please open an issue on our GitHub repository.

---

## Page: https://www.heroui.com/docs/frameworks/nextjs

# Next.js

Requirements:

*   Next.js 12 or later
*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

To use HeroUI in your Next.js project, you need to follow the steps below, depending on your project structure.

## App Directory Setup

Next.js 13's `app/` directory uses Server Components by default. HeroUI components can be imported directly in Server Components since we add `use client` at build time.

### HeroUI CLI (recommended)

If you are starting a new project, you can use the HeroUI CLI to create a new project with HeroUI pre-configured:

or

npm

yarn

pnpm

bun

### create-next-app

If you are starting a new project, you can run one of the following commands to create a Next.js project pre-configured with HeroUI:

npm

yarn

pnpm

bun

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

You still need to add the provider to your app manually (we are working on automating this step).

### Manual Installation

### Add dependencies

In your Next.js project, run one of the following commands to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Setup Provider

Go to your `app/providers.tsx` or `app/providers.jsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider`:

### Add Provider to Root

Now, Go to your `root` layout page and wrap it with the `Providers`:

> **Note**: HeroUI automatically adds two themes, `light` and `dark`, to your application. You can use any of them by adding the `dark`/`light` class to the `html` tag. See the theme docs for more details.

### Use HeroUI Components

Now you can import any HeroUI component directly in your Server Components without needing to use the `use client;` directive:

> **Important 🚨**: Note that you need to import the component from the individual package, not from `@heroui/react`.

* * *

## Pages Directory Setup

### HeroUI CLI (recommended)

If you are starting a new project, you can use the HeroUI CLI to create a new project with HeroUI pre-configured:

If you are using the `/pages` Next.js project structure, you need to follow the steps below.

### create-next-app

If you are starting a new project, you can run one of the following commands to create a Next.js project pre-configured with HeroUI:

npm

yarn

pnpm

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

You still need to add the provider to your app manually (we are working on automating this step).

### Manual Installation

### Add dependencies

In your Next.js project, run one of the following commands to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Setup Provider

Go to pages`/_app.js` or `pages/_app.tsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider`:

### Use HeroUI Components

Now you can import any HeroUI component wherever you want:

---

## Page: https://www.heroui.com/docs/frameworks/vite

# Vite

Requirements:

*   Vite 2 or later
*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

To use HeroUI in your Vite project, you need to follow the following steps:

### HeroUI CLI (recommended)

If you are starting a new project, you can use the HeroUI CLI to create a new project with HeroUI pre-configured:

npm

yarn

pnpm

bun

### Using HeroUI + Vite template

If you are starting a new project, you can run one of the following commands to create a Vite project pre-configured with HeroUI:

npm

yarn

pnpm

bun

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

You still need to add the provider to your app manually (we are working on automating this step).

### Manual Installation

### Add dependencies

In your Vite React project, run one of the following command to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Provider Setup

After installing HeroUI, you need to set up the `HeroUIProvider` at the `root` of your application.

Go to the src directory and inside `main.jsx` or `main.tsx`, wrap `HeroUIProvider` around App:

---

## Page: https://www.heroui.com/docs/frameworks/remix

# Remix

Requirements:

*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

To use HeroUI in your Remix project, you need to follow the following steps:

### Using HeroUI + Remix template

If you are starting a new project, you can run one of the following commands to create a Remix project pre-configured with HeroUI:

npm

yarn

pnpm

bun

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

You still need to add the provider to your app manually (we are working on automating this step).

### Manual Installation

### Add dependencies

In your Remix project, run one of the following command to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Provider Setup

After installing HeroUI, you need to set up the `HeroUIProvider` at the `root` of your application.

Go to the src directory and inside `root.tsx`, wrap `HeroUIProvider` around App:

---

## Page: https://www.heroui.com/docs/frameworks/astro

# Astro

Requirements:

*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

To use HeroUI in your Astro project, you need to follow the following steps:

### Install React

HeroUI is built on top of React, so you need to install React first. You can follow the official integration guide to install React.

### Install HeroUI

In your Astro project, run one of the following command to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.cjs` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Usage

Now you can import HeroUI components and use them in your Astro project:

Note that you have to add `client:visible` to the component to make it visible only on the client side. Otherwise some functionalities of HeroUI components may not work properly.

---

## Page: https://www.heroui.com/docs/frameworks/laravel

# Laravel

Requirements:

*   Laravel 11
*   PHP v8.2
*   React 18 or later
*   Tailwind CSS 3.4 (For Tailwind CSS v4, please refer to our Tailwind v4 Migration Guide)
*   Framer Motion 11.9 or later

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

To use HeroUI in your Laravel project, you need to follow the following steps:

### Using HeroUI + Laravel template

If you are starting a new project, you can run one of the following commands to create a Laravel project pre-configured with HeroUI:

npm

yarn

pnpm

bun

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

Or you can add the main library `@heroui/react` by running the following command:

If you leave out the component name, the CLI will prompt you to select the components you want to add.

You still need to add the provider to your app manually (we are working on automating this step).

### Manual Installation

### Add dependencies

In your Laravel project, run one of the following command to install HeroUI:

npm

yarn

pnpm

bun

### Hoisted Dependencies Setup

> **Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your `tailwind.config.js` file:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Provider Setup

After installing HeroUI, you need to set up the `HeroUIProvider` at the `root` of your application.

Go to the src directory and inside `app.jsx` or `app.tsx`, wrap `HeroUIProvider` around App:

---

## Page: https://www.heroui.com/docs/customization/theme

# Theme

Theming allows you to maintain a consistent look and feel across your application. HeroUI provides theme customization through a TailwindCSS plugin based on tw-colors, enabling you to easily customize colors, layouts and other UI elements.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## What is a Theme?

A theme is a predefined set of colors and layout attributes that ensure visual consistency across your application. It simplifies managing and updating your app's appearance.

## Setup

The first step to using HeroUI's theming capability is adding the `heroui` plugin to your `tailwind.config.js` file. Below is an example of how to do this:

> **Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`

### Usage

After adding the plugin to your `tailwind.config.js` file, you can utilize any of the default themes (light/dark) or a custom one. Here's how you can apply these themes in your `main.jsx` or `main.tsx`:

Go to the src directory and inside `main.jsx` or `main.tsx`, apply the following class names to the root element:

*   `light` for the light theme.
*   `dark` for the dark theme.
*   `text-foreground` to set the text color.
*   `bg-background` to set the background color.

> **Note**: See the Colors section to learn more about the color classes.

### Default Plugin Options

The `heroui` plugin provides a default structure. It is outlined as follows:

### Themes Options

These are the options that you can use to apply custom configurations to your themes.

### Nested themes

HeroUI supports nested themes, allowing you to apply different themes to different sections of your application:

### Theme based variants

HeroUI enables you to apply TailwindCSS styles based on the currently active theme. Below are examples of how to do this:

### API Reference

The following table provides an overview of the various attributes you can use when working with themes in HeroUI:

| Attribute | Type | Description | Default |
| --- | --- | --- | --- |
| prefix | `string` | The prefix for the css variables. | `heroui` |
| addCommonColors | `boolean` | If true, the common heroui colors (e.g. "blue", "green", "purple") will replace the TailwindCSS default colors. | `false` |
| defaultTheme | `light` | `dark` | The default theme to use. | `light` |
| defaultExtendTheme | `light` | `dark` | The default theme to extend. | `light` |
| layout | LayoutTheme | The layout definitions. | \- |
| themes | ConfigThemes | The theme definitions. | \- |

### Types

#### ConfigThemes

#### LayoutTheme

#### ThemeColors

---

## Page: https://www.heroui.com/docs/customization/layout

# Layout

HeroUI provides layout customization options for spacing, fonts, and other visual properties. Layout tokens help maintain consistency across components without modifying Tailwind CSS defaults.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

> Layout options are applied to all components.

## Default Layout

Default values for the layout tokens are:

### CSS Variables

HeroUI creates CSS variables using the format `--prefix-prop-name-scale` for each layout token. By default the prefix is `heroui`, but you can change it with the `prefix` option.

Then you can use the CSS variables in your CSS files.

#### API Reference

| Attribute | Type | Description |
| --- | --- | --- |
| hoverOpacity | string, number | A number between 0 and 1 that is applied as opacity-\[value\] when the component is hovered. |
| disabledOpacity | string, number | A number between 0 and 1 that is applied as opacity-\[value\] when the component is disabled. |
| dividerWeight | string | The default height applied to the divider component. We recommend to use `px` units. |
| fontSize | FontThemeUnit | The default font size applied across the components. |
| lineHeight | FontThemeUnit | The default line height applied across the components. |
| radius | BaseThemeUnit | The default radius applied across the components. We recommend to use `rem` units. |
| borderWidth | BaseThemeUnit | The border width applied across the components. |
| boxShadow | BaseThemeUnit | The box shadow applied across the components. |

#### BaseThemeUnit

#### FontThemeUnit

---

## Page: https://www.heroui.com/docs/customization/colors

# Colors

HeroUI's plugin enables you to personalize the semantic colors of the theme such as `primary`, `secondary`, `success`, etc.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

> **Note**: Colors configurations apply globally across all components.

## Default Colors

HeroUI offers a default color palette right out of the box, perfect for when you're still undecided about your specific branding colors.

These colors are split into Common Colors and Semantic Colors.

*   Common Colors: Consistent across themes.
*   Semantic Colors: Adjust according to the chosen theme.

### Common Colors

Common colors, like TailwindCSS colors, remain consistent regardless of the theme.

To prevent conflicts with TailwindCSS colors, common colors are initially disabled but can be activated with the `addCommonColors` option.

Enabling this option supplements some TailwindCSS default colors with the following:

## White & Black

#FFFFFF#000000

## Blue

#E6F1FE50#CCE3FD100#99C7FB200#66AAF9300#338EF7400#006FEE500#005BC4600#004493700#002E62800#001731900

## Purple

#F2EAFA50#E4D4F4100#C9A9E9200#AE7EDE300#9353D3400#7828C8500#6020A0600#481878700#301050800#180828900

## Green

#E8FAF050#D1F4E0100#A2E9C1200#74DFA2300#45D483400#17C964500#12A150600#0E793C700#095028800#052814900

## Red

#FEE7EF50#FDD0DF100#FAA0BF200#F871A0300#F54180400#F31260500#C20E4D600#920B3A700#610726800#310413900

## Pink

#FFEDFA50#FFDCF5100#FFB8EB200#FF95E1300#FF71D7400#FF4ECD500#CC3EA4600#992F7B700#661F52800#331029900

## Yellow

#FEFCE850#FDEDD3100#FBDBA7200#F9C97C300#F7B750400#F5A524500#C4841D600#936316700#62420E800#312107900

## Cyan

#F0FCFF50#E6FAFE100#D7F8FE200#C3F4FD300#A5EEFD400#7EE7FC500#06B7DB600#09AACD700#0E8AAA800#053B48900

## Zinc

#FAFAFA50#F4F4F5100#E4E4E7200#D4D4D8300#A1A1AA400#71717A500#52525B600#3F3F46700#27272A800#18181B900

### Semantic Colors

Semantic colors adapt with the theme, delivering meaning and reinforcing your brand identity.

For an effective palette, we recommend using color ranges from `50` to `900`. You can use tools like Eva Design System, Smart Watch, Palette or Color Box to generate your palette.

> Semantic colors should be placed inside the `heroui` plugin options, not inside the TailwindCSS theme object.

> Change the docs theme to see the semantic colors in action.

## Layout

backgroundforegrounddividerfocus

## Content

content1content2content3content4

## Base

defaultprimarysecondarysuccesswarningdanger

## Default

default-50default-100default-200default-300default-400default-500default-600default-700default-800default-900

## Primary

primary-50primary-100primary-200primary-300primary-400primary-500primary-600primary-700primary-800primary-900

## Secondary

secondary-50secondary-100secondary-200secondary-300secondary-400secondary-500secondary-600secondary-700secondary-800secondary-900

## Success

success-50success-100success-200success-300success-400success-500success-600success-700success-800success-900

## Warning

warning-50warning-100warning-200warning-300warning-400warning-500warning-600warning-700warning-800warning-900

## Danger

danger-50danger-100danger-200danger-300danger-400danger-500danger-600danger-700danger-800danger-900

### Using Semantic Colors

Semantic colors can be applied anywhere in your project where colors are used, such as text color, border color, background color utilities, and more.

### Javascript Variables

Import semantic and common colors into your JavaScript files as follows:

### CSS Variables

HeroUI creates CSS variables using the format `--prefix-colorname-shade` for each semantic color. By default the prefix is `heroui`, but you can change it with the `prefix` option.

Then you can use the CSS variables in your CSS files.

---

## Page: https://www.heroui.com/docs/customization/customize-theme

# Customize theme

HeroUI provides `light` and `dark` themes that can be customized to match your needs. You can also create custom themes based on these defaults, using Layout and Color tokens.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Customizing Layout

Layout tokens let you customize spacing, typography, borders and more - either globally or per theme.

### Global Layout Customization

You can customize border radius, border width, and disabled opacity across all themes by modifying your `tailwind.config.js` file:

Layout tokens are used across all HeroUI components. For example, the Button component uses `radius` and `borderWidth` tokens for its styling. Here's how it looks with the customized values:

> See the Layout section for more details about the available tokens.

### Customizing Colors

Now, Let's say you wish to modify the primary and focus colors of the dark theme. This can be achieved by adding the following code to your `tailwind.config.js` file.

This modification will impact all components using the `primary` color. For instance, the Button component uses the `primary` color as background color when the variant is `solid` or `ghost`.

> 🎉 That's it! You have successfully customized the default theme. See the Colors section for more details about the available semantic colors and color tokens.

---

## Page: https://www.heroui.com/docs/customization/create-theme

# Create theme

Create a new theme by adding it to your `tailwind.config.js` file. For color palettes (50-900), you can use tools like Eva Design System or Smart Watch to generate them.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

### Add the new theme to the plugin

### Apply the new theme

Now, applying the new theme is as simple as adding the theme name `purple-dark` to the `className` of the `html` / `body` or `main` element.

### Use the new theme

All components that use the `primary` color will be affected by this change.

---

## Page: https://www.heroui.com/docs/customization/dark-mode

# Dark mode

HeroUI supports both `light` and `dark` themes. To enable dark mode, simply add the `dark` class to your root element (`html`, `body`, or `main`).

This enables dark mode application-wide. For theme switching functionality, you can use a theme library or create a custom implementation.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Using next-themes

For Next.js applications, next-themes provides seamless theme switching functionality.

> For more information, refer to the next-themes documentation.

### Next.js App Directory Setup

### Install next-themes

Install `next-themes` in your project.

npm

yarn

pnpm

### Add next-themes provider

Wrap your app with the `ThemeProvider` component from `next-themes`.

Go to your `app/providers.tsx` or `app/providers.jsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider` and the `next-themes` provider components.

> Note: We're using the `class` attribute to switch between themes, this is because HeroUI uses the `className` attribute.

### Add the theme switcher

Add the theme switcher to your app.

> **Note**: You can use any theme name you want, but make sure it exists in your `tailwind.config.js` file. See Create Theme for more details.

### Next.js Pages Directory Setup

### Install next-themes

Install `next-themes` in your project.

npm

yarn

pnpm

### Add next-themes provider

Go to pages`/_app.js` or `pages/_app.tsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider` and the `next-themes` provider components.

> Note: We're using the `class` attribute to switch between themes, this is because HeroUI uses the `className` attribute.

### Add the theme switcher

Add the theme switcher to your app.

> **Note**: You can use any theme name you want, but make sure it exists in your `tailwind.config.js` file. See Create Theme for more details.

## Using use-theme hook

In case you're using plain React with Vite or Create React App you can use the @heroui/use-theme hook to switch between themes.

### Install @heroui/use-theme

Install `@heroui/use-theme` in your project.

npm

yarn

pnpm

### Add the theme switcher

Add the theme switcher to your app.

> **Note**: You can use any theme name you want, but make sure it exists in your `tailwind.config.js` file. See Create Theme for more details.

---

## Page: https://www.heroui.com/docs/customization/override-styles

# Override styles

Overriding default component styles is as simple as passing your own class names to the `className` or to the `classNames` prop for components with slots.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

### What is a Slot?

A slot is a part of a component that can be styled separately using the `classNames` prop. For example, the CircularProgress component has slots like `track`, `indicator`, and `value` that can each be styled independently.

### Overriding a component

Let's override the default styles of the Button component, which is a component that has no slots.

### Components with slots

Some HeroUI components have slots that can be styled individually using the `classNames` prop. The CircularProgress component has the following slots:

*   **base**: The base slot of the circular progress, it is the main container.
*   **svgWrapper**: The wrapper of the svg circles and the value label.
*   **svg**: The svg element of the circles.
*   **track**: The track is the background circle of the circular progress.
*   **indicator**: The indicator is the one that is filled according to the `value`.
*   **value**: The value content.
*   **label**: The label content.

The example below demonstrates styling these slots to create a custom circular progress:

> **Note**: You will find a `Slots` section in the documentation of each component that has slots.

### CSS Modules

CSS Modules allow for the creation of local scope classes and variables. Here's how you can use it to override styles:

With the corresponding CSS module:

### CSS-in-JS

If you are using a CSS-in-JS library such as styled-components or emotion, you can use the following example to override the styles of a component:

Each styled component combines the original component styles with custom styles defined in the template strings. The `StyledCircularProgress` uses `.attrs` to add classNames.

---

## Page: https://www.heroui.com/docs/customization/custom-variants

# Custom Variants

HeroUI allows you to create new variants for components by extending and customizing their styles. You can override the component's `variants`, `defaultVariants` and `compoundVariants`.

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

> **Note**: For one-off customizations, refer to the Override Styles documentation.

## Creating new variants for non-slots components

Let's use the Button component as an example. It's a non-slots component, and you can view its source styles here.

> **Note**: If you are not familiar with the variants concept, please refer to the Tailwind Variants documentation.

### Extend the original component variants

Use the `extendVariants` function to create a new component with customized variants based on an existing component.

### Use your custom component in your application

Then, you can now use your custom component in your application. Here, `MyButton` is used with the color set to `olive` and the size set to `xl`.

The new component will include the original props of the `Button` component, plus the new variants that you have created.

## Creating new variants for slots components

The `extendVariants` function can also be used with slot-based components like Input to add or override variants. You can view the Input component's source styles here.

> **Note**: If you are not familiar with the variants/slots concept, please refer to the Tailwind Variants documentation.

### Extend the original component variants

Use the `extendVariants` function to create a new component with custom variants based on the original component.

### Use your custom component in your application

Then, you can now use your custom component in your application. Here, `MyInput` is used with the color set to `slate` and the size set to `xl`.

The new component will include the original props of the Input component, plus the new variants that you have created.

> Use the `Styles source` link at the top of each component page to view its source code as a reference for customization.

### Types

### Main Function

### Options

### Config

> **Note**: See the Tailwind Merge Config to learn more about it.

---

## Page: https://www.heroui.com/docs/components/autocomplete

# Autocomplete

An autocomplete combines a text input with a listbox, allowing users to filter a list of options to items matching a query.

Storybook@heroui/autocompleteReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 autocomplete-related components:

*   **Autocomplete**: The main component, which is a wrapper for the other components.
*   **AutocompleteSection**: The component that contains a group of autocomplete items.
*   **AutocompleteItem**: The component that represents a autocomplete item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic items

Autocomplete follows the Collection Components API, accepting both static and dynamic collections.

*   **Static**: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
*   **Dynamic**: The example below can be used when the options come from an external data source such as an API call, or update over time.

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Disabled Items

You can disable specific items by using the `disabledKeys` property.

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the autocomplete, it will have a `danger` asterisk at the end of the label and the autocomplete will be required.

Preview

Code

Open in Chat

### Read Only

If you pass the `isReadOnly` property to the Autocomplete, the Listbox will open to display all available options, but users won't be able to select any of the listed options.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Start Content

You can use the `startContent` and `endContent` properties to add content to the start and end of the autocomplete.

Preview

Code

Open in Chat

### Item Start & End Content

Since the `Autocomplete` component uses the Listbox component under the hood, you can use the `startContent` and `endContent` properties of the `AutocompleteItem` component to add content to the start and end of the autocomplete item.

Preview

Code

Open in Chat

### Custom Value

By default, `Autocomplete` doesn't allow users to specify a value that doesn't exist in the list of options and will revert the input value to the current selected value on blur. By specifying `allowsCustomValue`, this behavior is suppressed and the user is free to enter any value within the field.

Preview

Code

Open in Chat

### Custom Selector Icon

By default, `Autocomplete` uses a `chevron-down` icon as the selector icon which rotates when the autocomplete is open. You can customize this icon by passing a custom one to the `selectorIcon` property.

Preview

Code

Open in Chat

> **Note**: Use the `disableSelectorIconRotation` property to disable the rotation of the icon.

### Without Scroll Shadow

Autocomplete component uses the ScrollShadow under the hood to show a shadow when the autocomplete content is scrollable. You can disable this shadow by passing using the `scrollShadowProps` property.

Preview

Code

Open in Chat

> **Note**: You can also use the `showScrollIndicators` property to disable the scroll indicators.

### With Description

You can add a description to the autocomplete by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid autocomplete.

Preview

Code

Open in Chat

### Events

The `Autocomplete` component supports selection via mouse, keyboard, and touch. You can handle all of these via the `onSelectionChange` prop. `Autocomplete` will pass the selected key to the onSelectionChange handler. Additionally, ComboBox accepts an `onInputChange` prop which is triggered whenever the value is edited by the user, whether through typing or option selection.

The example below uses `onSelectionChange` and `onInputChange` to update the selection and input value stored in React state.

Preview

Code

Open in Chat

### Controlled

You can use the `selectedKey` and `onSelectionChange` properties to control the select value.

Preview

Code

Open in Chat

### Fully Controlled

By passing in `inputValue`, `selectedKey`, and `items` to the `Autocomplete` you can control exactly what your `Autocomplete` should display.

The following example shows how you would create a controlled `Autocomplete`, controlling everything from the selected value `selectedKey` to the combobox options `items`.

We recommend using the `useFilter` hook from @react-aria/i18n to manage the filtering of the items.

npm

yarn

pnpm

> **Note**: It is important to note that you don't have to control every single aspect of a `Autocomplete`. If you decide to only control a single property of the `Autocomplete`, be sure to provide the change handler for that prop as well e.g. controlling `selectedKey` would require `onSelectionChange`.

### Custom Items

You can customize the autocomplete items by modifying the `AutocompleteItem` children.

Preview

Code

Open in Chat

### Custom Empty Content Message

By default, a message `No results found.` will be shown if there is no result matching a query with your filter. You can customize the empty content message by modifying the `emptyContent` in `listboxProps`.

Preview

Code

Open in Chat

### Custom Filtering

By default, `Autocomplete` uses a `"contains"` function from useFilter to filter the list of options. This can be overridden using the `defaultFilter` prop, or by using the `items` prop to control the filtered list. When `items` is provided rather than `defaultItems`, `Autocomplete` does no filtering of its own.

The following example uses the `defaultFilter` prop to filter the list of options using a custom filter function.

Preview

Code

Open in Chat

### Asynchronous Filtering

Autocomplete supports asynchronous filtering, in the example below we are using the useAsyncList function from react-aria to handle asynchronous loading and filtering of data from a server.

npm

yarn

pnpm

### Asynchronous Loading

Autocomplete supports asynchronous loading, in the example below we are using a custom hook to fetch the Pokemon API data in combination with the `useInfiniteScroll` hook to load more data when the user reaches the end of the list.

The `isLoading` prop is used to show a loading indicator instead of the selector icon when the data is being fetched.

npm

yarn

pnpm

### Virtualization

Autocomplete supports virtualization, in the example below we are using the `isVirtualized` prop to enable virtualization.

Preview

Code

Open in Chat

> **Note**: The virtualization strategy is based on the @tanstack/react-virtual package, which provides efficient rendering of large lists by only rendering items that are visible in the viewport.

#### Ten Thousand Items

Virtualization with 10,000 items.

Preview

Code

Open in Chat

#### Max Listbox Height

The `maxListboxHeight` prop is used to set the maximum height of the listbox. This is required when using virtualization. By default, it's set to `256`.

Preview

Code

Open in Chat

#### Custom Item Height

The `itemHeight` prop is used to set the height of each item in the listbox. This is required when using virtualization. By default, it's set to `32`.

> **Note**: If the height of the list items differs from the default due to `startContent` or other custom content, be sure to pass the correct value to `itemHeight` to prevent layout issues.

Preview

Code

Open in Chat

### With Sections

You can use the `AutocompleteSection` component to group autocomplete items.

Preview

Code

Open in Chat

### Custom Sections Style

You can customize the sections style by using the `classNames` property of the `AutocompleteSection` component.

Preview

Code

Open in Chat

### Customizing the Autocomplete

You can customize any slot of the autocomplete by using the `classNames` property. Autocomplete component also provides the popoverProps, listboxProps, inputProps properties to customize the popover, listbox and input components.

Preview

Code

Open in Chat

## Slots

*   **base**: The main wrapper of the autocomplete. This wraps the input and popover components.
*   **listboxWrapper**: The wrapper of the listbox. This wraps the listbox component, this slot is used on top of the scroll shadow component.
*   **listbox**: The listbox component. This is the component that wraps the autocomplete items.
*   **popoverContent**: The popover content slot. Use this to modify the popover content styles.
*   **endContentWrapper**: The wrapper of the end content. This wraps the clear button and selector button.
*   **clearButton**: The clear button slot.
*   **selectorButton**: The selector button slot.

## Data Attributes

`Autocomplete` has the following attributes on the `base` element:

*   **data-invalid**: When the autocomplete is invalid. Based on `isInvalid` prop.
*   **data-open**: Indicates if the autocomplete's popover is open.

`Autocomplete` has the following attributes on the `selectorButton` element:

*   **data-open**: Indicates if the autocomplete's popover is open.

`Autocomplete` has the following attributes on the `clearButton` element:

*   **data-visible**: Indicates if the autocomplete's clear button is visible. By default it is visible when hovering the autocomplete and when the autocomplete has a value (desktop), or when the autocomplete has a value (mobile).

`AutocompleteItem` has the following attributes on the `base` element:

*   **data-disabled**: When the autocomplete item is disabled. Based on autocomplete `disabledKeys` prop.
*   **data-selected**: When the autocomplete item is selected. Based on autocomplete `selectedKey` prop.
*   **data-hover**: When the autocomplete item is being hovered. Based on useHover
*   **data-pressed**: When the autocomplete item is pressed. Based on usePress
*   **data-focus**: When the autocomplete item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the autocomplete item is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Support for filtering a list of options by typing
*   Support for selecting a single option
*   Support for disabled options
*   Support for groups of items in sections
*   Support for custom user input values
*   Support for controlled and uncontrolled options, selection, input value, and open state
*   Support for custom filter functions
*   Async loading and infinite scrolling support
*   Support for virtualized scrolling for performance with long lists
*   Exposed to assistive technology as a combobox with ARIA
*   Labeling support for accessibility
*   Required and invalid states exposed to assistive technology via ARIA
*   Support for mouse, touch, and keyboard interactions
*   Keyboard support for opening the combo box list box using the arrow keys, including automatically focusing the first or last item accordingly
*   Support for opening the list box when typing, on focus, or manually
*   Handles virtual clicks on the input from touch screen readers to toggle the list box
*   Virtual focus management for combo box list box option navigation
*   Hides elements outside the input and list box from assistive technology while the list box is open in a portal
*   Custom localized announcements for option focusing, filtering, and selection using an ARIA live region to work around VoiceOver bugs
*   Support for description and error message help text linked to the input via ARIA

## API

### Autocomplete Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `name`

 | `   string   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `defaultItems`

 | `   Iterable<T>   ` |  |
| `inputValue`

 | `   string   ` |  |
| `defaultInputValue`

 | `   string   ` |  |
| `allowsCustomValue`

 | `   boolean   ` | `false` |
| `allowsEmptyCollection`

 | `   boolean   ` | `true` |
| `shouldCloseOnBlur`

 | `   boolean   ` | `true` |
| `placeholder`

 | `   string   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `menuTrigger`

 | `   focus | input | manual   ` | `"focus"` |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `selectedKey`

 | `   React.Key   ` |  |
| `defaultSelectedKey`

 | `   React.Key   ` |  |
| `disabledKeys`

 | `   all | React.Key[]   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: { inputValue: string, selectedKey: React.Key }) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `defaultFilter`

 | `   (textValue: string, inputValue: string) => boolean   ` |  |
| `filterOptions`

 | `   Intl.CollatorOptions   ` | `"{ sensitivity: 'base'}"` |
| `maxListboxHeight`

 | `   number   ` | `"256"` |
| `itemHeight`

 | `   number   ` | `"32"` |
| `isVirtualized`

 | `   boolean   ` | `"undefined"` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `selectorIcon`

 | `   ReactNode   ` |  |
| `clearIcon`

 | `   ReactNode   ` |  |
| `showScrollIndicators`

 | `   boolean   ` | `true` |
| `scrollRef`

 | `   React.RefObject<HTMLElement>   ` |  |
| `inputProps`

 | `   InputProps   ` |  |
| `popoverProps`

 | `   PopoverProps   ` |  |
| `listboxProps`

 | `   ListboxProps   ` |  |
| `scrollShadowProps`

 | `   ScrollShadowProps   ` |  |
| `selectorButtonProps`

 | `   ButtonProps   ` |  |
| `clearButtonProps`

 | `   ButtonProps   ` |  |
| `isClearable`

 | `   boolean   ` | `true` |
| `disableClearable`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `true` |
| `disableSelectorIconRotation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'listboxWrapper' | 'listbox' | 'popoverContent' | 'endContentWrapper' | 'clearButton' | 'selectorButton', string>>   ` |  |

### Autocomplete Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean, menuTrigger?: MenuTriggerAction) => void   ` |  |
| `onInputChange`

 | `   (value: string) => void   ` |  |
| `onSelectionChange`

 | `   (key: React.Key) => void   ` |  |
| `onFocus`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

* * *

### AutocompleteItem Props

Check the ListboxItem props.

### AutocompleteItem Events

Check the ListboxItem events.

### AutocompleteSection Props

Check the ListboxSection props.

* * *

### Types

#### Menu Trigger Action

---

## Page: https://www.heroui.com/docs/components/alert

# Alert

Alerts are temporary notifications that provide concise feedback about an action or event.

Storybook@heroui/alertSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Colors

Alert comes with 6 color variants to convey different meanings.

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Custom Icon

By default, Alert displays an appropriate icon based on the `color` prop. You can override this by providing a custom icon using the `icon` prop.

Preview

Code

Open in Chat

### Without Icon

You can hide the icon by setting the `hideIcon` prop to `true`.

Preview

Code

Open in Chat

### Without Icon Wrapper

You can hide the icon wrapper by setting the `hideIconWrapper` prop to `true`.

Preview

Code

Open in Chat

### With Action

Alert supports an `endContent` prop for additional actions.

Preview

Code

Open in Chat

### Controlled Visibility

You can control the alert visibility using the `isVisible` and `onVisibleChange` props.

Preview

Code

Open in Chat

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

You can use the `useAlert` hook to create your own alert component.

## Data Attributes

Alert has the following attributes on the `base` element:

*   **data-visible**: When the alert is visible
*   **data-closeable**: When the alert can be closed
*   **data-has-title**: When the alert has a title
*   **data-has-description**: When the alert has a description

### Slots

Alert has the following slots:

*   `base`: The main alert container element
*   `title`: The title element
*   `description`: The description element
*   `mainWrapper`: The wrapper for the title and description content
*   `closeButton`: The close button element
*   `iconWrapper`: The wrapper for the alert icon
*   `alertIcon`: The alert icon element

## Accessibility

*   Alert has role of `alert`
*   Close button has aria-label="Close" by default
*   When closed, alert is removed from the DOM

## API

### Alert Props

| Prop | Type | Default |
| --- | --- | --- |
| `title`
 | `   ReactNode   ` |  |
| `icon`

 | `   ReactNode   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `variant`

 | `   solid | bordered | flat | faded   ` | `"flat"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"md"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `isVisible`

 | `   boolean   ` |  |
| `isClosable`

 | `   boolean   ` | `false` |
| `hideIcon`

 | `   boolean   ` | `false` |
| `hideIconWrapper`

 | `   boolean   ` | `false` |
| `closeButtonProps`

 | `   ButtonProps   ` |  |

### Alert Events

| Prop | Type | Default |
| --- | --- | --- |
| `onClose`
 | `   () => void   ` |  |
| `onVisibleChange`

 | `   (isVisible: boolean) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/avatar

# Avatar

The Avatar component is used to represent a user, and displays the profile picture, initials or fallback icon.

Storybook@heroui/avatarSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 avatar-related components:

*   **Avatar**: The main component to display an avatar.
*   **AvatarGroup**: A wrapper component to display a group of avatars.
*   **AvatarIcon**: The default icon used as fallback when the image fails to load.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Bordered

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Avatar Fallbacks

If there is an error loading the `src` of the avatar, there are 2 fallbacks:

*   If there's a `name` prop, we use it to generate the initials and a random, accessible background color.
*   If there's no `name` prop, we use a default avatar.

If the `showFallback` is not passed, the fallbacks will not be displayed.

Preview

Code

Open in Chat

### Custom Fallback

You can also provide a custom fallback component to be displayed when the `src` fails to load.

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the avatar even further, you can use the `useAvatar` hook to create your own implementation.

### Custom initials logic

It is possible to customize the logic used to generate the initials by passing a function to the `getInitials` prop. By default we merge the first characters of each word in the `name` prop.

## Avatar Group

Preview

Code

Open in Chat

### Group Disabled

Preview

Code

Open in Chat

### Group Max Count

You can limit the number of avatars displayed by passing the `max` prop to the `AvatarGroup` component.

Preview

Code

Open in Chat

### Group Total Count

You can display the total number of avatars by passing the `total` prop to the `AvatarGroup` component.

Preview

Code

Open in Chat

### Group Custom count

`AvatarGroup` provides a `renderCount` prop to customize the count displayed when the `total` prop is passed.

Preview

Code

Open in Chat

### Group Grid

By passing the `isGrid` prop to the `AvatarGroup` component, the avatars will be displayed in a grid layout.

Preview

Code

Open in Chat

### Group Custom Implementation

In case you need to customize the avatar group even further, you can use the `useAvatarGroup` hook and the `AvatarGroupProvider` to create your own implementation.

## Slots

*   **base**: Avatar wrapper, it includes styles for focus ring, position, and general appearance.
*   **img**: Image element within the avatar, it includes styles for opacity transition and size.
*   **fallback**: Fallback content when the image fails to load or is not provided, it includes styles for centering the content.
*   **name**: Initials displayed when the image is not provided or fails to load, it includes styles for font, text alignment, and inheritance.
*   **icon**: Icon element within the avatar, it includes styles for centering the content, text inheritance, and size.

### Custom Avatar Styles

You can customize any part of the avatar by using the `classNames` prop, each `slot` has its own `className`.

Preview

Code

Open in Chat

## Data Attributes

`Avatar` has the following attributes on the `base` element:

*   **data-hover**: When the avatar is being hovered. Based on useHover
*   **data-focus**: When the avatar is being focused. Based on useFocusRing, it is applied when `isFocusable` is `true` or when the `as` property is assigned as `button`.
*   **data-focus-visible**: When the avatar is being focused with the keyboard. Based on useFocusRing, it is applied when `isFocusable` is `true` or when the `as` property is assigned as `button`.

## API

### Avatar Props

| Prop | Type | Default |
| --- | --- | --- |
| `src`
 | `   string   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"full"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `name`

 | `   string   ` |  |
| `icon`

 | `   ReactNode   ` |  |
| `fallback`

 | `   ReactNode   ` |  |
| `isBordered`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isFocusable`

 | `   boolean   ` | `false` |
| `showFallback`

 | `   boolean   ` | `false` |
| `ImgComponent`

 | `   React.ElementType   ` | `"img"` |
| `imgProps`

 | `   ImgComponentProps   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "img" | "fallback" | "name" | "icon", string>>   ` |  |

### Avatar Group Props

| Prop | Type | Default |
| --- | --- | --- |
| `max`
 | `   number   ` | `"5"` |
| `total`

 | `   number   ` |  |
| `size`

 | `   AvatarProps['size']   ` |  |
| `color`

 | `   AvatarProps['color']   ` |  |
| `radius`

 | `   AvatarProps['radius']   ` |  |
| `isGrid`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` |  |
| `isBordered`

 | `   boolean   ` |  |
| `renderCount`

 | `   (count: number) => ReactNode   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "count", string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/badge

# Badge

Badges are used as a small numerical value or status descriptor for UI elements.

Storybook@heroui/badgeSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Placements

Preview

Code

Open in Chat

### Shapes

For a better positioning, you can use the `shape` property to define the shape of the badge.

Preview

Code

Open in Chat

### Badge Visibility

You can control the visibility of the badge by using the `isInvisible` property.

Preview

Code

Open in Chat

### Content Examples

Preview

Code

Open in Chat

### Disable Outline

By default, the badge has an outline, you can disable it by using the `showOutline={false}` property.

Preview

Code

Open in Chat

### Accessibility

It's not advisable to depend on the badge's content for accurate announcement. Instead, consider supplying a comprehensive description, such as using `aria-label`.

Preview

Code

Open in Chat

## Slots

The Badge component has two slots:

*   **base**: The base slot for the badge, which is the container of the badge.
    
*   **badge**: The main slot for the badge content, which is the content of the badge.
    

## API

### Badge Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `content`

 | `   string | number | ReactNode   ` |  |
| `variant`

 | `   solid | flat | faded | shadow   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `shape`

 | `   circle | rectangle   ` | `"rectangle"` |
| `placement`

 | `   top-right | top-left | bottom-right | bottom-left   ` | `"top-right"` |
| `showOutline`

 | `   boolean   ` | `true` |
| `disableOutline`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `isInvisible`

 | `   boolean   ` | `false` |
| `isOneChar`

 | `   boolean   ` | `false` |
| `isDot`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base"｜"badge", string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/breadcrumbs

# Breadcrumbs

Breadcrumbs display a hierarchy of links to the current page or resource in an application.

Storybook@heroui/breadcrumbsSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 2 breadcrumb-related components:

*   **Breadcumbs**: The main component, which is a wrapper for the other components.
*   **BreadcrumbItem**: The component that represents a breadcrumb item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Disabled breadcrumbs display items but prevent navigation, ensuring a consistent layout. The last item, signifying the current page, isn't disabled.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Underlines

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Routing

The `<BreadcrumbItem>` component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

Preview

Code

Open in Chat

### Controlled

You can control the current/active item by using the `isCurrent` and `onAction` props.

Preview

Code

Open in Chat

> **Note**: If needed you can use the `onPress` prop to handle the click event on the breadcrumb item.

### Menu Type

It is possible to use the `Breadcrumbs` component as a horizontal menu. This is useful when you want to display a list of possible navigations and let the user choose one of them.

Preview

Code

Open in Chat

### Start & End Content

You can add any element to the start or end of the breadcrumbs by using the `startContent` and `endContent` props. The above example uses the `startContent` prop to add icons to the start of the breadcrumbs.

Preview

Code

Open in Chat

### Custom Separator

You can customize the separator between breadcrumbs by using the `separator` prop.

Preview

Code

Open in Chat

### Custom Items

the `BreadcrumbItem` component accepts any element as its children. This allows you to customize the appearance of the breadcrumb items.

The above example uses the Dropdown component to create a dropdown menu in the breadcrumb.

Preview

Code

Open in Chat

The `Breadcrumbs` component picks only the `BreadcrumbItem` components as its children. This means that you cannot place any other component directly inside the `Breadcrumbs` component.

### Collapsing Items

The `Breadcrumb` component provides 3 props to control the collapsing of items:

*   `maxItems`: Specifies the maximum number of breadcrumbs to display. When there are more than the maximum number, only the first `itemsBeforeCollapse` and last `itemsAfterCollapse` will be shown, with an ellipsis in between.
*   `itemsBeforeCollapse`: If max items is exceeded, the number of items to show before the ellipsis.
*   `itemsAfterCollapse`: If max items is exceeded, the number of items to show after the ellipsis.

Preview

Code

Open in Chat

> **Note**: The ellipsis item will use the first collapsed item as its `href` prop.

### Customizing the Ellipsis Item

You can customize the ellipsis item by using the `renderEllipsis` prop. This prop accepts a function that returns a React element.

Preview

Code

Open in Chat

## Slots

*   Breadcrumbs Slots
    
*   **base**: The main slot for the breadcrumbs. It wraps the `list` slot.
    
*   **list**: The list of breadcrumbs wrapper.
    
*   **ellipsis**: The slot for the ellipsis item. This is only visible when the breadcrumbs are collapsed.
    
*   **separator**: The slot for the custom separator, the one that can be set using the `separator` prop.
    
*   BreadcrumbItem Slots
    
*   **base**: The main slot for the breadcrumb item. It wraps the `item` slot.
    
*   **item**: The breadcrumb item wrapper.
    
*   **separator**: The slot for the item separator.
    

### Customizing the Breadcrumbs Styles

You can customize the `Breadcrumbs` style by using the `classNames` prop and its items by using the `itemClasses` prop.

Preview

Code

Open in Chat

## Data Attributes

`BreadcrumbItem` has the following attributes on the `item` element:

*   **data-current**: When the breadcrumb item is the current item. Based on breadcrumb `isCurrent` prop or on whether the item is the last one.
*   **data-disabled**: When the breadcrumb item is disabled. Based on breadcrumb `isDisabled` prop.
*   **data-focus**: When the breadcrumb item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the breadcrumb item is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Implemented as an ordered list of items.
*   Support for mouse, touch, and keyboard interactions on breadcrumbs.
*   Support for navigation links via `<a>` elements or custom element types via ARIA.
*   Localized ARIA labeling support for landmark navigation region.
*   Support for disabled breadcrumbs.
*   The last item is automatically marked as the current page using `aria-current`.

## API

### Breadcrumbs Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `variant`

 | `   solid | bordered | light   ` | `"solid"` |
| `color`

 | `   foreground | primary | secondary | success | warning | danger   ` | `"foreground"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `underline`

 | `   none | active | hover | focus | always   ` | `"none"` |
| `separator`

 | `   ReactNode   ` |  |
| `maxItems`

 | `   number   ` |  |
| `itemsBeforeCollapse`

 | `   number   ` |  |
| `itemsAfterCollapse`

 | `   number   ` |  |
| `hideSeparator`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `itemClasses`

 | `   Partial<Record<"base" | "item" | "separator", string>>   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "list" | "ellipsis" | "separator", string>>   ` |  |

### Breadcrumbs Events

| Prop | Type | Default |
| --- | --- | --- |
| `onAction`
 | `   (key: React.Key) => void   ` |  |

### BreadcrumbItem Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `color`

 | `   foreground | primary | secondary | success | warning | danger   ` | `"foreground"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `underline`

 | `   none | active | hover | focus | always   ` | `"none"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `separator`

 | `   ReactNode   ` |  |
| `isCurrent`

 | `   boolean   ` | `false` |
| `isLast`

 | `   boolean   ` | `false` |
| `hideSeparator`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "item" | "separator", string>>   ` |  |

### BreadcrumbItem Events

| Prop | Type | Default |
| --- | --- | --- |
| `onPress`
 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |

### Types

#### Render Ellipsis Function

---

## Page: https://www.heroui.com/docs/components/button

# Button

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

Storybook@heroui/buttonReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 2 button-related components:

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

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Loading

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

Preview

Code

Open in Chat

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

Preview

Code

Open in Chat

### With Icons

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

Preview

Code

Open in Chat

### Icon Only

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

Preview

Code

Open in Chat

### Custom Styles

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

Preview

Code

Open in Chat

> 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

Preview

Code

Open in Chat

### Group Disabled

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

Preview

Code

Open in Chat

### 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`.

Preview

Code

Open in Chat

> 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

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `variant`

 | `   solid | bordered | light | flat | faded | shadow | ghost   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `spinner`

 | `   ReactNode   ` |  |
| `spinnerPlacement`

 | `   start | end   ` | `"start"` |
| `fullWidth`

 | `   boolean   ` | `false` |
| `isIconOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isLoading`

 | `   boolean   ` | `false` |
| `disableRipple`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |

### Button Events

| Prop | Type | Default |
| --- | --- | --- |
| `onPress`
 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onClick`

 | `   MouseEventHandler   ` |  |

### Button Group Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode | ReactNode[]   ` |  |
| `variant`

 | `   solid | bordered | light | flat | faded | shadow | ghost   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"xl"` |
| `fullWidth`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |

---

## Page: https://www.heroui.com/docs/components/calendar

# Calendar

A calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating between date ranges. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date.

Storybook@heroui/calendarReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar using the `defaultValue` prop. Alternatively, a controlled value can be provided using the `value` prop.

Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

Preview

Code

Open in Chat

### Disabled

The `isDisabled` boolean prop makes the Calendar disabled. Cells cannot be focused or selected.

Preview

Code

Open in Chat

### Read Only

The `isReadOnly` boolean prop makes the Calendar's value immutable. Unlike `isDisabled`, the Calendar remains focusable.

Preview

Code

Open in Chat

### Controlled

A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar using the `defaultValue` prop. Alternatively, a controlled value can be provided using the value prop.

Preview

Code

Open in Chat

### Min Date Value

By default, Calendar allows selecting any date. The `minValue` can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

Preview

Code

Open in Chat

### Max Date Value

By default, Calendar allows selecting any date. The `maxValue` can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates before today.

Preview

Code

Open in Chat

### Unavailable Dates

Calendar supports marking certain dates as unavailable. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.

Preview

Code

Open in Chat

### Controlled Focused Value

Calendar tries to avoid allowing the user to select invalid dates in the first place. However, if according to application logic a selected date is invalid, the isInvalid prop can be set. This alerts assistive technology users that the selection is invalid, and can be used for styling purposes as well. In addition, the errorMessage slot may be used to help the user fix the issue.

By default, the selected date is focused when a Calendar first mounts. If no `value` or `defaultValue` prop is provided, then the current date is focused. However, Calendar supports controlling which date is focused using the `focusedValue` and `onFocusChange` props. This also determines which month is visible. The `defaultFocusedValue` prop allows setting the initial focused date when the Calendar first mounts, without controlling it.

Preview

Code

Open in Chat

### Invalid Date

This example validates that the selected date is a weekday and not a weekend according to the current locale.

Preview

Code

Open in Chat

### With Month And Year Picker

Calendar supports month and year picker for rapid selection. You can enable this feature by setting `showMonthAndYearPickers` to `true`. However, if `visibleMonths` is set to a number greater than 1, this feature will be disabled.

Preview

Code

Open in Chat

### International Calendars

Calendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the `Provider` component.

Preview

Code

Open in Chat

### Visible Months

By default, the Calendar displays a single month. The `visibleMonths` prop allows displaying up to 3 months at a time.

Preview

Code

Open in Chat

### Custom first day of week

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.

Preview

Code

Open in Chat

### Page Behaviour

By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.

Preview

Code

Open in Chat

### Presets

Here's the example to customize `topContent` and `bottomContent` to have some preset values.

Preview

Code

Open in Chat

## Slots

*   **base**: Calendar wrapper, it handles alignment, placement, and general appearance.
*   **prevButton**: The previous button of the calendar.
*   **nextButton**: The next button of the calendar.
*   **headerWrapper**: Wraps the picker (month / year).
*   **header**: The header element.
*   **title**: A description of the visible date range, for use in the calendar title.
*   **gridWrapper**: The wrapper for the calendar grid.
*   **grid**: The date grid element (e.g. `<table>`).
*   **gridHeader**: The date grid header element (e.g. `<th>`).
*   **gridHeaderRow**: The date grid header row element (e.g. `<tr>`).
*   **gridHeaderCell**: The date grid header cell element (e.g. `<td>`).
*   **gridBody**: The date grid body element (e.g. `<tbody>`).
*   **gridBodyRow**: The date grid body row element (e.g. `<tr>`).
*   **cell**: The date grid cell element (e.g. `<td>`).
*   **cellButton**: The button element within the cell.
*   **pickerWrapper**: The wrapper for the picker
*   **pickerMonthList**: The month list picker.
*   **pickerYearList**: The year list picker.
*   **pickerHighlight**: The highlighted item of the picker.
*   **pickerItem**: The item of the picker.
*   **helperWrapper**: The helper message of the calendar.
*   **errorMessage**: The error message of the calendar.

## Data Attributes

`Calendar` has the following attributes on the `CalendarCell` element:

*   **data-focused**: Whether the cell is focused.
*   **data-hovered**: Whether the cell is currently hovered with a mouse.
*   **data-pressed**: Whether the cell is currently being pressed.
*   **data-unavailable**: Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough.
*   **data-disabled**: Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props.
*   **data-focus-visible**: Whether the cell is keyboard focused.
*   **data-outside-visible-range**: Whether the cell is outside the visible range of the calendar.
*   **data-outside-month**: Whether the cell is outside the current month.
*   **data-selected**: Whether the cell is selected.
*   **data-selected-start**: Whether the cell is the first date in a range selection.
*   **data-selected-end**: Whether the cell is the last date in a range selection.
*   **data-invalid**: Whether the cell is part of an invalid selection.

## Accessibility

*   Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
*   Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
*   Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.

## API

### Calendar Props

| Prop | Type | Default |
| --- | --- | --- |
| `value`
 | `   DateValue | null   ` |  |
| `defaultValue`

 | `   DateValue | null   ` |  |
| `minValue`

 | `   DateValue   ` |  |
| `maxValue`

 | `   DateValue   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `visibleMonths`

 | `   number   ` | `"1"` |
| `firstDayOfWeek`

 | `   sun | mon | tue | wed | thu | fri | sat   ` |  |
| `focusedValue`

 | `   DateValue   ` |  |
| `defaultFocusedValue`

 | `   DateValue   ` |  |
| `calendarWidth`

 | `   number | string   ` | `"256"` |
| `pageBehavior`

 | `   single | visible   ` | `"visible"` |
| `weekdayStyle`

 | `   narrow | short | long | undefined   ` | `"narrow"` |
| `showMonthAndYearPickers`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `showHelper`

 | `   boolean   ` | `false` |
| `showShadow`

 | `   boolean   ` | `false` |
| `isHeaderExpanded`

 | `   boolean   ` | `false` |
| `isHeaderDefaultExpanded`

 | `   boolean   ` | `false` |
| `topContent`

 | `   ReactNode   ` |  |
| `bottomContent`

 | `   ReactNode   ` |  |
| `isDateUnavailable`

 | `   (date: DateValue) => boolean   ` |  |
| `createCalendar`

 | `   (calendar: SupportedCalendars) => Calendar | null   ` | `"all calendars"` |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `hideDisabledDates`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'prevButton' | 'nextButton' | 'headerWrapper' | 'header' | 'title' | 'content' | 'gridWrapper' | 'grid' | 'gridHeader' | 'gridHeaderRow' | 'gridHeaderCell' | 'gridBody' | 'gridBodyRow' | 'cell' | 'cellButton' | 'pickerWrapper' | 'pickerMonthList' | 'pickerYearList' | 'pickerHighlight' | 'pickerItem' | 'helperWrapper' | 'errorMessage', string>>   ` |  |

### Calendar Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: MappedDateValue) => void   ` |  |
| `onFocusChange`

 | `   (date: CalendarDate) => void   ` |  |
| `onHeaderExpandedChange`

 | `   (isExpanded: boolean) => void   ` |  |

### Types

#### Supported Calendars

---

## Page: https://www.heroui.com/docs/components/card

# Card

Card is a container for text, photos, and actions in the context of a single subject.

Storybook@heroui/cardSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 4 card-related components:

*   **Card**: The main component to display a card.
*   **CardHeader**: Commonly used for the title of a card.
*   **CardBody**: The content of the card.
*   **CardFooter**: Commonly used for actions.

Individual

Global

## Usage

Preview

Code

Open in Chat

### With Divider

Preview

Code

Open in Chat

> See the Divider component for more details.

### With Image

Preview

Code

Open in Chat

### Blurred Footer

You can pass the `isFooterBlurred` prop to the card to blur the footer.

Preview

Code

Open in Chat

### Composition

You can use other HeroUI components inside the card to compose a more complex card.

Preview

Code

Open in Chat

### Blurred Card

You can pass the `isBlurred` prop to the card to blur the card. Card gets blurred properties based on its ancestor element.

> **Note**: To achieve the blur effect as seen in the preview, you need to provide a suitable background (e.g., `bg-gradient-to-tr from-[#FFB457] to-[#FF705B]`) to an ancestor element of the Card component allowing the Card's blur effect to be visible.

Preview

Code

Open in Chat

### Primary Action

If you pass the `isPressable` prop to the card, it will be rendered as a button.

Preview

Code

Open in Chat

> **Note**: that the used callback function is `onPress` instead of `onClick`. Please see the usePress component for more details.

### Cover Image

You can use `Image` component as the cover of the card by taking it out of the `CardBody` component.

Preview

Code

Open in Chat

## Slots

*   **base**: The main container of the card, where the header, body, and footer are placed.
*   **header**: The header of the card, usually used for the title.
*   **body**: The body of the card, where the main content is placed.
*   **footer**: The footer of the card, usually used for actions.

## Data Attributes

`Card` has the following attributes on the `base` element:

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

## API

### Card Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode | ReactNode[]   ` |  |
| `shadow`

 | `   none | sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg   ` | `"lg"` |
| `fullWidth`

 | `   boolean   ` | `false` |
| `isHoverable`

 | `   boolean   ` | `false` |
| `isPressable`

 | `   boolean   ` | `false` |
| `isBlurred`

 | `   boolean   ` | `false` |
| `isFooterBlurred`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `disableRipple`

 | `   boolean   ` | `false` |
| `allowTextSelectionOnPress`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'header' | 'body' | 'footer', string>>   ` |  |

### Card Events

| Prop | Type | Default |
| --- | --- | --- |
| `onPress`
 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/checkbox

# Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

Storybook@heroui/checkboxReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Indeterminate

The `isIndeterminate` prop sets a `Checkbox` to an indeterminate state, overriding its appearance and maintaining it until set to `false`, regardless of user interaction.

Preview

Code

Open in Chat

### Line Through

Preview

Code

Open in Chat

### Custom Check Icon

> By default, `IconProps` will be passed to your icon component. Please make sure that `isSelected`, `isIndeterminate`, and `disableAnimation` are not passed to a DOM element.

Preview

Code

Open in Chat

### Controlled

Preview

Code

Open in Chat

> **Note**: HeroUI `Checkbox` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

## Slots

*   **base**: Checkbox wrapper, it handles alignment, placement, and general appearance.
*   **wrapper**: An inner container that includes styles for relative positioning, flex properties, overflow handling and managing hover and selected states.
*   **hiddenInput**: The hidden input element that is used to handle the checkbox state.
*   **icon**: Icon within the checkbox, controlling size, visibility, and changes when checked.
*   **label**: The text associated with the checkbox.

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the checkbox even further, you can use the `useCheckbox` hook to create your own implementation.

Preview

Code

Open in Chat

> **Note**: We used Tailwind Variants to implement the styles above, you can use any other library such as clsx to achieve the same result.

## Data Attributes

`Checkbox` has the following attributes on the `base` element:

*   **data-selected**: When the checkbox is checked. Based on `isSelected` prop.
*   **data-pressed**: When the checkbox is pressed. Based on usePress
*   **data-invalid**: When the checkbox is invalid. Based on `validationState` prop.
*   **data-readonly**: When the checkbox is readonly. Based on `isReadOnly` prop.
*   **data-indeterminate**: When the checkbox is indeterminate. Based on `isIndeterminate` prop.
*   **data-hover**: When the checkbox is being hovered. Based on useHover
*   **data-focus**: When the checkbox is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the checkbox is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the checkbox is disabled. Based on `isDisabled` prop.
*   **data-loading**: When the checkbox is loading. Based on `isLoading` prop.

## Accessibility

*   Built with a native HTML `<input>` element.
*   Full support for browser features like form autofill.
*   Keyboard focus management and cross browser normalization.
*   Keyboard event support for Tab and Space keys.
*   Labeling support for assistive technology.
*   Indeterminate state support.

## API

### Checkbox Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `icon`

 | `   CheckboxIconProps   ` |  |
| `value`

 | `   string   ` |  |
| `name`

 | `   string   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `lineThrough`

 | `   boolean   ` | `false` |
| `isSelected`

 | `   boolean   ` |  |
| `defaultSelected`

 | `   boolean   ` |  |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isIndeterminate`

 | `   boolean   ` |  |
| `isInvalid`

 | `   boolean   ` | `false` |
| `validationState`

 | `   valid | invalid   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base"｜ "wrapper"｜ "icon"｜ "label", string>>   ` |  |

### Checkbox Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (isSelected: boolean) => void   ` |  |

### Types

#### Checkbox Icon Props

---

## Page: https://www.heroui.com/docs/components/checkbox-group

# Checkbox Group

A CheckboxGroup allows users to select one or more items from a list of choices.

Storybook@heroui/checkboxReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 2 checkbox-related components:

*   **CheckboxGroup**: The root component, it wraps the label and the wrapper.
*   **Checkbox**: The checkbox component.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Horizontal

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onValueChange` properties to control the checkbox input value.

Preview

Code

Open in Chat

### Invalid

Preview

Code

Open in Chat

## Slots

*   **base**: Checkbox group root wrapper, it wraps the label and the wrapper.
*   **wrapper**: Checkbox group wrapper, it wraps all checkboxes.
*   **label**: Checkbox group label, it is placed before the wrapper.
*   **description**: The description of the checkbox group.
*   **errorMessage**: The error message of the checkbox group.

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the checkbox even further, you can use the `useCheckboxGroup` hook to create your own implementation.

Preview

Code

Open in Chat

> **Note**: We used Tailwind Variants to implement the styles above, you can use any other library such as clsx to achieve the same result.

## API

### Checkbox Group Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode[] | ReactNode[]   ` |  |
| `orientation`

 | `   vertical | horizontal   ` | `"vertical"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `size`

 | `   xs | sm | md | lg | xl   ` | `"md"` |
| `radius`

 | `   none | base | xs | sm | md | lg | xl | full   ` | `"md"` |
| `name`

 | `   string   ` |  |
| `label`

 | `   string   ` |  |
| `value`

 | `   string[]   ` |  |
| `lineThrough`

 | `   boolean   ` | `false` |
| `defaultValue`

 | `   string[]   ` |  |
| `isInvalid`

 | `   boolean   ` | `false` |
| `validationState`

 | `   valid | invalid   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: string[]) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "wrapper" | "label", string>>   ` |  |

### Checkbox Group Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: string[]) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/chip

# Chip

A Chip is a small block of essential information that represent an input, attribute, or action.

Storybook@heroui/chipSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Start & End Content

Preview

Code

Open in Chat

### With Close Button

If you pass the `onClose` prop, the close button will be visible. You can override the close icon by passing the `endContent` prop.

Preview

Code

Open in Chat

### With Avatar

Preview

Code

Open in Chat

### List of Chips

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the chip, it is the container of the chip.
*   **content**: The content slot of the chip, it is the container of the chip children.
*   **dot**: Small dot on the left side of the chip. It is visible when the `variant=dot` prop is passed.
*   **avatar**: Avatar classes of the chip. It is visible when the `avatar` prop is passed.
*   **closeButton**: Close button classes of the chip. It is visible when the `onClose` prop is passed.

### Custom Styles

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

Preview

Code

Open in Chat

## API

### Chip Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `variant`

 | `   solid | bordered | light | flat | faded | shadow | dot   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"full"` |
| `avatar`

 | `   ReactNode   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "content" | "dot" | "avatar" | "closeButton", string>>   ` |  |

### Chip Events

| Prop | Type | Default |
| --- | --- | --- |
| `onClose`
 | `   (e: PressEvent) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/circular-progress

# Circular Progress

Circular progress indicators are utilized to indicate an undetermined wait period or visually represent the duration of a process.

Storybook@heroui/progressReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

> **Note**: Make sure to pass the `aria-label` prop when the `label` prop is not provided. This is required for accessibility.

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### With Label

Preview

Code

Open in Chat

### With Value

Preview

Code

Open in Chat

### Value Formatting

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format. `formatOptions` is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the circular progress, it is the main container.
*   **svgWrapper**: The wrapper of the svg circles and the value label.
*   **svg**: The svg element of the circles.
*   **track**: The track is the background circle of the circular progress.
*   **indicator**: The indicator is the one that is filled according to the `value`.
*   **value**: The value content.
*   **label**: The label content.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`CircularProgress` has the following attributes on the `base` element:

*   **data-indeterminate**: Indicates whether the progress is indeterminate.
*   **data-disabled**: Indicates whether the progress is disabled. Based on `isDisabled` prop.

## Accessibility

*   Exposed to assistive technology as a progress bar via ARIA.
*   Labeling support for accessibility.
*   Internationalized number formatting as a percentage or value.
*   Determinate and indeterminate progress support.
*   Exposes the `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` attributes.

## API

### Circular Progress Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `value`

 | `   number   ` |  |
| `valueLabel`

 | `   ReactNode   ` |  |
| `minValue`

 | `   number   ` | `"0"` |
| `maxValue`

 | `   number   ` | `"100"` |
| `formatOptions`

 | `   Intl.NumberFormat   ` | `"{style: 'percent'}"` |
| `isIndeterminate`

 | `   boolean   ` | `true` |
| `showValueLabel`

 | `   boolean   ` | `true` |
| `strokeWidth`

 | `   number   ` | `"2"` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base'｜'svgWrapper'｜'svg'｜'track'｜'indicator'｜'value'｜'label', string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/code

# Code

Code is a component used to display inline code.

Storybook@heroui/codeServer componentSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

## API

### Code Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"sm"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"sm"` |

---

## Page: https://www.heroui.com/docs/components/date-input

# DateInput

DateInput is a component that allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment.

Storybook@heroui/date-inputSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Start & End Content

You can use the `startContent` and `endContent` properties to add content to the start and end of the `DateInput`.

Preview

Code

Open in Chat

### With Description

You can add a description to the input by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.

Preview

Code

Open in Chat

You can also pass an error message as a function. This allows for dynamic error message handling based on the ValidationResult.

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onChange` properties to control the input value.

Preview

Code

Open in Chat

### Time Zones

DateInput is time zone aware when a `ZonedDateTime` object is provided as the value. In this case, the time zone abbreviation is displayed, and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateInput By default, the value is displayed with "day" granularity (year, month, and day), and `CalendarDateTime` and `ZonedDateTime` values are displayed with "minute" granularity.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Min Date And Max Date

The minValue and maxValue props can also be used to ensure the value is within a specific range.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### International Calendar

DateInput supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Hide Time Zone

When a `ZonedDateTime` object is provided as the value to DateInput, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Hourly Cycle

By default, DateInput displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the `hourCycle` prop if needed for a specific usecase. This example forces DateInput to use 24-hour time, regardless of the locale.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **label**: Label of the date-input, it is the one that is displayed above, inside or left of the date-input.
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **input**: The date-input element.
*   **innerWrapper**: Wraps the `input`, the `startContent` and the `endContent`.
*   **clearButton**: The clear button, it is at the end of the input.
*   **helperWrapper**: Wraps the `description` and the `errorMessage`.
*   **description**: The description of the date-input.
*   **errorMessage**: The error message of the date-input.

## Data Attributes

`DateInput` has the following attributes on the `base` element:

*   **data-slot**: All slots have this prop. which slot the element represents(e.g. `slot`).
*   **data-invalid**: When the date-input is invalid. Based on `isInvalid` prop.
*   **data-required**: When the date-input is required. Based on `isRequired` prop.
*   **data-readonly**: When the date-input is readonly. Based on `isReadOnly` prop.
*   **data-disabled**: When the date-input is disabled. Based on `isDisabled` prop.
*   **data-has-helper**: When the date-input has helper text(`errorMessage` or `description`). Base on those two props.
*   **data-has-start-content**: When the date-input has a start content. Base on those `startContent` prop.
*   **data-has-end-content**: When the date-input has a end content. Base on those `endContent` prop.

## Accessibility

*   Built with a native `<input>` element.
*   Visual and ARIA labeling support.
*   Change, clipboard, composition, selection, and input event support.
*   Required and invalid states exposed to assistive technology via ARIA.
*   Support for description and error message help text linked to the input via ARIA.
*   Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale.
*   Date segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.

## API

### DateInput Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `value`

 | `   DateValue   ` |  |
| `defaultValue`

 | `   DateValue   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `placeholderValue`

 | `   DateValue   ` |  |
| `minValue`

 | `   DateValue   ` |  |
| `maxValue`

 | `   DateValue   ` |  |
| `locale`

 | `   string   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `autoFocus`

 | `   boolean   ` | `false` |
| `hideTimeZone`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "label" | "inputWrapper" | "input" | "segment" | "helperWrapper" | "description" | "errorMessage", string>>   ` |  |

### DateInput Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: ZonedDateTime | CalendarDate | CalendarDateTime) => void   ` |  |
| `onFocus`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/date-picker

# DatePicker

DatePickers combine a DateInput and a Calendar popover to allow users to enter or select a date and time value.

Storybook@heroui/date-pickerSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### With Description

You can add a description to the date-picker by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.

Preview

Code

Open in Chat

You can also pass an error message as a function. This allows for dynamic error message handling based on the ValidationResult.

Preview

Code

Open in Chat

### With Month and Year Pickers

You can show month and year pickers in the calendar popover by setting the `showMonthAndYearPickers` property to `true`. However, passing a number greater than 1 to the `visibleMonths` prop will disable this feature.

Preview

Code

Open in Chat

### With Time Fields

Preview

Code

Open in Chat

### Selector Icon

You can use the `selectorIcon` to add content to the start and end of the date-picker.

Preview

Code

Open in Chat

### Selector Button Placement

You can change the position of the selector button by setting the `selectorButtonPlacement` property to `start` or `end`.

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onChange` properties to control the input value.

Preview

Code

Open in Chat

### Time Zones

DatePicker is time zone aware when a `ZonedDateTime` object is provided as the value. In this case, the time zone abbreviation is displayed, and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Granularity

The granularity prop allows you to control the smallest unit that is displayed by DatePicker By default, the value is displayed with "day" granularity (year, month, and day), and `CalendarDateTime` and `ZonedDateTime` values are displayed with "minute" granularity.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Min Date And Max Date

The minValue and maxValue props can also be used to ensure the value is within a specific range.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### International Calendar

DatePicker supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Unavailable Dates

DatePicker supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance in the calendar. In the date field, an invalid state is displayed if a user enters an unavailable date.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Visible Months

By default, the calendar popover displays a single month. The `visibleMonths` prop allows displaying up to 3 months at a time, if screen space permits.

Preview

Code

Open in Chat

### Custom first day of week

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.

Preview

Code

Open in Chat

### Page Behavior

By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.

Preview

Code

Open in Chat

### Preset

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **selectorButton**: Selector button element.
*   **selectorIcon**: Selector icon element.
*   **popoverContent**: The calendar popover element.
*   **calendar**: The calendar element.
*   **calendarContent**: The calendar's content element.
*   **timeInputLabel**: The time-input component's label element.
*   **timeInput**: The time-input component element.

## Data Attributes

`DatePicker` has the following attributes on the `base` element:

*   **data-slot**: All slots have this prop. which slot the element represents(e.g. `calendar`).
*   **data-open**: Indicates if the calendar popover is open.
*   **data-invalid**: When the date-picker is invalid. Based on `isInvalid` prop.
*   **data-required**: When the date-picker is required. Based on `isRequired` prop.
*   **data-readonly**: When the date-picker is readonly. Based on `isReadOnly` prop.
*   **data-disabled**: When the date-picker is disabled. Based on `isDisabled` prop.

## Accessibility

*   Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale.
*   Users can also open a calendar popover to select dates in a standard month grid.
*   Localized screen reader messages are included to announce when the selection and visible date range change.
*   Date segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.
*   Integrates with HTML forms, supporting required, minimum and maximum values, unavailable dates, custom validation functions, realtime validation, and server-side validation errors

## API

### DatePicker Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `value`

 | `   ZonedDateTime | CalendarDate | CalendarDateTime | undefined | null   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `placeholderValue`

 | `   ZonedDateTime | CalendarDate | CalendarDateTime | undefined | null   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `validate`

 | `   (value: MappedDateValue<DateValue>) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `visibleMonths`

 | `   number   ` | `"1"` |
| `firstDayOfWeek`

 | `   sun | mon | tue | wed | thu | fri | sat   ` |  |
| `selectorIcon`

 | `   ReactNode   ` |  |
| `pageBehavior`

 | `   PageBehavior   ` | `"visible"` |
| `calendarWidth`

 | `   number   ` | `"256"` |
| `isDateUnavailable`

 | `   (date: DateValue) => boolean   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `hourCycle`

 | `   12 | 24   ` |  |
| `granularity`

 | `   day | hour | minute | second   ` |  |
| `hideTimeZone`

 | `   boolean   ` | `false` |
| `shouldForceLeadingZeros`

 | `   boolean   ` | `true` |
| `CalendarBottomContent`

 | `   ReactNode   ` |  |
| `showMonthAndYearPickers`

 | `   boolean | undefined   ` | `false` |
| `popoverProps`

 | `   PopoverProps | undefined   ` | `"{ placement: "bottom", triggerScaleOnOpen: false, offset: 13 }"` |
| `selectorButtonProps`

 | `   ButtonProps | undefined   ` | `"{ size: "sm", variant: "light", radius: "full", isIconOnly: true }"` |
| `calendarProps`

 | `   CalendarProps | undefined   ` | `"{ size: "sm", variant: "light", radius: "full", isIconOnly: true }"` |
| `timeInputProps`

 | `   TimeInputProps | undefined   ` | `"{ size: "sm", variant: "light", radius: "full", isIconOnly: true }"` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "selectorButton" | "selectorIcon" | "popoverContent" | "calendar" | "calendarContent" | "timeInputLabel" | "timeInput", string>>   ` |  |

### DatePicker Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: ZonedDateTime | CalendarDate | CalendarDateTime) => void   ` |  |
| `onFocus`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/date-range-picker

# Date Range Picker

Date Range Picker combines two DateInputs and a RangeCalendar popover to allow users to enter or select a date and time range.

Storybook@heroui/date-pickerSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the input, it will have a `danger` asterisk at the end of the label and the input will be required.

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Visible Months

By default, the calendar popover displays a single month. The `visibleMonths` prop allows displaying up to 3 months at a time, if screen space permits.

Preview

Code

Open in Chat

### Custom first day of week

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.

Preview

Code

Open in Chat

### Page Behavior

By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### With Description

You can add a description to the input by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.

Preview

Code

Open in Chat

You can also pass an error message as a function. This allows for dynamic error message handling based on the ValidationResult.

Preview

Code

Open in Chat

### With Month and Year Pickers

You can show month and year pickers in the calendar popover by setting the `showMonthAndYearPickers` property to `true`. However, passing a number greater than 1 to the `visibleMonths` prop will disable this feature.

Preview

Code

Open in Chat

### With Time Fields

DateRangePicker automatically includes time fields when a `CalendarDateTime` or `ZonedDateTime` object is provided as the value.

Preview

Code

Open in Chat

### Selector Icon

You can use the `selectorIcon` to add content to the start and end of the date-range-picker.

Preview

Code

Open in Chat

### Selector Button Placement

You can change the position of the selector button by setting the `selectorButtonPlacement` property to `start` or `end`.

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onChange` properties to control the input value.

Preview

Code

Open in Chat

### Time Zones

DateRangePicker is time zone aware when a `ZonedDateTime` object is provided as the value. In this case, the time zone abbreviation is displayed, and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateRangePicker By default, the value is displayed with "day" granularity (year, month, and day), and `CalendarDateTime` and `ZonedDateTime` values are displayed with "minute" granularity.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Min Date And Max Date

The minValue and maxValue props can also be used to ensure the value is within a specific range.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### International Calendar

DateRangePicker supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Unavailable Dates

DateRangePicker supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance in the calendar. In the date field, an invalid state is displayed if a user enters an unavailable date.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Non Contiguous

The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Presets

@internationalized/date includes functions for parsing strings in multiple formats into `ZonedDateTime` objects.

npm

yarn

pnpm

Preview

Code

Open in Chat

## Slots

*   **base**: base element. it handles alignment, placement, and general appearance.
*   **label**: Label of the date-range-picker, it is the one that is displayed above, inside or left of the date-input.
*   **calendar**: The calendar element.
*   **selectorButton**: Selector button element.
*   **selectorIcon**: Selector icon element.
*   **popoverContent**: The calendar popover element.
*   **calendarContent**: The calendar's content element.
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **input**: The input element.
*   **segment**: The segment element.
*   **separator**: The separator element.
*   **bottomContent**: The bottom content element.
*   **timeInputWrapper**: The wrapper element for the input element.
*   **helperWrapper**: Wraps the `description` and the `errorMessage`.
*   **description**: The description of the date-input.
*   **errorMessage**: The error message of the date-input.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`DateRangePicker` has the following attributes on the `base` element:

*   **data-slot**: All slots have this prop. which slot the element represents(e.g. `canlendar`).
*   **data-open**: Indicates if the calendar popover is open.
*   **data-invalid**: When the date-range-picker is invalid. Based on `isInvalid` prop.
*   **data-required**: When the date-range-picker is required. Based on `isRequired` prop.
*   **data-readonly**: When the date-range-picker is readonly. Based on `isReadOnly` prop.
*   **data-disabled**: When the date-range-picker is disabled. Based on `isDisabled` prop.
*   **data-has-start-content**: When the date-range-picker has a start content. Base on those `startContent` prop.
*   **data-has-end-content**: When the date-range-picker has a end content. Base on those `endContent` prop.
*   **data-has-multiple-months**: When the date-range-picker's `visibleMonth` is more than 2.

## Accessibility

*   Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale
*   Users can also open a calendar popover to select date ranges in a standard month grid. Localized screen reader messages are included to announce when the selection and visible date range change.
*   Date segments are editable using an easy to use numeric keypad, date ranges can be selected by dragging over dates in the calendar using a touch screen, and all interactions are accessible using touch-based screen readers.
*   Integrates with HTML forms, supporting required, minimum and maximum values, unavailable dates, custom validation functions, realtime validation, and server-side validation errors

## API

### DateRangePicker Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `value`

 | `   RangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | null   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `minValue`

 | `   RangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | null   ` |  |
| `maxValue`

 | `   RangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | null   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `placeholderValue`

 | `   ZonedDateTime | CalendarDate | CalendarDateTime | undefined | null   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `validate`

 | `   (value: RangeValue<MappedDateValue<DateValue>>) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `startName`

 | `   string   ` |  |
| `endName`

 | `   string   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `selectorIcon`

 | `   ReactNode   ` |  |
| `pageBehavior`

 | `   single | visible   ` | `"visible"` |
| `visibleMonths`

 | `   number   ` | `"1"` |
| `firstDayOfWeek`

 | `   sun | mon | tue | wed | thu | fri | sat   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `hourCycle`

 | `   12 | 24   ` |  |
| `granularity`

 | `   day | hour | minute | second   ` |  |
| `hideTimeZone`

 | `   boolean   ` | `false` |
| `allowsNonContiguousRanges`

 | `   boolean   ` | `false` |
| `shouldForceLeadingZeros`

 | `   boolean   ` | `true` |
| `calendarWidth`

 | `   number   ` | `"256"` |
| `CalendarTopContent`

 | `   ReactNode   ` |  |
| `CalendarBottomContent`

 | `   ReactNode   ` |  |
| `showMonthAndYearPickers`

 | `   boolean   ` | `false` |
| `popoverProps`

 | `   PopoverProps   ` | `"{ placement: "bottom", triggerScaleOnOpen: false, offset: 13 }"` |
| `selectorButtonProps`

 | `   ButtonProps   ` | `"{ size: "sm", variant: "light", radius: "full", isIconOnly: true }"` |
| `selectorButtonPlacement`

 | `   start | end   ` | `"end"` |
| `calendarProps`

 | `   CalendarProps   ` |  |
| `timeInputProps`

 | `   TimeInputProps   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "label" | "calendar" | "selectorButton" | "selectorIcon" | "popoverContent" | "calendarContent" | "inputWrapper" | "input" | "segment" | "separator" | "bottomContent" | "timeInputWrapper" | "timeInputLabel" | "timeInput" | "helperWrapper" | "description" | "errorMessage", string>>   ` |  |

### DateRangePicker Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: RangeValue<CalendarDate | CalendarDateTime | ZonedDateTime>) => void   ` |  |
| `onOpenChange`

 | `   (isOpen: boolean) => void   ` |  |
| `onFocus`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent<HTMLInputElement>) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/divider

# Divider

Divider is a component that separates content in a page.

Storybook@heroui/dividerReact AriaServer componentSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

## Data Attributes

`Divider` has the following attributes on the `base` element:

*   **data-orientation**: The orientation of the divider. Based on `orientation` prop.

## Accessibility

*   Separator role is added to the divider.
*   Support for horizontal and vertical orientation.
*   Support for HTML `<hr>` element or a custom element type.

## API

### Divider Props

| Prop | Type | Default |
| --- | --- | --- |
| `orientation`
 | ``   `horizontal` | `vertical`   `` | ``"`horizontal`"`` |

---

## Page: https://www.heroui.com/docs/components/dropdown

# Dropdown

Displays a list of actions or options that a user can choose.

Storybook@heroui/dropdownReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 5 dropdown-related components:

*   **Dropdown**: The main component, which is a wrapper for the other components. This component is an extension of the Popover component, so it accepts all the props of the Popover component.
*   **DropdownTrigger**: The component that triggers the dropdown menu to open.
*   **DropdownMenu**: The component that contains the dropdown items.
*   **DropdownSection**: The component that contains a group of dropdown items.
*   **DropdownItem**: The component that represents a dropdown item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic items

Dropdown follows the Collection Components API, accepting both static and dynamic collections.

*   **Static**: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
*   **Dynamic**: The example below can be used when the options come from an external data source such as an API call, or update over time.

Preview

Code

Open in Chat

### Disabled Keys

Dropdown items can be disabled using the `disabledKeys` prop to the `DropdownMenu` component.

Preview

Code

Open in Chat

> **Note**: It's important to have a unique key for each item, otherwise the disabled keys will not work.

### Action event

You can use the `onAction` prop to get the key of the selected item.

Preview

Code

Open in Chat

### Variants

You can use the `variant` in the `DropdownMenu` component to change the `hover` style of the dropdown items.

Preview

Code

Open in Chat

### Single Selection

You can set the `selectionMode` property as `single` to allow the user to select only one item at a time.

Preview

Code

Open in Chat

### Multiple Selection

You can set the `selectionMode` property as `multiple` to allow the user to select multiple items at a time.

Preview

Code

Open in Chat

> **Note**: To allow empty selection, you can set the `disallowEmptySelection` property as `false`.

### With Shortcut

You can use the `shortcut` prop to add a shortcut to the dropdown item.

Preview

Code

Open in Chat

> **Note**: Dropdown does not handle the shortcut event, you need to handle it yourself.

### With Icons

It is possible to add icons to the dropdown items using the `startContent` / `endContent` props.

Preview

Code

Open in Chat

> **Note**: If you use `currentColor` as the icon color, the icon will have the same color as the item text.

### With Description

You can use the `description` prop to add a description to the dropdown item.

Preview

Code

Open in Chat

### With Sections

You can use the `DropdownSection` component to group dropdown items.

Preview

Code

Open in Chat

> **Note**: Sections without a `title` must provide an `aria-label` for accessibility.

### Custom Trigger

You can use any component as a trigger for the dropdown menu, just wrap it in the `DropdownTrigger` component.

Preview

Code

Open in Chat

### Changing the backdrop

As we mentioned earlier, the `Dropdown` component is an extension of the Popover component, so it accepts all the props of the Popover component, including the `backdrop` prop.

Preview

Code

Open in Chat

### Routing

The `<DropdownItem>` component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

## Slots

Dropdown has 3 components with slots the `DropdownMenu`, `DropdownItem` and `DropdownSection` components.

### DropdownMenu

*   **base**: The main wrapper for the menu component. This slot wraps the `topContent`, `bottomContent` and the `list` slot.
*   **list**: The slot for the menu list component. You can see this slot as the `ul` slot.
*   **emptyContent**: The slot content to display when the collection is empty.

### DropdownItem

*   **base**: The main slot for the dropdown item. It wraps all the other slots.
*   **wrapper**: The `title` and `description` wrapper.
*   **title**: The title of the dropdown item.
*   **description**: The description of the dropdown item.
*   **shortcut**: The shortcut slot.
*   **selectedIcon**: The selected icon slot. This is only visible when the item is selected.

### DropdownSection

*   **base**: The main slot for the dropdown section. It wraps all the other slots.
*   **heading**: The title that is render on top of the section group.
*   **group**: The group of dropdown items.
*   **divider**: The divider that is render between the groups. This is only visible when `showDivider` is `true`.

### Customizing the dropdown popover

The `Dropdown` component is an extension of the Popover component, so you can use the same slots to customize the dropdown.

Preview

Code

Open in Chat

### Customizing the dropdown items style

You can customize the dropdown items either by using the `DropdownMenu` `itemClasses` prop or by using the `DropdownItem` slots, the `itemClasses` allows you to customize all the items at once, while the slots allow you to customize each item individually.

Preview

Code

Open in Chat

### Keyboard Interactions

| Key | Description |
| --- | --- |
| Space | When focus is on `DropdownTrigger`, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item. |
| Enter | When focus is on `DropdownTrigger`, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item. |
| ArrowDown | When focus is on `DropdownTrigger`, opens the dropdown menu. When focus is on an item, moves focus to the next item. |
| ArrowUp | When focus is on an item, moves focus to the previous item. |
| Esc | Closes the dropdown menu and moves focus to `DropdownTrigger`. |
| A-Z or a-z | When the menu is open, moves focus to the next menu item with a label that starts with the typed character if such an menu item exists. |

## Data Attributes

`DropdownItem` has the following attributes on the `base` element:

*   **data-disabled**: When the dropdown item is disabled. Based on dropdown `disabledKeys` prop.
*   **data-selected**: When the dropdown item is selected. Based on dropdown `selectedKeys` prop.
*   **data-hover**: When the dropdown item is being hovered. Based on useHover
*   **data-pressed**: When the dropdown item is pressed. Based on usePress
*   **data-focus**: When the dropdown item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the dropdown item is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Exposed to assistive technology as a `button` with a `menu` using ARIA.
*   Support for single, multiple, or no selection.
*   Support for disabled items.
*   Support for sections.
*   Complex item labeling support for accessibility.
*   Keyboard navigation support including arrow keys, home/end, page up/down. See Keyboard Interactions for more details.
*   Automatic scrolling support during keyboard navigation.
*   Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly.
*   Typeahead to allow focusing items by typing text.
*   Virtualized scrolling support for performance with long lists.

## API

### Dropdown Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `type`

 | `   menu | listbox   ` | `"menu"` |
| `trigger`

 | `   press | longPress   ` | `"press"` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `closeOnSelect`

 | `   boolean   ` | `true` |
| `shouldBlockScroll`

 | `   boolean   ` | `true` |
| `PopoverProps`

 | `   PopoverProps   ` |  |

### Dropdown Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `shouldCloseOnInteractOutside`

 | `   (e: HTMLElement) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### DropdownTrigger Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |

### DropdownMenu Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode | ((item: T) => ReactElement)   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `variant`

 | `   solid | bordered | light | flat | faded | shadow   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `selectionMode`

 | `   none | single | multiple   ` |  |
| `selectedKeys`

 | `   all | Iterable<React.Key>   ` |  |
| `disabledKeys`

 | `   Iterable<React.Key>   ` |  |
| `defaultSelectedKeys`

 | `   all | Iterable<React.Key>   ` |  |
| `disallowEmptySelection`

 | `   boolean   ` | `false` |
| `autoFocus`

 | `   boolean | first | last   ` | `false` |
| `topContent`

 | `   ReactNode   ` |  |
| `bottomContent`

 | `   ReactNode   ` |  |
| `emptyContent`

 | `   ReactNode   ` | `"No items."` |
| `hideEmptyContent`

 | `   boolean   ` | `false` |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `shouldFocusWrap`

 | `   boolean   ` | `false` |
| `closeOnSelect`

 | `   boolean   ` | `true` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base'｜'list'｜'emptyContent', string>>   ` |  |
| `itemClasses`

 | `   Partial<Record<'base'｜'wrapper'｜'title'｜'description'｜'shortcut'｜'selectedIcon', string>>   ` |  |

### DropdownMenu Events

| Prop | Type | Default |
| --- | --- | --- |
| `onAction`
 | `   (key: React.Key) => void   ` |  |
| `onSelectionChange`

 | `   (keys: "all" | Set<React.Key> & {anchorKey?: string; currentKey?: string}) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### DropdownSection Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `title`

 | `   string   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `showDivider`

 | `   boolean   ` | `false` |
| `dividerProps`

 | `   DividerProps   ` |  |
| `classNames`

 | `   Record<'base'｜'heading'｜'group'｜'divider', string>>   ` |  |
| `itemClasses`

 | `   Record<'base'｜'wrapper'｜'title'｜'description'｜'shortcut'｜'selectedIcon', string>>   ` |  |

### DropdownItem Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `key`

 | `   React.Key   ` |  |
| `title`

 | `   string | ReactNode   ` |  |
| `textValue`

 | `   string   ` |  |
| `description`

 | `   string | ReactNode   ` |  |
| `shortcut`

 | `   string | ReactNode   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `selectedIcon`

 | `   SelectedIconProps   ` |  |
| `showDivider`

 | `   boolean   ` | `false` |
| `href`

 | `   string   ` |  |
| `target`

 | `   HTMLAttributeAnchorTarget   ` |  |
| `rel`

 | `   string   ` |  |
| `download`

 | `   boolean | string   ` |  |
| `ping`

 | `   string   ` |  |
| `referrerPolicy`

 | `   HTMLAttributeReferrerPolicy   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isSelected`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `closeOnSelect`

 | `   boolean   ` | `true` |
| `classNames`

 | `   Record<'base'｜'wrapper'｜'title'｜'description'｜'shortcut'｜'selectedIcon', string>>   ` |  |

### DropdownItem Events

| Prop | Type | Default |
| --- | --- | --- |
| `onAction`
 | `   () => void   ` |  |
| `onClose`

 | `   () => void   ` |  |
| `onPress`

 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onClick`

 | `   MouseEventHandler   ` |  |

### Types

#### Dropdown Item Selected Icon Props

---

## Page: https://www.heroui.com/docs/components/drawer

# Drawer

Displays a panel that slides in from the edge of the screen, containing supplementary content.

Storybook@heroui/drawerReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 5 drawer-related components:

*   **Drawer**: The main component to display a drawer.
*   **DrawerContent**: The wrapper of the other drawer components.
*   **DrawerHeader**: The header of the drawer.
*   **DrawerBody**: The body of the drawer.
*   **DrawerFooter**: The footer of the drawer.

Individual

Global

## Usage

When the drawer opens:

*   Focus is bounded within the drawer and set to the first tabbable element.
*   Content behind a drawer is inert, meaning that users cannot interact with it.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Non-dismissible

By default, the drawer can be closed by clicking on the overlay or pressing the Esc key. You can disable this behavior by setting the following properties:

*   Set the `isDismissable` property to `false` to prevent the drawer from closing when clicking on the overlay.
*   Set the `isKeyboardDismissDisabled` property to `true` to prevent the drawer from closing when pressing the Esc key.

Preview

Code

Open in Chat

### Drawer placement

The drawer can be placed on any edge of the screen using the `placement` prop:

*   `left`
*   `right` (default)
*   `top`
*   `bottom`

Preview

Code

Open in Chat

### With Form

The `Drawer` handles the focus within the drawer content. It means that you can use the drawer with form elements without any problem. The focus returns to the trigger when the drawer closes.

Preview

Code

Open in Chat

> **Note**: You can add the `autoFocus` prop to the first `Input` component to focus it when the drawer opens.

### Backdrop

The `Drawer` component has a `backdrop` prop to show a backdrop behind the drawer. The backdrop can be either `transparent`, `opaque` or `blur`. The default value is `opaque`.

Preview

Code

Open in Chat

### Custom Motion

Drawer offers a `motionProps` property to customize the `enter` / `exit` animation.

Preview

Code

Open in Chat

> Learn more about Framer motion variants here.

### Custom Styles

Preview

Code

Open in Chat

**Credits**

The Drawer component design is inspired by Luma.

## Slots

*   **wrapper**: The wrapper slot of the drawer. It wraps the `base` and the `backdrop` slots.
*   **base**: The main slot of the drawer content.
*   **backdrop**: The backdrop slot, it is displayed behind the drawer.
*   **header**: The header of the drawer, it is displayed at the top of the drawer.
*   **body**: The body of the drawer, it is displayed in the middle of the drawer.
*   **footer**: The footer of the drawer, it is displayed at the bottom of the drawer.
*   **closeButton**: The close button of the drawer.

## Data Attributes

`Drawer` has the following attributes on the `base` element:

*   **data-open**: When the drawer is open. Based on drawer state.
*   **data-dismissable**: When the drawer is dismissable. Based on `isDismissable` prop.

## Accessibility

*   Content outside the drawer is hidden from assistive technologies while it is open.
*   The drawer optionally closes when interacting outside, or pressing the Esc key.
*   Focus is moved into the drawer on mount, and restored to the trigger element on unmount.
*   While open, focus is contained within the drawer, preventing the user from tabbing outside.
*   Scrolling the page behind the drawer is prevented while it is open, including in mobile browsers.

## API

### Drawer Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `size`

 | `   xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | full   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg   ` | `"lg"` |
| `placement`

 | `   left | right | top | bottom   ` | `"right"` |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` |  |
| `isDismissable`

 | `   boolean   ` | `true` |
| `isKeyboardDismissDisabled`

 | `   boolean   ` | `false` |
| `shouldBlockScroll`

 | `   boolean   ` | `true` |
| `hideCloseButton`

 | `   boolean   ` | `false` |
| `closeButton`

 | `   ReactNode   ` |  |
| `motionProps`

 | `   MotionProps   ` |  |
| `portalContainer`

 | `   HTMLElement   ` | `"document.body"` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'wrapper' | 'base' | 'backdrop' | 'header' | 'body' | 'footer' | 'closeButton', string>>   ` |  |

### Drawer Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### Drawer types

#### Motion Props

---

## Page: https://www.heroui.com/docs/components/form

# Form

A form is a group of inputs that allows users to submit data to a server, with support for providing field validation errors.

Storybook@heroui/formSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

## Anatomy

A `Form` is a container for input elements and submit/reset buttons, with support for validation messages. When labeled with `aria-label` or `aria-labelledby`, it becomes a navigable form landmark for assistive technology.

## Events

The `onSubmit` event will be triggered when a user submits the form with the `Enter` key or by pressing a submit button. The onReset event will be triggered when a user presses a reset button.

Preview

Code

Open in Chat

## Validation

`Form` supports native HTML constraint validation with customizable UI, custom validation functions, and server-side validation. Server-side validation errors can be provided via the `validationErrors` prop as an object mapping field names to error messages, which are cleared when the user modifies the field.

Preview

Code

Open in Chat

See the Forms guide to learn more about form validation, including client-side validation, and integration with other frameworks and libraries.

### Validation Behavior

`Form` validation uses native validation behavior by default, but can be switched to ARIA validation by setting `validationBehavior="aria"`. ARIA validation shows realtime errors without blocking submission. This can be set at the form or field level. To set the default behavior at the app level, you can change the form defaults for your entire app using HeroUI Provider.

Preview

Code

Open in Chat

## Accessibility

*   Built with a native HTML `<form>` element, with support for ARIA labelling to create a form landmark.
*   Full support for browser features like form autofill.
*   Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors.

## API

### Form Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `validationBehavior`

 | `   'native' | 'aria'   ` | `"native"` |
| `validationErrors`

 | `   Record<string, string | string[]>   ` |  |
| `action`

 | `   string | FormHTMLAttributes<HTMLFormElement>['action']   ` |  |
| `encType`

 | `   'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'   ` |  |
| `method`

 | `   'get' | 'post' | 'dialog'   ` |  |
| `target`

 | `   '_blank' | '_self' | '_parent' | '_top'   ` |  |
| `autoComplete`

 | `   'off' | 'on'   ` |  |
| `autoCapitalize`

 | `   'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'   ` |  |
| `className`

 | `   string   ` |  |
| `style`

 | `   CSSProperties   ` |  |

---

## Page: https://www.heroui.com/docs/components/image

# Image

The Image component is used to display images with support for fallback.

Storybook@heroui/imageSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Blurred

You can use the `isBlurred` prop to duplicate the image and blur it to create a blurred effect.

Preview

Code

Open in Chat

### Zoomed

You can use the `isZoomed` prop make the image zoomed when hovered.

Preview

Code

Open in Chat

### Animated Loading

Image component has a built-in `skeleton` animation to indicate the image is loading and an `opacity` animation when the image loads.

Preview

Code

Open in Chat

> **Note**: The `URL` uses `https://app.requestly.io/delay` to simulate a slow network.

### Image with fallback

You can use the `fallbackSrc` prop to display a fallback image when:

*   The `fallbackSrc` prop is provided.
*   The image provided in `src` is still loading.
*   The image provided in `src` fails to load.
*   The image provided in `src` is not found.

Preview

Code

Open in Chat

### With Next.js Image

Next.js provides an optimized Image component, you can use it with HeroUI `Image` component as well.

> **Note**: HeroUI's `Image` component is `client-side`, using hooks like `useState` for loading states and animations. Use Next.js `Image` alone if these features aren't required.

## Slots

*   **img**: Slot for the image element.
*   **wrapper**: Image wrapper, it handles alignment, placement, and general appearance.
*   **zoomedWrapper**: The wrapper slot for the zoomed image it avoids the image content to overflow the parent container.
*   **blurredImg**: The wrapper slot for the duplicated blurred image.

## API

### Image Props

| Prop | Type | Default |
| --- | --- | --- |
| `src`
 | `   string   ` |  |
| `srcSet`

 | `   string   ` |  |
| `sizes`

 | `   string   ` |  |
| `alt`

 | `   string   ` |  |
| `width`

 | `   number   ` |  |
| `height`

 | `   number   ` |  |
| `radius`

 | `   none | sm | md | lg | full   ` | `"xl"` |
| `shadow`

 | `   none | sm | md | lg   ` | `"none"` |
| `loading`

 | `   eager | lazy   ` |  |
| `fallbackSrc`

 | `   string   ` |  |
| `isBlurred`

 | `   boolean   ` | `false` |
| `isZoomed`

 | `   boolean   ` | `false` |
| `removeWrapper`

 | `   boolean   ` | `false` |
| `disableSkeleton`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"img" | "wrapper" | "zoomedWrapper" | "blurredImg", string>>   ` |  |

### Image Events

| Prop | Type | Default |
| --- | --- | --- |
| `onLoad`
 | `   ReactEventHandler<HTMLImageElement>   ` |  |
| `onError`

 | `   () => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/input

# Input

Input is a component that allows users to enter text. It can be used to get user inputs in forms, search fields, and more.

Storybook@heroui/inputReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the input, it will have a `danger` asterisk at the end of the label and the input will be required.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Password Input

You can use the `type` property to change the input type to `password`.

Preview

Code

Open in Chat

### Clear Button

If you pass the `isClearable` property to the input, it will have a clear button at the end of the input, it will be visible when the input has a value.

Preview

Code

Open in Chat

### Start & End Content

You can use the `startContent` and `endContent` properties to add content to the start and end of the input.

Preview

Code

Open in Chat

### With Description

You can add a description to the input by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input. `errorMessage` is only shown when `isInvalid` is set to `true`.

Preview

Code

Open in Chat

Example with `regex` email validation:

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onValueChange` properties to control the input value.

Preview

Code

Open in Chat

> **Note**: HeroUI `Input` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

### With Form

`Input` can be used with a `Form` component to leverage form state management. For more on form and validation behaviors, see the Forms guide.

#### Built-in Validation

`Input` supports the following native HTML constraints:

*   `isRequired` indicates that a field must have a value before the form can be submitted.
*   `minLength` and `maxLength` specify the minimum and length of text input.
*   `pattern` provides a custom regular expression that a text input must conform to.
*   `type="email"` and `type="url"` provide built-in validation for email addresses and URLs.

When using native validation, error messages can be customized by passing a function to `errorMessage` and checking the ValidityState of `validationDetails`.

Preview

Code

Open in Chat

#### Custom Validation

In addition to built-in constraints, you can provide a function to the `validate` property for custom validation.

Preview

Code

Open in Chat

#### Realtime Validation

If you want to display validation errors while the user is typing, you can control the field value and use the `isInvalid` prop along with the `errorMessage` prop.

Preview

Code

Open in Chat

#### Server Validation

Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. HeroUI allows you to display server-side validation errors by using the `validationErrors` prop in the `Form` component. This prop should be an object where each key is the field `name` and the value is the error message.

Preview

Code

Open in Chat

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **label**: Label of the input, it is the one that is displayed above, inside or left of the input.
*   **mainWrapper**: Wraps the `inputWrapper` when position is `outside` / `outside-left`.
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **innerWrapper**: Wraps the `input`, the `startContent` and the `endContent`.
*   **input**: The input element.
*   **clearButton**: The clear button, it is at the end of the input.
*   **helperWrapper**: Wraps the `description` and the `errorMessage`.
*   **description**: The description of the input.
*   **errorMessage**: The error message of the input.

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the input even further, you can use the `useInput` hook to create your own implementation.

## Data Attributes

`Input` has the following attributes on the `base` element:

*   **data-invalid**: When the input is invalid. Based on `isInvalid` prop.
*   **data-required**: When the input is required. Based on `isRequired` prop.
*   **data-readonly**: When the input is readonly. Based on `isReadOnly` prop.
*   **data-hover**: When the input is being hovered. Based on useHover
*   **data-focus**: When the input is being focused. Based on useFocusRing.
*   **data-focus-within**: When the input is being focused or any of its children. Based on useFocusWithin.
*   **data-focus-visible**: When the input is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the input is disabled. Based on `isDisabled` prop.

## Accessibility

*   Built with a native `<input>` element.
*   Visual and ARIA labeling support.
*   Change, clipboard, composition, selection, and input event support.
*   Required and invalid states exposed to assistive technology via ARIA.
*   Support for description and error message help text linked to the input via ARIA.

## API

### Input Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `value`

 | `   string   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `placeholder`

 | `   string   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: string) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `minLength`

 | `   number   ` |  |
| `maxLength`

 | `   number   ` |  |
| `pattern`

 | `   string   ` |  |
| `type`

 | `   text | email | url | password | tel | search | file   ` | `"text"` |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `isClearable`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `baseRef`

 | `   RefObject<HTMLDivElement>   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'label' | 'inputWrapper' | 'innerWrapper' | 'mainWrapper' | 'input' | 'clearButton' | 'helperWrapper' | 'description' | 'errorMessage', string>>   ` |  |

### Input Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (value: string) => void   ` |  |
| `onClear`

 | `   () => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/input-otp

# Input OTP

The InputOtp component enables users to enter one-time passwords (OTP). It is built on top of the input-otp library by @guilherme\_rodz.

Storybook@heroui/input-otpSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

## Disabled

The `isDisabled` prop disables user interaction with the `InputOtp` component.

Preview

Code

Open in Chat

## Read Only

The `isReadOnly` prop makes the `InputOtp` component read-only while maintaining its visual appearance.

Preview

Code

Open in Chat

## Required

The `isRequired` prop marks the `InputOtp` as a required field.

Preview

Code

Open in Chat

## Sizes

The size of the `InputOtp` can be customized using the `size` prop. The default value is `md`.

Preview

Code

Open in Chat

## Colors

Color of the `InputOtp` can be changed by `color` property.

Preview

Code

Open in Chat

## Variants

Styling/Variant of the `InputOtp` can be changed by `variant` property. By default, `variant` property is set to `flat`.

Preview

Code

Open in Chat

## Radius

Radius of the `InputOtp` can be changed by `radius` property. By default, `radius` property is set to `md`.

Preview

Code

Open in Chat

## Password

`InputOtp` can be used as password/secured-pin input by setting `type` as `password`.

Preview

Code

Open in Chat

## Description

Description of the `InputOtp` can be set by `description` property.

Preview

Code

Open in Chat

## Error Message

Custom error message of the `InputOtp` can be set by `errorMessage` property.

Preview

Code

Open in Chat

## Allowed Keys

*   The `InputOtp` component only accepts specified input keys. Any other input is ignored.
*   You can customize the allowed keys using the `allowedKeys` prop, which accepts a regex pattern.
*   By default, `allowedKeys` is set to `^[0-9]*$` (only numerical digits).

Preview

Code

Open in Chat

## Controlled

Preview

Code

Open in Chat

## React Hook Form

You can use `InputOtp` with React Hook Form for form validation and submission handling.

Preview

Code

Open in Chat

## Different Lengths & Validation

The `InputOtp` component supports different lengths through the `length` property. You can set the number of input segments by passing a number value to the `length` prop. Common use cases include 4-digit PINs and 6-digit authentication codes.

Preview

Code

Open in Chat

## Custom Styles

You can customize the styles of the `InputOtp` component using the `classNames` prop.

Preview

Code

Open in Chat

## Slots

*   **base**: InputOtp wrapper, it handles alignment, placement, and general appearance.
*   **wrapper**: Wraps the underlying input-otp component. Sent as `containerClassName` prop to underlying input-otp component.
*   **input**: The input element.
*   **segmentWrapper**: Wraps all the segment elements.
*   **segment**: The segment element.
*   **caret**: The caret represents the typing indicator of the input-otp component.
*   **passwordChar**: The passwordChar represents the text styling when input-type is password.
*   **helperWrapper**: Wraps the `description` and the `errorMessage`.
*   **description**: The description of the input-otp.
*   **errorMessage**: The error message of the input-otp.

## Data Attributes

`InputOtp` has the following attributes on the `base` element:

*   **data-invalid**: When the input-otp is invalid. Based on `isInvalid` prop.
*   **data-required**: When the input-otp is required. Based on `isRequired` prop.
*   **data-readonly**: When the input-otp is readonly. Based on `isReadOnly` prop.
*   **data-filled**: When the input-otp is completely filled.
*   **data-disabled**: When the input-otp is disabled. Based on `isDisabled` prop.

`InputOtp` also has the following attributes on the `segment` element:

*   **data-active**: When the segment is active.
*   **data-focus**: When the segment is focused.
*   **data-focus-visible**: When the segment is focused visible.
*   **data-has-value**: When the segment has value.

## Accessibility

*   Built on top of input-otp.
*   Required and invalid states exposed to assistive technology via ARIA.
*   Support for description and error message help text linked to the input-otp via ARIA.
*   Keyboard navigation:
    *   Tab: Moves focus between input segments
    *   Arrow keys: Navigate between segments
    *   Backspace: Clears current segment and moves focus to previous segment
*   ARIA attributes:
    *   `aria-invalid`: Indicates validation state
    *   `aria-required`: Indicates if the input is required

## API

### InputOtp Props

| Prop | Type | Default |
| --- | --- | --- |
| `length`
 | `   number   ` | `"4"` |
| `allowedKeys`

 | `   regEx string   ` | `"^[0-9]*$"` |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `value`

 | `   string   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `fullWidth`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `baseRef`

 | `   RefObject<HTMLDivElement>   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'inputWrapper' | 'input' | 'segmentWrapper' | 'segment' | 'caret' | 'passwordChar' | 'helperWrapper' | 'description' | 'errorMessage', string>>   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `textAlign`

 | `   left | center | right   ` | `"center"` |
| `pushPasswordManagerStrategy`

 | `   'none' | 'hidden' | 'input'   ` |  |
| `pasteTransformer`

 | `   (text: string) => string   ` |  |
| `containerClassName`

 | `   string   ` |  |
| `noScriptCSSFallback`

 | `   string   ` |  |

### InputOtp Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (value: string) => void   ` |  |
| `onComplete`

 | `   (value: string) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/kbd

# Keyboard Key

Keyboard key is a component to display which key or combination of keys performs a given action.

Storybook@heroui/kbdServer componentSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Keys

Preview

Code

Open in Chat

> **Note**: Check the API section to see all available keys.

## Slots

*   **base**: Kbd wrapper, it handles alignment, placement, and general appearance.
*   **abbr**: The `keys` wrapper that handles the appearance of the keys.
*   **content**: The children wrapper that handles the appearance of the content.

## Accessibility

*   Each command `key` has a `title` attribute that describes the action that the key performs.

## API

### Keyboard Key Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `keys`

 | `   KbdKey | KbdKey[]   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "abbr" | "content", string>>   ` |  |

### Keyboard Keys

List of supported keys.

---

## Page: https://www.heroui.com/docs/components/link

# Link

Links allow users to click their way from page to page. This component is styled to resemble a hyperlink and semantically renders an `<a>`

Storybook@heroui/linkReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Underline

Preview

Code

Open in Chat

### External

If you pass the `isExternal` prop, the link will have the `target="_blank"` and `rel="noopener noreferrer"` attributes.

Preview

Code

Open in Chat

### Custom Anchor Icon

Preview

Code

Open in Chat

### Block Link

If you pass the `isBlock` prop, the link will be rendered as a block element with a `hover` effect.

Preview

Code

Open in Chat

### Polymorphic Component

HeroUI's components expose a `as` prop that allows you to customize the React element type that is used to render the component.

Preview

Code

Open in Chat

### Routing

The `<Link>` component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

### Custom Implementation

In case you need to customize the link even further, you can use the `useLink` hook to create your own implementation.

## Data Attributes

`Link` has the following attributes on the `base` element:

*   **data-focus**: When the link is being focused. Based on useFocusRing
*   **data-focus-visible**: When the link is being focused with the keyboard. Based on useFocusRing
*   **data-disabled**: When the link is disabled. Based on `isDisabled` prop.

## Accessibility

*   Support for mouse, touch, and keyboard interactions.
*   Support for navigation links via `<a>` elements or custom element types via ARIA.
*   Support for disabled links.
*   Keyboard users may activate links using the Enter key.

## API

### Link Props

| Prop | Type | Default |
| --- | --- | --- |
| `size`
 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   foreground | primary | secondary | success | warning | danger   ` | `"primary"` |
| `underline`

 | `   none | hover | always | active | focus   ` | `"none"` |
| `href`

 | `   string   ` |  |
| `target`

 | `   HTMLAttributeAnchorTarget   ` |  |
| `rel`

 | `   string   ` |  |
| `download`

 | `   boolean | string   ` |  |
| `ping`

 | `   string   ` |  |
| `referrerPolicy`

 | `   HTMLAttributeReferrerPolicy   ` |  |
| `isExternal`

 | `   boolean   ` | `false` |
| `showAnchorIcon`

 | `   boolean   ` | `false` |
| `anchorIcon`

 | `   ReactNode   ` |  |
| `isBlock`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |

### Link Events

| Prop | Type | Default |
| --- | --- | --- |
| `onPress`
 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onClick`

 | `   MouseEventHandler   ` |  |

---

## Page: https://www.heroui.com/docs/components/listbox

# Listbox

A listbox displays a list of options and allows a user to select one or more of them.

Storybook@heroui/listboxReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 listbox-related components:

*   **Listbox**: The main component, which is a wrapper for the other components.
*   **ListboxSection**: The component that contains a group of listbox items.
*   **ListboxItem**: The component that represents a listbox item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic items

Listbox follows the Collection Components API, accepting both static and dynamic collections.

*   **Static**: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
*   **Dynamic**: The example below can be used when the options come from an external data source such as an API call, or update over time.

Preview

Code

Open in Chat

### Disabled Keys

Listbox items can be disabled using the `disabledKeys` prop to the `Listbox` component.

Preview

Code

Open in Chat

> **Note**: It's important to have a unique key for each item, otherwise the disabled keys will not work.

### Variants

You can use the `variant` in the `Listbox` component to change the `hover` style of the listbox items.

Preview

Code

Open in Chat

### Single Selection

You can set the `selectionMode` property as `single` to allow the user to select only one item at a time.

Preview

Code

Open in Chat

### Multiple Selection

You can set the `selectionMode` property as `multiple` to allow the user to select multiple items at a time.

Preview

Code

Open in Chat

> **Note**: To allow empty selection, you can set the `disallowEmptySelection` property as `false`.

### With Icons

It is possible to add icons to the listbox items using the `startContent` / `endContent` props.

Preview

Code

Open in Chat

> **Note**: If you use `currentColor` as the icon color, the icon will have the same color as the item text.

### With Description

You can use the `description` prop to add a description to the listbox item.

Preview

Code

Open in Chat

### With Top & Bottom Content

You can use the `topContent` and `bottomContent` props to add content above and below the listbox items.

Preview

Code

Open in Chat

### With Sections

You can use the `ListboxSection` component to group listbox items.

Preview

Code

Open in Chat

> **Note**: Sections without a `title` must provide an `aria-label` for accessibility.

### Routing

The `<ListboxItem>` component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

### Virtualization

Listbox supports virtualization, which allows efficient rendering of large lists by only rendering items that are visible in the viewport. You can enable virtualization by setting the `isVirtualized` prop to `true`.

Preview

Code

Open in Chat

> **Note**: The virtualization strategy is based on the @tanstack/react-virtual package, which provides efficient rendering of large lists by only rendering items that are visible in the viewport.

#### Ten Thousand Items

Here's an example of using virtualization with 10,000 items.

Preview

Code

Open in Chat

## Slots

Listbox has 3 components with slots the base one `Listbox`, `ListboxItem` and `ListboxSection` components.

### Listbox

*   **base**: The main wrapper for the listbox component. This slot wraps the `topContent`, `bottomContent` and the `list` slot.
*   **list**: The slot for the listbox component. You can see this slot as the `ul` slot.
*   **emptyContent**: The slot content to display when the collection is empty.

### ListboxItem

*   **base**: The main slot for the listbox item. It wraps all the other slots.
*   **wrapper**: The `title` and `description` wrapper.
*   **title**: The title of the listbox item.
*   **description**: The description of the listbox item.
*   **selectedIcon**: The selected icon slot. This is only visible when the item is selected.

### ListboxSection

*   **base**: The main slot for the listbox section. It wraps all the other slots.
*   **heading**: The title that is render on top of the section group.
*   **group**: The group of listbox items.
*   **divider**: The divider that is render between the groups. This is only visible when `showDivider` is `true`.

### Customizing the listbox

You can customize the `Listbox` items style by using the `itemClasses` prop and passing custom Tailwind CSS classes.

Preview

Code

Open in Chat

> **Note**: In the above example, we've utilized the Boxicons icons collection.

### Keyboard Interactions

| Key | Description |
| --- | --- |
| Home | Moves focus to the first item. |
| End | Moves focus to the last item. |
| ArrowDown | When focus is on an item, moves focus to the next item. |
| ArrowUp | When focus is on an item, moves focus to the previous item. |
| Enter or Space | When focus is on an item, selects the item. |
| A-Z or a-z | Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists. |

## Data Attributes

`ListboxItem` has the following attributes on the `base` element:

*   **data-disabled**: When the listbox item is disabled. Based on listbox `disabledKeys` prop.
*   **data-selected**: When the listbox item is selected. Based on listbox `selectedKeys` prop.
*   **data-selectable**: When the listbox item is selectable. Based on listbox `selectionMode` prop.
*   **data-hover**: When the listbox item is being hovered. Based on useHover
*   **data-pressed**: When the listbox item is pressed. Based on usePress
*   **data-focus**: When the listbox item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the listbox item is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Exposed to assistive technology as a `listbox` using ARIA.
*   Support for single, multiple, or no selection.
*   Support for disabled items.
*   Support for sections.
*   Labeling support for accessibility.
*   Support for mouse, touch, and keyboard interactions.
*   Tab stop focus management.
*   Keyboard navigation support including arrow keys, home/end, page up/down, select all, and clear.
*   Automatic scrolling support during keyboard navigation.
*   Typeahead to allow focusing options by typing text.

## API

### Listbox Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `variant`

 | `   solid | bordered | light | flat | faded | shadow   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `selectionMode`

 | `   none | single | multiple   ` |  |
| `selectedKeys`

 | `   React.Key[]   ` |  |
| `disabledKeys`

 | `   React.Key[]   ` |  |
| `defaultSelectedKeys`

 | `   all | React.Key[]   ` |  |
| `disallowEmptySelection`

 | `   boolean   ` | `false` |
| `shouldHighlightOnFocus`

 | `   boolean   ` | `false` |
| `autoFocus`

 | `   boolean | first | last   ` | `false` |
| `topContent`

 | `   ReactNode   ` |  |
| `bottomContent`

 | `   ReactNode   ` |  |
| `emptyContent`

 | `   ReactNode   ` | `"No items."` |
| `shouldFocusWrap`

 | `   boolean   ` | `false` |
| `isVirtualized`

 | `   boolean   ` | `false` |
| `virtualization`

 | `   Record<"maxListboxHeight" & "itemHeight", number>   ` |  |
| `hideEmptyContent`

 | `   boolean   ` | `false` |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "list" | "emptyContent", string>>   ` |  |
| `itemClasses`

 | `   Partial<Record<"base" | "wrapper" | "title" | "description" | "selectedIcon", string>>   ` |  |

### Listbox Events

| Prop | Type | Default |
| --- | --- | --- |
| `onAction`
 | `   (key: React.Key) => void   ` |  |
| `onSelectionChange`

 | `   (keys: React.Key[]) => void   ` |  |

### ListboxSection Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `title`

 | `   string   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `showDivider`

 | `   boolean   ` | `false` |
| `dividerProps`

 | `   DividerProps   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "heading" | "group" | "divider", string>>   ` |  |
| `itemClasses`

 | `   Partial<Record<"base" | "wrapper" | "title" | "description" | "shortcut" | "selectedIcon", string>>   ` |  |

### ListboxItem Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `key`

 | `   React.Key   ` |  |
| `title`

 | `   string | ReactNode   ` |  |
| `textValue`

 | `   string   ` |  |
| `description`

 | `   string | ReactNode   ` |  |
| `shortcut`

 | `   string | ReactNode   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `selectedIcon`

 | `   ListboxItemSelectedIconProps   ` |  |
| `href`

 | `   string   ` |  |
| `target`

 | `   HTMLAttributeAnchorTarget   ` |  |
| `rel`

 | `   string   ` |  |
| `download`

 | `   boolean | string   ` |  |
| `ping`

 | `   string   ` |  |
| `referrerPolicy`

 | `   HTMLAttributeReferrerPolicy   ` |  |
| `shouldHighlightOnFocus`

 | `   boolean   ` | `false` |
| `hideSelectedIcon`

 | `   boolean   ` | `false` |
| `showDivider`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isSelected`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "wrapper" | "title" | "description" | "shortcut" | "selectedIcon", string>>   ` |  |

### ListboxItem Events

| Prop | Type | Default |
| --- | --- | --- |
| `onAction`
 | `   () => void   ` |  |
| `onPress`

 | `   (e: PressEvent) => void   ` |  |
| `onPressStart`

 | `   (e: PressEvent) => void   ` |  |
| `onPressEnd`

 | `   (e: PressEvent) => void   ` |  |
| `onPressChange`

 | `   (isPressed: boolean) => void   ` |  |
| `onPressUp`

 | `   (e: PressEvent) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onClick`

 | `   MouseEventHandler   ` |  |

* * *

### Types

#### Listbox Item Selected Icon Props

---

## Page: https://www.heroui.com/docs/components/modal

# Modal

Displays a dialog with custom content that requires attention or provides additional information.

Storybook@heroui/modalReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 5 modal-related components:

*   **Modal**: The main component to display a modal.
*   **ModalContent**: The wrapper of the other modal components.
*   **ModalHeader**: The header of the modal.
*   **ModalBody**: The body of the modal.
*   **ModalFooter**: The footer of the modal.

Individual

Global

## Usage

When the modal opens:

*   Focus is bounded within the modal and set to the first tabbable element.
*   Content behind the modal dialog is inert, meaning that users cannot interact with it.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Non-dismissible

By default, the modal can be closed by clicking on the overlay or pressing the Esc key. You can disable this behavior by setting the following properties:

*   Set the `isDismissable` property to `false` to prevent the modal from closing when clicking on the overlay.
*   Set the `isKeyboardDismissDisabled` property to `true` to prevent the modal from closing when pressing the Esc key.

Preview

Code

Open in Chat

### Modal placement

By default the modal is centered on screens larger than `sm` and is at the `bottom` of the screen on mobile. This placement is called `auto`, but you can change it by using the `placement` prop.

Preview

Code

Open in Chat

> **Note**: The `top-center` and `bottom-center` positions mean that the modal is positioned at the top / bottom of the screen on mobile, and at the center of the screen on desktop.

### Overflow scroll

You can use the `scrollBehavior` prop to set the scroll behavior of the modal.

*   **inside**: The modal content will be scrollable.
*   **outside**: The modal content will be scrollable and the modal will be fixed.

Preview

Code

Open in Chat

### With Form

The `Modal` handles the focus within the modal content. It means that you can use the modal with form elements without any problem. The focus returns to the trigger when the modal closes.

Preview

Code

Open in Chat

> **Note**: You can add the `autoFocus` prop to the first `Input` component to focus it when the modal opens.

### Backdrop

The `Modal` component has a `backdrop` prop to show a backdrop behind the modal. The backdrop can be either `transparent`, `opaque` or `blur`. The default value is `opaque`.

Preview

Code

Open in Chat

### Custom Backdrop

You can customize the backdrop by using the `backdrop` slot.

Preview

Code

Open in Chat

### Custom Motion

Modal offers a `motionProps` property to customize the `enter` / `exit` animation.

Preview

Code

Open in Chat

> Learn more about Framer motion variants here.

### Draggable

Try to drag the modal by clicking on the modal header and dragging.

Preview

Code

Open in Chat

### Draggable Overflow

Setting overflow to `true` allows users to drag the modal to a position where it overflows the viewport.

Preview

Code

Open in Chat

## Slots

*   **wrapper**: The wrapper slot of the modal. It wraps the `base` and the `backdrop` slots.
*   **base**: The main slot of the modal content.
*   **backdrop**: The backdrop slot, it is displayed behind the modal.
*   **header**: The header of the modal, it is displayed at the top of the modal.
*   **body**: The body of the modal, it is displayed in the middle of the modal.
*   **footer**: The footer of the modal, it is displayed at the bottom of the modal.
*   **closeButton**: The close button of the modal.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`Modal` has the following attributes on the `base` element:

*   **data-open**: When the modal is open. Based on modal state.
*   **data-dismissable**: When the modal is dismissable. Based on `isDismissable` prop.

## Accessibility

*   Content outside the modal is hidden from assistive technologies while it is open.
*   The modal optionally closes when interacting outside, or pressing the Esc key.
*   Focus is moved into the modal on mount, and restored to the trigger element on unmount.
*   While open, focus is contained within the modal, preventing the user from tabbing outside.
*   Scrolling the page behind the modal is prevented while it is open, including in mobile browsers.

## API

### Modal Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `size`

 | `   xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | full   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg   ` | `"lg"` |
| `shadow`

 | `   none | sm | md | lg   ` | `"lg"` |
| `backdrop`

 | `   transparent | opaque | blur   ` | `"opaque"` |
| `scrollBehavior`

 | `   normal | inside | outside   ` | `"normal"` |
| `placement`

 | `   auto | top | center | bottom   ` | `"auto"` |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` |  |
| `isDismissable`

 | `   boolean   ` | `true` |
| `isKeyboardDismissDisabled`

 | `   boolean   ` | `false` |
| `shouldBlockScroll`

 | `   boolean   ` | `true` |
| `hideCloseButton`

 | `   boolean   ` | `false` |
| `closeButton`

 | `   ReactNode   ` |  |
| `motionProps`

 | `   MotionProps   ` |  |
| `portalContainer`

 | `   HTMLElement   ` | `"document.body"` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'wrapper' | 'base' | 'backdrop' | 'header' | 'body' | 'footer' | 'closeButton', string>>   ` |  |

### Modal Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### Modal types

#### Motion Props

---

## Page: https://www.heroui.com/docs/components/navbar

# Navbar

A responsive navigation header positioned on top side of your page that includes support for branding, links, navigation, collapse menu and more.

Storybook@heroui/navbarSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 7 navbar-related components:

*   **Navbar**: The main component of navbar.
*   **NavbarBrand**: The component for branding.
*   **NavbarContent**: The component for wrapping navbar items.
*   **NavbarItem**: The component for navbar item.
*   **NavbarMenuToggle**: The component for toggling navbar menu.
*   **NavbarMenu**: The component for wrapping navbar menu items.
*   **NavbarMenuItem**: The component for navbar menu item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Static

You can use the `position` prop to make the navbar static positioned (the default behavior is `sticky`).

Preview

Code

Open in Chat

### Hide on scroll

It is possible to hide the navbar on scroll by using the `shouldHideOnScroll` prop.

Preview

Code

Open in Chat

### With Menu

You can use the `NavbarMenuToggle` and `NavbarMenu` components to display a togglable menu.

Preview

Code

Open in Chat

If you want to remove the `open` / `close` animation, you can pass the `disableAnimation={true}` prop to `Navbar` component.

Preview

Code

Open in Chat

### Controlled Menu

You can use the `isMenuOpen` and `onMenuOpenChange` props to control the navbar menu state.

Preview

Code

Open in Chat

### With Border

You can use the `isBordered` prop to add a bottom border to the navbar.

Preview

Code

Open in Chat

### Disabling Blur

Navbar has a blur effect by default. You can disable it by using the `isBlurred=false` prop.

Preview

Code

Open in Chat

### With Dropdown Menu

It is possible to use the Dropdown component to display a dropdown menu as navbar item.

Preview

Code

Open in Chat

### With Avatar

Example of a navbar with avatar and dropdown menu.

Preview

Code

Open in Chat

### With Search Input

Example of a navbar with search input.

Preview

Code

Open in Chat

### Customizing the active item

When the `NavbarItem` is active, it will have a `data-active` attribute. You can use this attribute to customize it.

Preview

Code

Open in Chat

## Slots

*   **base**: The main slot for the navbar. It takes the full width of the parent and wraps the navbar elements including the menu.
*   **wrapper**: The slot that contains the navbar elements such as `brand`, `content` and `toggle`.
*   **brand**: The slot for the `NavbarBrand` component.
*   **content**: The slot for the `NavbarContent` component.
*   **item**: The slot for the `NavbarItem` component.
*   **toggle**: The slot for the `NavbarMenuToggle` component.
*   **toggleIcon**: The slot for the `NavbarMenuToggle` icon.
*   **menu**: The slot for the `NavbarMenu` component.
*   **menuItem**: The slot for the `NavbarMenuItem` component.

## Data Attributes

`Navbar` has the following attributes on the `base` element:

*   **data-menu-open**: Indicates if the navbar menu is open.
*   **data-hidden**: Indicates if the navbar is hidden. It is used when the `shouldHideOnScroll` prop is `true`.

`NavbarContent`

*   **data-justify**: The justify content of the navbar content. It takes into account the correct space distribution.

`NavbarItem` has the following attributes on the `base` element:

*   **data-active**: Indicates if the navbar item is active. It is used when the `isActive` prop is `true`.

`NavbarMenuToggle` has the following attributes on the `base` element:

*   **data-open**: Indicates if the navbar menu is open. It is used when the `isMenuOpen` prop is `true`.
*   **data-pressed**: When the navbar menu toggle is pressed. Based on usePress
*   **data-hover**: When the navbar menu toggle is being hovered. Based on useHover
*   **data-focus-visible**: When the navbar menu toggle is being focused with the keyboard. Based on useFocusRing.

`NavbarMenuItem` has the following attributes on the `base` element:

*   **data-active**: Indicates if the menu item is active. It is used when the `isActive` prop is `true`.

## API

### Navbar Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `height`

 | `   string | number   ` | `"4rem (64px)"` |
| `position`

 | `   static | sticky   ` | `"sticky"` |
| `maxWidth`

 | `   sm | md | lg | xl | 2xl | full   ` | `"lg"` |
| `parentRef`

 | `   React.RefObject<HTMLElement>   ` | `"window"` |
| `isBordered`

 | `   boolean   ` | `false` |
| `isBlurred`

 | `   boolean   ` | `true` |
| `isMenuOpen`

 | `   boolean   ` | `false` |
| `isMenuDefaultOpen`

 | `   boolean   ` | `false` |
| `shouldHideOnScroll`

 | `   boolean   ` | `false` |
| `motionProps`

 | `   MotionProps   ` |  |
| `disableScrollHandler`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'wrapper' | 'brand' | 'content' | 'item' | 'toggle' | 'toggleIcon' | 'menu' | 'menuItem', string>>   ` |  |

### Navbar Events

| Prop | Type | Default |
| --- | --- | --- |
| `onMenuOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `onScrollPositionChange`

 | `   (position: number) => void   ` |  |

### NavbarContent Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `justify`

 | `   start | center | end   ` | `"start"` |

### NavbarItem Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `isActive`

 | `   boolean   ` | `false` |

### NavbarMenuToggle Props

| Prop | Type | Default |
| --- | --- | --- |
| `icon`
 | `   ReactNode | ((isOpen: boolean | undefined) => ReactNode)   ` |  |
| `isSelected`

 | `   boolean   ` | `false` |
| `defaultSelected`

 | `   boolean   ` | `false` |
| `srOnlyText`

 | `   string   ` | `"open/close navigation menu"` |

### NavbarMenuToggle Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (isOpen: boolean) => void   ` |  |

### NavbarMenu Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `portalContainer`

 | `   HTMLElement   ` | `"document.body"` |
| `motionProps`

 | `   MotionProps   ` |  |

### NavbarMenuItem Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `isActive`

 | `   boolean   ` | `false` |

### Types

---

## Page: https://www.heroui.com/docs/components/number-input

# Number Input

The numeric input component is designed for users to enter a number, and increase or decrease the value using stepper buttons

Storybook@heroui/number-inputReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the input, it will have a `danger` asterisk at the end of the label and the input will be required.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Clear Button

If you pass the `isClearable` property to the input, it will have a clear button at the end of input, it will be visible when input has a value.

Preview

Code

Open in Chat

### Hide Stepper

You can hide the stepper buttons by passing the `hideStepper` property.

Preview

Code

Open in Chat

### Start & End Content

You can use the `startContent` and `endContent` properties to add content to the start and end of NumberInput.

Preview

Code

Open in Chat

### With Label

You can add a label to the input by passing the `label` property.

Preview

Code

Open in Chat

### With Description

You can add a description to the input by passing the `description` property.

Preview

Code

Open in Chat

### With Min Value

You can set the minimum value of the input by passing the `minValue` property.

Preview

Code

Open in Chat

### With Max Value

You can set the maximum value of the input by passing the `maxValue` property.

Preview

Code

Open in Chat

### With Wheel Disabled

By default, you can increase or decrease the value with scroll wheel. You can disable changing the vaule with scroll in NumberInput by passing the `isWheelDisabled` property.

Preview

Code

Open in Chat

### With Format Options

You can format the value of the input by passing the `formatOptions` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input. `errorMessage` is only shown when `isInvalid` is set to `true`.

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onValueChange` properties to control the input value.

Preview

Code

Open in Chat

> **Note**: HeroUI `NumberInput` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

### With Form

`NumberInput` can be used with a `Form` component to leverage form state management. For more on form and validation behaviors, see the Forms guide.

#### Custom Validation

In addition to built-in constraints, you can provide a function to the `validate` property for custom validation.

Preview

Code

Open in Chat

#### Realtime Validation

If you want to display validation errors while the user is typing, you can control the field value and use the `isInvalid` prop along with the `errorMessage` prop.

Preview

Code

Open in Chat

#### Server Validation

Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. HeroUI allows you to display server-side validation errors by using the `validationErrors` prop in the `Form` component. This prop should be an object where each key is the field `name` and the value is the error message.

Preview

Code

Open in Chat

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **label**: Label of the input, it is the one that is displayed above, inside or left of the input.
*   **mainWrapper**: Wraps the `inputWrapper`
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **innerWrapper**: Wraps the `input`, the `startContent` and the `endContent`.
*   **input**: The input element.
*   **clearButton**: The clear button, it is at the end of the input.
*   **stepperButton**: The stepper button to increase or decrease the value.
*   **stepperWrapper**: The wrapper for the stepper.
*   **description**: The description of NumberInput.
*   **errorMessage**: The error message of NumberInput.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`NumberInput` has the following attributes on the `base` element:

*   **data-invalid**: When the input is invalid. Based on `isInvalid` prop.
*   **data-required**: When the input is required. Based on `isRequired` prop.
*   **data-readonly**: When the input is readonly. Based on `isReadOnly` prop.
*   **data-hover**: When the input is being hovered. Based on useHover
*   **data-focus**: When the input is being focused. Based on useFocusRing.
*   **data-focus-within**: When the input is being focused or any of its children. Based on useFocusWithin.
*   **data-focus-visible**: When the input is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the input is disabled. Based on `isDisabled` prop.
*   **data-filled**: When the input has content, placeholder, start content or the placeholder is shown.
*   **data-has-elements**: When the input has any element (label, helper text, description, error message).
*   **data-has-helper**: When the input has helper text.
*   **data-has-description**: When the input has a description.
*   **data-has-label**: When the input has a label.
*   **data-has-value**: When the input has a value (placeholder is not shown).

## Accessibility

*   Built with a native `<input>` element with `type="number"`.
*   Visual and ARIA labeling support.
*   Change, clipboard, composition, selection, and input event support.
*   Required and invalid states exposed to assistive technology via ARIA.
*   Support for description, helper text, and error message linked to the input via ARIA.

## API

### NumberInput Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `name`

 | `   string   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `value`

 | `   string   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `placeholder`

 | `   string   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: string) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `minValue`

 | `   number   ` |  |
| `maxValue`

 | `   number   ` |  |
| `formatOptions`

 | `   Intl.NumberFormatOptions   ` |  |
| `step`

 | `   number   ` | `"1"` |
| `hideStepper`

 | `   boolean   ` |  |
| `isWheelDisabled`

 | `   boolean   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `isClearable`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `incrementAriaLabel`

 | `   string   ` |  |
| `decrementAriaLabel`

 | `   string   ` |  |
| `baseRef`

 | `   RefObject<HTMLDivElement>   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'label' | 'inputWrapper' | 'innerWrapper' | 'mainWrapper' | 'input' | 'clearButton' | 'stepperButton' | 'helperWrapper' | 'stepperWrapper' | 'description' | 'errorMessage', string>>   ` |  |

### NumberInput Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (value: number) => void   ` |  |
| `onClear`

 | `   () => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/pagination

# Pagination

The Pagination component allows you to display active page and navigate between multiple pages.

Storybook@heroui/paginationSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 pagination-related components:

*   **Pagination**: The main component to display a pagination.
*   **PaginationItem**: The internal component to display a pagination item.
*   **PaginationCursor**: The internal item component to display the current page.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

You can use the `variant` property to change the pagination items style.

Preview

Code

Open in Chat

### With Controls

You can set the `showControls` to `true` to display the `next` and `previous` buttons.

Preview

Code

Open in Chat

### Pagination Loop

In case you want to loop the pagination, you can set the `loop` property to `true`. The cursor will go back to the first page when it reaches the last page and vice versa.

Preview

Code

Open in Chat

### Changing the initial page

You can change the initial page by setting the `initialPage` property.

Preview

Code

Open in Chat

### Compact Pagination

You can set the `isCompact` property to `true` to display reduced version of the pagination.

Preview

Code

Open in Chat

### With Shadow

You can use the `showShadow` property to display a shadow below the active page item.

Preview

Code

Open in Chat

### Controlled

Preview

Code

Open in Chat

### Siblings

You can control the number of pages to show before and after the current page by setting the `siblings` property.

Preview

Code

Open in Chat

### Boundaries

You can control the number of pages to show at the beginning and end of the pagination by setting the `boundaries` property.

Preview

Code

Open in Chat

### Custom items

You can use the `renderItem` property to customize the pagination items.

Preview

Code

Open in Chat

## Slots

*   **base**: The main pagination slot.
*   **wrapper**: The pagination wrapper slot. This wraps the pagination items.
*   **prev**: The previous button slot.
*   **next**: The next button slot.
*   **item**: The pagination item slot, applied to the middle items.
*   **cursor**: The current page slot. Available only when `disableCursorAnimation` is `false` and `disableAnimation` is `false`.
*   **forwardIcon**: The forward icon slot. The one that appears when hovering the ellipsis button.
*   **ellipsis**: The ellipsis slot.
*   **chevronNext**: The chevron next icon slot.

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the pagination even further, you can use the `usePagination` hook to create your own implementation.

Preview

Code

Open in Chat

## Data Attributes

`Pagination` has the following attributes on the `base` element:

*   **data-controls**: Indicates whether the pagination has controls. Based on `showControls` prop.
*   **data-loop**: When the pagination is looped. Based on `loop` prop.
*   **data-dots-jump**: Indicates whether the pagination has dots jump. Based on `dotsJump` prop.
*   **data-total**: The total number of pages. Based on `total` prop.
*   **data-active-page**: The active page. Based on `activePage` prop.

## Accessibility

*   The root node has a role of `navigation` by default.
*   The pagination items have an aria-label that identifies the item purpose ("next page button", "previous page button", etc.), you can override this label by using the `getItemAriaLabel` function.
*   The pagination items are in tab order, with a tabindex of "0".

## API

### Pagination Props

| Prop | Type | Default |
| --- | --- | --- |
| `variant`
 | `   flat | bordered | light | faded   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"xl"` |
| `total`

 | `   number   ` | `"1"` |
| `dotsJump`

 | `   number   ` | `"5"` |
| `initialPage`

 | `   number   ` | `"1"` |
| `page`

 | `   number   ` |  |
| `siblings`

 | `   number   ` | `"1"` |
| `boundaries`

 | `   number   ` | `"1"` |
| `loop`

 | `   boolean   ` | `false` |
| `isCompact`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `showShadow`

 | `   boolean   ` | `false` |
| `showControls`

 | `   boolean   ` | `false` |
| `disableCursorAnimation`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `renderItem`

 | `   PaginationItemProps   ` |  |
| `getItemAriaLabel`

 | `   (page: string) => string   ` |  |
| `classNames`

 | `   Partial<Record<'base' | 'wrapper' | 'prev' | 'next' | 'item' | 'cursor' | 'forwardIcon' | 'ellipsis' | 'chevronNext', string>>   ` |  |

### Pagination Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (page: number) => void   ` |  |

* * *

### Types

#### Pagination Item Props

---

## Page: https://www.heroui.com/docs/components/popover

# Popover

Popover is a **non-modal** dialog that floats around its disclosure. It's commonly used for displaying additional rich content on top of something.

Storybook@heroui/popoverReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 popover-related components:

*   **Popover**: The main component to display a popover.
*   **PopoverTrigger**: The component that triggers the popover.
*   **PopoverContent**: The component that contains the popover content.

Individual

Global

## Usage

Preview

Code

Open in Chat

### With Arrow

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Placements

Preview

Code

Open in Chat

### Offset

Preview

Code

Open in Chat

### Controlled

Preview

Code

Open in Chat

### Title Props

To be sure that the popover exposes the correct title to assistive technologies, you should use the `titleProps` prop on the `PopoverContent` component. To use this prop, you must pass a function as a child.

Preview

Code

Open in Chat

### With Form

The `Popover` handles the focus within the popover content. It means that you can use the popover with form elements without any problem. the focus returns to the trigger when the popover closes.

Preview

Code

Open in Chat

> **Note**: You can add the `autoFocus` prop to the first `Input` component to focus it when the popover opens.

### Backdrop

The `Popover` component has a `backdrop` prop to show a backdrop behind the popover. The backdrop can be either `transparent`, `opaque` or `blur`. The default value is `transparent`.

Preview

Code

Open in Chat

### Custom Motion

Popover offers a `motionProps` property to customize the `enter` / `exit` animation.

Preview

Code

Open in Chat

> Learn more about Framer motion variants here.

### Custom Trigger

Preview

Code

Open in Chat

## Slots

*   **base**: The main popover slot, it wraps the popover content and contains the arrow as a pseudo-element (::before).
*   **trigger**: The popover trigger slot, it has small styles to ensure the trigger works correctly.
*   **backdrop**: The backdrop slot, it contains the backdrop styles.
*   **content**: The content slot, it contains the popover content.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`Popover` has the following attributes on the `PopoverContent` element:

*   **data-open**: When the popover is open. Based on popover state.
*   **data-placement**: The placement of the popover. Based on `placement` prop. The arrow element is positioned based on this attribute.
*   **data-focus**: When the popover is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the popover is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   The trigger and popover are automatically associated semantically via ARIA.
*   Content outside the popover is hidden from assistive technologies while it is open.
*   The popover closes when interacting outside, or pressing the Escape key.
*   Focus is moved into the popover on mount, and restored to the trigger element on unmount.
*   The popover is positioned relative to the trigger element, and automatically flips and adjusts to avoid overlapping with the edge of the browser window.
*   Scrolling is prevented outside the popover to avoid unintentionally repositioning or closing it.

## API

### Popover Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"lg"` |
| `shadow`

 | `   none | sm | md | lg   ` | `"lg"` |
| `backdrop`

 | `   transparent | opaque | blur   ` | `"transparent"` |
| `placement`

 | `   PopoverPlacement   ` | `"bottom"` |
| `state`

 | `   OverlayTriggerState   ` |  |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` |  |
| `offset`

 | `   number   ` | `"7"` |
| `containerPadding`

 | `   number   ` | `"12"` |
| `crossOffset`

 | `   number   ` | `"0"` |
| `triggerType`

 | `   dialog | menu | listbox | tree | grid   ` | `"dialog"` |
| `showArrow`

 | `   boolean   ` | `false` |
| `shouldFlip`

 | `   boolean   ` | `true` |
| `triggerScaleOnOpen`

 | `   boolean   ` | `true` |
| `shouldBlockScroll`

 | `   boolean   ` | `false` |
| `shouldCloseOnScroll`

 | `   boolean   ` | `false` |
| `isKeyboardDismissDisabled`

 | `   boolean   ` | `false` |
| `shouldCloseOnBlur`

 | `   boolean   ` | `false` |
| `motionProps`

 | `   MotionProps   ` |  |
| `portalContainer`

 | `   HTMLElement   ` | `"document.body"` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'trigger' | 'backdrop' | 'content', string>>   ` |  |

### Popover Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `shouldCloseOnInteractOutside`

 | `   (e: HTMLElement) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### PopoverTrigger Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |

### PopoverContent Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |

### Popover types

#### Popover Placement

#### Motion Props

---

## Page: https://www.heroui.com/docs/components/progress

# Progress

The Progress component allows you to view the progress of any activity.

Storybook@heroui/progressReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

> **Note**: Make sure to pass the `aria-label` prop when the `label` prop is not provided. This is required for accessibility.

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Indeterminate

You can use the `isIndeterminate` prop to display an indeterminate progress bar. This is useful when you don't know how long an operation will take.

Preview

Code

Open in Chat

### Striped

Preview

Code

Open in Chat

### With Label

Preview

Code

Open in Chat

> **Note**: If you pass the `label` prop you don't need to pass `aria-label` prop anymore.

### With Value

Preview

Code

Open in Chat

### Value Formatting

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format. `formatOptions` is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the progress, it is the main container.
*   **labelWrapper**: The label and value label wrapper.
*   **label**: The label of the progress.
*   **value**: The value label of the progress.
*   **track**: The track is the background bar of the progress.
*   **indicator**: The indicator is the bar that is filled according to the `value`.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`CircularProgress` has the following attributes on the `base` element:

*   **data-indeterminate**: Indicates whether the progress is indeterminate.
*   **data-disabled**: Indicates whether the progress is disabled. Based on `isDisabled` prop.

## Accessibility

*   Exposed to assistive technology as a progress bar via ARIA.
*   Labeling support for accessibility.
*   Internationalized number formatting as a percentage or value.
*   Determinate and indeterminate progress support.
*   Exposes the `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` attributes.

## API

### Progress Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"full"` |
| `value`

 | `   number   ` |  |
| `valueLabel`

 | `   ReactNode   ` |  |
| `minValue`

 | `   number   ` | `"0"` |
| `maxValue`

 | `   number   ` | `"100"` |
| `formatOptions`

 | `   Intl.NumberFormat   ` | `"{style: 'percent'}"` |
| `isIndeterminate`

 | `   boolean   ` | `false` |
| `isStriped`

 | `   boolean   ` | `false` |
| `showValueLabel`

 | `   boolean   ` | `true` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'labelWrapper' | 'label' | 'track' | 'value' | 'indicator', string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/radio-group

# Radio group

Radio Group allow users to select a single option from a list of mutually exclusive options.

Storybook@heroui/radioReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Default Value

Preview

Code

Open in Chat

### With Description

Preview

Code

Open in Chat

### Horizontal

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onValueChange` properties to control the radio input value.

Preview

Code

Open in Chat

> **Note**: HeroUI `Radio` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

### Invalid

Preview

Code

Open in Chat

## Slots

*   RadioGroup Slots
    
    *   **base**: Radio group root wrapper, it wraps the label and the wrapper.
    *   **wrapper**: Radio group wrapper, it wraps all Radios.
    *   **label**: Radio group label, it is placed before the wrapper.
    *   **description**: Description slot for the radio group.
    *   **errorMessage**: Error message slot for the radio group.
*   Radio Slots
    
    *   **base**: Radio root wrapper, it wraps all elements.
    *   **wrapper**: Radio wrapper, it wraps the control element.
    *   **hiddenInput**: The hidden input element that is used to handle the radio state.
    *   **labelWrapper**: Label and description wrapper.
    *   **label**: Label slot for the radio.
    *   **control**: Control element, it is the circle element.
    *   **description**: Description slot for the radio.

### Custom Styles

You can customize the `RadioGroup` and `Radio` component by passing custom Tailwind CSS classes to the component slots.

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the radio group even further, you can use the `useRadio` hook to create your own implementation.

Preview

Code

Open in Chat

## Data Attributes

*   RadioGroup has the following attributes on the `base` element:
    
    *   **data-orientation**: The orientation of the radio group. Based on `orientation` prop.
*   Radio has the following attributes on the `base` element:
    
    *   **data-selected**: When the radio is checked. Based on `isSelected` prop.
    *   **data-pressed**: When the radio is pressed. Based on usePress.
    *   **data-invalid**: When the radio is invalid. Based on `validationState` prop.
    *   **data-readonly**: When the radio is readonly. Based on `isReadOnly` prop.
    *   **data-hover-unselected**: When the radio is being hovered and unchecked. Based on useHover.
    *   **data-hover**: When the radio is being hovered. Based on useHover.
    *   **data-focus**: When the radio is being focused. Based on useFocusRing.
    *   **data-focus-visible**: When the radio is being focused with the keyboard. Based on useFocusRing.
    *   **data-disabled**: When the radio is disabled. Based on `isDisabled` prop.

## Accessibility

*   Radio groups are exposed to assistive technology via ARIA.
*   Each radio is built with a native HTML `<input>` element, which can be optionally visually hidden to allow custom styling.
*   Full support for browser features like form autofill.
*   Keyboard event support for arrows keys.
*   Keyboard focus management and cross browser normalization.
*   Group and radio labeling support for assistive technology.

## API

### RadioGroup Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode | ReactNode[]   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `orientation`

 | `   horizontal | vertical   ` | `"vertical"` |
| `name`

 | `   string   ` |  |
| `value`

 | `   string[]   ` |  |
| `defaultValue`

 | `   string[]   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: string) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `isInvalid`

 | `   boolean   ` | `false` |
| `validationState`

 | `   valid | invalid   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "wrapper" | "label", string>>   ` |  |

### RadioGroup Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   ((value: string) => void)   ` |  |

### Radio Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `description`

 | `   ReactNode   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `isInvalid`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "wrapper" | "labelWrapper" | "label" | "control" | "description", string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/range-calendar

# Range Calendar

A range calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating through time. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date range. Once a start date is selected, the user can navigate to another date using the keyboard or by hovering over it, and clicking it or pressing the Enter key commits the selected date range.

Storybook@heroui/calendarReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

A RangeCalendar has no selection by default. An initial, uncontrolled value can be provided to the RangeCalendar using the `defaultValue` prop. Alternatively, a controlled value can be provided using the `value` prop.

Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

Preview

Code

Open in Chat

### Disabled

The `isDisabled` boolean prop makes the Calendar disabled. Cells cannot be focused or selected.

Preview

Code

Open in Chat

### Read Only

The `isReadOnly` boolean prop makes the Calendar's value immutable. Unlike `isDisabled`, the Calendar remains focusable.

Preview

Code

Open in Chat

### Controlled

A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar using the `defaultValue` prop. Alternatively, a controlled value can be provided using the value prop.

Preview

Code

Open in Chat

### Min Date Value

By default, Calendar allows selecting any date. The `minValue` can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

Preview

Code

Open in Chat

### Max Date Value

By default, Calendar allows selecting any date. The `maxValue` can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates before today.

Preview

Code

Open in Chat

### Unavailable Dates

Calendar supports marking certain dates as unavailable. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.

Preview

Code

Open in Chat

### Non-Contiguous Ranges

The `allowsNonContiguousRanges` prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.

Preview

Code

Open in Chat

### Controlled Focused Value

Calendar tries to avoid allowing the user to select invalid dates in the first place. However, if according to application logic a selected date is invalid, the isInvalid prop can be set. This alerts assistive technology users that the selection is invalid, and can be used for styling purposes as well. In addition, the errorMessage slot may be used to help the user fix the issue.

By default, the selected date is focused when a Calendar first mounts. If no `value` or `defaultValue` prop is provided, then the current date is focused. However, Calendar supports controlling which date is focused using the `focusedValue` and `onFocusChange` props. This also determines which month is visible. The `defaultFocusedValue` prop allows setting the initial focused date when the Calendar first mounts, without controlling it.

Preview

Code

Open in Chat

### Invalid Date

This example validates that the selected date is a weekday and not a weekend according to the current locale.

Preview

Code

Open in Chat

### With Month And Year Picker

Calendar supports month and year picker for rapid selection. You can enable this feature by setting `showMonthAndYearPickers` to `true`. However, if `visibleMonths` is set to a number greater than 1, this feature will be disabled.

Preview

Code

Open in Chat

### International Calendars

Calendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the `Provider` component.

Preview

Code

Open in Chat

### Visible Months

By default, the Calendar displays a single month. The `visibleMonths` prop allows displaying up to 3 months at a time.

Preview

Code

Open in Chat

### Custom first day of week

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.

Preview

Code

Open in Chat

### Page Behaviour

By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.

Preview

Code

Open in Chat

### Presets

Here's the example to customize `topContent` and `bottomContent` to have some preset values.

Preview

Code

Open in Chat

## Slots

*   **base**: Calendar wrapper, it handles alignment, placement, and general appearance.
*   **prevButton**: The previous button of the calendar.
*   **nextButton**: The next button of the calendar.
*   **headerWrapper**: Wraps the picker (month / year).
*   **header**: The header element.
*   **title**: A description of the visible date range, for use in the calendar title.
*   **gridWrapper**: The wrapper for the calendar grid.
*   **grid**: The date grid element (e.g. `<table>`).
*   **gridHeader**: The date grid header element (e.g. `<th>`).
*   **gridHeaderRow**: The date grid header row element (e.g. `<tr>`).
*   **gridHeaderCell**: The date grid header cell element (e.g. `<td>`).
*   **gridBody**: The date grid body element (e.g. `<tbody>`).
*   **gridBodyRow**: The date grid body row element (e.g. `<tr>`).
*   **cell**: The date grid cell element (e.g. `<td>`).
*   **cellButton**: The button element within the cell.
*   **pickerWrapper**: The wrapper for the picker
*   **pickerMonthList**: The month list picker.
*   **pickerYearList**: The year list picker.
*   **pickerHighlight**: The highlighted item of the picker.
*   **pickerItem**: The item of the picker.
*   **helperWrapper**: The helper message of the calendar.
*   **errorMessage**: The error message of the calendar.

## Data Attributes

`Calendar` has the following attributes on the `CalendarCell` element:

*   **data-focused**: Whether the cell is focused.
*   **data-hovered**: Whether the cell is currently hovered with a mouse.
*   **data-pressed**: Whether the cell is currently being pressed.
*   **data-unavailable**: Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough.
*   **data-disabled**: Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props.
*   **data-focus-visible**: Whether the cell is keyboard focused.
*   **data-outside-visible-range**: Whether the cell is outside the visible range of the calendar.
*   **data-outside-month**: Whether the cell is outside the current month.
*   **data-selected**: Whether the cell is selected.
*   **data-selected-start**: Whether the cell is the first date in a range selection.
*   **data-selected-end**: Whether the cell is the last date in a range selection.
*   **data-invalid**: Whether the cell is part of an invalid selection.

## Accessibility

*   Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
*   Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
*   Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.

## API

### RangeCalendar Props

| Prop | Type | Default |
| --- | --- | --- |
| `value`
 | `   RangeValue   ` | `"null"` |
| `defaultValue`

 | `   RangeValue   ` | `"null"` |
| `minValue`

 | `   DateValue   ` |  |
| `maxValue`

 | `   DateValue   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `visibleMonths`

 | `   number   ` | `"1"` |
| `firstDayOfWeek`

 | `   sun | mon | tue | wed | thu | fri | sat   ` |  |
| `focusedValue`

 | `   DateValue   ` |  |
| `defaultFocusedValue`

 | `   DateValue   ` |  |
| `calendarWidth`

 | `   number | string   ` | `"256"` |
| `pageBehavior`

 | `   PageBehavior   ` | `"visible"` |
| `weekdayStyle`

 | `   narrow | short | long   ` | `"narrow"` |
| `showMonthAndYearPickers`

 | `   boolean   ` | `false` |
| `allowsNonContiguousRanges`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` |  |
| `autoFocus`

 | `   boolean   ` | `false` |
| `showHelper`

 | `   boolean   ` | `false` |
| `showShadow`

 | `   boolean   ` | `false` |
| `topContent`

 | `   ReactNode   ` |  |
| `bottomContent`

 | `   ReactNode   ` |  |
| `isDateUnavailable`

 | `   (date: DateValue) => boolean   ` |  |
| `createCalendar`

 | `   (calendar: SupportedCalendars) => Calendar | null   ` | `"all calendars"` |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `validate`

 | `   (value: { inputValue: string, selectedKey: React.Key }) => ValidationError | true | null | undefined   ` |  |
| `hideDisabledDates`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |

### RangeCalendar Events

| Prop | Type | Default |
| --- | --- | --- |
| `onFocusChange`
 | `   (date: CalendarDate) => void   ` |  |
| `onChange`

 | `   (value: RangeValue<DateValue> | null) => void   ` |  |

#### Supported Calendars

---

## Page: https://www.heroui.com/docs/components/scroll-shadow

# Scroll Shadow

Applies top and bottom shadows when content overflows on scroll.

Storybook@heroui/scroll-shadowSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Hide Scrollbar

You can use the `hideScrollBar` property to hide vertical and horizontal scrollbars.

Preview

Code

Open in Chat

### Custom Shadow Size

By default, the shadow size is `40` in pixels, but you can change it using the `size` property.

Preview

Code

Open in Chat

### Horizontal Orientation

In case you need to apply the shadow on the horizontal scroll, you can set the `orientation` property to `horizontal`.

Preview

Code

Open in Chat

### Shadow Offset

By default the shadow offset is `0` in pixels, but you can change it using the `offset` property. This allows you to apply the shadow on a specific position.

Preview

Code

Open in Chat

## API

### ScrollShadow Props

| Prop | Type | Default |
| --- | --- | --- |
| `size`
 | `   number   ` | `"40"` |
| `offset`

 | `   number   ` | `"0"` |
| `hideScrollBar`

 | `   boolean   ` | `false` |
| `orientation`

 | `   horizontal | vertical   ` | `"vertical"` |
| `isEnabled`

 | `   boolean   ` | `true` |
| `visibility`

 | `   ScrollShadowVisibility   ` | `"auto"` |

### ScrollShadow Events

| Prop | Type | Default |
| --- | --- | --- |
| `onVisibilityChange`
 | `   (visibility: ScrollShadowVisibility) => void   ` |  |

### Types

#### Scroll Shadow Visibility

---

## Page: https://www.heroui.com/docs/components/select

# Select

A select displays a collapsible list of options and allows a user to select one or more of them.

Storybook@heroui/selectReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 3 select-related components:

*   **Select**: The main component, which is a wrapper for the other components.
*   **SelectSection**: The component that contains a group of select items.
*   **SelectItem**: The component that represents a select item.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic items

Select follows the Collection Components API, accepting both static and dynamic collections.

*   **Static**: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
*   **Dynamic**: The example below can be used when the options come from an external data source such as an API call, or update over time.

Preview

Code

Open in Chat

### Multiple Selection

You can use the `selectionMode="multiple"` property to allow multiple selection.

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Disabled Items

You can disable specific items by using the `disabledKeys` property.

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the select, it will have a `danger` asterisk at the end of the label and the select will be required.

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

Preview

Code

Open in Chat

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Start Content

You can use the `startContent` and `endContent` properties to add content to the start and end of the select.

Preview

Code

Open in Chat

### Item Start & End Content

Since the `Select` component uses the Listbox component under the hood, you can use the `startContent` and `endContent` properties of the `SelectItem` component to add content to the start and end of the select item.

Preview

Code

Open in Chat

### Custom Selector Icon

By default the select uses a `chevron-down` icon as the selector icon which rotates when the select is open. You can customize this icon by passing a custom one to the `selectorIcon` property.

Preview

Code

Open in Chat

> **Note**: Use the `disableSelectorIconRotation` property to disable the rotation of the icon.

### Without Scroll Shadow

Select component uses the ScrollShadow under the hood to show a shadow when the select content is scrollable. You can disable this shadow by passing using the `scrollShadowProps` property.

Preview

Code

Open in Chat

> **Note**: You can also use the `showScrollIndicators` property to disable the scroll indicators.

### With Description

You can add a description to the select by passing the `description` property.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid select.

Preview

Code

Open in Chat

### Controlled

You can use the `selectedKeys` and `onSelectionChange` / `onChange` properties to control the select value.

Using `onSelectionChange`:

Preview

Code

Open in Chat

Using `onChange`:

Preview

Code

Open in Chat

### Controlling the open state

You can control the open state of the select by using the `isOpen` and `onOpenChange` / `onClose` properties.

Preview

Code

Open in Chat

### Custom Items

You can customize the select items by modifying the `SelectItem` children.

Preview

Code

Open in Chat

### Custom Render Value

By default the select will render the selected item's text value, but you can customize this by passing a `renderValue` function.

Preview

Code

Open in Chat

The `renderValue` function receives the selected items as a parameter and must return a `ReactNode`. Check the Render Value Function section for more details.

### Asynchronous Loading

Select supports asynchronous loading, in the example below we are using a custom hook to fetch the Pokemon API data in combination with the `useInfiniteScroll` hook to load more data when the user reaches the end of the list.

The `isLoading` prop is used to show a loading indicator instead of the selector icon when the data is being fetched.

npm

yarn

pnpm

Preview

Code

Open in Chat

### Virtualization

Select supports virtualization, which allows efficient rendering of large lists by only rendering items that are visible in the viewport. You can enable virtualization by setting the `isVirtualized` prop to `true`.

Preview

Code

Open in Chat

> **Note**: The virtualization strategy is based on the @tanstack/react-virtual package, which provides efficient rendering of large lists by only rendering items that are visible in the viewport.

#### Ten Thousand Items

Here's an example of using virtualization with 10,000 items.

Preview

Code

Open in Chat

#### Max Listbox Height

The `maxListboxHeight` prop is used to set the maximum height of the listbox. This is required when using virtualization. By default, it's set to `256`.

Preview

Code

Open in Chat

#### Custom Item Height

The `itemHeight` prop is used to set the height of each item in the listbox. This is required when using virtualization. By default, it's set to `32`.

> **Note**: If the height of the list items differs from the default due to `startContent` or other custom content, be sure to pass the correct value to `itemHeight` to prevent layout issues.

Preview

Code

Open in Chat

### With Sections

You can use the `SelectSection` component to group select items.

Preview

Code

Open in Chat

### Custom Sections Style

You can customize the sections style by using the `classNames` property of the `SelectSection` component.

Preview

Code

Open in Chat

### Multiple Select Controlled

You can use the same properties as the single select to control the multiple select, `selectedKeys` and `onSelectionChange` / `onChange`.

Using `onSelectionChange`:

Preview

Code

Open in Chat

Using `onChange`:

Preview

Code

Open in Chat

### Multiple With Chips

You can render any component as the select value by using the `renderValue` property. In this example we are using the Chip component to render the selected items.

Preview

Code

Open in Chat

> **Note**: Make sure to pass the `isMultiline` property to the `Select` component to allow the chips to wrap.

The `renderValue` function receives the selected items as a parameter and must return a `ReactNode`. Check the Render Value Function section for more details.

### Customizing the select

You can customize any slot of the select by using the `classNames` property. Select component also provides the popoverProps and listboxProps properties to customize the popover and listbox components.

Preview

Code

Open in Chat

### Using `value` attribute in option

The `value` attribute is not directly supported in `SelectItem`. Instead, the `key` property should be used to set the `value` to be submitted in forms.

If you need to submit a specific `value` instead of the `key` during form submission, consider implementing a lookup map in your application.

## Slots

*   **base**: The main wrapper of the select. This wraps the rest of the slots.
*   **label**: The label of the select.
*   **mainWrapper**: Wraps the `helperWrapper` and the `trigger` slots.
*   **trigger**: The trigger of the select. This wraps the label the inner wrapper and the selector icon.
*   **innerWrapper**: The wrapper of the select content. This wraps the start/end content and the select value.
*   **selectorIcon**: The selector icon of the select. This is the icon that rotates when the select is open (`data-open`).
*   **value**: The select value. This is also the slot that wraps the `renderValue` function result.
*   **listboxWrapper**: The wrapper of the listbox. This wraps the listbox component, this slot is used on top of the scroll shadow component.
*   **listbox**: The listbox component. This is the component that wraps the select items.
*   **popoverContent**: The popover content slot. Use this to modify the popover content styles.
*   **helperWrapper**: The wrapper of the helper text. This wraps the helper text and the error message.
*   **description**: The description of the select.
*   **errorMessage**: The error message of the select.

## Data Attributes

`Select` has the following attributes on the `base` element:

*   **data-filled**: Indicates if the select has a value, is focused, has start/end content or is open.
*   **data-has-value**: Indicates if the select has selected item(s).
*   **data-has-label**: Indicates if the select has a label. Based on `label` prop.
*   **data-has-helper**: Indicates if the select has helper text. Based on `errorMessage` or `description` prop.
*   **data-invalid**: Indicates if the select is invalid. Based on `isInvalid` prop.

`Select` has the following attributes on the `trigger` element:

*   **data-open**: Indicates if the select is open.
*   **data-disabled**: When the select trigger is disabled. Based on select `isDisabled` prop.
*   **data-focus**: When the select trigger is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the select trigger is being focused with the keyboard. Based on useFocusRing.
*   **data-pressed**: When the select trigger is pressed. Based on usePress
*   **data-hover**: When the select trigger is being hovered. Based on useHover

`Select` has the following attributes on the `selectorIcon` element:

*   **data-open**: Indicates if the select is open.

`SelectItem` has the following attributes on the `base` element:

*   **data-disabled**: When the select item is disabled. Based on select `disabledKeys` prop.
*   **data-selected**: When the select item is selected. Based on select `selectedKeys` prop.
*   **data-hover**: When the select item is being hovered. Based on useHover
*   **data-pressed**: When the select item is pressed. Based on usePress
*   **data-focus**: When the select item is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the select item is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Exposed to assistive technology as a button with a listbox popup using ARIA (combined with Listbox).
*   Support for selecting a single option.
*   Support for selecting multiple options.
*   Support for disabled options.
*   Support for sections.
*   Labeling support for accessibility.
*   Support for description and error message help text linked to the input via ARIA.
*   Support for mouse, touch, and keyboard interactions.
*   Tab stop focus management.
*   Keyboard support for opening the listbox using the arrow keys, including automatically focusing the first or last item accordingly.
*   Typeahead to allow selecting options by typing text, even without opening the listbox.
*   Browser autofill integration via a hidden native `<select>` element.
*   Mobile screen reader listbox dismissal support.

## API

### Select Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `selectionMode`

 | `   single | multiple   ` |  |
| `selectedKeys`

 | `   all | Iterable<React.Key>   ` |  |
| `disabledKeys`

 | `   Iterable<React.Key>   ` |  |
| `defaultSelectedKeys`

 | `   all | Iterable<React.Key>   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `placeholder`

 | `   string   ` | `"Select an option"` |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `label`

 | `   ReactNode   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `selectorIcon`

 | `   ReactNode   ` |  |
| `scrollRef`

 | `   React.RefObject<HTMLElement>   ` |  |
| `spinnerRef`

 | `   React.RefObject<HTMLElement>   ` |  |
| `maxListboxHeight`

 | `   number   ` | `"256"` |
| `itemHeight`

 | `   number   ` | `"32"` |
| `isVirtualized`

 | `   boolean   ` | `"undefined"` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` |  |
| `isRequired`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isMultiline`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `validationState`

 | `   valid | invalid   ` |  |
| `showScrollIndicators`

 | `   boolean   ` | `true` |
| `autoFocus`

 | `   boolean   ` | `false` |
| `disallowEmptySelection`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `true` |
| `disableSelectorIconRotation`

 | `   boolean   ` | `false` |
| `hideEmptyContent`

 | `   boolean   ` | `false` |
| `popoverProps`

 | `   PopoverProps   ` |  |
| `listboxProps`

 | `   ListboxProps   ` |  |
| `scrollShadowProps`

 | `   ScrollShadowProps   ` |  |
| `classNames`

 | `   Partial<Record<"base"｜ "label"｜ "trigger"｜ "mainWrapper" ｜ "innerWrapper"｜ "selectorIcon" ｜ "value" ｜ "listboxWrapper"｜ "listbox" ｜ "popoverContent" ｜ "helperWrapper" ｜ "description" ｜ "errorMessage", string>>   ` |  |

### Select Events

| Prop | Type | Default |
| --- | --- | --- |
| `onClose`
 | `   () => void   ` |  |
| `onOpenChange`

 | `   (isOpen: boolean) => void   ` |  |
| `onSelectionChange`

 | `   (keys: "all" | Set<React.Key> & {anchorKey?: string; currentKey?: string}) => void   ` |  |
| `onChange`

 | `   React.ChangeEvent<HTMLSelectElement>   ` |  |
| `renderValue`

 | `   RenderValueFunction   ` |  |

* * *

### SelectItem Props

Check the ListboxItem props.

### SelectItem Events

Check the ListboxItem events.

### SelectSection Props

Check the ListboxSection props.

* * *

### Types

#### Render Value Function

The `T` type is the type of the data passed to the select `items`.

---

## Page: https://www.heroui.com/docs/components/skeleton

# Skeleton

Skeleton is a placeholder to show a loading state and the expected shape of a component.

Storybook@heroui/skeletonSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Standalone

Skeleton takes the shape of its `children` component by default, but you can also use it as a standalone component.

Preview

Code

Open in Chat

### Loaded State

You can use the `isLoaded` prop to stop the skeleton animation and show the children component.

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the skeleton, it contains the `before` and `after` pseudo elements to create the animation.
*   **content**: The wrapped component to show the skeleton shape. It is visible only when the `isLoaded` prop is `true`.

## Data Attributes

`Skeleton` has the following attributes on the `base` element:

*   **data-loaded**: Indicates the loaded state of the skeleton. Based on the `isLoaded` prop.

## API

### Skeleton Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `isLoaded`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "content", string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/slider

# Slider

A slider allows a user to select one or more values within a range.

Storybook@heroui/sliderSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Vertical Slider

It is possible to change the orientation of the slider by using the `orientation="vertical"` prop.

Preview

Code

Open in Chat

### With Visible Steps

You can use the `showSteps` prop to display small dots on each step.

Preview

Code

Open in Chat

### With Marks

You can use the `marks` prop to display a label on each step.

Preview

Code

Open in Chat

### Range Slider

If you pass an array of values to the `value` prop or to the `defaultValue` prop, the slider will become a range slider.

Preview

Code

Open in Chat

### Fill Offset

The `fillOffset` prop allows you to set where the fill should start.

Preview

Code

Open in Chat

### With Tooltip

The `showTooltip` prop allows you to show a tooltip with the current thumb value when the user hovers or drags the thumb.

Preview

Code

Open in Chat

> **Note:** You can change any of the tooltip props by passing the `tooltipProps` to the `Slider` component.

### With Outline

It is possible to add a small outline to the slider's thumbs by passing the `showOutline` prop.

Preview

Code

Open in Chat

### Start & End Content

Slider component provides `startContent` and `endContent` props that allows you to add any `ReactNode` to the start and end of the slider.

Preview

Code

Open in Chat

### Value Formatting

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format. `formatOptions` is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

Preview

Code

Open in Chat

> **Note:** Use the `tooltipValueFormatOptions` prop to format the tooltip value.

It is also possible to format the value using the `getValue` prop.

Preview

Code

Open in Chat

### Hiding the Value

The Slider value is shown by default, but can be hidden by passing the `hideValue` prop.

Preview

Code

Open in Chat

### Hiding the Thumbs

The Slider thumbs are shown by default, but can be hidden by passing the `hideThumb` prop.

Preview

Code

Open in Chat

### Controlled

You can control the slider by passing the `value` and `onChange` props.

Preview

Code

Open in Chat

If you want to capture the slider value only when the user stops dragging the thumb, you can use the `onChangeEnd` prop.

Preview

Code

Open in Chat

### Controlled Range

You can also control the range slider by using an array of values in the `value` and `onChange` props.

Preview

Code

Open in Chat

### Custom Thumb

The Slider component provides a `renderThumb` prop that allows you to customize the thumb in any way you want.

Preview

Code

Open in Chat

### Custom Range Thumbs

You can also use the `renderThumb` prop to customize the thumbs of a range slider. The `index` prop will tell you which thumb is being rendered.

Preview

Code

Open in Chat

### Custom Label

The Slider component provides a `renderLabel` prop that allows you to customize the label in any way you want.

Preview

Code

Open in Chat

### Custom Value

The Slider component provides a `renderValue` prop that allows you to customize the value label element.

Preview

Code

Open in Chat

### Disabling Thumb Scale

In case you want to disable the thumb scale animation, you can pass the `disableThumbScale` prop.

Preview

Code

Open in Chat

## Slots

*   **base**: The foundational slot, encompassing all other slots and elements. It serves as the primary container.
*   **labelWrapper**: The container for the Slider's label and value. It aligns these elements and ensures a consistent layout.
*   **label**: A dedicated slot to display the Slider's label.
*   **value**: Displays the current value of the Slider. Located within the `labelWrapper`.
*   **step**: Represents individual steps or intervals on the Slider.
*   **mark**: Denotes specific values or intervals along the Slider.
*   **trackWrapper**: A container for the slider's track, ensuring it is consistently aligned and positioned.
*   **track**: The base bar of the Slider, along which the thumb moves.
*   **filler**: A visual representation of the selected value, filling the track from the start point to the current thumb position.
*   **thumb**: The interactive element that users drag along the track to select a value on the Slider.
*   **startContent**: A slot for additional content or icons at the beginning of the Slider.
*   **endContent**: A slot for additional content or icons at the end of the Slider.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`Slider` has the following attributes:

*   **data-hover**: When the slider is being hovered. Based on useHover
*   **data-orientation**: The orientation of the slider. Based on `orientation` prop.

`Thumbs` have the following attributes which are returned by the `renderThumb` prop:

*   **data-dragging**: When the thumb is being dragged.
*   **data-focus-visible**: When the thumb is focused. Based on useFocusVisible
*   **data-hover**: When the thumb is being hovered. Based on useHover
*   **data-pressed**: When the thumb is being pressed. Based on usePress

## Accessibility

*   Support for one or multiple thumbs.
*   Support for mouse, touch, and keyboard via the useMove hook.
*   Multi-touch support for dragging multiple thumbs or multiple sliders at once.
*   Pressing on the track moves the nearest thumb to that position.
*   Supports using the arrow keys, as well as page up/down, home, and end keys.
*   Support for both horizontal and vertical orientations.
*   Support for custom min, max, and step values with handling for rounding errors.
*   Support for disabling the whole slider or individual thumbs.
*   Prevents text selection while dragging.
*   Exposed to assistive technology as a group of slider elements via ARIA.
*   Slider thumbs use hidden native input elements to support touch screen readers.
*   Support for labeling both the slider as a whole and individual thumbs.
*   Support for displaying the current thumb values using an `<output>` element.
*   Internationalized number formatting as a percentage or value.
*   Support for mirroring in RTL locales.

## API

### Slider Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `name`

 | `   string   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   foreground | primary | secondary | success | warning | danger   ` | `"primary"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"full"` |
| `step`

 | `   number   ` | `"1"` |
| `value`

 | `   number   ` |  |
| `defaultValue`

 | `   number   ` |  |
| `minValue`

 | `   number   ` | `"0"` |
| `maxValue`

 | `   number   ` | `"100"` |
| `orientation`

 | `   horizontal | vertical   ` | `"horizontal"` |
| `fillOffset`

 | `   number   ` |  |
| `showSteps`

 | `   boolean   ` | `false` |
| `showTooltip`

 | `   boolean   ` | `false` |
| `marks`

 | `   SliderStepMarks   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `formatOptions`

 | `   Intl.NumberFormat   ` |  |
| `tooltipValueFormatOptions`

 | `   Intl.NumberFormat   ` |  |
| `tooltipProps`

 | `   TooltipProps   ` |  |
| `showOutline`

 | `   boolean   ` | `false` |
| `hideValue`

 | `   boolean   ` | `false` |
| `hideThumb`

 | `   boolean   ` | `false` |
| `disableThumbScale`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |

### Slider Functions

| Prop | Type | Default |
| --- | --- | --- |
| `getValue`
 | `   (value: SliderValue) => string   ` |  |
| `renderLabel`

 | `   (props: DOMAttributes<HTMLLabelElement>) => ReactNode   ` |  |
| `renderValue`

 | `   (props: DOMAttributes<HTMLOutputElement>) => ReactNode   ` |  |
| `renderThumb`

 | `   (props: DOMAttributes<HTMLDivElement> & {index?: number}) => ReactNode   ` |  |

### Slider Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   (value: SliderValue) => void   ` |  |
| `onChangeEnd`

 | `   (value: SliderValue) => void   ` |  |

### Types

#### Slider Value

#### Slider Step Marks

---

## Page: https://www.heroui.com/docs/components/snippet

# Snippet

Snippet is a component that can be used to display inline or multiline code snippets.

Storybook@heroui/snippetSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Custom Symbol

Preview

Code

Open in Chat

### Without Copy

You can hide the copy button by setting the `hideCopyButton` property to `true`.

Preview

Code

Open in Chat

### Custom Tooltip

You can customize the tooltip by using the `tooltipProps` property.

Preview

Code

Open in Chat

> **Note**: For more information about the `Tooltip` props, please visit the Tooltip page.

### Multiline

Preview

Code

Open in Chat

### Custom Icons

You can customize the copy and copied icons by using the `copyIcon` and `checkIcon` properties.

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the snippet, it is the main container.
*   **content**: This is the wrapper of the `<pre/>` slot.
*   **pre**: The `<pre/>` slot of the snippet. It is used to wrap the code.
*   **symbol**: The symbol wrapper slot.
*   **copyButton**: The copy button slot.
*   **copyIcon**: The copy icon slot.
*   **checkIcon**: The check icon slot.

## API

### Snippet Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode | ReactNode[]   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg   ` | `"lg"` |
| `symbol`

 | `   string | ReactNode   ` | `"$"` |
| `timeout`

 | `   number   ` | `"2000"` |
| `codeString`

 | `   string   ` |  |
| `tooltipProps`

 | `   TooltipProps   ` |  |
| `copyIcon`

 | `   ReactNode   ` |  |
| `checkIcon`

 | `   ReactNode   ` |  |
| `disableTooltip`

 | `   boolean   ` | `false` |
| `disableCopy`

 | `   boolean   ` | `false` |
| `hideCopyButton`

 | `   boolean   ` | `false` |
| `hideSymbol`

 | `   boolean   ` | `false` |
| `copyButtonProps`

 | `   ButtonProps   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<'base' | 'content' | 'pre' | 'symbol' | 'copyButton' | 'checkIcon', string>>   ` |  |

### Snippet Events

| Prop | Type | Default |
| --- | --- | --- |
| `onCopy`
 | `   (value: string | string[]) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/spacer

# Spacer

Spacer is a component used to add space between components.

Storybook@heroui/spacerServer componentSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

> **Note**: The `x` and `y` values are based on Tailwind Spacing Scale

## API

### Spacer Props

| Prop | Type | Default |
| --- | --- | --- |
| `x`
 | `   Space   ` | `"1"` |
| `y`

 | `   Space   ` | `"1"` |

### Types

---

## Page: https://www.heroui.com/docs/components/spinner

# Spinner

Spinner express an unspecified wait time or display the length of a process.

Storybook@heroui/spinnerServer componentSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

> **Note**: Spinner adds `Loading` as `aria-label` by default. This is required for accessibility. You can change it by passing a `label` or `aria-label` prop.

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### With Label

Preview

Code

Open in Chat

### Label colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the spinner, it wraps the circles and the label.
*   **wrapper**: The wrapper of the circles.
*   **circle1**: The first circle of the spinner component. (Effective only when variant is `default` or `gradient`)
*   **circle2**: The second circle of the spinner component. (Effective only when variant is `default` or `gradient`)
*   **dots**: Dots of the spinner component. (Effective only when variant is `wave` or `dots`)
*   **spinnerBars**: Bars of the spinner component. (Effective only when variant is `spinner`)
*   **label**: The label content.

## API

### Spinner Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   string   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `variant`

 | `   default | simple | gradient | wave | dots | spinner   ` | `"default"` |
| `labelColor`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `classNames`

 | `   Partial<Record<'base' | 'wrapper' | 'circle1' | 'circle2' | 'dots' | 'spinnerBars' | 'label', string>>   ` |  |

---

## Page: https://www.heroui.com/docs/components/switch

# Switch

The Switch component is used as an alternative between checked and not checked states.

Storybook@heroui/switchReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### With Label

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### With Thumb Icon

Preview

Code

Open in Chat

### With Icons

You can also add icons to start and end of the switch by using `startContent` and `endContent` props.

Preview

Code

Open in Chat

### Controlled

Preview

Code

Open in Chat

> **Note**: HeroUI `Switch` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

## Slots

*   **base**: Base slot for the switch. It is the main wrapper.
*   **wrapper**: The wrapper of the start icon, end icon and thumb.
*   **hiddenInput**: The hidden input element that is used to handle the switch state.
*   **thumb**: The thumb element of the switch. It is the circle element.
*   **label**: The label slot of the switch.
*   **startContent**: The icon slot at the start of the switch.
*   **endContent**: The icon slot at the end of the switch.
*   **thumbIcon**: The icon slot inside the thumb.

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Implementation

In case you need to customize the switch even further, you can use the `useSwitch` hook to create your own implementation.

Preview

Code

Open in Chat

## Data Attributes

`Switch` has the following attributes on the `base` element:

*   **data-selected**: When the switch is checked. Based on `isSelected` prop.
*   **data-pressed**: When the switch is pressed. Based on usePress
*   **data-readonly**: When the switch is readonly. Based on `isReadOnly` prop.
*   **data-hover**: When the switch is being hovered. Based on useHover
*   **data-focus**: When the switch is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the switch is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the switch is disabled. Based on `isDisabled` prop.

## Accessibility

*   Built with a native HTML `<input>` element.
*   Full support for browser features like form autofill.
*   Keyboard focus management and cross browser normalization.
*   Keyboard event support for Tab and Space keys.
*   Labeling support for assistive technology.
*   Exposed as a switch to assistive technology via ARIA

## API

### Switch Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `value`

 | `   string   ` |  |
| `name`

 | `   string   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"primary"` |
| `thumbIcon`

 | `   ThumbIconProps   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `isSelected`

 | `   boolean   ` |  |
| `defaultSelected`

 | `   boolean   ` |  |
| `isReadOnly`

 | `   boolean   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base"｜ "wrapper"｜ "thumb"｜ "label" ｜ "startContent" ｜ "endContent" ｜ "thumbIcon" , string>>   ` |  |

### Switch Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (isSelected: boolean) => void   ` |  |

### Types

#### Switch Icon Props

---

## Page: https://www.heroui.com/docs/components/table

# Table

Tables are used to display tabular data using rows and columns. They allow users to quickly scan, sort, compare, and take action on large amounts of data.

Storybook@heroui/tableSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 6 table-related components:

*   **Table**: The main component to display a table.
*   **TableHeader**: The header of the table.
*   **TableBody**: The body of the table.
*   **TableColumn**: The column of the table.
*   **TableRow**: The row of the table.
*   **TableCell**: The cell of the table.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic

To render a table dynamically, you can use the `columns` prop to pass the columns and `items` prop to pass the data.

Preview

Code

Open in Chat

#### Why not array map?

Using the `items` prop and providing a render function allows react-aria to automatically cache the results of rendering each item and avoid re-rendering all items in the collection when only one of them changes. This has big performance benefits for large collections.

You could also use `Array.map` to render the items, but it will not be as performant as using the `items` and `columns` prop.

Example:

> **Note**: To learn more about React Aria collections and how to use them, please check React Aria Collections.

### Empty State

You can use the `emptyContent` prop to render a custom component when the table is empty.

Preview

Code

Open in Chat

### Without Header

In case you don't want to render the header, you can use the `hideHeader` prop.

Preview

Code

Open in Chat

### Without Wrapper

By default the table is wrapped in a `div` element with a small shadow effect and a border radius. You can use the `removeWrapper` prop to remove the wrapper and only render the table.

Preview

Code

Open in Chat

### Custom Cells

You can render any component inside the table cell. In the example below, we are rendering different components according to the `key` of the column.

Preview

Code

Open in Chat

### Striped Rows

You can use the `isStriped` prop to render striped rows.

Preview

Code

Open in Chat

### Single Row Selection

It is possible to make the table rows selectable. To do so, you can use the `selectionMode` prop. Use `defaultSelectedKeys` to provide a default set of selected rows.

Preview

Code

Open in Chat

> **Note**: The value of the selected keys must match the key prop of the row.

### Multiple Row Selection

You can also select multiple rows by using the `selectionMode="multiple"` prop. Use `defaultSelectedKeys` to provide a default set of selected rows.

Preview

Code

Open in Chat

> **Note**: When using multiple selection, selectable checkboxes will be rendered in the first column of the table.

### Disallow Empty Selection

Table also supports a `disallowEmptySelection` prop which forces the user to have at least one row in the Table selected at all times. In this mode, if a single row is selected and the user presses it, it will not be deselected.

Preview

Code

Open in Chat

### Controlled Selection

To programmatically control row selection, use the `selectedKeys` prop paired with the `onSelectionChange` callback. The key prop from the selected rows will be passed into the callback when the row is pressed, allowing you to update state accordingly.

Preview

Code

Open in Chat

> **Note**: The `selectedKeys` property must be a `Set` object.

### Disabled Rows

You can disable rows by using the `disabledKeys` prop. This will prevent rows from being selectable as shown in the example below.

Preview

Code

Open in Chat

### Selection Behavior

By default, Table uses the `toggle` selection behavior, which behaves like a checkbox group: clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused row.

When the `selectionBehavior` prop is set to `replace`, clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used.

Preview

Code

Open in Chat

### Rows Actions

Table supports rows via the `onRowAction` callback. In the default `toggle` selection behavior, when nothing is selected, clicking or tapping the row triggers the row action.

This behavior is slightly different in the `replace` selection behavior, where single clicking selects the row and actions are performed via double click.

Preview

Code

Open in Chat

### Sorting Rows

Table supports sorting its data when a column header is pressed. To designate that a `Column` should support sorting, provide it with the `allowsSorting` prop.

Table accepts a `sortDescriptor` prop that defines the current column key to sort by and the sort direction (ascending/descending). When the user presses a sortable column header, the column's key and sort direction is passed into the `onSortChange` callback, allowing you to update the `sortDescriptor` appropriately.

We recommend using the `useAsyncList` hook from @react-stately/data to manage the data sorting. So make sure to install it before using the sorting feature.

npm

yarn

pnpm

bun

Preview

Code

Open in Chat

> Note that we passed the `isLoading` and `loadingContent` props to `TableBody` to render a loading state while the data is being fetched.

### Loading more data

Table allows you to add a custom component at the end of the table, on the example below we are using a button to load more data.

Preview

Code

Open in Chat

> **Note**: We passed the `isHeaderSticky` to the `Table` component to make the header sticky.

### Paginated Table

You can use the Pagination component to paginate the table.

Preview

Code

Open in Chat

### Async Pagination

It is also possible to use the Pagination component to paginate the table asynchronously. To fetch the data, we are using the `useSWR` hook from SWR.

Preview

Code

Open in Chat

### Infinite Pagination

Table also supports infinite pagination. To do so, you can use the `useAsyncList` hook from @react-stately/data and @heroui/use-infinite-scroll hook.

npm

yarn

pnpm

bun

Preview

Code

Open in Chat

### Virtualization

Table supports virtualization, which allows efficient rendering of large lists by only rendering items that are visible in the viewport. You can enable virtualization by setting the `isVirtualized` prop to `true`.

Preview

Code

Open in Chat

> **Note**: The virtualization strategy is based on the @tanstack/react-virtual package, which provides efficient rendering of large lists by only rendering items that are visible in the viewport.

#### Ten Thousand Items

Here's an example of using virtualization with 10,000 items.

Preview

Code

Open in Chat

#### Max Table Height

The `maxTableHeight` prop is used to set the maximum height of the table. This is required when using virtualization. By default, it's set to `600`.

Preview

Code

Open in Chat

#### Custom Row Height

The `rowHeight` prop is used to set the height of each row in the table. This is required when using virtualization. By default, it's set to `40`.

Preview

Code

Open in Chat

### Use Case Example

When creating a table, you usually need core functionalities like sorting, pagination, and filtering. In the example below, we combined all these functionalities to create a complete table.

Preview

Code

Open in Chat

## Slots

*   **base**: Defines a flexible column layout and relative positioning for the table component.
*   **wrapper**: Applies to the outermost wrapper, providing padding, flexible layout, relative positioning, visual styles, and scrollable overflow handling.
*   **table**: Sets the table to have a full minimum width and auto-adjusting height.
*   **thead**: Specifies rounded corners for the first child row in the table header.
*   **tbody**: No specific styles are applied to the body of the table.
*   **tr**: Styles for table rows including group focus, outline properties, and a set of undefined focus-visible classes.
*   **th**: Styles for table headers, including padding, text alignment, font properties, and special styles for sortable columns.
*   **td**: Applies to table cells, with properties for padding, alignment, and relative positioning, plus special styles for first child elements, selection indication, and disabled cells.
*   **tfoot**: No specific styles are applied to the footer of the table.
*   **sortIcon**: Styles for sorting icons, with properties for margin, opacity, and transition effects based on sorting direction and hover state.
*   **emptyWrapper**: Defines style for an empty table, with text alignment, color, and a specified height.
*   **loadingWrapper**: Style applied when the table is loading, positioning it centrally in its container.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`TableBody` has the following attributes:

*   **data-empty**: When the table is empty.
*   **data-loading**: When the table data is loading. Based on `TableBody` `isLoading` and `loadingContent` props.

`TableRow` has the following attributes:

*   **data-selected**: When the row is selected. Based on `Table` `selectedKeys` prop.
*   **data-disabled**: When the row is disabled. Based on `Table` `disabledKeys` prop.
*   **data-hover**: When the row is being hovered. Based on useHover
*   **data-focus-visible**: When the row is being focused with the keyboard. Based on useFocusRing.
*   **data-first**: When the row is the first row.
*   **data-middle**: When the row is in the middle.
*   **data-odd**: When the row is odd.
*   **data-last**: When the row is the last row.

`TableCell` has the following attributes:

*   **data-selected**: When the cell row is selected. Based on `Table` `selectedKeys` prop.
*   **data-focus-visible**: When the cell is being focused with the keyboard. Based on useFocusRing.

## Accessibility

*   Exposed to assistive technology as a grid using ARIA.
*   Keyboard navigation between columns, rows, cells, and in-cell focusable elements via the arrow keys.
*   Single, multiple, or no row selection via mouse, touch, or keyboard interactions.
*   Support for disabled rows, which cannot be selected.
*   Column sorting support.
*   Async loading, infinite scrolling, filtering, and sorting support.
*   Support for both toggle and replace selection behaviors.
*   Labeling support for accessibility.
*   Ensures that selections are announced using an ARIA live region.
*   Support for marking columns as row headers, which will be read when navigating the rows with a screen reader.
*   Optional support for checkboxes in each row for selection, as well as in the header to select all rows.
*   Automatic scrolling support during keyboard navigation.
*   Support for row actions via double click, Enter key, or tapping.
*   Typeahead to allow focusing rows by typing text.
*   Long press to enter selection mode on touch when there is both selection and row actions.

## API

### Table Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `layout`

 | `   auto | fixed   ` | `"auto"` |
| `radius`

 | `   none | sm | md | lg   ` | `"lg"` |
| `shadow`

 | `   none | sm | md | lg   ` | `"sm"` |
| `maxTableHeight`

 | `   number   ` | `"600"` |
| `rowHeight`

 | `   number   ` | `"40"` |
| `isVirtualized`

 | `   boolean   ` | `"undefined"` |
| `hideHeader`

 | `   boolean   ` | `false` |
| `isStriped`

 | `   boolean   ` | `false` |
| `isCompact`

 | `   boolean   ` | `false` |
| `isHeaderSticky`

 | `   boolean   ` | `false` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `removeWrapper`

 | `   boolean   ` | `false` |
| `BaseComponent`

 | `   React.ComponentType<any>   ` | `"div"` |
| `topContent`

 | `   ReactNode   ` |  |
| `bottomContent`

 | `   ReactNode   ` |  |
| `topContentPlacement`

 | `   inside | outside   ` | `"inside"` |
| `bottomContentPlacement`

 | `   inside | outside   ` | `"inside"` |
| `showSelectionCheckboxes`

 | `   boolean   ` |  |
| `sortDescriptor`

 | `   SortDescriptor   ` |  |
| `selectedKeys`

 | `   Selection   ` |  |
| `defaultSelectedKeys`

 | `   Selection   ` |  |
| `disabledKeys`

 | `   Selection   ` |  |
| `disallowEmptySelection`

 | `   boolean   ` |  |
| `selectionMode`

 | `   single | multiple | none   ` | `"none"` |
| `selectionBehavior`

 | `   toggle | replace   ` | `"toggle"` |
| `disabledBehavior`

 | `   selection | all   ` | `"selection"` |
| `allowDuplicateSelectionEvents`

 | `   boolean   ` |  |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `checkboxesProps`

 | `   CheckboxProps   ` |  |
| `classNames`

 | `   Partial<Record<'base' | 'table' | 'thead' | 'tbody' | 'tfoot' | 'emptyWrapper' | 'loadingWrapper' | 'wrapper' | 'tr' | 'th' | 'td' | 'sortIcon', string>>   ` |  |
| `isKeyboardNavigationDisabled`

 | `   boolean   ` | `false` |

### Table Events

| Prop | Type | Default |
| --- | --- | --- |
| `onRowAction`
 | `   (key: React.Key) => void   ` |  |
| `onCellAction`

 | `   (key: React.Key) => void   ` |  |
| `onSelectionChange`

 | `   (keys: Selection) => any   ` |  |
| `onSortChange`

 | `   (descriptor: SortDescriptor) => any   ` |  |

### TableHeader Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `columns`

 | `   T[]   ` |  |

### TableColumn Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `align`

 | `   start | center | end   ` | `"start"` |
| `hideHeader`

 | `   boolean   ` | `false` |
| `allowsSorting`

 | `   boolean   ` |  |
| `isRowHeader`

 | `   boolean   ` |  |
| `textValue`

 | `   string   ` |  |
| `width`

 | `   string | number   ` |  |
| `minWidth`

 | `   string | number   ` |  |
| `maxWidth`

 | `   string | number   ` |  |

### TableBody Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   RowElement | RowElement[] | ((item: T) => RowElement)   ` |  |
| `items`

 | `   Iterable<T>   ` |  |
| `isLoading`

 | `   boolean   ` |  |
| `loadingState`

 | `   LoadingState   ` |  |
| `loadingContent`

 | `   ReactNode   ` |  |
| `emptyContent`

 | `   ReactNode   ` |  |

### TableBody Events

| Prop | Type | Default |
| --- | --- | --- |
| `onLoadMore`
 | `   () => any   ` |  |

### TableRow Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   CellElement | CellElement[] | CellRenderer   ` |  |
| `textValue`

 | `   string   ` |  |

### TableCell Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode   ` |  |
| `textValue`

 | `   string   ` |  |

* * *

### Table types

#### Sort descriptor

#### Selection

#### Loading state

---

## Page: https://www.heroui.com/docs/components/tabs

# Tabs

Tabs organize content into multiple sections and allow users to navigate between them.

Storybook@heroui/tabsReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

HeroUI exports 2 tabs-related components:

*   **Tabs**: The main component to display a tab list.
*   **Tab**: The component to display a tab item. The children of this component will be displayed as the content of the tab.

Individual

Global

## Usage

Preview

Code

Open in Chat

### Dynamic

You can render tabs dynamically by using `items` prop.

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Disabled Item

Preview

Code

Open in Chat

### Sizes

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### With Icons

Preview

Code

Open in Chat

### Controlled

You can use the `onSelectionChange` and `selectedKey` props to control the selected tab.

Preview

Code

Open in Chat

### Placement

You can change the position of the tabs by using the `placement` prop. The default value is `top`.

Preview

Code

Open in Chat

### Vertical

Change the orientation of the tabs it will invalidate the placement prop when the value is `true`.

Preview

Code

Open in Chat

### Links

Tabs items can be rendered as links by passing the `href` prop to the `Tab` component. By default, links perform native browser navigation. However, you'll usually want to synchronize the selected tab with the current URL from your client side router. You can do this by doing the following:

1.  Set up your router at the root of your app. See Routing guide to learn how to do this.
2.  Use the `selectedKey` prop to set the selected tab based on the current URL.

#### Next.js

This example uses Next.js App router to set up routes for each tab and synchronize the selected tab with the current URL.

#### React Router

This example uses React Router to setup routes for each tab and synchronize the selection with the URL.

> **Note**: See the Routing guide to learn how to set up the router for your framework.

### With Form

Preview

Code

Open in Chat

## Slots

*   **base**: The main tabs slot, it wraps the items and the panels.
*   **tabList**: The tab list slot, it wraps the tab items.
*   **tab**: The tab slot, it wraps the tab item.
*   **tabContent**: The tab content slot, it wraps the tab content.
*   **cursor**: The cursor slot, it wraps the cursor. This is only visible when `disableAnimation=false`
*   **panel**: The panel slot, it wraps the tab panel (content).
*   **tabWrapper**: The tab wrapper slot, it wraps the tab and the tab content.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`Tab` has the following attributes on the `base` element:

*   **data-selected**: When the tab is selected.
*   **data-disabled**: When the tab is disabled.
*   **data-hover**: When the tab is being hovered. Based on useHover.
*   **data-hover-selected**: When the tab is being hovered and is not selected. Based on useHover and `selected` state.
*   **data-focus**: When the tab is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the tab is being focused with the keyboard. Based on useFocusRing.
*   **data-pressed**: When the tab is pressed. Based on usePress.

## Accessibility

*   Support for mouse, touch, and keyboard interactions on tabs.
*   Keyboard event support for arrows keys.
*   Support for disabled tabs.
*   Follows the tabs ARIA pattern, semantically linking tabs and their associated tab panels.
*   Focus management for tab panels without any focusable children.

## API

### Tabs Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode | ((item: T) => ReactElement)   ` |  |
| `variant`

 | `   solid | bordered | light | underlined   ` | `"solid"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `fullWidth`

 | `   boolean   ` | `false` |
| `items`

 | `   Iterable<T>   ` |  |
| `disabledKeys`

 | `   React.Key[]   ` |  |
| `selectedKey`

 | `   React.Key   ` |  |
| `defaultSelectedKey`

 | `   React.Key   ` |  |
| `shouldSelectOnPressUp`

 | `   boolean   ` | `true` |
| `keyboardActivation`

 | `   automatic | manual   ` | `"automatic"` |
| `motionProps`

 | `   MotionProps   ` |  |
| `disableCursorAnimation`

 | `   boolean   ` | `false` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base"｜ "tabList"｜ "tab"｜ "tabContent"｜ "cursor" ｜ "panel" ｜ "tabWrapper", string>>   ` |  |
| `placement`

 | `   top | bottom | start | end   ` | `"top"` |
| `isVertical`

 | `   boolean   ` | `false` |
| `destroyInactiveTabPanel`

 | `   boolean   ` | `true` |

### Tabs Events

| Prop | Type | Default |
| --- | --- | --- |
| `onSelectionChange`
 | `   (key: React.Key) => any   ` |  |

### Tab Props

| Prop | Type | Default |
| --- | --- | --- |
| `tabRef`
 | `   RefObject<HTMLButtonElement>   ` |  |
| `children*`

 | `   ReactNode   ` |  |
| `title`

 | `   ReactNode   ` |  |
| `titleValue`

 | `   string   ` |  |
| `href`

 | `   string   ` |  |
| `target`

 | `   HTMLAttributeAnchorTarget   ` |  |
| `rel`

 | `   string   ` |  |
| `download`

 | `   boolean | string   ` |  |
| `ping`

 | `   string   ` |  |
| `referrerPolicy`

 | `   HTMLAttributeReferrerPolicy   ` |  |
| `shouldSelectOnPressUp`

 | `   boolean   ` |  |

---

## Page: https://www.heroui.com/docs/components/toast

# Toast

Toasts are temporary notifications that provide concise feedback about an action or event.

Storybook@heroui/toastSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Requirement

The `ToastProvider` must be added to the application before using the `addToast` function. This is required to initialize the context for managing toasts.

### Usage

Preview

Code

Open in Chat

### Colors

Toast comes with 6 color variants to convey different meanings.

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### Radius

Preview

Code

Open in Chat

### Toast Placement

Preview

Code

Open in Chat

### Custom Styles

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

Preview

Code

Open in Chat

### Custom Close Icon

You can pass a custom close icon to the toast by passing the `closeIcon` prop and a custom class name to the `closeButton` slot.

Preview

Code

Open in Chat

### Global Toast Props

You can pass global toast props to the `ToastProvider` to apply to all toasts.

## Data Attributes

Toast has the following attributes on the `base` element:

*   **data-has-title**: When the toast has a title
*   **data-has-description**: When the toast has a description
*   **data-animation**: Shows the current animation of toast ("entering", "queued", "exiting", "undefined")
*   **data-placement**: Where the toast is placed on the view-port.
*   **data-drag-value**: Value by which the toast is dragged from it's original position. (This remains "0" in case of disabledAnimation)

### Slots

Toast has the following slots:

*   `base`: The main toast container element
*   `title`: The title element
*   `description`: The description element
*   `icon`: The icon element
*   `loadingIcon`: The icon to be displayed until `promise` is resolved/rejected.
*   `content`: The wrapper for the title, description and icon content.
*   `motionDiv`: The motion.div for the FramerMotion.
*   `progressTrack`: The track of the progressBar.
*   `progressIndicator`: The indicator of the progressBar.
*   `closeButton`: The close button element
*   `closeIcon`: The icon which resides in the close button.

## Accessibility

*   Toast has role of `alert`
*   All Toasts are present in `ToastRegion`.
*   Close button has aria-label="Close" by default
*   When no toast are present, ToastRegion is removed from the DOM

## API

### Toast Props

| Prop | Type | Default |
| --- | --- | --- |
| `title`
 | `   ReactNode   ` |  |
| `icon`

 | `   ReactNode   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `variant`

 | `   solid | bordered | flat   ` | `"flat"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"md"` |
| `endContent`

 | `   ReactNode   ` |  |
| `closeIcon`

 | `   ReactNode   ` |  |
| `timeout`

 | `   number   ` | `"6000"` |
| `promise`

 | `   Promise | undefined   ` | `"undefined"` |
| `loadingIcon`

 | `   ReactNode   ` |  |
| `hideIcon`

 | `   boolean   ` | `false` |
| `hideCloseButton`

 | `   boolean   ` | `false` |
| `shouldShowTimeoutProgress`

 | `   boolean   ` | `false` |
| `severity`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `classNames`

 | `   Partial<Record<"base" | "content" | "wrapper" | "title" | "description" | "icon" | "loadingIcon" | "progressTrack" | "progressIndicator | "motionDiv" | "closeButton" | "closeIcon", string>>   ` |  |

### ToastProvider Props

| Prop | Type | Default |
| --- | --- | --- |
| `maxVisibleToasts`
 | `   number   ` | `"3"` |
| `placement`

 | `   bottom-right | bottom-left | bottom-center | top-right | top-left | top-center   ` | `"bottom-right"` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `toastOffset`

 | `   number   ` | `"0"` |
| `toastProps`

 | `   ToastProps   ` |  |
| `regionProps`

 | `   ToastRegionProps   ` |  |

### ToastRegion Props

| Prop | Type | Default |
| --- | --- | --- |
| `classNames`
 | `   Partial<Record<"base", string>>   ` |  |

### Toast Events

| Prop | Type | Default |
| --- | --- | --- |
| `onClose`
 | `   () => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/textarea

# Textarea

Textarea component is a multi-line Input which allows you to write large texts.

Storybook@heroui/inputReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

### Disabled

Preview

Code

Open in Chat

### Read Only

Preview

Code

Open in Chat

### Required

If you pass the `isRequired` property to the input, it will have a `danger` asterisk at the end of the label and the textarea will be required.

Preview

Code

Open in Chat

### Clear Button

If you pass the `isClearable` property to the textarea, it will have a clear button at the end of the textarea, it will be visible when the textarea has a value.

Preview

Code

Open in Chat

### Autosize

Textarea grows automatically based on the content, but you can also set a min and max height to it using the `minRows` and `maxRows` properties. It is based on react-textarea-autosize.

Preview

Code

Open in Chat

### Without Autosize

In case you want to disable the autosize feature, you can use the `disableAutosize` property.

Preview

Code

Open in Chat

### Variants

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid textarea.

Preview

Code

Open in Chat

### Description

Preview

Code

Open in Chat

### Controlled

You can use the `value` and `onValueChange` properties to control the input value.

Preview

Code

Open in Chat

> **Note**: HeroUI `Textarea` also supports native events like `onChange`, useful for form libraries such as Formik and React Hook Form.

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **label**: Label of the textarea, it is the one that is displayed above, inside or left of the textarea.
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **input**: The textarea input element.
*   **description**: The description of the textarea.
*   **errorMessage**: The error message of the textarea.
*   **headerWrapper**: Wraps the `label` and the `clearButton`.

## Data Attributes

`Textarea` has the following attributes on the `base` element:

*   **data-invalid**: When the textarea is invalid. Based on `isInvalid` prop.
*   **data-required**: When the textarea is required. Based on `isRequired` prop.
*   **data-readonly**: When the textarea is readonly. Based on `isReadOnly` prop.
*   **data-hover**: When the textarea is being hovered. Based on useHover
*   **data-focus**: When the textarea is being focused. Based on useFocusRing.
*   **data-focus-visible**: When the textarea is being focused with the keyboard. Based on useFocusRing.
*   **data-disabled**: When the textarea is disabled. Based on `isDisabled` prop.

## Accessibility

*   Built with a native `<input>` element.
*   Visual and ARIA labeling support.
*   Change, clipboard, composition, selection, and input event support.
*   Required and invalid states exposed to assistive technology via ARIA.
*   Support for description and error message help text linked to the input via ARIA.

## API

### Textarea Props

| Prop | Type | Default |
| --- | --- | --- |
| `children`
 | `   ReactNode   ` |  |
| `minRows`

 | `   number   ` | `"3"` |
| `maxRows`

 | `   number   ` | `"8"` |
| `cacheMeasurements`

 | `   boolean   ` | `false` |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `label`

 | `   ReactNode   ` |  |
| `value`

 | `   string   ` |  |
| `defaultValue`

 | `   string   ` |  |
| `placeholder`

 | `   string   ` |  |
| `startContent`

 | `   ReactNode   ` |  |
| `endContent`

 | `   ReactNode   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | ((v: ValidationResult) => ReactNode)   ` |  |
| `validate`

 | `   (value: string) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `fullWidth`

 | `   boolean   ` | `true` |
| `isRequired`

 | `   boolean   ` | `false` |
| `isReadOnly`

 | `   boolean   ` |  |
| `isDisabled`

 | `   boolean   ` | `false` |
| `isClearable`

 | `   boolean   ` | `false` |
| `isInvalid`

 | `   boolean   ` | `false` |
| `validationState`

 | `   valid | invalid   ` |  |
| `disableAutosize`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base" | "label" | "inputWrapper" | "innerWrapper" | "input" | "description" | "errorMessage", string>>   ` |  |

### Input Events

| Prop | Type | Default |
| --- | --- | --- |
| `onChange`
 | `   React.ChangeEvent<HTMLInputElement>   ` |  |
| `onValueChange`

 | `   (value: string) => void   ` |  |
| `onClear`

 | `   () => void   ` |  |
| `onHeightChange`

 | `   (height: number, meta: { rowHeight: number }) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/time-input

# Time Input

The `TimeInput` component consists of a label, and a group of segments representing each unit of a time (e.g. hours, minutes, and seconds). Each segment is individually focusable and editable by the user, by typing or using the arrow keys to increment and decrement the value. This approach allows values to be formatted and parsed correctly regardless of the locale or time format, and offers an easy and error-free way to edit times using the keyboard.

Storybook@heroui/date-inputReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

A `TimeInput` displays a placeholder by default. An initial, uncontrolled value can be provided to the TimeField using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Time values are provided using objects in the `@internationalized/date` package. This library handles correct international date and time manipulation across calendars, time zones, and other localization concerns.

`TimeInput` only supports selecting times, but values with date components are also accepted. By default, `TimeInput` will emit `Time` objects in the onChange event, but if a `CalendarDateTime` or `ZonedDateTime` object is passed as the `value` or `defaultValue`, values of that type will be emitted, changing only the time and preserving the date components.

Preview

Code

Open in Chat

### Required

`TimeInput` supports the `isRequired` prop to ensure the user enters a value, as well as minimum and maximum values, and custom client and server-side validation.

Preview

Code

Open in Chat

### Disabled

The `isDisabled` boolean prop makes `TimeInput` disabled. Inputs cannot be focused or selected.

Preview

Code

Open in Chat

### Read Only

The `isReadOnly` boolean prop makes `TimeInput`'s value immutable. Unlike `isDisabled`, `TimeInput` remains focusable.

Preview

Code

Open in Chat

### Without Label

`TimeInput` supports the `label` prop to show or not show the label.

Preview

Code

Open in Chat

### With Description

A description for the field. Provides a hint such as specific requirements for what to choose.

Preview

Code

Open in Chat

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.

Preview

Code

Open in Chat

You can also pass an error message as a function. This allows for dynamic error message handling based on the ValidationResult.

Preview

Code

Open in Chat

### Label Placement

The label's overall position relative to the element it is labeling.

Preview

Code

Open in Chat

### Start Content

If you want to display some content before the time inputs, you can set the `startContent` property.

Preview

Code

Open in Chat

### End Content

If you want to display some content after the time inputs, you can set the `endContent` property.

Preview

Code

Open in Chat

### Controlled

An initial, uncontrolled value can be provided to the `TimeInput` using the `defaultValue` prop. A controlled value can be provided using the `value` prop.

Preview

Code

Open in Chat

### Time Zones

`TimeInput` is time zone aware when a `ZonedDateTime` object is provided as the value. In this case, the time zone abbreviation is displayed, and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

In most cases, your data will come from and be sent to a server as an ISO 8601 formatted string. @internationalized/date includes functions for parsing strings in multiple formats into ZonedDateTime objects. Which format you use will depend on what information you need to store.

*   `parseZonedDateTime` – This function parses a date with an explicit time zone and optional UTC offset attached (e.g. `2021-11-07T00:45[America/Los_Angeles]` or `2021-11-07T00:45-07:00[America/Los_Angeles]`). This format preserves the maximum amount of information. If the exact local time and time zone that a user selected is important, use this format. Storing the time zone and offset that was selected rather than converting to UTC ensures that the local time is correct regardless of daylight saving rule changes (e.g. if a locale abolishes DST). Examples where this applies include calendar events, reminders, and other times that occur in a particular location.
*   `parseAbsolute` – This function parses an absolute date and time that occurs at the same instant at all locations on Earth. It can be represented in UTC (e.g. `2021-11-07T07:45:00Z`), or stored with a particular offset (e.g. `2021-11-07T07:45:00-07:00`). A time zone identifier, e.g. America/Los\_Angeles, must be passed, and the result will be converted into that time zone. Absolute times are the best way to represent events that occurred in the past, or future events where an exact time is needed, regardless of time zone.
*   `parseAbsoluteToLocal` – This function parses an absolute date and time into the current user's local time zone. It is a shortcut for parseAbsolute, and accepts the same formats.

Preview

Code

Open in Chat

### Granularity

The `granularity` prop allows you to control the smallest unit that is displayed by TimeInput. By default, times are displayed with "minute" granularity. More granular time values can be displayed by setting the granularity prop to "second".

Preview

Code

Open in Chat

### Min Time Value

The `minValue` prop allows you to validate time value before a certain time.

Preview

Code

Open in Chat

### Max Time Value

The `maxValue` prop allows you to validate time value before a certain time.

Preview

Code

Open in Chat

### Placeholder Value

When no value is set, a placeholder is shown. The format of the placeholder is influenced by the `granularity` and `placeholderValue` props. placeholderValue also controls the default values of each segment when the user first interacts with them, e.g. using the up and down arrow keys. By default, the placeholderValue is midnight, but you can set it to a more appropriate value if needed.

Preview

Code

Open in Chat

### Hide Time Zone

When a `ZonedDateTime` object is provided as the value to `TimeInput`, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the `hideTimeZone` option.

Preview

Code

Open in Chat

### Hour Cycle

By default, `TimeInput` displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the `hourCycle` prop if needed for a specific usecase. This example forces `TimeInput` to use 24-hour time, regardless of the locale.

Preview

Code

Open in Chat

## Slots

*   **base**: Input wrapper, it handles alignment, placement, and general appearance.
*   **label**: Label of the time input, it is the one that is displayed above, inside or left of the time input.
*   **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
*   **input**: The time input element.
*   **innerWrapper**: Wraps the segments, the `startContent` and the `endContent`.
*   **segment**: The segment of input elements.
*   **helperWrapper**: The wrapper of the helper text. This wraps the helper text and the error message.
*   **description**: The description of the time input.
*   **errorMessage**: The error message of the time input.

## Data Attributes

`TimeInput` has the following attributes on the `base` element:

*   **data-has-helper**: When the time input has description or error message. Based on `description` or `errorMessage` props.
*   **data-required**: When the time input is required. Based on `isRequired` prop.
*   **data-disabled**: When the time input is disabled. Based on `isDisabled` prop.
*   **data-readonly**: When the time input is readonly. Based on `isReadOnly` prop.
*   **data-invalid**: When the time input is invalid. Based on `isInvalid` prop.
*   **data-has-start-content**: When the time input has start content. Based on `startContent` prop.
*   **data-has-end-content**: When the time input has end content. Based on `endContent` prop.

## Accessibility

*   Support for locale-specific formatting, number systems, hour cycles, and right-to-left layout.
*   Times can optionally include a time zone. All modifications follow time zone rules such as daylight saving time.
*   Each time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit times using the keyboard, in any format and locale.
*   Time segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.

## API

### TimeInput Props

| Prop | Type | Default |
| --- | --- | --- |
| `label`
 | `   ReactNode   ` |  |
| `name`

 | `   string   ` |  |
| `value`

 | `   TimeValue | null   ` |  |
| `defaultValue`

 | `   TimeValue | null   ` |  |
| `variant`

 | `   flat | bordered | faded | underlined   ` | `"flat"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `radius`

 | `   none | sm | md | lg | full   ` |  |
| `hourCycle`

 | `   12 | 24   ` |  |
| `granularity`

 | `   hour | minute | second   ` | `"minute"` |
| `hideTimeZone`

 | `   boolean   ` |  |
| `labelPlacement`

 | `   inside | outside | outside-left   ` | `"inside"` |
| `shouldForceLeadingZeros`

 | `   boolean   ` | `true` |
| `placeholderValue`

 | `   TimeValue   ` |  |
| `minValue`

 | `   TimeValue   ` |  |
| `maxValue`

 | `   TimeValue   ` |  |
| `isDisabled`

 | `   boolean   ` |  |
| `isReadOnly`

 | `   boolean   ` |  |
| `isRequired`

 | `   boolean   ` |  |
| `isInvalid`

 | `   boolean   ` |  |
| `autoFocus`

 | `   boolean   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `errorMessage`

 | `   ReactNode | (v: ValidationResult) => ReactNode   ` |  |
| `validate`

 | `   (value: MappedTimeValue<TimeValue>) => ValidationError | true | null | undefined   ` |  |
| `validationBehavior`

 | `   native | aria   ` | `"native"` |
| `disableAnimation`

 | `   boolean   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "label" | "inputWrapper" | "innerWrapper" | "segment" | "helperWrapper" | "input" | "description" | "errorMessage", string>>   ` |  |

### TimeInput Events

| Prop | Type | Default |
| --- | --- | --- |
| `onFocus`
 | `   (e: FocusEvent<Target>) => void   ` |  |
| `onBlur`

 | `   (e: FocusEvent<Target>) => void   ` |  |
| `onFocusChange`

 | `   (isFocused: boolean) => void   ` |  |
| `onKeyDown`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onKeyUp`

 | `   (e: KeyboardEvent) => void   ` |  |
| `onChange`

 | `   (value: MappedTimeValue<TimeValue>) => void   ` |  |

---

## Page: https://www.heroui.com/docs/components/tooltip

# Tooltip

Tooltips display a brief, informative message that appears when a user interacts with an element.

Storybook@heroui/tooltipReact AriaSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

> For individual installation, please note that you should add `./node_modules/@heroui/theme/dist/components/popover.js` to your `tailwind.config.js` file instead since tooltip reuses popover styles.

## Usage

Preview

Code

Open in Chat

### With Arrow

Preview

Code

Open in Chat

### Colors

Preview

Code

Open in Chat

### Placements

Preview

Code

Open in Chat

### Offset

Preview

Code

Open in Chat

### Controlled

Preview

Code

Open in Chat

### With Delay

You can control the `open` and `close` delay of the tooltip with `delay` and `closeDelay` props.

Preview

Code

Open in Chat

Hovering over the second button shows the tooltip immediately. If you wait for a delay before hovering another element, the delay restarts.

Preview

Code

Open in Chat

### Custom Content

Preview

Code

Open in Chat

### Custom Motion

Tooltip offers a `motionProps` property to customize the `enter` / `exit` animation.

Preview

Code

Open in Chat

> Learn more about Framer motion variants here.

## Slots

*   **base**: The main tooltip slot, it wraps the tooltip content.
*   **arrow**: The arrow slot, it wraps the tooltip arrow, the placement of the arrow is based on the tooltip placement, e.g. `data-[placement=top]:...`.

### Custom Styles

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

Preview

Code

Open in Chat

## Data Attributes

`Tooltip` has the following attributes on the `base` element:

*   **data-open**: When the tooltip is open. Based on tooltip state.
*   **data-placement**: The placement of the tooltip. Based on `placement` prop. The arrow element is positioned based on this attribute.
*   **data-disabled**: When the tooltip is disabled. Based on `isDisabled` prop.

## Accessibility

*   Keyboard focus management and cross browser normalization.
*   Hover management and cross browser normalization.
*   Labeling support for screen readers (aria-describedby).
*   Exposed as a tooltip to assistive technology via ARIA.
*   Matches native tooltip behavior with delay on hover of first tooltip and no delay on subsequent tooltips.

## API

### Tooltip Props

| Prop | Type | Default |
| --- | --- | --- |
| `children*`
 | `   ReactNode[]   ` |  |
| `content`

 | `   ReactNode   ` |  |
| `size`

 | `   sm | md | lg   ` | `"md"` |
| `color`

 | `   default | primary | secondary | success | warning | danger   ` | `"default"` |
| `radius`

 | `   none | sm | md | lg | full   ` | `"md"` |
| `shadow`

 | `   none | sm | md | lg   ` | `"sm"` |
| `placement`

 | `   TooltipPlacement   ` | `"top"` |
| `delay`

 | `   number   ` | `"0"` |
| `closeDelay`

 | `   number   ` | `"500"` |
| `isOpen`

 | `   boolean   ` |  |
| `defaultOpen`

 | `   boolean   ` |  |
| `offset`

 | `   number   ` | `"7"` |
| `containerPadding`

 | `   number   ` | `"12"` |
| `crossOffset`

 | `   number   ` | `"0"` |
| `showArrow`

 | `   boolean   ` | `false` |
| `shouldFlip`

 | `   boolean   ` | `true` |
| `triggerScaleOnOpen`

 | `   boolean   ` | `true` |
| `isKeyboardDismissDisabled`

 | `   boolean   ` | `false` |
| `isDismissable`

 | `   boolean   ` | `false` |
| `shouldCloseOnBlur`

 | `   boolean   ` | `true` |
| `motionProps`

 | `   MotionProps   ` |  |
| `portalContainer`

 | `   HTMLElement   ` | `"document.body"` |
| `updatePositionDeps`

 | `   any[]   ` | `"[]"` |
| `isDisabled`

 | `   boolean   ` | `false` |
| `disableAnimation`

 | `   boolean   ` | `false` |
| `classNames`

 | `   Partial<Record<"base"｜"content", string>>   ` |  |

### Tooltip Events

| Prop | Type | Default |
| --- | --- | --- |
| `onOpenChange`
 | `   (isOpen: boolean) => void   ` |  |
| `shouldCloseOnInteractOutside`

 | `   (e: HTMLElement) => void   ` |  |
| `onClose`

 | `   () => void   ` |  |

### Tooltip types

#### Tooltip Placement

#### Motion Props

---

## Page: https://www.heroui.com/docs/components/user

# User

Display user information with avatar and name.

Storybook@heroui/userSourceStyles source

* * *

![Product Hunt](https://heroui-chat-assets.nyc3.cdn.digitaloceanspaces.com/herohack.png)

Hackathon #HeroHack

Join our hackathon, $6k in prizes + 3 months of HeroUI Chat Pro! ↗

## Installation

CLI

npm

yarn

pnpm

bun

> The above command is for individual installation only. You may skip this step if `@heroui/react` is already installed globally.

## Import

Individual

Global

## Usage

Preview

Code

Open in Chat

> **Note**: See the Avatar component for more details about `avatarProps`.

### Link Description

Preview

Code

Open in Chat

## Slots

*   **base**: The base slot of the user, it is the main container.
*   **wrapper**: The name and description wrapper.
*   **name**: The name of the user.
*   **description**: The description of the user.

## Data Attributes

`User` has the following attributes on the `root` element only when `isFocusable` is `true`:

*   **data-focus**: When the user is being focused. Based on useFocusRing
*   **data-focus-visible**: When the user is being focused with the keyboard. Based on useFocusRing

## API

### User Props

| Prop | Type | Default |
| --- | --- | --- |
| `name`
 | `   string   ` |  |
| `description`

 | `   ReactNode   ` |  |
| `isFocusable`

 | `   boolean   ` | `false` |
| `avatarProps`

 | `   AvatarProps   ` |  |
| `classNames`

 | `   Partial<Record<"base" | "wrapper" | "name" | "description", string>>   ` |  |