# HeroUI v3 > design-principles > Design Principles
URL: /docs/design-principles
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/design-principles.mdx

Core principles that guide HeroUI v3's design and development
        
***

title: Design Principles
description: Core principles that guide HeroUI v3's design and development
icon: book
----------

## Overview

HeroUI v3 follows 10 core principles that prioritize clarity, accessibility, customization, and developer experience.

## Core Principles

### 1. Semantic Intent Over Visual Style

Components use semantic naming (primary, secondary, tertiary) instead of visual descriptions (solid, flat, bordered).

Inspired by [Uber's Base design system](https://base.uber.com/6d2425e9f/p/756216-button), our variants follow a clear hierarchy:

![Semantic Intent Hierarchy](https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/semantic-intent.jpg)

```tsx
// ✅ Semantic variants communicate hierarchy
<Button variant="primary">Save</Button>
<Button variant="secondary">Edit</Button>
<Button variant="tertiary">Cancel</Button>
```

| Variant       | Purpose                           | Usage            |
| ------------- | --------------------------------- | ---------------- |
| **Primary**   | Main action to move forward       | 1 per context    |
| **Secondary** | Alternative actions               | Multiple allowed |
| **Tertiary**  | Dismissive actions (cancel, skip) | Sparingly        |
| **Danger**    | Destructive actions               | When needed      |

### 2. Accessibility as Foundation

Built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/) for WCAG 2.1 AA compliance, keyboard navigation, and screen reader support.

```tsx
// Automatic ARIA attributes, keyboard navigation, and focus management
<Tabs defaultSelectedKey="profile">
  <Tabs.List aria-label="Settings">
    <Tabs.Tab id="profile">Profile</Tabs.Tab>
    <Tabs.Tab id="security">Security</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel id="profile">Content</Tabs.Panel>
  <Tabs.Panel id="security">Content</Tabs.Panel>
</Tabs>
```

### 3. Composition Over Configuration

Compound components let you rearrange, customize, or omit parts as needed.

```tsx
// Compose parts to build exactly what you need
<Accordion>
  <Accordion.Item id="1">
    <Accordion.Heading>
      <Accordion.Trigger>
        Question Text
        <Accordion.Indicator />
      </Accordion.Trigger>
    </Accordion.Heading>
    <Accordion.Panel>
      <Accordion.Body>Answer content</Accordion.Body>
    </Accordion.Panel>
  </Accordion.Item>
</Accordion>
```

### 4. Progressive Disclosure

Start simple, add complexity only when needed.

```tsx
// Level 1: Minimal
<Button>Click me</Button>

// Level 2: Enhanced
<Button variant="primary" size="lg">
  <Icon icon="gravity-ui:check" className="mr-2" />
  Submit
</Button>

// Level 3: Advanced
<Button variant="primary" isDisabled={isLoading}>
  {isLoading ? <><Spinner size="sm" className="mr-2" /> Loading...</> : 'Submit'}
</Button>
```

### 5. Predictable Behavior

Consistent patterns across all components: sizes (`sm`, `md`, `lg`), variants, className support, and data attributes.

```tsx
// All components follow the same patterns
<Button size="lg" variant="primary" className="custom" data-pressed="true" />
<Chip size="lg" variant="success" className="custom" />
<Avatar size="lg" className="custom" />

// Compound components use dot notation
<Alert.Icon />
<Card.Header />
<Accordion.Trigger />
```

### 6. Type Safety First

Full TypeScript support with IntelliSense, auto-completion, and compile-time error detection.

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

// Type-safe props and event handlers
<Button
  variant="primary"  // Autocomplete: primary | secondary | tertiary | danger | ghost
  size="md"          // Type checked: sm | md | lg
  onPress={(e) => {  // e is properly typed as PressEvent
    console.log(e.target);
  }}
/>

// Extend types for custom components
interface CustomButtonProps extends Omit<ButtonProps, 'variant'> {
  intent: 'save' | 'cancel' | 'delete';
}
```

### 7. Separation of Styles and Logic

Styles (`@heroui/styles`) are separate from logic (`@heroui/react`), enabling use with any framework or vanilla HTML.

Full Example: [Tailwind Play](https://play.tailwindcss.com/Ioomj2xdce)

```html
<!-- Use with plain HTML -->
<button class="button button--primary">Click me</button>
```

or with React:

```tsx
// Apply styles to any component
import { buttonVariants } from '@heroui/react';

<Link className={buttonVariants({ variant: "primary" })} href="/home">
  Home
</Link>
```

### 8. Developer Experience Excellence

Clear APIs, descriptive errors, IntelliSense, AI-friendly markdown docs, and Storybook for visual testing.

### 9. Complete Customization

Beautiful defaults out-of-the-box. Transform the entire look with CSS variables or BEM classes.

```css
/* Theme-wide changes with variables */
:root {
  --accent: oklch(0.7 0.25 260);
  --radius: 0.375rem;
  --spacing: 0.5rem;
}

/* Component-specific customization */
@layer components {
  .button {
    @apply uppercase tracking-wider;
  }
  .button--primary {
    @apply bg-gradient-to-r from-purple-500 to-pink-500;
  }
}
```

### 10. Open and Extensible

Wrap, extend, and customize components to match your needs.

```tsx
// Custom wrapper component
const CTAButton = ({
  intent = 'primary-cta',
  children,
  ref,
  ...props
}: CTAButtonProps) => {
  const variantMap = {
    'primary-cta': 'primary',
    'secondary-cta': 'secondary',
    'minimal': 'ghost'
  };

  return (
    <Button ref={ref} variant={variantMap[intent]} {...props}>
      {children}
    </Button>
  );
};
```

Or extend with Tailwind Variants:

```tsx
import { Button, buttonVariants } from '@heroui/react';
import { tv } from 'tailwind-variants';

// Extend button styles with custom variants
const myButtonVariants = tv({
  extend: buttonVariants,
  variants: {
    variant: {
      'primary-cta': 'bg-gradient-to-r from-blue-500 to-purple-600 text-white shadow-lg',
      'secondary-cta': 'border-2 border-blue-500 text-blue-500 hover:bg-blue-50',
    }
  }
});

// Use the custom variants
function CustomButton({ variant, className, ...props }) {
  return <Button className={myButtonVariants({ variant, className })} {...props} />;
}

// Usage
<CustomButton variant="primary-cta">Get Started</CustomButton>
<CustomButton variant="secondary-cta">Learn More</CustomButton>
```

## Comparison with HeroUI v2

| Aspect                       | HeroUI v2                            | HeroUI v3                                 |
| ---------------------------- | ------------------------------------ | ----------------------------------------- |
| **Animations**               | Framer Motion                        | CSS + GPU accelerated                     |
| **Component Pattern**        | Single components with many props    | Compound components                       |
| **Variants**                 | Visual-based (solid, bordered, flat) | Semantic (primary, secondary, tertiary)   |
| **Styling**                  | Tailwind v4 partially supported      | Tailwind v4 fully supported               |
| **Accessibility**            | Excellent (React Aria powered)       | Excellent (React Aria powered)            |
| **Bundle Size**              | Larger (Bundle)                      | Smaller (tree-shakeable)                  |
| **Customization Difficulty** | Medium (Props-based)                 | Simple (Compound components + Native CSS) |


# HeroUI v3 > introduction > Introduction
URL: /docs/introduction
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/introduction.mdx

An open-source UI component library for building beautiful and accessible user interfaces.
        
***

title: Introduction
description: An open-source UI component library for building beautiful and accessible user interfaces.
icon: book-open
---------------

HeroUI is a UI library for React that helps you build beautiful and accessible user interfaces. Created on top of [Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/index.html).

<div className="not-prose relative w-full h-[220px] md:h-[340px] overflow-hidden rounded-xl shadow-border">
  <img className="absolute inset-0 w-full h-full object-cover opacity-0 dark:opacity-100 transition-opacity duration-300 ease-in-out" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/docs-intro-cover-dark.jpg" alt="HeroUI v3 Introduction" />

  <img className="absolute inset-0 w-full h-full object-cover opacity-100 dark:opacity-0 transition-opacity duration-300 ease-in-out" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/docs-intro-cover.jpg" alt="HeroUI v3 Introduction" />
</div>

Every component is designed with care: smooth animations, polished details, and accessibility built in. It works out of the box, yet gives you the freedom to make it your own.

We believe design should not be copied and pasted. It should evolve. HeroUI gives you components that grow with you, always improving, always up to date.

## Why HeroUI?

### Beautiful by Default

Looks professional the moment you use it. No extra styling required.

### Accessible

Accessibility is not optional. With [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html), we handle focus management, keyboard navigation, and screen readers support.

### Flexible Architecture

Each component is made of parts you can control. Change what you need. Leave the rest.

### Developer Experience

Typed APIs. Predictable patterns. Autocompletion that just works.

### Ship Faster

We maintain the library so you can focus on your product. Just update the package to get bug fixes, new features, and more. No manual code changes needed.

### Optimized & Lightweight

Tree-shaken. Only what you use goes into your app.

### AI-Ready

HeroUI v3 is designed for a future where AI writes code. Components are simple for humans and AI agents to assemble into great products.

### Future-Proof

Built for [React 19](https://react.dev/blog/2024/12/05/react-19) and [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4). Always improving with the web.

## Mission

We want to make world-class interfaces available to everyone. HeroUI turns complexity into simplicity. It helps you build apps that are beautiful, accessible, and effortless to use.

When you use HeroUI, you are not just moving faster. You are giving your users something that feels and performs better.

## Vision

The future of UI should not be tied to one framework. HeroUI v3 begins with React, but the goal is bigger: React Native, AI-driven design tools, and more.

We are building an ecosystem where interfaces are alive. Maintained, improved, and ready for whatever comes next.

### Why not copy-paste?

Copy-paste looks like control, but it is an illusion.
You paste code, it works for a while, then it breaks. You are left maintaining a pile of dependencies.

Most copy-paste UIs end up looking the same. They age. They stop evolving.

HeroUI is different. It is a living library:

* Updates and fixes flow to you automatically
* New features arrive without extra work
* Components stay current with React, Tailwind, and browsers
* You get deep customization, not shallow theme tweaks
* AI can generate clean, efficient code with HeroUI

HeroUI v3 is not a snapshot. It is a garden that keeps growing. 🌱

## HeroUI Ecosystem

Explore the full HeroUI platform:

* **🌐 HeroUI v3** (web) - You're here! React components with Tailwind CSS v4
* **📱 [HeroUI Native](https://link.heroui.com/native)** (mobile) - Beautiful components for React Native
* **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)** (text-to-app) - Create beautiful apps with natural language
* **🧠 UI for LLMs** - New platform & MCPs coming soon

### Why React Aria over Radix?

We chose React Aria because it solves accessibility at scale with a strong community behind it.\
We've used it since HeroUI v2 (via hooks) and v3 keeps API conventions like `isDisabled` and `onPress`.

Huge thanks to [Devon Govett](https://x.com/devongovett) and the Adobe team for their work here.

## FAQ

### Is HeroUI free?

Yes, completely free and open source under the MIT license.

### Is it production-ready?

Currently in alpha. We're actively working towards a stable release with community feedback.

### Can I customize the components?

Yes! Use Tailwind utilities, CSS variables, BEM modifiers, or compose component parts differently. Every slot is customizable.

### Does it work with TypeScript?

Fully typed with excellent IDE support and autocompletion.

### What about accessibility?

Built on React Aria Components for WCAG compliance. Keyboard navigation, focus management, and screen reader support included.

### Can I use the styles without React?

Yes, the CSS can be applied to plain HTML. See our [Tailwind Play example](https://play.tailwindcss.com/Ioomj2xdce).

### Is there a Figma file?

Yes! You can access our Figma design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429).

## 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!

* [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
* [Discord](https://discord.gg/9b6yyZKmH4)
* [X/Twitter](https://x.com/hero_ui)

## Contributing

PRs on HeroUI are always welcome, please see our [contribution guidelines](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md) to learn how you can contribute to this project.

## License

HeroUI is released under the [MIT License](https://github.com/heroui-inc/heroui/blob/main/LICENSE).


# HeroUI v3 > llms-txt > LLMs.txt
URL: /docs/llms-txt
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/llms-txt.mdx

Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI v3
        
***

title: LLMs.txt
description: Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI v3
icon: face-robot
----------------

We provide [LLMs.txt](https://llmstxt.org/) files to make HeroUI v3 documentation accessible to AI coding assistants.

## Available Files

### Core Documentation

* [/llms.txt](https://v3.heroui.com/llms.txt) - Quick reference index
* [/llms-full.txt](https://v3.heroui.com/llms-full.txt) - Complete HeroUI v3 documentation

### Coming Soon

For limited context windows:

* `/llms-components.txt` - Component documentation only
* `/llms-patterns.txt` - Common patterns and recipes
* `/llms-migration.txt` - Migration guide from v2

## Integration

### Claude Code

Tell Claude to reference the documentation:

```
Use HeroUI v3 documentation from https://v3.heroui.com/llms.txt
```

Or add to your project's `.claude` file for automatic loading.

### Cursor

Use the `@Docs` feature to add HeroUI documentation:

```
@Docs https://v3.heroui.com/llms-full.txt
```

[Learn more](https://docs.cursor.com/context/@-symbols/@-docs)

### Windsurf

Add to your `.windsurfrules` file:

```
#docs https://v3.heroui.com/llms-full.txt
```

[Learn more](https://docs.codeium.com/windsurf/memories#memories-and-rules)

### Other AI Tools

Most AI assistants can reference documentation by URL. Simply provide:

```
https://v3.heroui.com/llms.txt
```

## Contributing

Found an issue with AI-generated code? Help us improve our LLMs.txt files on [GitHub](https://github.com/heroui-inc/heroui).


# HeroUI v3 > quick-start > Quick Start
URL: /docs/quick-start
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/quick-start.mdx

Get started with HeroUI v3 in minutes
        
***

title: Quick Start
description: Get started with HeroUI v3 in minutes
icon: rocket
------------

## Requirements

* [React 19+](https://reactjs.org/)
* [Tailwind CSS v4](https://tailwindcss.com/docs/installation/framework-guides)

## Quick Install

Install HeroUI and required dependencies:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm i @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>
</Tabs>

## Import Styles

Add to your main CSS file `globals.css`:

```css
@import "tailwindcss";
@import "@heroui/styles"; /* [!code highlight]*/
```

<Callout type="warning">
  Import order matters. Always import `tailwindcss` first.
</Callout>

## Use Components

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

function App() {
  return (
    <Button>
      My Button
    </Button>
  );
}
```

## What's Next?

* [Browse Components](/docs/components) - See all available components
* [Learn Styling](/docs/handbook/styling) - Customize with Tailwind CSS
* [Explore Patterns](/docs/handbook/composition) - Master compound components


# HeroUI v3 > components > Accordion
URL: /docs/components/accordion
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/accordion.mdx

A collapsible content panel for organizing information in a compact space
        
***

title: Accordion
description: A collapsible content panel for organizing information in a compact space
links:
rac: Disclosure
source: accordion/accordion.tsx
styles: accordion.css
storybook: accordion
figma: true
-----------

## Import

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

### Example

<ComponentPreview name="accordion-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Accordion>
    <Accordion.Item>
      <Accordion.Heading>
        <Accordion.Trigger>
          <Accordion.Indicator />
        </Accordion.Trigger>
      </Accordion.Heading>
      <Accordion.Panel>
        <Accordion.Body/>
      </Accordion.Panel>
    </Accordion.Item>
  </Accordion>
)
```

### Outline

<ComponentPreview name="accordion-outline" />

### Multiple Expanded

<ComponentPreview name="accordion-multiple" />

### Custom Indicator

<ComponentPreview name="accordion-custom-indicator" />

### Disabled State

<ComponentPreview name="accordion-disabled" />

### FAQ Layout

<ComponentPreview name="accordion-faq" />

### Custom Styles

<ComponentPreview name="accordion-custom-styles" />

## Styling

### Passing Tailwind CSS classes

<CollapsibleCode
  lang="tsx"
  code={`"use client";

import {Accordion, cn} from "@heroui/react";
import {Icon} from "@iconify/react";

const items = [
{
  content:
    "Stay informed about your account activity with real-time notifications. You'll receive instant alerts for important events like transactions, new messages, security updates, and system announcements. ",
  iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png",
  title: "Set Up Notifications",
  subtitle: "Receive account activity updates",
},
{
  content:
    "Enhance your browsing experience by installing our official browser extension. The extension provides seamless integration with your account, allowing you to receive notifications directly in your browser, quickly access your dashboard, and interact with web3 applications securely. Compatible with Chrome, Firefox, Edge, and Brave browsers.",
  iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png",
  title: "Set up Browser Extension",
  subtitle: "Connect you browser to your account",
},
{
  content:
    "Begin your journey into the world of digital collectibles by creating your first NFT. Our intuitive minting process guides you through uploading your artwork, setting metadata, choosing royalty percentages, and deploying to the blockchain. Whether you're an artist, creator, or collector, you'll find all the tools you need to bring your digital assets to life. Your collectibles are stored on IPFS for permanent decentralized storage.",
  iconUrl:
    "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png",
  title: "Mint Collectible",
  subtitle: "Create your first collectible",
},
];

export function CustomStyles() {
return (
  <Accordion className="bg-surface-1 w-full max-w-md rounded-2xl" variant="outline">
    {items.map((item, index) => (
      <Accordion.Item
        key={index}
        className={cn(
          "group/item",
          "first:[&_[data-accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top
          "last:[&:not(:has([data-accordion-trigger][aria-expanded='true']))_[data-accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom
        )}
      >
        <Accordion.Heading>
          <Accordion.Trigger className="hover:bg-surface-2 group flex items-center gap-2">
            {item.iconUrl ? (
              <img
                alt={item.title}
                className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg"
                src={item.iconUrl}
              />
            ) : null}
            <div className="flex flex-col gap-0">
              <span className="font-medium leading-5">{item.title}</span>
              <span className="text-muted/80 font-normal leading-6">{item.subtitle}</span>
            </div>
            <Accordion.Indicator className="text-muted/50 [&>svg]:size-4">
              <Icon icon="gravity-ui:chevron-down" />
            </Accordion.Indicator>
          </Accordion.Trigger>
        </Accordion.Heading>
        <Accordion.Panel>
          <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body>
        </Accordion.Panel>
      </Accordion.Item>
    ))}
  </Accordion>
);
}`}
/>

### Customizing the component classes

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

```css
@layer components {
  .accordion {
    @apply rounded-xl bg-gray-50;
  }

  .accordion__trigger {
    @apply font-semibold text-lg;
  }

  .accordion--outline {
    @apply shadow-lg border-2;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.accordion` - Base accordion container
* `.accordion__body` - Content body container
* `.accordion__heading` - Heading wrapper
* `.accordion__indicator` - Expand/collapse indicator icon
* `.accordion__item` - Individual accordion item
* `.accordion__panel` - Collapsible panel container
* `.accordion__trigger` - Clickable trigger button

#### Variant Classes

* `.accordion--outline` - Outline variant with border and background

#### State Classes

* `.accordion__trigger[aria-expanded="true"]` - Expanded state
* `.accordion__panel[aria-hidden="false"]` - Panel visible state

### Interactive States

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

* **Hover**: `:hover` or `[data-hover="true"]` on trigger
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
* **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger
* **Expanded**: `[aria-expanded="true"]` on trigger

## API Reference

### Accordion Props

| Prop                     | Type                       | Default     | Description                                    |
| ------------------------ | -------------------------- | ----------- | ---------------------------------------------- |
| `allowsMultipleExpanded` | `boolean`                  | `false`     | Whether multiple items can be expanded at once |
| `defaultExpandedKeys`    | `Iterable<Key>`            | -           | The initial expanded keys                      |
| `expandedKeys`           | `Iterable<Key>`            | -           | The controlled expanded keys                   |
| `onExpandedChange`       | `(keys: Set<Key>) => void` | -           | Handler called when expanded keys change       |
| `isDisabled`             | `boolean`                  | `false`     | Whether the entire accordion is disabled       |
| `variant`                | `"default" \| "outline"`   | `"default"` | The visual variant of the accordion            |
| `className`              | `string`                   | -           | Additional CSS classes                         |
| `children`               | `ReactNode`                | -           | The accordion items                            |

### Accordion.Item Props

| Prop               | Type                            | Default | Description                        |
| ------------------ | ------------------------------- | ------- | ---------------------------------- |
| `id`               | `Key`                           | -       | Unique identifier for the item     |
| `isDisabled`       | `boolean`                       | `false` | Whether this item is disabled      |
| `defaultExpanded`  | `boolean`                       | `false` | Whether item is initially expanded |
| `isExpanded`       | `boolean`                       | -       | Controlled expanded state          |
| `onExpandedChange` | `(isExpanded: boolean) => void` | -       | Handler for expanded state changes |
| `className`        | `string`                        | -       | Additional CSS classes             |
| `children`         | `ReactNode`                     | -       | The item content                   |

### Accordion.Trigger Props

| Prop         | Type                          | Default | Description                        |
| ------------ | ----------------------------- | ------- | ---------------------------------- |
| `className`  | `string`                      | -       | Additional CSS classes             |
| `children`   | `ReactNode \| RenderFunction` | -       | Trigger content or render function |
| `onPress`    | `() => void`                  | -       | Additional press handler           |
| `isDisabled` | `boolean`                     | -       | Whether trigger is disabled        |

### Accordion.Panel Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `className` | `string`    | -       | Additional CSS classes |
| `children`  | `ReactNode` | -       | Panel content          |

### Accordion.Indicator Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `className` | `string`    | -       | Additional CSS classes |
| `children`  | `ReactNode` | -       | Custom indicator icon  |

### Accordion.Body Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `className` | `string`    | -       | Additional CSS classes |
| `children`  | `ReactNode` | -       | Body content           |


# HeroUI v3 > components > Avatar
URL: /docs/components/avatar
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/avatar.mdx

Display user profile images with customizable fallback content
        
***

title: Avatar
description: Display user profile images with customizable fallback content
links:
radix: avatar
source: avatar/avatar.tsx
styles: avatar.css
storybook: avatar
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="avatar-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Avatar>
    <Avatar.Image/>
    <Avatar.Fallback/>
  </Avatar>
)
```

### Sizes

<ComponentPreview name="avatar-sizes" />

### Colors

<ComponentPreview name="avatar-colors" />

### Fallback Content

<ComponentPreview name="avatar-fallback" />

### Avatar Group

<ComponentPreview name="avatar-group" />

### Custom Styles

<ComponentPreview name="avatar-custom-styles" />

## Styling

### Passing Tailwind CSS classes

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

function CustomAvatar() {
  return (
    <Avatar className="size-20">
      <Avatar.Image src="..." alt="..." />
      <Avatar.Fallback>XL</Avatar.Fallback>
    </Avatar>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .avatar {
    @apply size-16 border-2 border-primary;
  }

  .avatar__fallback {
    @apply bg-gradient-to-br from-purple-500 to-pink-500;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.avatar` - Base container with default size (size-10)
* `.avatar__image` - Image element with aspect-square sizing
* `.avatar__fallback` - Fallback container with centered content

#### Size Modifiers

* `.avatar--sm` - Small avatar (size-8)
* `.avatar--md` - Medium avatar (default, no additional styles)
* `.avatar--lg` - Large avatar (size-12)

#### Color Modifiers

* `.avatar__fallback--default` - Default text color
* `.avatar__fallback--accent` - Accent text color
* `.avatar__fallback--success` - Success text color
* `.avatar__fallback--warning` - Warning text color
* `.avatar__fallback--danger` - Danger text color

## API Reference

### Avatar Props

| Prop        | Type                                                          | Default     | Description             |
| ----------- | ------------------------------------------------------------- | ----------- | ----------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Avatar size             |
| `color`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback color theme    |
| `className` | `string`                                                      | -           | Additional CSS classes  |
| `asChild`   | `boolean`                                                     | `false`     | Render as child element |

### Avatar.Image Props

| Prop                    | Type                                                               | Default | Description                                                               |
| ----------------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------- |
| `src`                   | `string`                                                           | -       | Image source URL                                                          |
| `srcSet`                | `string`                                                           | -       | The image `srcset` attribute for responsive images                        |
| `sizes`                 | `string`                                                           | -       | The image `sizes` attribute for responsive images                         |
| `alt`                   | `string`                                                           | -       | Alternative text for the image                                            |
| `onLoad`                | `(event: SyntheticEvent<HTMLImageElement>) => void`                | -       | Callback when the image loads successfully                                |
| `onError`               | `(event: SyntheticEvent<HTMLImageElement>) => void`                | -       | Callback when there's an error loading the image                          |
| `onLoadingStatusChange` | `(status: 'loading' \| 'loaded' \| 'pending' \| 'failed') => void` | -       | Callback for loading status changes                                       |
| `ignoreFallback`        | `boolean`                                                          | `false` | If `true`, opt out of the fallback logic and use as regular `img`         |
| `shouldBypassImageLoad` | `boolean`                                                          | `false` | If `true`, image load will be bypassed and handled by `asChild` component |
| `crossOrigin`           | `'anonymous' \| 'use-credentials'`                                 | -       | CORS setting for the image request                                        |
| `loading`               | `'eager' \| 'lazy'`                                                | -       | Native lazy loading attribute                                             |
| `className`             | `string`                                                           | -       | Additional CSS classes                                                    |
| `asChild`               | `boolean`                                                          | `false` | Render as child element                                                   |

### Avatar.Fallback Props

| Prop        | Type                                                          | Default | Description                                    |
| ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------- |
| `delayMs`   | `number`                                                      | -       | Delay before showing fallback (prevents flash) |
| `color`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | -       | Override color from parent                     |
| `className` | `string`                                                      | -       | Additional CSS classes                         |
| `asChild`   | `boolean`                                                     | `false` | Render as child element                        |


# HeroUI v3 > components > Button
URL: /docs/components/button
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/button.mdx

A clickable button component with multiple variants and states
        
***

title: Button
description: A clickable button component with multiple variants and states
links:
rac: Button
source: button/button.tsx
styles: button.css
storybook: button
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="button-basic" />

### Variants

<ComponentPreview name="button-variants" />

### With Icons

<ComponentPreview name="button-with-icons" />

### Icon Only

<ComponentPreview name="button-icon-only" />

### Loading

<ComponentPreview name="button-loading" />

### Loading State

<ComponentPreview name="button-loading-state" />

### Sizes

<ComponentPreview name="button-sizes" />

### Disabled State

<ComponentPreview name="button-disabled" />

### Social Buttons

<ComponentPreview name="button-social" />

## Styling

### Passing Tailwind CSS classes

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

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

### Customizing the component classes

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

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

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

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

### Adding custom variants

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

<ComponentPreview name="button-custom-variants" />

### CSS Classes

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

#### Base & Size Classes

* `.button` - Base button styles
* `.button--sm` - Small size variant
* `.button--md` - Medium size variant
* `.button--lg` - Large size variant

#### Variant Classes

* `.button--primary`
* `.button--secondary`
* `.button--tertiary`
* `.button--ghost`
* `.button--danger`

#### Modifier Classes

* `.button--icon-only`
* `.button--icon-only.button--sm`
* `.button--icon-only.button--lg`

### Interactive States

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

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

## API Reference

### Button Props

| Prop         | Type                                                                | Default     | Description                               |
| ------------ | ------------------------------------------------------------------- | ----------- | ----------------------------------------- |
| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'`     | `'primary'` | Visual style variant                      |
| `size`       | `'sm' \| 'md' \| 'lg'`                                              | `'md'`      | Size of the button                        |
| `isDisabled` | `boolean`                                                           | `false`     | Whether the button is disabled            |
| `isPending`  | `boolean`                                                           | `false`     | Whether the button is in a loading state  |
| `isIconOnly` | `boolean`                                                           | `false`     | Whether the button contains only an icon  |
| `onPress`    | `(e: PressEvent) => void`                                           | -           | Handler called when the button is pressed |
| `children`   | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | -           | Button content or render prop             |

### ButtonRenderProps

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

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


# HeroUI v3 > components > Chip
URL: /docs/components/chip
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/chip.mdx

Small informational badges for displaying labels, statuses, and categories
        
***

title: Chip
description: Small informational badges for displaying labels, statuses, and categories
links:
source: chip/chip.tsx
styles: chip.css
storybook: chip
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="chip-basic" />

### Variants

<ComponentPreview name="chip-variants" />

### With Icons

<ComponentPreview name="chip-with-icon" />

### Statuses

<ComponentPreview name="chip-statuses" />

## Styling

### Passing Tailwind CSS classes

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

function CustomChip() {
  return (
    <Chip className="rounded-full px-4 py-2 font-bold">
      Custom Styled
    </Chip>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .chip {
    @apply rounded-full text-xs;
  }

  .chip--accent {
    @apply border-accent/20;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.chip` - Base chip styles

#### Color Classes

* `.chip--accent` - Accent color variant
* `.chip--danger` - Danger color variant
* `.chip--default` - Default color variant
* `.chip--success` - Success color variant
* `.chip--warning` - Warning color variant

#### Variant Classes

* `.chip--primary` - Primary variant with filled background
* `.chip--secondary` - Secondary variant with border
* `.chip--tertiary` - Tertiary variant with transparent background

#### Compound Variant Classes

* `.chip--primary.chip--accent` - Primary accent combination
* `.chip--primary.chip--success` - Primary success combination
* `.chip--primary.chip--warning` - Primary warning combination
* `.chip--primary.chip--danger` - Primary danger combination

### Interactive States

The component supports focus visibility:

* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`

## API Reference

### Chip Props

| Prop        | Type                                                          | Default       | Description                        |
| ----------- | ------------------------------------------------------------- | ------------- | ---------------------------------- |
| `children`  | `React.ReactNode`                                             | -             | Content to display inside the chip |
| `className` | `string`                                                      | -             | Additional CSS classes             |
| `color`     | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"`   | Color variant of the chip          |
| `variant`   | `"primary" \| "secondary" \| "tertiary"`                      | `"secondary"` | Visual style variant               |


# HeroUI v3 > components > Disclosure
URL: /docs/components/disclosure
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/disclosure.mdx

A disclosure is a collapsible section with a header containing a heading and a trigger button, and a panel that wraps the content.
        
***

title: Disclosure
description: A disclosure is a collapsible section with a header containing a heading and a trigger button, and a panel that wraps the content.
links:
rac: Disclosure
source: disclosure/disclosure.tsx
styles: disclosure.css
storybook: disclosure
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="disclosure-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Disclosure>
    <Disclosure.Heading>
      <Disclosure.Trigger>
        <Disclosure.Indicator />
      </Disclosure.Trigger>
    </Disclosure.Heading>
    <Disclosure.Content/>
  </Disclosure>
)
```

## Styling

### Passing Tailwind CSS classes

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

function CustomDisclosure() {
  return (
    <Disclosure className="border rounded-lg p-4">
      <Disclosure.Trigger className="text-lg font-semibold">
        Click to expand
        <Disclosure.Indicator className="ml-2" />
      </Disclosure.Trigger>
      <Disclosure.Content className="mt-4 text-gray-600">
        Hidden content
      </Disclosure.Content>
    </Disclosure>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .disclosure {
    @apply relative;
  }
  
  .disclosure__trigger {
    @apply cursor-pointer;
  }
  
  .disclosure__indicator {
    @apply transition-transform duration-300;
  }
  
  .disclosure__content {
    @apply overflow-hidden transition-all;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.disclosure` - Base container styles
* `.disclosure__heading` - Heading wrapper
* `.disclosure__trigger` - Trigger button styles
* `.disclosure__indicator` - Chevron indicator styles
* `.disclosure__content` - Content container with animations

### Interactive States

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

* **Expanded**: `[data-expanded="true"]` on indicator for rotation
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
* **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger
* **Hidden**: `[aria-hidden="false"]` on content for visibility

## API Reference

### Disclosure Props

| Prop               | Type                            | Default | Description                          |
| ------------------ | ------------------------------- | ------- | ------------------------------------ |
| `isExpanded`       | `boolean`                       | `false` | Controls the expanded state          |
| `onExpandedChange` | `(isExpanded: boolean) => void` | -       | Callback when expanded state changes |
| `isDisabled`       | `boolean`                       | `false` | Whether the disclosure is disabled   |
| `children`         | `ReactNode \| RenderFunction`   | -       | Content to render                    |
| `className`        | `string`                        | -       | Additional CSS classes               |

### Disclosure.Trigger Props

| Prop        | Type                          | Default     | Description              |
| ----------- | ----------------------------- | ----------- | ------------------------ |
| `children`  | `ReactNode \| RenderFunction` | -           | Trigger content          |
| `className` | `string`                      | -           | Additional CSS classes   |
| `slot`      | `string`                      | `"trigger"` | Slot name for React Aria |

### Disclosure.Content Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `children`  | `ReactNode` | -       | Content to show/hide   |
| `className` | `string`    | -       | Additional CSS classes |

### Disclosure.Indicator Props

| Prop        | Type           | Default               | Description              |
| ----------- | -------------- | --------------------- | ------------------------ |
| `children`  | `ReactElement` | `<IconChevronDown />` | Custom indicator element |
| `className` | `string`       | -                     | Additional CSS classes   |

### RenderProps

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

| Prop         | Type      | Description                    |
| ------------ | --------- | ------------------------------ |
| `isExpanded` | `boolean` | Current expanded state         |
| `isDisabled` | `boolean` | Whether disclosure is disabled |


# HeroUI v3 > components > Kbd
URL: /docs/components/kbd
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/kbd.mdx

Display keyboard shortcuts and key combinations
        
***

title: Kbd
description: Display keyboard shortcuts and key combinations
links:
source: kbd/kbd.tsx
styles: kbd.css
storybook: kbd
figma: true
-----------

## Import

```tsx
import {Kbd} from "@heroui/react";
```

### Usage

<ComponentPreview name="kbd-basic" />

### Anatomy

Import all parts and piece them together.

```tsx
import {Kbd} from "@heroui/react";

export default () => (
  <Kbd>
    <Kbd.Abbr keyValue="command" />
    <Kbd.Content>K</Kbd.Content>
  </Kbd>
);
```

### Navigation Keys

<ComponentPreview name="kbd-navigation-keys" />

### Inline Usage

<ComponentPreview name="kbd-inline-usage" />

### Instructional Text

<ComponentPreview name="kbd-instructional-text" />

### Special Keys

<ComponentPreview name="kbd-special-keys" />

## Styling

### Passing Tailwind CSS classes

```tsx
import {Kbd} from "@heroui/react";

function CustomKbd() {
  return (
    <Kbd className="bg-gray-100 dark:bg-gray-800">
      <Kbd.Content>K</Kbd.Content>
    </Kbd>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .kbd {
    @apply bg-gray-100 dark:bg-gray-800 border-gray-300;
  }

  .kbd__abbr {
    @apply font-bold;
  }

  .kbd__content {
    @apply text-sm;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.kbd` - Base keyboard key styles with background, border, and spacing
* `.kbd__abbr` - Abbreviation element for modifier keys
* `.kbd__content` - Content wrapper for key text

## API Reference

### Kbd Props

| Prop        | Type              | Default | Description        |
| ----------- | ----------------- | ------- | ------------------ |
| `children`  | `React.ReactNode` | -       | Content of the key |
| `className` | `string`          | -       | Custom CSS classes |

### Kbd.Abbr Props

| Prop        | Type     | Default | Description                                                                          |
| ----------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `keyValue`  | `KbdKey` | -       | The keyboard key to display. Available values include modifier keys and special keys |
| `className` | `string` | -       | Custom CSS classes                                                                   |

### Kbd.Content Props

| Prop        | Type              | Default | Description             |
| ----------- | ----------------- | ------- | ----------------------- |
| `children`  | `React.ReactNode` | -       | Text content of the key |
| `className` | `string`          | -       | Custom CSS classes      |

### KbdKey Type

Available key values for the `keyValue` prop:

| Modifier Keys | Special Keys | Navigation Keys | Function Keys |
| ------------- | ------------ | --------------- | ------------- |
| `command`     | `enter`      | `up`            | `fn`          |
| `shift`       | `delete`     | `down`          |               |
| `ctrl`        | `escape`     | `left`          |               |
| `option`      | `tab`        | `right`         |               |
| `alt`         | `space`      | `pageup`        |               |
| `win`         | `capslock`   | `pagedown`      |               |
|               | `help`       | `home`          |               |
|               |              | `end`           |               |


# HeroUI v3 > components > Link
URL: /docs/components/link
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/link.mdx

A styled anchor component for navigation with built-in icon support
        
***

title: Link
description: A styled anchor component for navigation with built-in icon support
links:
rac: Link
source: link/link.tsx
styles: link.css
storybook: link
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="link-basic" />

### With Icons

<ComponentPreview name="link-with-icon" />

## Styling

### Passing Tailwind CSS classes

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

function CustomLink() {
  return (
    <Link
      href="#"
      className="text-lg font-bold text-accent hover:text-accent/80"
    >
      Custom styled link
    </Link>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .link {
    @apply font-semibold no-underline hover:underline;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.link` - Base link styles with underline on hover

### Interactive States

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

* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`

## API Reference

### Link Props

| Prop            | Type                      | Default | Description                                        |
| --------------- | ------------------------- | ------- | -------------------------------------------------- |
| `href`          | `string`                  | -       | URL for navigation                                 |
| `target`        | `string`                  | -       | Specifies where to open the linked document        |
| `rel`           | `string`                  | -       | Specifies the relationship between documents       |
| `isDisabled`    | `boolean`                 | `false` | Disables link interaction                          |
| `showIcon`      | `boolean`                 | `false` | Shows the link icon                                |
| `iconPlacement` | `"start" \| "end"`        | `"end"` | Position of the icon                               |
| `className`     | `string`                  | -       | Additional CSS classes                             |
| `children`      | `React.ReactNode`         | -       | Link content                                       |
| `onPress`       | `(e: PressEvent) => void` | -       | Handler called when the link is pressed            |
| `autoFocus`     | `boolean`                 | -       | Whether the element should receive focus on render |

### Link.Icon Props

| Prop        | Type              | Default | Description                    |
| ----------- | ----------------- | ------- | ------------------------------ |
| `asChild`   | `boolean`         | `false` | Merge props with child element |
| `children`  | `React.ReactNode` | -       | Custom icon element            |
| `className` | `string`          | -       | Additional CSS classes         |


# HeroUI v3 > components > Popover
URL: /docs/components/popover
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/popover.mdx

Displays rich content in a portal triggered by a button or any custom element
        
***

title: Popover
description: Displays rich content in a portal triggered by a button or any custom element
links:
rac: Popover
source: popover/popover.tsx
styles: popover.css
storybook: popover
------------------

## Import

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

### Usage

<ComponentPreview name="popover-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Popover>
    <Popover.Trigger/>
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Dialog>
        <Popover.Heading/>
        {/* content goes here */}
      </Popover.Dialog>
    </Popover.Content>
  </Popover>
)
```

### With Arrow

<ComponentPreview name="popover-with-arrow" />

### Placement

<ComponentPreview name="popover-placement" />

### Interactive Content

<ComponentPreview name="popover-interactive" />

## Styling

### Passing Tailwind CSS classes

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

function CustomPopover() {
  return (
    <Popover>
      <Button>Open</Button>
      <Popover.Content className="bg-accent text-accent-foreground">
        <Popover.Dialog>
          <Popover.Heading>Custom Styled</Popover.Heading>
          <p>This popover has custom styling</p>
        </Popover.Dialog>
      </Popover.Content>
    </Popover>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .popover {
    @apply rounded-xl shadow-2xl;
  }

  .popover__dialog {
    @apply p-4;
  }

  .popover__heading {
    @apply text-lg font-bold;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.popover` - Base popover container styles
* `.popover__dialog` - Dialog content wrapper
* `.popover__heading` - Heading text styles
* `.popover__trigger` - Trigger element styles

### Interactive States

The component supports animation states:

* **Entering**: `[data-entering]` - Applied during popover appearance
* **Exiting**: `[data-exiting]` - Applied during popover disappearance
* **Placement**: `[data-placement="*"]` - Applied based on popover position
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`

## API Reference

### Popover Props

| Prop           | Type                        | Default | Description                              |
| -------------- | --------------------------- | ------- | ---------------------------------------- |
| `children`     | `React.ReactNode`           | -       | Trigger and content elements             |
| `isOpen`       | `boolean`                   | -       | Controls popover visibility (controlled) |
| `defaultOpen`  | `boolean`                   | `false` | Initial open state (uncontrolled)        |
| `onOpenChange` | `(isOpen: boolean) => void` | -       | Called when open state changes           |

### Popover.Content Props

| Prop         | Type                                                    | Default    | Description                                   |
| ------------ | ------------------------------------------------------- | ---------- | --------------------------------------------- |
| `children`   | `React.ReactNode`                                       | -          | Content to display in the popover             |
| `placement`  | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"bottom"` | Placement of the popover                      |
| `offset`     | `number`                                                | `8`        | Distance from the trigger element             |
| `shouldFlip` | `boolean`                                               | `true`     | Whether popover can change orientation to fit |
| `className`  | `string`                                                | -          | Additional CSS classes                        |

### Popover.Dialog Props

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `children`  | `React.ReactNode` | -       | Dialog content         |
| `className` | `string`          | -       | Additional CSS classes |

### Popover.Trigger Props

| Prop        | Type              | Default | Description                       |
| ----------- | ----------------- | ------- | --------------------------------- |
| `children`  | `React.ReactNode` | -       | Element that triggers the popover |
| `className` | `string`          | -       | Additional CSS classes            |

### Popover.Heading Props

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `children`  | `React.ReactNode` | -       | Heading text content   |
| `className` | `string`          | -       | Additional CSS classes |

### Popover.Arrow Props

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `children`  | `React.ReactNode` | -       | Custom arrow element   |
| `className` | `string`          | -       | Additional CSS classes |


# HeroUI v3 > components > Separator
URL: /docs/components/separator
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/separator.mdx

Visually divide content sections
        
***

title: Separator
description: Visually divide content sections
links:
rac: Separator
source: separator/separator.tsx
styles: separator.css
storybook: separator
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="separator-basic" />

### Vertical

<ComponentPreview name="separator-vertical" />

### With Content

<ComponentPreview name="separator-with-content" />

## Styling

### Passing Tailwind CSS classes

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

function CustomSeparator() {
  return (
    <Separator className="my-8 bg-gradient-to-r from-transparent via-default-500 to-transparent" />
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .separator {
    @apply bg-accent h-[2px];
  }
  
  .separator--vertical {
    @apply bg-accent w-[2px];
  }
}
```

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

### CSS Classes

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

#### Base & Orientation Classes

* `.separator` - Base separator styles with default horizontal orientation
* `.separator--horizontal` - Horizontal orientation (full width, 1px height)
* `.separator--vertical` - Vertical orientation (full height, 1px width)

## API Reference

### Separator Props

| Prop          | Type                         | Default        | Description                      |
| ------------- | ---------------------------- | -------------- | -------------------------------- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the separator |
| `className`   | `string`                     | -              | Additional CSS classes           |


# HeroUI v3 > components > Skeleton
URL: /docs/components/skeleton
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/skeleton.mdx

Skeleton is a placeholder to show a loading state and the expected shape of a component.
        
***

title: Skeleton
description: Skeleton is a placeholder to show a loading state and the expected shape of a component.
links:
source: skeleton/skeleton.tsx
styles: skeleton.css
storybook: skeleton
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="skeleton-basic" />

### Text Content

<ComponentPreview name="skeleton-text-content" />

### User Profile

<ComponentPreview name="skeleton-user-profile" />

### List Items

<ComponentPreview name="skeleton-list" />

## Styling

### Passing Tailwind CSS classes

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

function CustomSkeleton() {
  return (
    <Skeleton className="h-20 w-32 rounded-full" />
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .skeleton {
    @apply bg-gray-200;
  }
  
  .skeleton:before {
    @apply via-gray-100;
  }
}
```

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

### CSS Classes

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

#### Base Class

`.skeleton` - Base skeleton styles with shimmer animation

### Animation

The shimmer effect is created using a CSS gradient animation that moves across the skeleton element:

```css
.skeleton {
  @apply bg-surface-3 pointer-events-none relative overflow-hidden rounded-md;

  &:before {
    @apply animate-skeleton via-surface-2 absolute inset-0 -translate-x-full bg-gradient-to-r from-transparent to-transparent content-[''];
  }
}

@theme inline {
 --animate-skeleton: skeleton 2s linear infinite;

  @keyframes skeleton {
    100% {
      transform: translateX(200%);
    }
  }
}
```

## API Reference

### Skeleton Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `className` | `string`    | -       | Additional CSS classes |
| `children`  | `ReactNode` | -       | Optional child content |


# HeroUI v3 > components > Spinner
URL: /docs/components/spinner
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/spinner.mdx

A loading indicator component to show pending states
        
***

title: Spinner
description: A loading indicator component to show pending states
links:
source: spinner/spinner.tsx
styles: spinner.css
storybook: spinner
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="spinner-basic" />

### Colors

<ComponentPreview name="spinner-colors" />

### Sizes

<ComponentPreview name="spinner-sizes" />

## Styling

### Passing Tailwind CSS classes

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

function CustomSpinner() {
  return (
    <Spinner className="text-blue-500" />
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .spinner {
    @apply animate-spin;
  }

  .spinner--accent {
    color: var(--accent);
  }
}
```

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

### CSS Classes

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

#### Base & Size Classes

* `.spinner` - Base spinner styles with default size
* `.spinner--sm` - Small size variant
* `.spinner--md` - Medium size variant (default)
* `.spinner--lg` - Large size variant
* `.spinner--xl` - Extra large size variant

#### Color Classes

* `.spinner--current` - Inherits current text color
* `.spinner--accent` - Accent color variant
* `.spinner--danger` - Danger color variant
* `.spinner--success` - Success color variant
* `.spinner--warning` - Warning color variant

## API Reference

### Spinner Props

| Prop        | Type                                                          | Default     | Description                  |
| ----------- | ------------------------------------------------------------- | ----------- | ---------------------------- |
| `size`      | `"sm" \| "md" \| "lg" \| "xl"`                                | `"md"`      | Size of the spinner          |
| `color`     | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Color variant of the spinner |
| `className` | `string`                                                      | -           | Additional CSS classes       |


# HeroUI v3 > components > Tabs
URL: /docs/components/tabs
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/tabs.mdx

Tabs organize content into multiple sections and allow users to navigate between them.
        
***

title: Tabs
description: Tabs organize content into multiple sections and allow users to navigate between them.
links:
rac: Tabs
source: tabs/tabs.tsx
styles: tabs.css
storybook: tabs
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="tabs-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Tabs>
    <Tabs.ListWrapper>
      <Tabs.List aria-label="Options">
        <Tabs.Tab/>
      </Tabs.List>
      <Tabs.Indicator />
    </Tabs.ListWrapper>
    <Tabs.Panel/>
  </Tabs>
)
```

### Vertical

<ComponentPreview name="tabs-vertical" />

### Disabled Tab

<ComponentPreview name="tabs-disabled" />

### Custom Styles

<ComponentPreview name="tabs-custom-styles" />

## Styling

### Passing Tailwind CSS classes

<CollapsibleCode
  lang="tsx"
  code={`
import { Tabs } from '@heroui/react';

function CustomTabs() {
return (
  <Tabs className="w-full max-w-lg text-center">
    <Tabs.ListWrapper>
      <Tabs.List
        aria-label="Options"
        className="*:data-[selected=true]:text-accent-foreground w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal"
      >
        <Tabs.Tab id="daily">Daily</Tabs.Tab>
        <Tabs.Tab id="weekly">Weekly</Tabs.Tab>
        <Tabs.Tab id="bi-weekly">Bi-Weekly</Tabs.Tab>
        <Tabs.Tab id="monthly">Monthly</Tabs.Tab>
      </Tabs.List>
      <Tabs.Indicator className="bg-accent" />
    </Tabs.ListWrapper>
    <Tabs.Panel className="px-4" id="daily">
      <h3 className="mb-2 font-semibold">Daily</h3>
      <p className="text-sm text-gray-600">Manage your daily tasks and goals.</p>
    </Tabs.Panel>
    <Tabs.Panel className="px-4" id="weekly">
      <h3 className="mb-2 font-semibold">Weekly</h3>
      <p className="text-sm text-gray-600">Manage your weekly tasks and goals.</p>
    </Tabs.Panel>
    <Tabs.Panel className="px-4" id="bi-weekly">
      <h3 className="mb-2 font-semibold">Bi-Weekly</h3>
      <p className="text-sm text-gray-600">Manage your bi-weekly tasks and goals.</p>
    </Tabs.Panel>
    <Tabs.Panel className="px-4" id="monthly">
      <h3 className="mb-2 font-semibold">Monthly</h3>
      <p className="text-sm text-gray-600">Manage your monthly tasks and goals.</p>
    </Tabs.Panel>
  </Tabs>
);
}
`}
/>

### CSS Classes

The Tabs component uses these CSS classes:

#### Base Classes

* `.tabs` - Base tabs container
* `.tabs__list-wrapper` - Tab list wrapper
* `.tabs__list` - Tab list container
* `.tabs__tab` - Individual tab button
* `.tabs__panel` - Tab panel content
* `.tabs__indicator` - Tab indicator

#### Orientation Attributes

* `.tabs[data-orientation="horizontal"]` - Horizontal tab layout (default)
* `.tabs[data-orientation="vertical"]` - Vertical tab layout

### Interactive States

The component supports both CSS pseudo-classes and data attributes:

* **Selected**: `[aria-selected="true"]`
* **Hover**: `:hover` or `[data-hover="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `[aria-disabled="true"]`

## API Reference

### Tabs Props

| Prop                 | Type                         | Default        | Description                 |
| -------------------- | ---------------------------- | -------------- | --------------------------- |
| `orientation`        | `"horizontal" \| "vertical"` | `"horizontal"` | Tab layout orientation      |
| `selectedKey`        | `string`                     | -              | Controlled selected tab key |
| `defaultSelectedKey` | `string`                     | -              | Default selected tab key    |
| `onSelectionChange`  | `(key: Key) => void`         | -              | Selection change handler    |
| `className`          | `string`                     | -              | Additional CSS classes      |

### Tabs.List Props

| Prop         | Type     | Default | Description                      |
| ------------ | -------- | ------- | -------------------------------- |
| `aria-label` | `string` | -       | Accessibility label for tab list |
| `className`  | `string` | -       | Additional CSS classes           |

### Tabs.Tab Props

| Prop         | Type      | Default | Description             |
| ------------ | --------- | ------- | ----------------------- |
| `id`         | `string`  | -       | Unique tab identifier   |
| `isDisabled` | `boolean` | `false` | Whether tab is disabled |
| `className`  | `string`  | -       | Additional CSS classes  |

### Tabs.Panel Props

| Prop        | Type     | Default | Description                      |
| ----------- | -------- | ------- | -------------------------------- |
| `id`        | `string` | -       | Panel identifier matching tab id |
| `className` | `string` | -       | Additional CSS classes           |


# HeroUI v3 > components > TextField
URL: /docs/components/text-field
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/text-field.mdx

Text input fields for forms with labels, descriptions, and error messages
        
***

title: TextField
description: Text input fields for forms with labels, descriptions, and error messages
links:
rac: TextField
source: text-field/text-field.tsx
styles: text-field.css
storybook: text-field
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="text-field-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <TextField>
    <TextField.Label>Field label</TextField.Label>
    <TextField.Input placeholder="Enter value" />
    <TextField.Description>
      Helper text for the field
    </TextField.Description>
    <TextField.Error>
      Error message when invalid
    </TextField.Error>
  </TextField>
)
```

### With Description

<ComponentPreview name="text-field-with-description" />

### Required Field

<ComponentPreview name="text-field-required" />

### With Error

<ComponentPreview name="text-field-with-error" />

### Disabled State

<ComponentPreview name="text-field-disabled" />

### TextArea

<ComponentPreview name="text-field-textarea" />

### Input Types

<ComponentPreview name="text-field-input-types" />

## Styling

### Passing Tailwind CSS classes

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

function CustomTextField() {
  return (
    <TextField className="space-y-3">
      <TextField.Label className="text-lg font-bold">
        Custom styled field
      </TextField.Label>
      <TextField.Input
        className="border-2 border-blue-500 focus:border-blue-600"
        placeholder="Custom input"
      />
      <TextField.Description className="text-xs italic">
        With custom styles
      </TextField.Description>
    </TextField>
  );
}
```

### CSS Classes

The TextField component uses these CSS classes:

#### Base Classes

* `.text-field` - Base container styles
* `.text-field__label` - Label element styles
* `.text-field__input` - Input element styles
* `.text-field__textarea` - TextArea element styles
* `.text-field__description` - Description text styles
* `.text-field__error` - Error message styles

#### State Classes

* `.text-field--disabled` - Disabled state styles
* `.text-field--invalid` - Invalid/error state styles
* `.text-field--required` - Required field styles

### Interactive States

The component supports both CSS pseudo-classes and data attributes:

* **Focus**: `:focus` or `[data-focus="true"]`
* **Focus Within**: `:focus-within` or `[data-focus-within="true"]`
* **Invalid**: `:invalid` or `[aria-invalid="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`
* **Required**: `:required` or `[aria-required="true"]`

## Accessibility

#### Keyboard Navigation

* **Tab** - Move focus to the input field
* **Shift + Tab** - Move focus to the previous element
* **Arrow keys** - Navigate within textarea content

#### Screen Reader Support

* Labels are properly associated with input fields
* Required fields are announced
* Error messages are announced when present
* Descriptions provide additional context
* Invalid state is communicated via ARIA attributes

#### Focus Management

* Clear focus indicators on interactive elements
* Focus moves naturally through form fields
* Error messages receive focus when validation fails

## API Reference

### TextField Props

| Prop         | Type      | Default | Description                   |
| ------------ | --------- | ------- | ----------------------------- |
| `isRequired` | `boolean` | `false` | Whether the field is required |
| `isInvalid`  | `boolean` | `false` | Whether the field is invalid  |
| `isDisabled` | `boolean` | `false` | Whether the field is disabled |
| `className`  | `string`  | -       | Additional CSS classes        |

### TextField.Label Props

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |

### TextField.Input Props

| Prop          | Type                      | Default  | Description                              |
| ------------- | ------------------------- | -------- | ---------------------------------------- |
| `type`        | `string`                  | `"text"` | Input type (text, email, password, etc.) |
| `placeholder` | `string`                  | -        | Placeholder text                         |
| `value`       | `string`                  | -        | Input value                              |
| `onChange`    | `(value: string) => void` | -        | Change handler                           |
| `className`   | `string`                  | -        | Additional CSS classes                   |

### TextField.TextArea Props

| Prop          | Type                      | Default | Description                  |
| ------------- | ------------------------- | ------- | ---------------------------- |
| `rows`        | `number`                  | `3`     | Number of visible text lines |
| `placeholder` | `string`                  | -       | Placeholder text             |
| `value`       | `string`                  | -       | TextArea value               |
| `onChange`    | `(value: string) => void` | -       | Change handler               |
| `className`   | `string`                  | -       | Additional CSS classes       |

### TextField.Description Props

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |

### TextField.Error Props

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |


# HeroUI v3 > components > Tooltip
URL: /docs/components/tooltip
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/components/tooltip.mdx

Displays informative text when users hover over or focus on an element
        
***

title: Tooltip
description: Displays informative text when users hover over or focus on an element
links:
rac: Tooltip
source: tooltip/tooltip.tsx
styles: tooltip.css
storybook: tooltip
figma: true
-----------

## Import

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

### Usage

<ComponentPreview name="tooltip-basic" />

### Anatomy

Import all parts and piece them together.

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

export default () => (
  <Tooltip>
    <Tooltip.Trigger>
      <button>Hover for tooltip</button>
    </Tooltip.Trigger>
    <Tooltip.Content>
      <Tooltip.Arrow />
      Helpful information about this element
    </Tooltip.Content>
  </Tooltip>
)
```

### With Arrow

<ComponentPreview name="tooltip-with-arrow" />

### Placement

<ComponentPreview name="tooltip-placement" />

### Custom Triggers

<ComponentPreview name="tooltip-custom-trigger" />

## Styling

### Passing Tailwind CSS classes

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

function CustomTooltip() {
  return (
    <Tooltip>
      <Button>Hover me</Button>
      <Tooltip.Content className="bg-accent text-accent-foreground">
        <p>Custom styled tooltip</p>
      </Tooltip.Content>
    </Tooltip>
  );
}
```

### Customizing the component classes

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

```css
@layer components {
  .tooltip {
    @apply rounded-xl shadow-lg;
  }

  .tooltip__trigger {
    @apply cursor-help;
  }
}
```

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

### CSS Classes

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

#### Base Classes

* `.tooltip` - Base tooltip styles with animations
* `.tooltip__trigger` - Trigger element styles

### Interactive States

The component supports animation states:

* **Entering**: `[data-entering]` - Applied during tooltip appearance
* **Exiting**: `[data-exiting]` - Applied during tooltip disappearance
* **Placement**: `[data-placement="*"]` - Applied based on tooltip position

## API Reference

### Tooltip Props

| Prop         | Type                 | Default   | Description                                  |
| ------------ | -------------------- | --------- | -------------------------------------------- |
| `children`   | `React.ReactNode`    | -         | Trigger element and content                  |
| `delay`      | `number`             | `700`     | Delay in milliseconds before showing tooltip |
| `closeDelay` | `number`             | `0`       | Delay in milliseconds before hiding tooltip  |
| `trigger`    | `"hover" \| "focus"` | `"hover"` | How the tooltip is triggered                 |
| `isDisabled` | `boolean`            | `false`   | Whether the tooltip is disabled              |

### Tooltip.Content Props

| Prop        | Type                                                    | Default            | Description                         |
| ----------- | ------------------------------------------------------- | ------------------ | ----------------------------------- |
| `children`  | `React.ReactNode`                                       | -                  | Content to display in the tooltip   |
| `showArrow` | `boolean`                                               | `false`            | Whether to show the arrow indicator |
| `offset`    | `number`                                                | `3` (7 with arrow) | Distance from the trigger element   |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"top"`            | Placement of the tooltip            |
| `className` | `string`                                                | -                  | Additional CSS classes              |

### Tooltip.Trigger Props

| Prop        | Type              | Default | Description                       |
| ----------- | ----------------- | ------- | --------------------------------- |
| `children`  | `React.ReactNode` | -       | Element that triggers the tooltip |
| `className` | `string`          | -       | Additional CSS classes            |

### Tooltip.Arrow Props

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `children`  | `React.ReactNode` | -       | Custom arrow element   |
| `className` | `string`          | -       | Additional CSS classes |


# HeroUI v3 > handbook > Animation
URL: /docs/handbook/animation
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/handbook/animation.mdx

Add smooth animations and transitions to HeroUI v3 components
        
***

title: Animation
description: Add smooth animations and transitions to HeroUI v3 components
icon: copy-transparent
----------------------

## Overview

HeroUI components are built on React Aria and support multiple animation approaches:

* **Built-in animations** - Components come with default CSS transitions
* **CSS animations** - Customize with Tailwind utilities or custom CSS
* **JavaScript libraries** - Integrate with Framer Motion, React Spring, etc.

## Built-in Animations

HeroUI components use data attributes to expose their state for animation:

```css
/* Popover entrance/exit */
.popover[data-entering] {
  @apply animate-in zoom-in-90 fade-in-0 duration-200;
}

.popover[data-exiting] {
  @apply animate-out zoom-out-95 fade-out duration-150;
}

/* Button press effect */
.button:active,
.button[data-pressed="true"] {
  transform: scale(0.97);
}

/* Accordion expansion */
.accordion__panel[aria-hidden="false"] {
  @apply h-[var(--panel-height)] opacity-100;
}
```

### State Attributes

Components expose these states for styling:

* `[data-hover="true"]` - Hover state
* `[data-pressed="true"]` - Active/pressed state
* `[data-focus-visible="true"]` - Keyboard focus
* `[data-disabled="true"]` - Disabled state
* `[data-entering]` / `[data-exiting]` - Transition states
* `[aria-expanded="true"]` - Expanded state

## CSS Animations

### Using Tailwind Utilities

```tsx
// Pulse on hover
<Button className="hover:animate-pulse">
  Hover me
</Button>

// Fade in entrance
<Alert className="animate-fade-in">
  Welcome message
</Alert>

// Staggered list
<div className="space-y-2">
  <Card className="animate-fade-in animate-delay-100">Item 1</Card>
  <Card className="animate-fade-in animate-delay-200">Item 2</Card>
</div>
```

### Custom Transitions

Override default component animations:

```css
/* Slower accordion */
.accordion__panel {
  @apply transition-all duration-500;
}

/* Bouncy button */
.button:active {
  animation: bounce 0.3s;
}

@keyframes bounce {
  50% { transform: scale(0.95); }
}
```

## Framer Motion

HeroUI components work seamlessly with Framer Motion for advanced animations.

### Basic Usage

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

const MotionButton = motion(Button);

<MotionButton
  whileHover={{ scale: 1.05 }}
  whileTap={{ scale: 0.95 }}
>
  Animated Button
</MotionButton>
```

### Entrance Animations

```tsx
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  <Alert>
    <Alert.Title>Welcome!</Alert.Title>
  </Alert>
</motion.div>
```

### Layout Animations

```tsx
import { AnimatePresence, motion } from 'framer-motion';

function Tabs({ items, selected }) {
  return (
    <div className="flex gap-2">
      {items.map((item, i) => (
        <Button key={i} onPress={() => setSelected(i)}>
          {item}
          {selected === i && (
            <motion.div
              layoutId="active"
              className="absolute inset-0 bg-accent"
              transition={{ type: "spring", bounce: 0.2 }}
            />
          )}
        </Button>
      ))}
    </div>
  );
}
```

## Render Props

Use render props to apply dynamic animations based on component state:

```tsx
<Button>
  {({ isPressed, isHovered }) => (
    <motion.span
      animate={{
        scale: isPressed ? 0.95 : isHovered ? 1.05 : 1
      }}
    >
      Interactive Button
    </motion.span>
  )}
</Button>
```

## Accessibility

### Respecting Motion Preferences

Always respect user motion preferences:

```css
@media (prefers-reduced-motion: reduce) {
  .button {
    transition: none;
  }

  .animate-* {
    animation: none !important;
  }
}
```

With Framer Motion:

```tsx
import { useReducedMotion } from 'framer-motion';

function AnimatedCard() {
  const shouldReduceMotion = useReducedMotion();

  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      transition={{ duration: shouldReduceMotion ? 0 : 0.5 }}
    >
      <Card>Content</Card>
    </motion.div>
  );
}
```

## Performance Tips

### Use GPU-Accelerated Properties

Prefer `transform` and `opacity` for smooth animations:

```css
/* Good - GPU accelerated */
.slide-in {
  transform: translateX(-100%);
  transition: transform 0.3s;
}

/* Avoid - Triggers layout */
.slide-in {
  left: -100%;
  transition: left 0.3s;
}
```

### Will-Change Optimization

```css
.button {
  will-change: transform;
}

.button:not(:hover) {
  will-change: auto;
}
```

## Next Steps

* Learn about [Styling](/docs/handbook/styling) approaches
* Explore [Component](/docs/components) examples
* View [Theming](/docs/handbook/theming) documentation


# HeroUI v3 > handbook > Colors
URL: /docs/handbook/colors
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/handbook/colors.mdx

Color palette and theming system for HeroUI v3
        
***

title: Colors
description: Color palette and theming system for HeroUI v3
icon: bucket-paint
links:
themes: true
tailwind: theme
---------------

import {ColorSwatch, ColorPalette} from "@/components/color-swatch";

HeroUI uses CSS variables for colors that automatically switch between light and dark themes. All colors use the `oklch` color space for better color transitions.

## How It Works

HeroUI's color system is built on top of Tailwind CSS v4's theme. When you import `@heroui/styles`, it uses Tailwind's built-in color palettes (like `--color-neutral-*`) and maps them to semantic variables.

Add a theme class to your HTML and apply colors to the body:

```html
<html class="light" data-theme="light">
  <body class="bg-background text-foreground">
    <!-- Your app -->
  </body>
</html>
```

We follow a simple naming pattern:

* Colors without a suffix are backgrounds (e.g., `--accent`)
* Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)

```tsx
// This gives you the right background and text colors
<div className="bg-accent text-accent-foreground">Hello</div>
```

## Available Colors

### Base Colors

These four colors stay the same in all themes:

<div className="flex flex-wrap gap-4 sm:gap-6">
  <ColorSwatch name="White" variable="--white" />

  <ColorSwatch name="Black" variable="--black" />

  <ColorSwatch name="Snow" variable="--snow" />

  <ColorSwatch name="Eclipse" variable="--eclipse" />
</div>

### Background & Surface

<ColorPalette
  colors={[
  { name: "Background", variable: "--background", foreground: "--foreground" },
  { name: "Foreground", variable: "--foreground" },
  { name: "Panel", variable: "--panel", foreground: "--panel-foreground" },
  { name: "Panel Foreground", variable: "--panel-foreground" },
  { name: "Surface 1", variable: "--surface-1", foreground: "--foreground" },
  { name: "Surface 2", variable: "--surface-2", foreground: "--foreground" },
  { name: "Surface 3", variable: "--surface-3", foreground: "--foreground" },
]}
/>

### Primary Colors

* **Accent**: Your main brand color (used for primary actions)
* **Accent Soft**: A lighter version for secondary actions

<ColorPalette
  colors={[
  { name: "Accent", variable: "--accent", foreground: "--accent-foreground" },
  { name: "Accent Foreground", variable: "--accent-foreground" },
  { name: "Accent Soft", variable: "--accent-soft", foreground: "--accent-soft-foreground" },
  { name: "Accent Soft Foreground", variable: "--accent-soft-foreground" },
]}
/>

### Status Colors

For alerts, validation, and status messages:

<ColorPalette
  colors={[
  { name: "Success", variable: "--success", foreground: "--success-foreground" },
  { name: "Success Foreground", variable: "--success-foreground" },
  { name: "Warning", variable: "--warning", foreground: "--warning-foreground" },
  { name: "Warning Foreground", variable: "--warning-foreground" },
  { name: "Danger", variable: "--danger", foreground: "--danger-foreground" },
  { name: "Danger Foreground", variable: "--danger-foreground" },
]}
/>

### Other Colors

<ColorPalette
  colors={[
  { name: "Default", variable: "--default", foreground: "--default-foreground" },
  { name: "Default Foreground", variable: "--default-foreground" },
  { name: "Muted", variable: "--muted", foreground: "--foreground" },
  { name: "Border", variable: "--border" },
  { name: "Focus", variable: "--focus" },
  { name: "Link", variable: "--link" },
  { name: "Scrollbar", variable: "--scrollbar" },
]}
/>

## How to Use Colors

### In Your Components

```jsx
// Use Tailwind classes
<div className="bg-background text-foreground">
  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
    Click me
  </button>
</div>
```

### In CSS Files

```css title="global.css"
/* Direct CSS variables */
.my-component {
  background: var(--accent);
  color: var(--accent-foreground);
  border: 1px solid var(--border);
}

/* With @apply and @layer */
@layer components {
  .button {
    @apply bg-accent text-accent-foreground;

    &:hover,
    &[data-hover="true"] {
      @apply bg-accent-hover;
    }

    &:active,
    &[data-pressed="true"] {
      @apply bg-accent-hover;
      transform: scale(0.97);
    }
  }
}
```

## Default Theme

The complete theme definition can be found in ([default.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/index.css)). This theme automatically switches between light and dark modes based on the `class="dark"` or `data-theme="dark"` attributes.

<CollapsibleCode
  lang="css"
  code={`@layer base {
  /* HeroUI Default Theme */
  :root {
    color-scheme: light;

    /* Primitive Colors (Do not change between light and dark) */
    --white: oklch(100% 0 0);
    --black: oklch(0% 0 0);
    --snow: oklch(0.9911 0 0);
    --eclipse: oklch(0.2221 0 0);

    /* Spacing scale */
    --spacing: 0.25rem;

    /* Border */
    --border-width: 1px;
    --disabled-opacity: 0.5;

    /* Panel specific radius */
    --radius-panel: 0.5rem;
    --radius-panel-inner: calc(var(--radius-panel) * 0.5);

    /* Typography */
    --font-size-base: 1rem;
    --font-size-scale-desktop: 0.875;
    --font-weight-medium: 500;
    --font-weight-semibold: 600;

    /* Cursor */
    --cursor-interactive: pointer;
    --cursor-disabled: not-allowed;

    /* Base Colors */
    --background: var(--white);
    --foreground: var(--eclipse);
    --panel: var(--white);
    --panel-foreground: var(--foreground);

    --radius: 0.75rem;

    --muted: var(--color-neutral-500);

    --scrollbar: var(--color-neutral-300);

    --default: var(--color-white);
    --default-foreground: var(--color-neutral-600);

    --surface-1: var(--background);
    --surface-2: var(--color-neutral-100);
    --surface-3: var(--color-neutral-200);

    --accent: var(--color-neutral-950);
    --accent-foreground: var(--snow);

    --accent-soft: var(--color-neutral-200);
    --accent-soft-foreground: var(--color-neutral-900);

    /* Status Colors */
    --success: oklch(0.5503 0.1244 153.56);
    --success-foreground: var(--snow);

    --warning: oklch(0.7186 0.1521 64.85);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.6259 0.1908 29.19);
    --danger-foreground: var(--snow);

    /* Misc Colors */
    --border: oklch(0 0 0 / 15%);
    --focus: oklch(0% 0 0 / 20%);
    --link: var(--foreground);

    /* Shadow */
    --shadow-border:
      0 0px 5px 0px rgba(0, 0, 0, 0.02), 0 2px 10px 0px rgba(0, 0, 0, 0.06),
      0 0px 1px 0px rgba(0, 0, 0, 0.3);
  }

  .dark,
  [data-theme="dark"] {
    color-scheme: dark;

    /* Base Colors */
    --background: var(--black);
    --foreground: var(--snow);
    --panel: var(--eclipse);

    --muted: var(--color-neutral-400);

    --scrollbar: var(--color-neutral-800);

    --default: var(--color-neutral-900);
    --default-foreground: var(--color-neutral-200);

    --surface-1: var(--background);
    --surface-2: var(--color-neutral-900);
    --surface-3: var(--color-neutral-800);

    --accent: var(--color-neutral-50);
    --accent-foreground: var(--eclipse);

    --accent-soft: var(--color-neutral-800);
    --accent-soft-foreground: var(--color-neutral-200);

    /* Status Colors */
    --success: oklch(80% 0.1561 154);
    --success-foreground: var(--eclipse);

    --warning: oklch(85% 0.1414 77.88);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.5798 0.1635 30.83);
    --danger-foreground: var(--snow);

    /* Misc Colors */
    --border: oklch(1 0 0 / 12%);
    --focus: oklch(100% 0 0 / 50%);
    --link: var(--foreground);

    /* Shadow */
    --shadow-border:
      0 0 0 1px var(--border), 0 5px 10px -3px rgba(0, 0, 0, 0.3), 0 3px 4px -2px rgba(0, 0, 0, 0.1);
  }
}
`}
/>

> **Note**: Colors like `--color-neutral-*`, `--color-white`, and `--color-black` come from [Tailwind CSS v4's built-in theme](https://tailwindcss.com/docs/colors).

## Customizing Colors

### Add Your Own Colors

```css
:root, 
[data-theme="light"] {
  --info: oklch(0.6 0.15 210);
  --info-foreground: oklch(0.98 0 0);
}

.dark,
[data-theme="dark"] {
  --info: oklch(0.7 0.12 210);
  --info-foreground: oklch(0.15 0 0);
}

/* Make the color available to Tailwind */
@theme inline {
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}
```

Now you can use it:

```tsx
<div className="bg-info text-info-foreground">Info message</div>
```

> **Note**: To learn more about theme variables and how they work in Tailwind CSS v4, see the [Tailwind CSS Theme documentation](https://tailwindcss.com/docs/theme).

### Override Existing Colors

```css
:root {
  /* Override default colors */
  --accent: oklch(0.7 0.15 250);
  --success: oklch(0.65 0.15 155);
}

[data-theme="dark"] {
  /* Override dark theme colors */
  --accent: oklch(0.8 0.12 250);
  --success: oklch(0.75 0.12 155);
}
```

**Tip**: Convert colors at [oklch.com](https://oklch.com)

## Quick Tips

* Always use color variables, not hard-coded values
* Use foreground/background pairs for good contrast
* Test in both light and dark modes
* The system respects user's theme preference automatically

## Related

* [Theming](/docs/handbook/theming) - Learn about the theming system
* [Styling](/docs/handbook/styling) - Styling components with CSS
* [Design Principles](/docs/design-principles) - Understanding HeroUI's design philosophy


# HeroUI v3 > handbook > Composition
URL: /docs/handbook/composition
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/handbook/composition.mdx

Build flexible UI with component composition patterns
        
***

title: Composition
description: Build flexible UI with component composition patterns
icon: layers
------------

## Overview

HeroUI uses composition patterns to create flexible, customizable components. This allows you to:

* Change the rendered element or component
* Compose components together
* Maintain full control over markup

## The asChild Prop

The `asChild` prop lets you change what element a component renders. When `asChild` is true, HeroUI won't render its default element - instead, it clones the child element and merges props.

### Basic Usage

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

// Renders as a Next.js Link
<Button asChild>
  <Link href="/about">About</Link>
</Button>

// Renders as a regular anchor
<Button asChild>
  <a href="https://example.com">External Link</a>
</Button>
```

### Available Components

These components support `asChild`:

* `Button` - Change button element
* `Alert` parts - Root, Icon, Content, Title, Description, Action, Close
* `Avatar` - Change root element
* More components coming soon

## Compound Components

HeroUI components are built as compound components - they export multiple parts that work together:

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

<Alert>
  <Alert.Icon />
  <Alert.Content>
    <Alert.Title>Success</Alert.Title>
    <Alert.Description>Your changes have been saved.</Alert.Description>
  </Alert.Content>
  <Alert.Close />
</Alert>
```

This pattern provides:

* **Flexibility** - Arrange parts as needed
* **Customization** - Style each part independently
* **Control** - Add or remove parts

## Style Variants

HeroUI exports variant functions that can be applied to any component. This allows you to use HeroUI's design system with any element or component:

### Using buttonVariants

Apply button styles to any component:

```tsx
import { Link, buttonVariants } from '@heroui/react';

// Link styled as a tertiary button
<Link
  className={buttonVariants({
    size: "md",
    variant: "tertiary",
    className: "px-3"
  })}
  href="https://heroui.com"
  target="_blank"
>
  HeroUI
  <Link.Icon className="h-2 w-2" />
</Link>

// Native anchor styled as primary button
<a
  className={buttonVariants({ variant: "primary" })}
  href="/dashboard"
>
  Go to Dashboard
</a>
```

### Available Variant Functions

Each component exports its variant function:

* `buttonVariants` - Button styles
* `chipVariants` - Chip styles
* `linkVariants` - Link styles
* `spinnerVariants` - Spinner styles
* More variant functions for each component

## Custom Components

Create your own components by composing HeroUI primitives:

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

// Link button component
function LinkButton({ href, children, ...props }) {
  return (
    <Button asChild {...props}>
      <a href={href}>{children}</a>
    </Button>
  );
}

// Icon button with tooltip
function IconButton({ icon, label, ...props }) {
  return (
    <Tooltip content={label}>
      <Button isIconOnly {...props}>
        <Icon icon={icon} />
      </Button>
    </Tooltip>
  );
}
```

## Custom Variants

You can create your own custom variants by extending the component's variant function.

```tsx
import type {ButtonProps} from "@heroui/react";
import type {VariantProps} from "tailwind-variants";

import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";

const myButtonVariants = tv({
  extend: buttonVariants,
  base: "text-md text-shadow-lg font-semibold shadow-md data-[pending=true]:opacity-40",
  variants: {
    radius: {
      lg: "rounded-lg",
      md: "rounded-md",
      sm: "rounded-sm",
      full: "rounded-full",
    },
    size: {
      sm: "h-10 px-4",
      md: "h-11 px-6",
      lg: "h-12 px-8",
      xl: "h-13 px-10",
    },
    variant: {
      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
    },
  },
  defaultVariants: {
    radius: "full",
    variant: "primary",
  },
});

type MyButtonVariants = VariantProps<typeof myButtonVariants>;
export type MyButtonProps = Omit<ButtonProps, "className"> &
  MyButtonVariants & {className?: string};

function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
  return <Button className={myButtonVariants({className, radius, variant})} {...props} />;
}

export function CustomVariants() {
  return <CustomButton>Custom Button</CustomButton>;
}
```

## With Next.js

Use `asChild` to integrate with Next.js:

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

<Button asChild variant="primary">
  <Link href="/dashboard">Dashboard</Link>
</Button>
```

## With React Router

Use `asChild` to integrate with routing libraries:

```tsx
import { Link } from 'react-router-dom';
import { Button } from '@heroui/react';

<Button asChild variant="primary">
  <Link to="/dashboard">Dashboard</Link>
</Button>
```

## Next Steps

* Learn about [Styling](/docs/handbook/styling) components
* Explore [Animation](/docs/handbook/animation) options
* Browse [Components](/docs/components) for more examples


# HeroUI v3 > handbook > Styling
URL: /docs/handbook/styling
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/handbook/styling.mdx

Style HeroUI components with CSS, Tailwind, or CSS-in-JS
        
***

title: Styling
description: Style HeroUI components with CSS, Tailwind, or CSS-in-JS
icon: brush
links:
themes: true
tailwind: theme
---------------

## Overview

HeroUI components are built on React Aria and provide flexible styling options:

* **Tailwind CSS** - Use utility classes directly
* **CSS** - Target BEM classes or data attributes
* **CSS-in-JS** - Integrate with styled-components, Emotion, etc.
* **Render props** - Dynamic styling based on component state

## Basic Styling

### Using className

All HeroUI components accept `className` props:

```tsx
<Button className="bg-purple-500 hover:bg-purple-600">
  Custom Button
</Button>

<Accordion className="border-2 border-gray-200 rounded-xl">
  {/* content */}
</Accordion>
```

### Using style

Components also accept inline styles:

```tsx
<Button style={{ backgroundColor: '#8B5CF6' }}>
  Styled Button
</Button>
```

## State-Based Styling

HeroUI components expose their state through data attributes, similar to CSS pseudo-classes:

```css
/* Target different states */
.button[data-hover="true"], .button:hover {
  background: var(--accent-hover);
}

.button[data-pressed="true"], .button:active {
  transform: scale(0.97);
}

.button[data-focus-visible="true"], .button:focus-visible {
  outline: 2px solid var(--focus);
}
```

## Render Props

Use render props for dynamic styling based on component state:

```tsx
// Dynamic classes
<Button
  className={({ isPressed }) =>
    isPressed ? 'bg-blue-600' : 'bg-blue-500'
  }
>
  Press me
</Button>

// Dynamic content
<Button>
  {({ isHovered, isPressed }) => (
    <>
      <Icon
        icon="gravity-ui:heart"
        className={isPressed ? 'text-red-500' : 'text-neutral-400'}
      />
      <span className={isHovered ? 'underline' : ''}>
        Like
      </span>
    </>
  )}
</Button>
```

## BEM Classes

HeroUI uses [BEM methodology](https://getbem.com/) for consistent class naming:

```css
/* Block */
.button { }
.accordion { }

/* Element */
.accordion__trigger { }
.accordion__panel { }

/* Modifier */
.button--primary { }
.button--lg { }
.accordion--outline { }
```

### Customizing Components Globally

```css
/* global.css */

@layer components {
  /* Override button styles */
  .button {
    @apply font-semibold uppercase;
  }

  .button--primary {
    @apply bg-indigo-600 hover:bg-indigo-700;
  }

  /* Add custom variant */
  .button--gradient {
    @apply bg-gradient-to-r from-purple-500 to-pink-500;
  }
}
```

## Creating Wrapper Components

For reusable custom components, create wrappers using [tailwind-variants](https://tailwind-variants.org/) - a Tailwind CSS first-class variant API created by us as well:

```tsx
import { Button as HeroButton, buttonVariants, type ButtonProps } from '@heroui/react';
import { tv, type VariantProps } from 'tailwind-variants';

const customButtonVariants = tv({
  extend: buttonVariants,
  base: 'font-medium transition-all',
  variants: {
    intent: {
      primary: 'bg-blue-500 hover:bg-blue-600 text-white',
      secondary: 'bg-gray-200 hover:bg-gray-300',
      danger: 'bg-red-500 hover:bg-red-600 text-white',
    },
    size: {
      small: 'text-sm px-2 py-1',
      medium: 'text-base px-4 py-2',
      large: 'text-lg px-6 py-3',
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'medium',
  },
});

type CustomButtonVariants = VariantProps<typeof customButtonVariants>;
interface CustomButtonProps
  extends Omit<ButtonProps, 'className'>,
  CustomButtonVariants {
  className?: string;
}

export function CustomButton({ intent, size, className, ...props }: CustomButtonProps) {
  return (
    <HeroButton
      className={customButtonVariants({ intent, size, className })}
      {...props}
    />
  );
}
```

## CSS-in-JS Integration

### Styled Components

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

const StyledButton = styled(Button)`
  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
  border-radius: 8px;
  color: white;
  padding: 12px 24px;

  &:hover {
    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
  }
`;
```

### Emotion

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

const buttonStyles = css`
  background: linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%);
  border-radius: 8px;
  color: white;
  padding: 12px 24px;

  &:hover {
    box-shadow: 0 3px 10px rgba(255, 105, 135, 0.3);
  }
`;

<Button className={buttonStyles}>
  Emotion Button
</Button>
```

## Responsive Design

Use Tailwind's responsive utilities:

```tsx
<Button className="text-sm md:text-base lg:text-lg px-3 md:px-4 lg:px-6">
  Responsive Button
</Button>
```

Or with CSS:

```css
.button {
  font-size: 0.875rem;
  padding: 0.5rem 1rem;
}

@media (min-width: 768px) {
  .button {
    font-size: 1rem;
    padding: 0.75rem 1.5rem;
  }
}
```

## CSS Modules

For scoped styles, use CSS Modules:

```css
/* Button.module.css */
.button {
  background: linear-gradient(135deg, #667eea, #764ba2);
  color: white;
  padding: 12px 24px;
  border-radius: 8px;
}

.button:hover {
  transform: translateY(-2px);
}

.button--primary {
  background: linear-gradient(135deg, #667eea, #764ba2);
  color: white;
  padding: 12px 24px;
  border-radius: 8px;
}
```

```tsx
import styles from './Button.module.css';
import { Button } from '@heroui/react';

<Button className={styles.button}>
  Scoped Button
</Button>
```

## Component Classes Reference

### Button

* `.button` - Base
* `.button--{variant}` - Variants
* `.button--{size}` - Sizes
* `.button--icon-only` - Icon button

> **Note**: See [Button](/docs/components/button#css-classes) for more information on button classes.

### Accordion

* `.accordion` - Container
* `.accordion__item` - Item
* `.accordion__trigger` - Header
* `.accordion__panel` - Content
* `.accordion--outline` - Variant

> **Note**: See [Accordion](/docs/components/accordion#css-classes) for more information on accordion classes.

View all component classes in [@heroui/styles/components](https://github.com/heroui-inc/heroui/tree/main/packages/styles/components).

## Next Steps

* Learn about [Animation](/docs/handbook/animation) techniques
* Explore [Theming](/docs/handbook/theming) system
* Browse [Component](/docs/components) examples


# HeroUI v3 > handbook > Theming
URL: /docs/handbook/theming
Source: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/handbook/theming.mdx

Customize HeroUI's design system with CSS variables and global styles
        
***

title: Theming
description: Customize HeroUI's design system with CSS variables and global styles
icon: palette
links:
themes: true
tailwind: theme
---------------

## Overview

HeroUI uses CSS variables and [BEM](https://getbem.com/) classes for theming. You can customize everything from colors to component styles using standard CSS.

## How It Works

HeroUI's theming system is built on top of [Tailwind CSS v4](https://tailwindcss.com/docs/theme)'s theme. When you import `@heroui/styles`, it:

1. Uses Tailwind's built-in color palettes (like `--color-neutral-*`)
2. Maps them to semantic variables for easier use
3. Automatically switches between light and dark themes
4. Uses CSS layers and the `@theme` directive for organization

The system follows a simple naming pattern:

* Colors without a suffix are backgrounds (e.g., `--accent`)
* Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)

## Quick Start

### Apply a Theme

Add a theme class to your HTML and apply colors to the body:

```html
<html class="light" data-theme="light">
  <body class="bg-background text-foreground">
    <!-- Your app -->
  </body>
</html>
```

### Switch Themes

```html
<!-- Light theme -->
<html class="light" data-theme="light">

<!-- Dark theme -->
<html class="dark" data-theme="dark">
```

### Override Colors

```css
/* app/globals.css */
@import "tailwindcss";
@import "@heroui/styles";

:root {
  /* Override any color variable */
  --accent: oklch(0.7 0.25 260);
  --success: oklch(0.65 0.15 155);
}
```

> **Note**: See [Colors](/docs/handbook/colors) for the complete color palette and visual reference.

### Create your own theme

<CollapsibleCode
  lang="css"
  code={`/* src/themes/ocean.css */
@layer base {
  /* Ocean Light */
  [data-theme="ocean"] {
    color-scheme: light;

    /* Base */
    --background: oklch(0.985 0.015 225);
    --foreground: var(--eclipse);
    --panel: var(--white);
    --panel-foreground: var(--foreground);

    --radius: 0.75rem;

    --muted: var(--color-neutral-500);
    --scrollbar: var(--color-neutral-300);

    --default: var(--color-white);
    --default-foreground: var(--color-neutral-600);

    --surface-1: var(--background);
    --surface-2: oklch(0.965 0.020 225);
    --surface-3: oklch(0.930 0.030 225);

    /* Ocean accent */
    --accent: oklch(0.450 0.150 230);
    --accent-foreground: var(--snow);

    --accent-soft: oklch(0.920 0.040 230);
    --accent-soft-foreground: oklch(0.280 0.080 230);

    /* Status (kept compatible) */
    --success: oklch(0.5503 0.1244 153.56);
    --success-foreground: var(--snow);

    --warning: oklch(0.7186 0.1521 64.85);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.6259 0.1908 29.19);
    --danger-foreground: var(--snow);

    /* Component Colors */
    --segment: var(--white);
    --segment-foreground: var(--foreground);

    /* Misc */
    --border: oklch(0.50 0.060 230 / 22%);
    --divider: var(--color-neutral-200);
    --focus: oklch(0.60 0.150 230 / 35%);
    --link: var(--accent);

    --shadow-border:
      0 0px 5px 0px rgba(0, 10, 40, 0.03),
      0 2px 10px 0px rgba(0, 10, 40, 0.07),
      0 0px 1px 0px rgba(0, 0, 0, 0.25);
  }

  /* Ocean Dark */
  [data-theme="ocean-dark"] {
    color-scheme: dark;

    /* Base */
    --background: oklch(0.140 0.020 230);
    --foreground: var(--snow);
    --panel: oklch(0.180 0.020 230);

    --muted: var(--color-neutral-400);
    --scrollbar: var(--color-neutral-800);

    --default: var(--color-neutral-900);
    --default-foreground: var(--color-neutral-200);

    --surface-1: var(--background);
    --surface-2: oklch(0.220 0.030 230);
    --surface-3: oklch(0.280 0.030 230);

    /* Ocean accent */
    --accent: oklch(0.860 0.080 230);
    --accent-foreground: var(--eclipse);

    --accent-soft: oklch(0.300 0.050 230);
    --accent-soft-foreground: var(--color-neutral-200);

    /* Status */
    --success: oklch(80% 0.1561 154);
    --success-foreground: var(--eclipse);

    --warning: oklch(85% 0.1414 77.88);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.5798 0.1635 30.83);
    --danger-foreground: var(--snow);

    /* Component Colors */
    --segment: oklch(1 0 0 / 16%);
    --segment-foreground: var(--foreground);

    /* Misc */
    --border: oklch(1 0 0 / 12%);
    --divider: var(--color-neutral-800);
    --focus: oklch(0.860 0.080 230 / 40%);
    --link: var(--accent);

    --shadow-border:
      0 0 0 1px var(--border),
      0 5px 10px -3px rgba(0, 10, 40, 0.35),
      0 3px 4px -2px rgba(0, 0, 0, 0.12);
  }
}
`}
/>

Use your theme:

```css
/* app/globals.css */
@layer theme, base, components, utilities;

@import "tailwindcss";
@import "@heroui/styles";

@import "./src/themes/ocean.css" layer(theme); /* [!code highlight]*/
```

Apply your theme:

```html
<!-- index.html -->

<!-- Light ocean -->
<html data-theme="ocean">

<!-- Dark ocean -->
<html data-theme="ocean-dark">
```

## Customize Components

### Global Component Styles

Override any component using BEM classes:

```css
@layer components {
  /* Customize buttons */
  .button {
    @apply font-semibold tracking-wide;
  }

  .button--primary {
    @apply bg-blue-600 hover:bg-blue-700;
  }

  /* Customize accordions */
  .accordion__trigger {
    @apply text-lg font-bold;
  }
}
```

> **Note**: See [Styling](/docs/handbook/styling) for the complete styling reference.

### Find Component Classes

Each component docs page lists all available classes:

* **Base classes**: `.button`, `.accordion`
* **Modifiers**: `.button--primary`, `.button--icon-only`
* **Elements**: `.accordion__trigger`, `.accordion__panel`
* **States**: `[data-hover="true"]`, `[aria-expanded="true"]`

Example: [Button classes](/docs/components/button#css-classes)

## Import Strategies

### Full Import (Recommended)

Get everything with two lines:

```css
@import "tailwindcss";
@import "@heroui/styles";
```

### Selective Import

Import only what you need:

```css
/* Define layers */
@layer theme, base, components, utilities;

/* Base requirements */
@import "tailwindcss";
@import "@heroui/styles/base/base.css" layer(base);
@import "@heroui/styles/themes/theme.css" layer(theme);
@import "@heroui/styles/themes/default.css" layer(theme);

/* Components (all components) */
@import "@heroui/styles/components/index.css" layer(components);
/* OR specific components */
@import "@heroui/styles/components/button.css" layer(components);
@import "@heroui/styles/components/accordion.css" layer(components);
```

### Headless Mode

Build your own styles from scratch:

```css
@import "tailwindcss";
@import "@heroui/styles/base/base.css";

/* Your custom styles */
.button {
  /* Your button styles */
}
```

## Adding Custom Colors

You can add your own semantic colors to the theme:

```css
/* Define in both light and dark themes */
:root, 
[data-theme="light"] {
  --info: oklch(0.6 0.15 210);
  --info-foreground: oklch(0.98 0 0);
}

.dark,
[data-theme="dark"] {
  --info: oklch(0.7 0.12 210);
  --info-foreground: oklch(0.15 0 0);
}

/* Make the color available to Tailwind */
@theme inline {
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}
```

Now use it in your components:

```tsx
<div className="bg-info text-info-foreground">Info message</div>
```

## Variables Reference

HeroUI defines three types of variables:

1. **Base Variables**: Non-changing values like `--white`, `--black`, spacing, and typography
2. **Theme Variables**: Colors that change between light/dark themes
3. **Calculated Variables**: Automatically generated hover states and size variants

For a complete reference of all variables and their values, see:

* [Colors Documentation](/docs/handbook/colors) - Visual color palette and base variables
* [Default Theme Source](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/index.css) - Complete theme implementation

### Calculated Variables (Tailwind)

We use Tailwind's `@theme` directive to automatically create calculated variables for hover states and radius variants:

<CollapsibleCode
  lang="css"
  code={`@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-panel: var(--panel);
--color-panel-foreground: var(--panel-foreground);

--color-muted: var(--muted);

--color-surface: var(--surface-1);
--color-surface-foreground: var(--foreground);

--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);

--color-accent-soft: var(--accent-soft);
--color-accent-soft-foreground: var(--accent-soft-foreground);

--color-segment: var(--segment);
--color-segment-foreground: var(--segment-foreground);

--color-border: var(--border);
--color-divider: var(--divider);
--color-focus: var(--focus);
--color-link: var(--link);

--color-default: var(--default);
--color-default-foreground: var(--default-foreground);

--color-success: var(--success);
--color-success-foreground: var(--success-foreground);

--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);

--color-danger: var(--danger);
--color-danger-foreground: var(--danger-foreground);

--shadow-border: var(--shadow-border);

/* Calculated Variables */

/* Colors */
--color-panel-hover: color-mix(
  in oklab,
  var(--color-panel) 90%,
  var(--color-panel-foreground) 5%
);
--color-default-hover: color-mix(
  in oklab,
  var(--color-default) 90%,
  var(--color-default-foreground) 5%
);
--color-accent-hover: color-mix(
  in oklab,
  var(--color-accent) 90%,
  var(--color-accent-foreground) 20%
);
--color-accent-soft-hover: color-mix(
  in oklab,
  var(--color-accent-soft) 10%,
  var(--color-accent-soft-foreground) 18%
);
--color-success-hover: color-mix(
  in oklab,
  var(--color-success) 90%,
  var(--color-success-foreground) 10%
);
--color-warning-hover: color-mix(
  in oklab,
  var(--color-warning) 90%,
  var(--color-warning-foreground) 10%
);
--color-danger-hover: color-mix(
  in oklab,
  var(--color-danger) 90%,
  var(--color-danger-foreground) 10%
);

/* Surface Colors */
--color-surface-1: var(--surface-1);
--color-surface-1-foreground: color-mix(
  in oklab,
  var(--color-surface-1) 80%,
  var(--color-foreground) 3.5%
);
--color-surface-2: var(--surface-2);
--color-surface-2-foreground: color-mix(
  in oklab,
  var(--color-surface-2) 80%,
  var(--color-foreground) 3.5%
);
--color-surface-3: var(--surface-3);
--color-surface-3-foreground: color-mix(
  in oklab,
  var(--color-surface-3) 80%,
  var(--color-foreground) 3.5%
);

/* Radius */
--radius-xs: calc(var(--radius) * 0.25);
--radius-sm: calc(var(--radius) * 0.5);
--radius-md: calc(var(--radius) * 0.75);
--radius-lg: calc(var(--radius) * 1);
--radius-xl: calc(var(--radius) * 1.5);
--radius-2xl: calc(var(--radius) * 2);
--radius-3xl: calc(var(--radius) * 3);
--radius-4xl: calc(var(--radius) * 4);
--radius-panel: var(--radius);
--radius-panel-inner: calc(var(--radius) * 0.5);

/* Transition Timing Functions  */
--ease-smooth: ease; /* same as transition: ease; */

/* From smoother to faster quad->circ @made by https://twitter.com/bdc */
--ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
--ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
--ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
--ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
--ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
--ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);

--ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
--ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
--ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
--ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
--ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
--ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);

--ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
--ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
--ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
--ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
--ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
--ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);

/* Animations */
--animate-spin-fast: spin 0.75s linear infinite;
--animate-skeleton: skeleton 2s linear infinite;
}
`}
/>

## Resources

* [Colors Documentation](/docs/handbook/colors)
* [Styling Guide](/docs/handbook/styling)
* [Tailwind CSS v4 Theming](https://tailwindcss.com/docs/theme)
* [BEM Methodology](https://getbem.com/)
* [OKLCH Color Tool](https://oklch.com)