# All Components
**Category**: react
**URL**: https://www.heroui.com/docs/react/components
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/index.mdx
> Explore the full list of components available in the library. More are on the way.
## Buttons
## Collections
## Colors
## Controls
## Data Display
## Date and Time
## Feedback
## Forms
## Layout
## Media
## Navigation
## Overlays
## Pickers
## Typography
## Utilities
# Introduction
**Category**: react
**URL**: https://www.heroui.com/docs/react/getting-started
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/getting-started/index.mdx
> An open-source UI component library for building beautiful and accessible user interfaces.
HeroUI is a React component library built on [Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/index.html). Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.
## Why HeroUI?
**Beautiful by default** — Professional look out of the box, no extra styling needed.
**Accessible** — Built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html) with focus management, keyboard navigation, and screen reader support.
**Flexible** — Each component is made of customizable parts. Change what you need, leave the rest.
**Developer-friendly** — Fully typed APIs, predictable patterns, and excellent autocompletion.
**Maintained** — We handle updates, bug fixes, and new features. Just update the package.
**Lightweight** — Tree-shaken. Only what you use goes into your app.
**Future-proof** — Built for [React 19](https://react.dev/blog/2024/12/05/react-19) and [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4), designed for AI-assisted development.
## A Living Library, Not Copy-Paste
Copy-paste code works until it breaks. You're left maintaining outdated dependencies that stop evolving.
HeroUI is different. It's a living library that grows with you:
* Automatic updates and fixes
* New features without extra work
* Components stay current with React, Tailwind, and browsers
* Deep customization, not shallow theme tweaks
* AI-friendly APIs for code generation
HeroUI v3 is not a snapshot—it's a garden that keeps growing. 🌱
## HeroUI Ecosystem
* **🌐 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 apps with natural language
* **🧠 UI for LLMs** — New platform & MCPs coming soon
**Why React Aria?** We chose React Aria for accessibility at scale. We've used it since HeroUI v2, and v3 keeps familiar API conventions like `isDisabled` and `onPress`. Thanks to [Devon Govett](https://x.com/devongovett) and the Adobe team.
## FAQ
**Is HeroUI free?**
Yes, completely free and open source under the MIT license.
**Is it production-ready?**
Yes. HeroUI v3 is stable and ready for production use.
**Can I customize the components?**
Yes! Use Tailwind utilities, CSS variables, [BEM](https://getbem.com/) 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! Access our design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429).
## Get Involved
Join the community, share feedback, or contribute:
* [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
* [Discord](https://discord.gg/9b6yyZKmH4)
* [X/Twitter](https://x.com/hero_ui)
* [Contributing Guidelines](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md)
HeroUI is released under the [MIT License](https://github.com/heroui-inc/heroui/blob/main/LICENSE).
# Migration (for AI assistants)
**Category**: react
**URL**: https://www.heroui.com/docs/react/migration/agent-index
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/agent-index.mdx
> Entry point for AI assistants helping migrate HeroUI v2 to v3
For AI assistants: use this as the entry point when helping migrate HeroUI v2 → v3.
## Entry
Choose a migration strategy:
* **Full migration** (project will be broken during migration) → read `(workflows)/agent-guide-full.mdx`.
* **Incremental** (v2 and v3 coexist) → read `(workflows)/agent-guide-incremental.mdx`.
## Reference in this bundle
* **Cross-cutting guides:** `hooks.mdx`, `styling.mdx`.
* The workflow guides above already inline the "major changes", "key API changes", component reference table, and "new components" sections.
* **Per-component guides:** `(components)/.mdx` (e.g. `(components)/button.mdx`, `(components)/select.mdx`). Use the component reference table in the workflow guides to find the right file.
# Hooks
**Category**: react
**URL**: https://www.heroui.com/docs/react/migration/hooks
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/hooks.mdx
> Migration guide for HeroUI hooks from v2 to v3
Refer to the [v3 component documentation](/docs/components-list) for complete API reference. This guide focuses on migrating hooks from HeroUI v2.
## Overview
HeroUI v3 removes most component hooks that existed in v2, replacing them with compound components and a new hook for overlay state management. This guide covers:
* Component hooks removal (useSwitch, useInput, useCheckbox, etc.)
* useDisclosure → useOverlayState migration
* Migration strategies and examples
## Component Hooks Removal
HeroUI v2 provided component hooks (like `useSwitch`, `useInput`, `useCheckbox`, etc.) that returned prop getters (`getBaseProps`, `getWrapperProps`, `getThumbProps`, etc.) to customize component structure when users couldn't directly modify inner child components. HeroUI v3 solves this with compound components, eliminating the need for hooks.
### Why Hooks Existed in v2
In v2, components had fixed internal structures. To customize these structures, users needed to use hooks that provided prop getters. For example, `useSwitch` returned `getBaseProps()`, `getWrapperProps()`, `getThumbProps()`, etc., which users could spread onto custom elements to build their own Switch structure.
### v3 Solution: Compound Components
v3 uses compound component patterns that give you direct access to component parts. Instead of using hooks with prop getters, you compose components directly using subcomponents like `Switch.Control`, `Switch.Thumb`, `Checkbox.Control`, `Checkbox.Indicator`, etc.
### Migration Strategy
1. **Identify hook usage**: Search your codebase for imports from `@heroui/react` that include hook names (`useSwitch`, `useInput`, `useCheckbox`, `useRadio`, etc.)
2. **Replace with compound components**: Instead of using hooks with prop getters, use the compound component pattern
3. **Preserve original structure**: When migrating, try to keep the same component structure you had with hooks. For example:
* If you used `useSwitch` to create a switch **without** a thumb, don't add `Switch.Thumb` in v3
* If you used `useCheckbox` to create a checkbox **without** an indicator, don't add `Checkbox.Indicator` in v3
* Only include the subcomponents that were actually used in your hook-based implementation
4. **Reference component guides**: Check individual component migration guides for specific examples
### Key Differences
* **v2**: Hooks provided prop getters to customize fixed component structures
* **v3**: Compound components allow direct composition of component parts
### Preserving Structure Example
**v2: Switch without thumb**
```tsx
import { useSwitch } from "@heroui/react";
function CustomSwitch() {
const { getBaseProps } = useSwitch();
return (
{/* No thumb element */}
);
}
```
**v3: Equivalent structure**
```tsx
import { Switch } from "@heroui/react";
function CustomSwitch() {
return (
{/* No Switch.Thumb - preserving the original structure */}
);
}
```
For detailed migration examples for specific components, see the individual component migration guides.
## useDisclosure → useOverlayState
The `useDisclosure` hook from v2 has been replaced with `useOverlayState` in v3. This hook manages open/close state for modals, popovers, and other overlay components.
### v2: useDisclosure
**API:**
```tsx
const {isOpen, onOpen, onClose, onOpenChange, isControlled, getButtonProps, getDisclosureProps} = useDisclosure({
isOpen?: boolean;
defaultOpen?: boolean;
onClose?(): void;
onOpen?(): void;
onChange?(isOpen: boolean | undefined): void;
id?: string;
});
```
**Example:**
```tsx
import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@heroui/react";
export default function App() {
const {isOpen, onOpen, onOpenChange} = useDisclosure();
return (
<>
TitleContent
);
}
```
### v3: useOverlayState
**API:**
```tsx
const state = useOverlayState({
isOpen?: boolean;
defaultOpen?: boolean;
onOpenChange?: (isOpen: boolean) => void;
});
// Returns:
// {
// isOpen: boolean;
// open(): void;
// close(): void;
// toggle(): void;
// setOpen(isOpen: boolean): void;
// }
```
**Example:**
```tsx
import { Modal, Button, useOverlayState } from "@heroui/react";
export default function App() {
const state = useOverlayState();
return (
{({close}) => (
<>
TitleContent
)}
);
}
```
### Migration Guide
#### Basic Migration
**v2:**
```tsx
const {isOpen, onOpen, onClose, onOpenChange} = useDisclosure();
```
**v3:**
```tsx
const state = useOverlayState();
// Use state.open(), state.close(), state.toggle(), state.setOpen(boolean)
```
#### Controlled State
**v2:**
```tsx
const {isOpen, onOpenChange} = useDisclosure({
isOpen: controlledIsOpen,
onChange: (isOpen) => setControlledIsOpen(isOpen)
});
```
**v3:**
```tsx
const state = useOverlayState({
isOpen: controlledIsOpen,
onOpenChange: setControlledIsOpen
});
```
#### Uncontrolled State
**v2:**
```tsx
const {isOpen, onOpen, onClose} = useDisclosure({
defaultOpen: false
});
```
**v3:**
```tsx
const state = useOverlayState({
defaultOpen: false
});
// Use state.open(), state.close(), state.toggle()
```
### API Differences
| v2 (useDisclosure) | v3 (useOverlayState) | Notes |
| ---------------------- | -------------------- | --------------------------------- |
| `isOpen` | `isOpen` | Same |
| `onOpen()` | `open()` | Renamed method |
| `onClose()` | `close()` | Renamed method |
| `onOpenChange()` | `toggle()` | New method for toggling |
| `onOpenChange` (prop) | `setOpen(boolean)` | Different API |
| `isControlled` | - | Removed (handled internally) |
| `getButtonProps()` | - | Removed (use compound components) |
| `getDisclosureProps()` | - | Removed (use compound components) |
### Benefits of useOverlayState
* **Cleaner API**: Dedicated methods (`open()`, `close()`, `toggle()`) instead of callbacks
* **Simpler state management**: Works seamlessly with both controlled and uncontrolled patterns
* **Better TypeScript support**: Improved type inference and autocomplete
* **Consistent with React Aria**: Aligns with React Aria Components patterns
### Alternative: useState
For simple cases, you can also use React's `useState` directly:
```tsx
import { useState } from "react";
import { Modal, Button } from "@heroui/react";
export default function App() {
const [isOpen, setIsOpen] = useState(false);
return (
{/* content */}
);
}
```
However, `useOverlayState` provides a cleaner API with dedicated methods for common operations.
## Removed Hooks
The following hooks from v2 have been removed in v3:
* **useDraggable**: Removed
* **useClipboard**: Removed
* **usePagination**: Removed
* **useToast**: Removed
## Summary
* **Component hooks** (`useSwitch`, `useInput`, etc.) → Use **compound components** instead
* **useDisclosure** → Use **useOverlayState** for overlay state management
* **useOverlayState** provides a cleaner API with `open()`, `close()`, `toggle()`, and `setOpen()` methods
* **Removed hooks**: `useDraggable`, `useClipboard`, `usePagination`, `useToast` are no longer available
* For simple cases, `useState` can be used directly, but `useOverlayState` offers better ergonomics
For component-specific hook migration examples, refer to the individual component migration guides.
# Migration
**Category**: react
**URL**: https://www.heroui.com/docs/react/migration
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/index.mdx
> Complete guide to migrate your HeroUI v2 application to v3
## For AI Assistants
Below are three approaches for AI assistants to access migration documentation. ***We recommend using the HeroUI Migration MCP server*** and leveraging its prompts and tools, but all options provide agents with the complete documentation.
| Feature | MCP Server | Agent Skills | AGENTS.md |
| ----------------- | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------- |
| **Data source** | Remote endpoints | Remote endpoints | Local files |
| **Access method** | MCP tools | Script files | Local file reads |
| **Setup** | MCP config | Install command | `heroui-cli` command |
| **Updates** | Real-time | Real-time | Manual |
| **Offline** | ❌ | ❌ | ✅ |
| **Tools** | MCP tools + prompts | Scripts | ❌ |
| **Guide** | [MCP Server →](/docs/react/migration/mcp-server) | [Agent Skills →](/docs/react/migration/agent-skills) | [AGENTS.md →](/docs/react/migration/agents-md) |
## Major Changes
* **Dependencies**: Update React to v19+, HeroUI packages to v3, Tailwind CSS to v4, remove Framer Motion
* **No Provider Required**: v3 removes the need for `HeroUIProvider`
* **Component API Updates**: Many components use React Aria Components patterns
* **Compound Components**: New compound component patterns for better customization. See individual component guides for details.
* **Hooks Removed**: v2 component hooks like `useSwitch` or `useInput` are removed - use compound components instead. `useDisclosure` is replaced with `useOverlayState`. See the [Hooks Migration Guide](/docs/react/migration/hooks) for details.
* **Configuration**: Remove `heroui()` plugin from Tailwind config, update CSS imports, remove `hero.ts` file
* **Item identity**: Collection items (Dropdown, Listbox, Select, Accordion, etc.) now use `id` and `textValue` in v3; keep React's `key` for lists.
### Item identity and accessibility (key, id, textValue)
In v2, collection components (Dropdown, Listbox, Select, Accordion, etc.) used **React's `key`** as the item identity. The same value drove both React's list reconciliation and the component's selection/expand state. In v3, which uses React Aria Components, those roles are split:
* **`id`** — v3 uses an explicit **`id`** prop on each item for selection state, focus, and callbacks (e.g. `selectedKeys`, `expandedKeys`, `onSelectionChange`). Use the same (or equivalent) value you used for `key` in v2 so that state and callbacks continue to refer to the correct item.
* **`textValue`** — v3 requires **`textValue`** on items when the visible content is not plain text (e.g. when using `Label`, icons, or `Description`). It is used for screen reader announcements and type-ahead.
* **`key`** — **Keep using React's `key`** on list items. It is still required for React's reconciliation and is independent of `id`.
When migrating: add `id` (and `textValue` where needed) for v3's API, but keep `key` for React.
## Migration Strategies
HeroUI v2 and v3 cannot coexist in the same project without special setup. You have two migration approaches to choose from:
### Full Migration
**Best for:** Projects that can dedicate focused time to complete migration in one go.
**How it works:**
* Migrate all component code first (project will be broken during this phase)
* Switch dependencies to v3
* Complete styling migration
**Advantages:**
* Simpler setup - no complex coexistence configuration
* Cleaner transition - only one version active at a time
* Supported by Migration MCP prompts
**Disadvantages:**
* Project is broken during migration
* All components should be migrated before switching dependencies
**Get started:** [Full Migration Guide](/docs/react/migration/full-migration)
### Incremental Migration
**Best for:** Projects that need to stay functional during migration, teams migrating gradually over time, large codebases migrating feature-by-feature.
**How it works:**
* Set up coexistence using pnpm aliases or component packages
* Migrate components one-by-one while keeping project functional
* Complete migration and remove v2 dependencies
**Advantages:**
* Project remains functional during migration
* Can migrate gradually over time
* Can test v3 components alongside v2
**Disadvantages:**
* More complex initial setup
* Potential styling conflicts
* Requires managing two versions simultaneously
**Get started:** [Incremental Migration Guide](/docs/react/migration/incremental-migration)
## Component Migration Reference
Use the table below to quickly find migration guidance for each component. Use the link in the "Migration Guide" column to jump to detailed migration instructions.
**Component Development Status**: Components marked with 🔄 In Progress or 📋 Planned are still being developed. Check the [Roadmap](https://herouiv3.featurebase.app/roadmap) for the task status. Guides for these components will be available once development is finished.
| v2 Component | v3 Component | Status | Migration Guide |
| ---------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------- |
| Accordion | Accordion | ✅ Available | [View guide →](/docs/react/migration/accordion) |
| Alert | Alert | ✅ Available | [View guide →](/docs/react/migration/alert) |
| Autocomplete | ComboBox | ✅ Renamed | [View guide →](/docs/react/migration/autocomplete) |
| Avatar | Avatar | ✅ Available | [View guide →](/docs/react/migration/avatar) |
| Badge | Badge | ✅ Available | [View guide →](/docs/react/migration/badge) |
| Breadcrumbs | Breadcrumbs | ✅ Available | [View guide →](/docs/react/migration/breadcrumbs) |
| Button | Button | ✅ Available | [View guide →](/docs/react/migration/button) |
| ButtonGroup | ButtonGroup | ✅ Available | [View guide →](/docs/react/migration/button-group) |
| Calendar | Calendar | ✅ Available | [View guide →](/docs/react/migration/calendar) |
| Card | Card | ✅ Available | [View guide →](/docs/react/migration/card) |
| Checkbox | Checkbox | ✅ Available | [View guide →](/docs/react/migration/checkbox) |
| CheckboxGroup | CheckboxGroup | ✅ Available | [View guide →](/docs/react/migration/checkbox-group) |
| Chip | Chip | ✅ Available | [View guide →](/docs/react/migration/chip) |
| Code | ❌ | ❌ Removed | [View guide →](/docs/react/migration/code) |
| DateInput | DateField | ✅ Renamed | [View guide →](/docs/react/migration/dateinput) |
| DatePicker | DatePicker | ✅ Available | [View guide →](/docs/react/migration/date-picker) |
| DateRangePicker | DateRangePicker | ✅ Available | [View guide →](/docs/react/migration/date-range-picker) |
| TimeInput | TimeField | ✅ Renamed | [View guide →](/docs/react/migration/timeinput) |
| Divider | Separator | ✅ Renamed | [View guide →](/docs/react/migration/divider) |
| Drawer | Drawer | ✅ Available | [View guide →](/docs/react/migration/drawer) |
| Dropdown | Dropdown | ✅ Available | [View guide →](/docs/react/migration/dropdown) |
| Form | Form | ✅ Available | [View guide →](/docs/react/migration/form) |
| Image | ❌ | ❌ Removed | [View guide →](/docs/react/migration/image) |
| Input | TextField, Input, InputGroup | ✅ Available | [View guide →](/docs/react/migration/input) |
| InputOTP | InputOTP | ✅ Available | [View guide →](/docs/react/migration/input-otp) |
| Kbd | Kbd | ✅ Available | [View guide →](/docs/react/migration/kbd) |
| Link | Link | ✅ Available | [View guide →](/docs/react/migration/link) |
| Listbox | ListBox | ✅ Available | [View guide →](/docs/react/migration/listbox) |
| Modal | Modal | ✅ Available | [View guide →](/docs/react/migration/modal) |
| Navbar | ❌ | ❌ Removed | [View guide →](/docs/react/migration/navbar) |
| NumberInput | NumberField | ✅ Renamed | [View guide →](/docs/react/migration/numberinput) |
| Pagination | Pagination | ✅ Available | [View guide →](/docs/react/migration/pagination) |
| Popover | Popover | ✅ Available | [View guide →](/docs/react/migration/popover) |
| Progress | ProgressBar | ✅ Renamed | [View guide →](/docs/react/migration/progress) |
| CircularProgress | ProgressCircle | ✅ Renamed | [View guide →](/docs/react/migration/circular-progress) |
| Radio | Radio | ✅ Available | [View guide →](/docs/react/migration/radio) |
| RadioGroup | RadioGroup | ✅ Available | [View guide →](/docs/react/migration/radio-group) |
| RangeCalendar | RangeCalendar | ✅ Available | [View guide →](/docs/react/migration/range-calendar) |
| Ripple | ❌ | ❌ Removed | [See Button ripple →](/docs/react/components/button#adding-ripple-effect) |
| ScrollShadow | ScrollShadow | ✅ Available | [View guide →](/docs/react/migration/scroll-shadow) |
| Select | Select | ✅ Available | [View guide →](/docs/react/migration/select) |
| Skeleton | Skeleton | ✅ Available | [View guide →](/docs/react/migration/skeleton) |
| Slider | Slider | ✅ Available | [View guide →](/docs/react/migration/slider) |
| Snippet | ❌ | ❌ Removed | [View guide →](/docs/react/migration/snippet) |
| Spacer | ❌ | ❌ Removed | [View guide →](/docs/react/migration/spacer) |
| Spinner | Spinner | ✅ Available | [View guide →](/docs/react/migration/spinner) |
| Switch | Switch | ✅ Available | [View guide →](/docs/react/migration/switch) |
| Table | Table | ✅ Available | [View guide →](/docs/react/migration/table) |
| Tabs | Tabs | ✅ Available | [View guide →](/docs/react/migration/tabs) |
| Toast | Toast | ✅ Available | [View guide →](/docs/react/migration/toast) |
| Tooltip | Tooltip | ✅ Available | [View guide →](/docs/react/migration/tooltip) |
| User | ❌ | ❌ Removed | [View guide →](/docs/react/migration/user) |
## New Components in v3
v3 introduces a number of new components not available in v2:
| Component | Purpose | Documentation |
| --------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| TextField | Enhanced text input with label and description support | [View docs →](/docs/react/components/text-field) |
| TextArea | Multi-line text input component | [View docs →](/docs/react/components/text-area) |
| AlertDialog | Modal dialog for confirmations and alerts | [View docs →](/docs/react/components/alert-dialog) |
| Label | Accessible form label component | [View docs →](/docs/react/components/label) |
| Description | Helper text for form fields | [View docs →](/docs/react/components/description) |
| FieldError | Form field error message display | [View docs →](/docs/react/components/field-error) |
| Fieldset | Group related form fields | [View docs →](/docs/react/components/fieldset) |
| InputGroup | Compose multiple inputs together | [View docs →](/docs/react/components/input-group) |
| Surface | Container component with elevation styles | [View docs →](/docs/react/components/surface) |
| Disclosure | Expandable/collapsible content sections | [View docs →](/docs/react/components/disclosure) |
| DisclosureGroup | Compound component for multiple disclosure sections | [View docs →](/docs/react/components/disclosure-group) |
| SearchField | Search input with clear button and optional loading state | [View docs →](/docs/react/components/search-field) |
| DateField | Date input with calendar picker | [View docs →](/docs/react/components/date-field) |
| TimeField | Time input component | [View docs →](/docs/react/components/time-field) |
| Tag, TagGroup | Tags and tag group for selection or display | [View docs →](/docs/react/components/tag-group) |
| ColorPicker | Color selection (ColorArea, ColorField, ColorSlider, ColorSwatch, ColorSwatchPicker) | [View docs →](/docs/react/components/color-picker) |
| CloseButton | Dismiss or close trigger button | [View docs →](/docs/react/components/close-button) |
| ErrorMessage | Form field error display (React Aria integration) | [View docs →](/docs/react/components/error-message) |
## Additional Migration Guides
* **[Hooks Migration Guide](/docs/react/migration/hooks)**: Detailed guide for migrating hooks from v2 to v3
* **[Styling Migration Guide](/docs/react/migration/styling)**: Comprehensive guide for updating utility classes, color tokens, and component styling
## Getting Help
If you encounter issues during migration:
1. Check the [v3 documentation](/docs/react)
2. Review component-specific migration guides
3. Check the [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions)
4. Join the [Discord community](https://discord.gg/9b6yyZKmH4)
# Styling & Theming
**Category**: react
**URL**: https://www.heroui.com/docs/react/migration/styling
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/styling.mdx
> Complete guide to styling changes and theming system migration from HeroUI v2 to v3
This guide covers all styling-related changes between HeroUI v2 and v3, including utility classes, component styles, theme system architecture, and visual differences. For component-specific API changes, see individual component migration guides.
**Note:** The `classNames` prop has been replaced with `className` prop in v3. All components now use the standard React `className` prop instead of the `classNames` object prop from v2.
## Overview
HeroUI v3 introduces significant changes to the styling system:
* **CSS-First Architecture**: Replaces Tailwind plugin with pure CSS files
* **Standard Tailwind Utilities**: Custom utilities replaced with standard Tailwind classes
* **CSS Variables**: New CSS variable naming and structure
* **Component Styles**: Updated default sizes, spacing, and visual appearance
* **No Plugin Required**: Removed dependency on Tailwind plugin configuration
* **Color System Overhaul**: Semantic colors reorganized (`primary` → `accent`, `secondary` removed, numbered scales removed)
* **Content Colors Removed**: `content1-4` replaced with `surface` and `overlay` system
## Quick Reference
### Utility Classes Mapping
| v2 Utility | v3 Equivalent | Notes |
| ---------------------------- | ---------------------------- | ----------------------------------------------- |
| `text-tiny` | `text-xs` | Font size: 0.75rem → 0.75rem (same) |
| `text-small` | `text-sm` | Font size: 0.875rem → 0.875rem (same) |
| `text-medium` | `text-base` | Font size: 1rem → 1rem (same) |
| `text-large` | `text-lg` | Font size: 1.125rem → 1.125rem (same) |
| `rounded-small` | `rounded-sm` | Border radius: 8px → 4px (different) |
| `rounded-medium` | `rounded-md` | Border radius: 12px → 6px (different) |
| `rounded-large` | `rounded-lg` | Border radius: 14px → 8px (different) |
| `border-small` | `border` | Border width: 1px → 1px (use standard Tailwind) |
| `border-medium` | `border-2` | Border width: 2px → 2px (use standard Tailwind) |
| `border-large` | `border-[3px]` | Border width: 3px → 3px (use arbitrary value) |
| `bg-content1` | `bg-surface` or `bg-overlay` | Content color removed, use surface/overlay |
| `bg-content2` | `bg-surface-secondary` | Content color removed, use surface level |
| `bg-primary` | `bg-accent` | Primary renamed to accent |
| `bg-secondary` | `bg-default` | Secondary color removed, use default |
| `bg-primary-50` | `bg-accent-soft` | Numbered scales removed |
| `bg-primary-100` | `bg-accent-soft` | Numbered scales removed |
| `text-primary-600` | `text-accent` | Numbered scales removed |
| `.transition-background` | Standard CSS transitions | Removed utility |
| `.transition-colors-opacity` | Standard CSS transitions | Removed utility |
## Utility Classes Migration
### Text Utilities
HeroUI v2 provided custom text size utilities that mapped to CSS variables. v3 uses standard Tailwind text size classes.
**v2 Text Utilities:**
```tsx
// v2 - Custom utilities with CSS variables
Tiny text
Small text
Medium text
Large text
```
**v3 Text Utilities:**
```tsx
// v3 - Standard Tailwind classes
```
**Mapping:**
| v2 Class | Width | v3 Class | Width |
| --------------- | ----- | -------------- | --------------- |
| `border-small` | 1px | `border` | 1px |
| `border-medium` | 2px | `border-2` | 2px |
| `border-large` | 3px | `border-[3px]` | 3px (arbitrary) |
### Transition Utilities
v2 provided custom transition utilities for common animation patterns with a default duration of 250ms. v3 removes these utilities in favor of standard Tailwind `transition-*` utilities, where you specify which properties to transition.
**v2 Transition Utilities:**
v2 provided custom transition utilities with a default duration of 250ms and `ease` timing function. The following table shows which CSS properties each utility transitions:
| v2 Utility | Transition Properties |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `.transition-background` | `background` |
| `.transition-colors-opacity` | `color, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
| `.transition-width` | `width` |
| `.transition-height` | `height` |
| `.transition-size` | `width, height` |
| `.transition-left` | `left` |
| `.transition-transform-opacity` | `transform, scale, opacity rotate` |
| `.transition-transform-background` | `transform, scale, background` |
| `.transition-transform-colors` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke` |
| `.transition-transform-colors-opacity` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
**Note:** These utilities are no longer available in v3. Use Tailwind's standard `transition-*` utilities to specify which properties to transition.
### Other Utilities
**Scrollbar Utilities:**
v2 provided `.scrollbar-hide` and `.scrollbar-default` utilities. These are not included in v3 by default, but you can use Tailwind's scrollbar plugin or custom CSS.
**Animation Utilities:**
v2 provided spinner animation utilities (`.spinner-bar-animation`, `.spinner-dot-animation`, etc.). These are handled internally by v3 components and are not exposed as utilities.
**Custom Utilities:**
v2 included utilities like:
* `.leading-inherit` → Use `leading-[inherit]`
* `.tap-highlight-transparent` → Use `[-webkit-tap-highlight-color:transparent]`
* `.input-search-cancel-button-none` → Use custom CSS if needed
## Theme System Architecture
### v2: Plugin-Based System
v2 used a Tailwind CSS plugin that:
1. **Generated Utilities**: Created custom utility classes via JavaScript
2. **CSS Variables**: Injected CSS variables through the plugin
3. **Theme Configuration**: Required configuration in `tailwind.config.js`
4. **Runtime Generation**: Utilities generated at build time
**v2 Configuration:**
```js
// tailwind.config.js
const {heroui} = require("@heroui/react");
module.exports = {
plugins: [
heroui({
layout: {
fontSize: {
tiny: "0.75rem",
small: "0.875rem",
medium: "1rem",
large: "1.125rem",
},
radius: {
small: "8px",
medium: "12px",
large: "14px",
},
},
themes: {
light: {
colors: {
primary: {
// color definitions
},
},
},
},
}),
],
};
```
### v3: CSS-First System
v3 uses a pure CSS approach:
1. **CSS Files**: Styles defined in CSS files (`packages/styles/`)
2. **CSS Variables**: Variables defined in CSS, not generated
3. **No Plugin**: No Tailwind plugin required
4. **Import-Based**: Styles imported via CSS imports
**v3 Configuration:**
```css
/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";
```
**No Tailwind Config Required:**
If you only use HeroUI, you can remove `tailwind.config.js` entirely. If you have custom Tailwind config, keep it but remove the HeroUI plugin.
### Architecture Comparison
| Aspect | v2 | v3 |
| ---------------------- | ---------------------------- | ---------------------- |
| **Styling Method** | Tailwind plugin (JavaScript) | CSS files |
| **Utility Generation** | Runtime via plugin | Pre-defined CSS |
| **CSS Variables** | Generated by plugin | Defined in CSS |
| **Configuration** | `tailwind.config.js` | CSS imports |
| **Customization** | Plugin config | CSS variable overrides |
| **Build Dependency** | Requires plugin | No plugin needed |
## CSS Variables & Design Tokens
### Variable Naming Changes
v2 used the pattern `--heroui-{property}-{scale}` while v3 uses `--{property}` or `--color-{property}`.
**v2 CSS Variables:**
```css
--heroui-font-size-tiny: 0.75rem;
--heroui-font-size-small: 0.875rem;
--heroui-radius-small: 8px;
--heroui-radius-medium: 12px;
--heroui-border-width-medium: 2px;
--heroui-disabled-opacity: 0.5;
```
**v3 CSS Variables:**
```css
/* Typography - handled by Tailwind */
/* No custom font-size variables */
/* 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);
/* Colors */
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-accent: var(--accent);
--color-muted: var(--muted);
/* Opacity */
--disabled-opacity: 0.5;
```
### Color System Changes
**v2 Color Structure:**
```css
--heroui-primary: 210 100% 50%;
--heroui-primary-50: 210 100% 95%;
--heroui-primary-100: 210 100% 90%;
/* ... more shades ... */
```
**v3 Color Structure:**
```css
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
```
**Key Differences:**
1. **Color Format**: v2 used HSL, v3 uses OKLCH
2. **Naming**: v2 used numbered shades (50-900), v3 uses semantic names
3. **Calculated Colors**: v3 uses `color-mix()` for hover states
4. **Foreground Colors**: v3 explicitly defines foreground colors
5. **Primary → Accent**: `primary` color renamed to `accent`
6. **Secondary Color Removed**: `secondary` semantic color removed (was purple in v2)
7. **Numbered Scales Removed**: Color scales like `primary-50`, `primary-100`, etc. no longer exist
### Primary → Accent Rename
v2 used `primary` as the main brand color. v3 renamed it to `accent` for better semantic clarity.
**v2 Primary Color:**
```tsx
// v2 - Primary color with numbered scales
Primary background
Light primary
Lighter primary
Primary text
```
**v3 Accent Color:**
```tsx
// v3 - Accent color (no numbered scales)
Accent background
Soft accent
Accent text
```
**Migration:**
| v2 Class | v3 Equivalent | Notes |
| ------------------ | ---------------- | -------------------- |
| `bg-primary` | `bg-accent` | Base accent color |
| `text-primary` | `text-accent` | Accent text color |
| `bg-primary-50` | `bg-accent-soft` | Light accent variant |
| `bg-primary-100` | `bg-accent-soft` | Light accent variant |
| `bg-primary-500` | `bg-accent` | Base accent color |
| `text-primary-600` | `text-accent` | Accent text color |
| `border-primary` | `border-accent` | Accent border |
**Note:** v3 doesn't have numbered color scales (`-50`, `-100`, `-200`, etc.). Use semantic variants like `-soft`, `-hover`, or custom Tailwind classes.
### Secondary Color Removed
v2 provided a `secondary` semantic color (purple). This has been removed in v3. Component variants named "secondary" now use different colors.
**v2 Secondary Color:**
```tsx
// v2 - Secondary as a semantic color (purple)
Secondary background
Light secondary
Secondary text
```
**v3 Secondary Variant:**
```tsx
// v3 - Secondary is a variant, not a color
Default background (used by secondary variant)
Accent text
```
**Migration:**
| v2 Class | v3 Equivalent | Notes |
| ------------------ | --------------- | ------------------------------------ |
| `bg-secondary` | `bg-default` | Secondary variant uses default color |
| `text-secondary` | `text-accent` | Use accent for emphasis |
| `bg-secondary-50` | `bg-default` | Use default color |
| `border-secondary` | `border-accent` | Use accent border |
**Note:** In v3, "secondary" refers to a component variant style (like `button--secondary`), not a color token. The secondary variant typically uses `bg-default` and `text-accent`.
### Numbered Color Scales Removed
v2 provided numbered color scales (50-900) for all semantic colors. v3 removed these in favor of semantic variants and calculated colors.
**v2 Numbered Scales:**
```tsx
// v2 - Numbered color scales
```
**Migration:**
* **Light shades** (`-50`, `-100`, `-200`): Use `-soft` variants or custom Tailwind opacity classes
* **Base color** (`-500`): Use base color name (`bg-accent`, `bg-danger`, etc.)
* **Dark shades** (`-600`, `-700`, `-800`, `-900`): Use hover variants or custom Tailwind classes
### Content Colors Removed
v2 provided `content1`, `content2`, `content3`, and `content4` colors for layered backgrounds. These have been removed in v3 and replaced with semantic surface colors.
**v2 Content Colors:**
```tsx
// v2 - Content colors for layered backgrounds
```
**Migration Mapping:**
| v2 Class | v3 Equivalent | Usage |
| ------------- | ----------------------- | ------------------------------------------------ |
| `bg-content1` | `bg-surface` | Non-overlay components (cards, accordions) |
| `bg-content1` | `bg-overlay` | Floating components (tooltips, popovers, modals) |
| `bg-content2` | `bg-surface-secondary` | Secondary surface level |
| `bg-content3` | `bg-surface-tertiary` | Tertiary surface level |
| `bg-content4` | `bg-surface-quaternary` | Quaternary surface level |
**Key Changes:**
1. **Semantic Naming**: `content1-4` replaced with `surface` and `overlay` for clearer semantics
2. **Component-Specific**: Use `bg-surface` for page-level components, `bg-overlay` for floating components
3. **Auto-Calculated**: Surface levels (`secondary`, `tertiary`, `quaternary`) are automatically calculated from the base `surface` color using `color-mix()`
### Spacing & Layout Tokens
**v2 Layout Tokens:**
```css
--heroui-divider-weight: 1px;
--heroui-disabled-opacity: 0.5;
--heroui-hover-opacity: 0.8;
```
**v3 Layout Tokens:**
```css
--border-width: 0px;
--field-border-width: var(--border-width);
--disabled-opacity: 0.5;
--cursor-interactive: pointer;
--cursor-disabled: not-allowed;
--radius: 0.5rem;
--field-radius: calc(var(--radius) * 1.5);
```
### Shadow Tokens
**v2 Shadows:**
```css
--heroui-box-shadow-small: 0px 0px 5px 0px rgb(0 0 0 / 0.02), ...;
--heroui-box-shadow-medium: 0px 0px 15px 0px rgb(0 0 0 / 0.03), ...;
--heroui-box-shadow-large: 0px 0px 30px 0px rgb(0 0 0 / 0.04), ...;
```
**v3 Shadows:**
```css
--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), ...;
--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
```
**Key Changes:**
1. **Semantic Naming**: v3 uses semantic names (`surface-shadow`, `overlay-shadow`) instead of size-based names
2. **Component-Specific**: Shadows are tied to component types (surface, overlay, field)
3. **Dark Mode**: Dark mode shadows are transparent in v3
## Visual Differences
### Alignment Changes
**Button Alignment:**
* v2: Icons and text aligned with `items-center justify-center`
* v3: Same alignment, but with responsive height adjustments
**Input Alignment:**
* v2: Text aligned with `text-left`
* v3: Same alignment, but padding adjustments may affect visual balance
### Spacing Changes
**Component Padding:**
Most components have increased padding in v3:
* **Card**: 12px → 16px
* **Button**: Similar padding, but responsive heights
* **Input**: Added vertical padding (`py-2`)
**Gap Spacing:**
v3 uses more consistent gap spacing:
* **Card**: `gap-3` between header, content, footer
* **Button**: `gap-2` between icon and text
* **Chip**: `gap-1.5` between elements
### Size Changes
**Button Heights:**
* **Small**: 32px → 36px (mobile) / 32px (desktop)
* **Medium**: 40px → 40px (mobile) / 36px (desktop)
* **Large**: 48px → 44px (mobile) / 40px (desktop)
**Input Heights:**
* **Medium**: 40px → 36px (default, only size available)
### Border Radius Changes
**Default Radius:**
* v2: Components used `rounded-medium` (12px) by default
* v3: Components use larger radius values:
* Button: `rounded-3xl` (24px)
* Card: `rounded-3xl` (24px)
* Chip: `rounded-2xl` (16px)
* Input: `rounded-field` (typically 12-16px)
### Color Appearance Changes
**Color System:**
* v2: HSL color format
* v3: OKLCH color format (more perceptually uniform)
**Default Colors:**
* v2: `primary`, `secondary`, `success`, `warning`, `danger`
* v3: `accent` (replaces `primary`), `success`, `warning`, `danger`
**Muted Colors:**
* v2: `foreground-400`, `foreground-500` for muted text
* v3: `muted` color token for muted text
## Migration Examples
### Utility Class Migration
**Example: Text Utilities**
```tsx
Title
Description
Helper
```
```tsx
Title
Description
Helper
```
### Border Radius Migration
**Example: Matching v2 Radius Values**
```tsx
Content
```
```tsx
{/* Option 1: Use standard Tailwind (smaller radius) */}
Content
{/* Option 2: Match exact v2 value (12px) */}
Content
```
### Theme Customization Migration
**Example: Custom Colors**
```js
// tailwind.config.js
const {heroui} = require("@heroui/react");
module.exports = {
plugins: [
heroui({
themes: {
light: {
colors: {
primary: {
DEFAULT: "#006FEE",
50: "#E6F1FE",
// ... more shades
},
},
},
},
}),
],
};
```
```css
/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";
:root {
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: oklch(0.9911 0 0);
}
```
## Best Practices
1. **Use Standard Tailwind**: Prefer standard Tailwind utilities over custom ones
2. **Match v2 Values**: If exact v2 appearance is needed, use arbitrary values
3. **Test Responsively**: v3 has responsive sizing - test on multiple screen sizes
4. **Update CSS Variables**: If customizing, update CSS variables instead of Tailwind config
5. **Check Component Docs**: Refer to individual component migration guides for API changes
## Related Guides
* [Main Migration Guide](/docs/react/migration)
* [Theming Documentation](/docs/react/getting-started/handbook/theming)
* [Styling Guide](/docs/react/getting-started/handbook/styling)
# All Releases
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/index.mdx
> All updates and changes to HeroUI v3, including new features, fixes, and breaking changes.
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## Latest Release
### v3.0.0
**March 2026**
A ground-up rewrite for React and React Native. 75+ web components, 37 native components, Tailwind CSS v4, React Aria, compound component architecture, CSS-first theming with OKLCH tokens, `data-reduce-motion` animation control, and built for AI-assisted development with MCP servers, agent skills, and LLMs.txt.
[Read the full announcement →](/docs/releases/v3-0-0)
### HeroUI Pro
Premium components, templates, and AI tooling for React and React Native. Pre-sale pricing is live.
[See plans and pricing at heroui.pro →](https://heroui.pro)
### v3.0.0-rc.1
**March 14, 2026**
Seven new components ([Drawer](/docs/components/drawer), [ToggleButton](/docs/components/toggle-button), [ToggleButtonGroup](/docs/components/toggle-button-group), [Meter](/docs/components/meter), [ProgressBar](/docs/components/progress-bar), [ProgressCircle](/docs/components/progress-circle), [Toolbar](/docs/components/toolbar)), **virtualization** for [Table](/docs/components/table) and [ListBox](/docs/components/list-box), `ButtonGroup.Separator` + vertical orientation for [ButtonGroup](/docs/components/button-group), and React Aria Components bumped to v1.16.0.
[Read full release notes →](/docs/releases/v3-0-0-rc-1)
### v3.0.0-beta.8
**March 2, 2026**
This release adds three new components ([Badge](/docs/components/badge), [Pagination](/docs/components/pagination), [Table](/docs/components/table)) and new `InputContainer` composition APIs for [DateField](/docs/components/date-field) + [TimeField](/docs/components/time-field). ⚠️ **Breaking changes**: TextField CSS classes were renamed from `.text-field` to `.textfield`.
[Read full release notes →](/docs/releases/v3-0-0-beta-8)
### v3.0.0-beta.7
**February 18, 2026**
This release introduces a comprehensive **Date & Time** system with four new components ([Calendar](/docs/components/calendar), [RangeCalendar](/docs/components/range-calendar), [DatePicker](/docs/components/date-picker), [DateRangePicker](/docs/components/date-range-picker)), new [Switch.Content](/docs/components/switch) sub-component, explicit [Tabs.Separator](/docs/components/tabs) for opt-in separator lines, and ⚠️ **breaking changes** removing `hideSeparator` from Tabs and consolidating `DateInputGroup`/`ColorInputGroup` under their respective field components.
[Read full release notes →](/docs/releases/v3-0-0-beta-7)
### v3.0.0-beta.6
**February 6, 2026**
This release introduces a comprehensive **Color System** with six new components ([ColorPicker](/docs/components/color-picker), [ColorArea](/docs/components/color-area), [ColorSlider](/docs/components/color-slider), [ColorField](/docs/components/color-field), [ColorSwatch](/docs/components/color-swatch), [ColorSwatchPicker](/docs/components/color-swatch-picker)), major [Toast](/docs/components/toast) improvements with loading states and promise support, [Separator](/docs/components/separator) variants, and ⚠️ **breaking changes** renaming `Toast.Container` to `Toast.Provider` and updating CSS class names to hyphenated format.
[Read full release notes →](/docs/releases/v3-0-0-beta-6)
### v3.0.0-beta.5
* Fixed build issue
### v3.0.0-beta.4
**January 20, 2026**
**Critical Build Issue Fixed**: This version (beta.4) had a critical build issue that has been fixed in **beta.5**. Please upgrade to `@heroui/styles@3.0.0-beta.5` and `@heroui/react@3.0.0-beta.5` to ensure proper TypeScript declaration generation and export resolution.
This release introduces the new [Theme Builder](/themes) for visual theme customization, three new components ([Autocomplete](/docs/components/autocomplete), [Breadcrumbs](/docs/components/breadcrumbs), [Toast](/docs/components/toast)), secondary variant for [Tabs](/docs/components/tabs), primary/secondary variants for [Input](/docs/components/input) and [InputGroup](/docs/components/input-group), and ⚠️ **breaking changes** removing Link's underline variants and `isInSurface` prop from form components.
[Read full release notes →](/docs/releases/v3-0-0-beta-4)
### v3.0.0-beta.3
**December 19, 2025**
This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form and input components, introduces `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) for cleaner layouts, includes styling fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variant.
[Read full release notes →](/docs/releases/v3-0-0-beta-3)
### v3.0.0-beta.2
**November 20, 2025**
This release introduces six essential new components ([AlertDialog](/docs/components/alert-dialog), [ComboBox](/docs/components/combo-box), [Dropdown](/docs/components/dropdown), [InputGroup](/docs/components/input-group), [Modal](/docs/components/modal), [NumberField](/docs/components/number-field)), enhances theme compatibility and motion preferences, improves the [Select](/docs/components/select) component API with a ⚠️ **breaking change**, plus various refinements and bug fixes.
[Read full release notes →](/docs/releases/v3-0-0-beta-2)
### v3.0.0-beta.1
**November 6, 2025**
This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components have been redesigned, 8 new components added ([Alert](/docs/compoenents/alert), [Checkbox](/docs/components/checkbox), [InputOTP](/docs/components/input-otp), [ListBox](/docs/components/listbox), [Select](/docs/components/select), [Slider](/docs/components/slider), [Surface](/docs/components/surface)), and the design system has been completely overhauled with better color tokens, shadows, and architecture. Includes breaking changes to design system variables, component APIs, and flexible component patterns.
[Read full release notes →](/docs/releases/v3-0-0-beta-1)
## Previous Releases
### v3.0.0-alpha.35
**October 21, 2025**
#### React Server Components Support
* Fixed critical issue where compound components didn't work in React Server Components (RSC)
* Moved compound pattern logic from components to index files, resolving `"use client"` conflicts
* **(⚠️ Breaking change)**: Main component now requires `.Root` suffix (e.g., `` → ``)
* Named exports remain unchanged and fully supported
#### React 19 Improvements
* Removed `forwardRef` (now native in [React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop))
* Simplified Context usage (`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider))
#### Switch Component Refactoring
* **(⚠️ Breaking change)**: Split Switch and SwitchGroup into separate components
* Cleaner API: `` replaces `` and ``
* Matches Radio/RadioGroup pattern for consistency
* Separate styles, types, and implementations
#### Affected Components
All compound components now require `.Root` suffix: `Accordion`, `Avatar`, `Card`, `Disclosure`, `Fieldset`, `Kbd`, `Link`, `Popover`, `Radio`, `Switch`, `Tabs`, `Tooltip`
[Read full release notes →](/docs/releases/v3-0-0-alpha-35)
### v3.0.0-alpha.34
**October 15, 2025**
* Added Form-based components: [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea).
* Introduced form field tokens `--field-*`
* Reorganized Storybook by category
* **(Breaking change)**: Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton)
* Aligned data-slot markers across components
* Improved documentation
[Read full release notes →](/docs/releases/v3-0-0-alpha-34)
### v3.0.0-alpha.33
**October 5, 2025**
* Upgraded RAC with [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html)
* Reordered [Tabs](/docs/components/tabs) Indicator (**Breaking change**)
* Updated [Tabs](/docs/components/tabs) component to use React Aria's `SelectionIndicator`, now supports SSR
* Updated [Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) components to use RAC CSS variables for the expand and collapse animations
* Updated [Switch](/docs/components/switch) component styles and animations
* Added `size` variants and added demo in [Switch](/docs/components/switch#sizes)
* Added related showcases in [Button](/docs/components/button), [Tabs](/docs/components/tabs), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group)
* Improved documentation
[Read full release notes →](/docs/releases/v3-0-0-alpha-33)
### v3.0.0-alpha.32
**October 1, 2025**
Card component redesigned with [new variants](/docs/components/card), added [CloseButton](/docs/components/close-button) component, [MCP Server](/docs/ui-for-agents/mcp-server) for AI coding assistants, and improved documentation.
[Read full release notes →](/docs/releases/v3-0-0-alpha-32)
### v3.0.0-alpha.31
**September 22, 2025**
* 🎨 **Showcases page** - Gallery of sites built with HeroUI
* 🌀 **DisclosureGroup component** - Groups multiple disclosures together
* 📇 **Card component** (preview) - First version of card component
* 🔀 **Switch component** (preview) - Toggle switch for settings
## Release Schedule
HeroUI v3 is now stable. Future releases follow a regular cycle:
* **Patch releases**: Bug fixes and minor improvements as needed
* **Minor releases**: New components and features, typically monthly
* **Major releases**: Architectural changes with migration guides
## Contributing
Found an issue or want to contribute? Check out our [GitHub repository](https://github.com/heroui-inc/heroui).
# v3.0.0-alpha.32
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-alpha-32
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-32.mdx
> Card component redesign, CloseButton, MCP Server for AI assistants
October 1, 2025
This release adds AI development tools, updates the [Card component](/docs/components/card) API, and improves the developer experience.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@alpha @heroui/react@alpha
```
```bash
pnpm add @heroui/styles@alpha @heroui/react@alpha
```
```bash
yarn add @heroui/styles@alpha @heroui/react@alpha
```
```bash
bun add @heroui/styles@alpha @heroui/react@alpha
```
## What's New
### MCP Server
HeroUI now includes an [MCP server](/docs/ui-for-agents/mcp-server) that lets AI assistants like Cursor, Claude Code, and VS Code Copilot access HeroUI v3 documentation and component information directly.
**Quick Setup:**
### Cursor
Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:
```json
{
"mcpServers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
```
### Claude Code
Run this command in your terminal:
```bash
claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest
```
[Learn more](/docs/ui-for-agents/mcp-server)
### Card Component API Redesign
The [Card component](/docs/components/card) has been updated with a new variant system that makes it more flexible.
**Breaking Changes:**
* Replaced `surface` prop with new `variant` system
* Removed `Card.Image`, `Card.Details`, and `Card.CloseButton` (use composition instead)
* New variants: `flat`, `outlined`, `elevated`, `filled`
**Before:**
```tsx
Old Card
```
**After:**
```tsx
New Card
```
**New Features:**
* Horizontal layout support
* Avatar integration
* Background image support
* Improved accessibility with semantic HTML
[View Card documentation](/docs/components/card)
### CloseButton Component
Added a [CloseButton component](/docs/components/close-button) for closing dialogs, modals, and other dismissible elements.
```tsx
import {CloseButton} from "@heroui/react";
// Basic usage
console.log("Closed")} />
// With custom icon
```
## Documentation Improvements
### UI for Agents
* **[MCP Server documentation](/docs/ui-for-agents/mcp-server)** for development with AI assistants
* **[llms.txt](/docs/ui-for-agents/llms-txt)** file for LLM-friendly documentation
* Setup guides for popular AI coding tools
### Component Documentation
* **[Card](/docs/components/card)**: Rewrote documentation with anatomy, variants, and more examples
* **[Switch](/docs/components/switch)**: Added anatomy diagrams and better examples
* **[CloseButton](/docs/components/close-button)**: New documentation with usage examples
## Migration Guide
### Card Component Migration
1. **Update variant prop:**
* `surface="1"` → `variant="flat"`
* `surface="2"` → `variant="outlined"`
* `surface="3"` → `variant="elevated"`
* `surface="4"` → `variant="filled"`
* Custom surfaces → Use new variant system
2. **Update component structure:**
* Replace `Card.Image` with `` in `Card.Header`
* Replace `Card.Details` with `Card.Body`
* Move `Card.CloseButton` to use new `CloseButton` component
3. **Update imports:**
```tsx
// Add CloseButton if needed
import {Card, CloseButton} from "@heroui/react";
```
## Links
* [GitHub PR #5747](https://github.com/heroui-inc/heroui/pull/5747)
* [MCP Server Documentation](/docs/ui-for-agents/mcp-server)
* [Card Component Guide](/docs/components/card)
* [CloseButton Component](/docs/components/close-button)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-alpha.33
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-alpha-33
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-33.mdx
> RAC upgrade, Tabs indicator redesign, Switch size variant, Related showcase
October 5, 2025
This release upgrades React Aria Components, redesigns the Tabs indicator, adds Switch sizes, and includes component showcases.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@alpha @heroui/react@alpha
```
```bash
pnpm add @heroui/styles@alpha @heroui/react@alpha
```
```bash
yarn add @heroui/styles@alpha @heroui/react@alpha
```
```bash
bun add @heroui/styles@alpha @heroui/react@alpha
```
## What's New
### RAC Upgrade
Upgraded React Aria Components to the [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html).
This release includes:
* CSS variables for animations
* Better SSR support
* Performance improvements for selection indicators
### Disclosure and Disclosure Group Updates
[Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) now use React Aria's CSS variables for animations. The components use `--disclosure-panel-width` and `--disclosure-panel-height` variables that track the panel's actual size during expand/collapse.
### Tabs Indicator Redesign
[Tabs](/docs/components/tabs) now uses React Aria's `SelectionIndicator` and supports SSR. This fixes layout shifts on initial render.
**🚧 Breaking Changes:**
* Moved `Tabs.Indicator` inside each `Tabs.Tab`
**Before:**
```diff tsx
+
-
```
### Switch Updates
[Switch](/docs/components/switch) has updated styles and animations. Added `size` prop with options: `sm`, `md`, `lg`.
```tsx
import {Label, Switch} from "@heroui/react";
export function Sizes() {
return (
);
}
```
### Related showcases
Related showcases have been added in [Button](/docs/components/button), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group) and [Tabs](/docs/components/tabs).
## Documentation Improvements
### Component Documentation
* **[Tabs](/docs/components/tabs)**: Updated anatomy, revised examples with new indicator design and added related showcase
* **[Switch](/docs/components/switch)**: Added size example and revised with-icon example
* **[Button](/docs/components/button)**, **[Disclosure](/docs/components/disclosure)**, **[Disclosure Group](/docs/components/disclosure-group)**: Added related showcase
## Migration Guide
### Tabs Component Migration
1. **Update component structure:**
* move `` inside each ``
## Links
* [GitHub PR #5777](https://github.com/heroui-inc/heroui/pull/5777)
* [Tabs Component](/docs/components/tabs)
* [Switch Component](/docs/components/switch)
* [Button Component](/docs/components/button)
* [Disclosure Component](/docs/components/disclosure)
* [Disclosure Group Component](/docs/components/disclosure-group)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-alpha.34
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-alpha-34
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-34.mdx
> Essentials for building forms with a clean API Form, TextField, RadioGroup, Label, Input, Fieldset and more.
October 15, 2025
This release introduces Form-based components, form field tokens, reorganizes Storybook, and aligns data-slot markers across components.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@alpha @heroui/react@alpha
```
```bash
pnpm add @heroui/styles@alpha @heroui/react@alpha
```
```bash
yarn add @heroui/styles@alpha @heroui/react@alpha
```
```bash
bun add @heroui/styles@alpha @heroui/react@alpha
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### Form-based Components
We've introduced a comprehensive set of form-based components built on React Aria Components, providing accessible and composable building blocks for creating forms. These components include [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea).
#### Description
```tsx
import {Description, Input, Label} from "@heroui/react";
export function Basic() {
return (
We'll never share your email with anyone else.
);
}
```
#### FieldError
```tsx
"use client";
import {FieldError, Input, Label, TextField} from "@heroui/react";
import {useState} from "react";
export function Basic() {
const [value, setValue] = useState("jr");
const isInvalid = value.length > 0 && value.length < 3;
return (
setValue(e.target.value)}
/>
Username must be at least 3 characters
);
}
```
#### Fieldset
```tsx
"use client";
import {FloppyDisk} from "@gravity-ui/icons";
import {
Button,
Description,
FieldError,
FieldGroup,
Fieldset,
Form,
Input,
Label,
TextArea,
TextField,
} from "@heroui/react";
export function Basic() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
// Convert FormData to plain object
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert("Form submitted successfully!");
};
return (
);
}
```
#### Form
```tsx
"use client";
import {Check} from "@gravity-ui/icons";
import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";
export function Basic() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
// Convert FormData to plain object
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);
};
return (
);
}
```
#### Input
```tsx
import {Input} from "@heroui/react";
export function Basic() {
return ;
}
```
#### Label
```tsx
import {Input, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
#### RadioGroup
```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";
export function Basic() {
return (
Choose the plan that suits you bestIncludes 100 messages per monthIncludes 200 messages per monthUnlimited messages
);
}
```
#### TextField
#### TextArea
```tsx
import {TextArea} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Form Field Tokens
Introduced form field tokens `--field-*` for consistent styling across form components. See [Theming](/docs/handbook/theming#calculated-variables-tailwind) for the `--field-*` variables.
### Storybook Organization
Reorganized Storybook by category for better navigation and component discovery.
### Skeleton Animation Token
**🚧 Breaking Changes:** Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton) for consistency with other component tokens.
### Data-Slot Alignment
Aligned data-slot markers across components for consistent styling and customization. This standardization makes it easier to target specific component parts with CSS selectors and improves the overall developer experience when customizing component styles.
Components now use consistent `data-slot` attributes like:
* `data-slot="base"` for the root element
* `data-slot="label"` for label text
* `data-slot="description"` for description text
* `data-slot="error"` for error messages
This allows for predictable CSS targeting across all form components:
```css
.radio {
[data-slot="label"] {
/* Styles apply to radio labels */
}
}
```
## Documentation Improvements
### Component Documentation
* **[Link](/docs/components/link)**: Added Anatomy, and examples with Icon. Updated Link and Link.Icon props section.
* **[Description](/docs/components/description)**, **[FieldError](/docs/components/field-error)**, **[Fieldset](/docs/components/fieldset)**, **[Form](/docs/components/form)**, **[Input](/docs/components/input)**, **[Label](/docs/components/label)**, **[RadioGroup](/docs/components/radio-group)**, **[TextField](/docs/components/text-field)**, and **[TextArea](/docs/components/textarea)**: New documentation with usage examples
## Migration Guide
### Skeleton Component Migration
1. **Update animation token:**
* Replace `--skeleton-default-animation-type` with `--skeleton-animation`
## Links
* [GitHub PR #5780](https://github.com/heroui-inc/heroui/pull/5780)
* [Description Component](/docs/components/description)
* [FieldError Component](/docs/components/field-error)
* [Fieldset Component](/docs/components/fieldset)
* [Form Component](/docs/components/form)
* [Input Component](/docs/components/input)
* [Label Component](/docs/components/label)
* [RadioGroup Component](/docs/components/radio-group)
* [TextField Component](/docs/components/text-field)
* [TextArea Component](/docs/components/textarea)
* [Skeleton Component](/docs/components/skeleton)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-alpha.35
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-alpha-35
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-35.mdx
> React Server Components support for compound components, React 19 improvements, and critical bug fixes.
October 21, 2025
This release fixes a critical issue where **compound components didn't work correctly in React Server Components (RSC)**. Additionally, this release adopts React 19 best practices by removing `forwardRef` and simplifying context usage. The Switch component has been refactored to match the Radio/RadioGroup pattern, providing a cleaner and more consistent API.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@alpha @heroui/react@alpha
```
```bash
pnpm add @heroui/styles@alpha @heroui/react@alpha
```
```bash
yarn add @heroui/styles@alpha @heroui/react@alpha
```
```bash
bun add @heroui/styles@alpha @heroui/react@alpha
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### React Server Components Support
Compound components now work correctly in React Server Components. The previous implementation had the compound pattern logic inside components, which conflicted with the `"use client"` directive. This has been fixed by moving the pattern logic to component index files.
### React 19 Improvements
This release adopts React 19 best practices:
1. **Removed `forwardRef`**: No longer needed in React 19, where `ref` is now a prop ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop))
2. **Simplified Context**: `Context.Provider` replaced with just `Context` ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider))
### Switch Component Architecture Improvement
The Switch component has been refactored to follow the same clean separation pattern as Radio/RadioGroup:
* **Separate Components**: Switch and SwitchGroup are now independent components (previously combined)
* **Cleaner API**: `` replaces the nested `` and `` pattern
* **Better Organization**: Separate styles, types, and implementations for each component
* **Consistent Pattern**: Matches the Radio/RadioGroup architecture for a more predictable API
**Before:**
```tsx
...
```
**After:**
```tsx
......
```
## ⚠️ Breaking Changes
### Main Component Requires `.Root` Suffix
To support React Server Components, the compound component pattern has been restructured. The main component now requires the `.Root` suffix when using the compound pattern.
**Before:**
```tsx
import { Avatar } from "@heroui/react"
JR
```
**After:**
```tsx
import { Avatar } from "@heroui/react"
JR
```
**Note:** Named exports (e.g., ``, ``, ``) remain unchanged and fully supported.
### Switch Component API Changes
The Switch component grouping API has been restructured to match the Radio/RadioGroup pattern:
**Before:**
```tsx
import { Switch } from "@heroui/react"
```
**After:**
```tsx
import { Switch, SwitchGroup } from "@heroui/react"
```
This change helps to:
* **Separate Components**: Switch and SwitchGroup are now independent components (previously combined)
* **Cleaner API**: `` replaces the nested `` and `` pattern
* **Better Organization**: Separate styles, types, and implementations for each component
* **Consistent Pattern**: Matches the Radio/RadioGroup architecture for a more predictable API
**Migration Steps:**
1. Import `SwitchGroup` separately: `import { Switch, SwitchGroup } from "@heroui/react"`
2. Replace `` with ``
3. Remove the nested `` wrapper
4. Individual `Switch.Root` components remain unchanged
#### Affected Components
All compound components are affected:
* `Accordion` → `Accordion.Root`
* `Avatar` → `Avatar.Root`
* `Card` → `Card.Root`
* `Disclosure` → `Disclosure.Root`
* `Fieldset` → `Fieldset.Root`
* `Kbd` → `Kbd.Root`
* `Link` → `Link.Root`
* `Popover` → `Popover.Root`
* `RadioGroup` → `RadioGroup.Root`
* `Switch` → `Switch.Root`
* `Tabs` → `Tabs.Root`
* `Tooltip` → `Tooltip.Root`
## Migration Guide
You have two options for using HeroUI compound components:
### Option 1: Update to Use `.Root` (Compound Pattern)
If you're using the compound pattern (dot notation), update your code to use `.Root` for the main component:
**Card Example:**
```tsx
import { Card } from "@heroui/react"
Card TitleCard description
Card content
Card footer
```
**Tabs Example:**
```tsx
import { Tabs } from "@heroui/react"
Tab 1Tab 2Panel 1Panel 2
```
[See more examples in the documentation](/docs/components/card)
**Avatar Example:**
```tsx
import { Avatar } from "@heroui/react"
JD
```
[See more examples in the documentation](/docs/components/avatar)
### Option 2: Use Named Exports
We added support for named exports for all compound components. You can use them like this:
**Card Example:**
```tsx
import {
CardRoot,
CardHeader,
CardTitle,
CardDescription,
CardContent,
CardFooter,
} from "@heroui/react"
Card TitleCard description
Card content
Card footer
```
**Tabs Example:**
```tsx
import { TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabPanel } from "@heroui/react"
Tab 1Tab 2Panel 1Panel 2
```
**Avatar Example:**
```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@heroui/react"
JD
```
### Migration Steps
If you're using the compound pattern, you only need to update the main component to use `.Root`:
1. **Find all instances of compound components** (e.g., `` with `` inside)
2. **Add `.Root` to the main component**:
```tsx
// Before
// After
```
3. **That's it!** All child components (e.g., `Avatar.Image`, `Avatar.Fallback`) remain unchanged.
### Complete Migration Reference
| Component | Named Export Pattern | Compound Pattern (with `.Root`) | Additional Changes |
| -------------- | ------------------------------- | ------------------------------------- | ------------------------------------------------------- |
| **Accordion** | `` | `` | - |
| **Avatar** | `` | `` | - |
| **Card** | `` | `` | - |
| **Disclosure** | `` | `` | - |
| **Fieldset** | `
# v3.0.0-beta.1
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-1
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-1.mdx
> Major redesign with new design system, 8 new components, and improved developer experience.
November 6, 2025
This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components redesigned, 8 new components, and improved design system with better color tokens, shadows, and architecture.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### New Design System
We've spent weeks crafting a new design system that merges the soul of HeroUI v2 with the simplicity of v3. Every component has been redesigned with attention to detail, smooth animations, and improved developer experience. The new design system is available in our [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3).
The redesign brings:
* New color system that brings v3's vision to life and stands out for its uniqueness
* Refined shadow system for better depth perception
* New variables and tokens for better customization
* Automatic `isOnSurface` support for form-based components
* Enhanced border and spacing tokens
* Better contrast and accessibility
* Consistent component patterns across web and native
### New Components
This release introduces **8 new** essential components:
* **[Alert](#alert)**: Display important messages and notifications with status indicators.
* **[Checkbox & CheckboxGroup](#checkbox-checkboxgroup)**: Select multiple items from a list.
* **[InputOTP](#inputotp)**: One-time password input for authentication flows.
* **[Listbox](#listbox)**: Display a list of options and allow single or multiple selection.
* **[Select](#select)**: Dropdown selection component built on top of Listbox.
* **[Slider](#slider)**: Select a value from a range with custom marks and labels.
* **[Surface](#surface)**: Base surface component for creating elevated containers.
### Alert
```tsx
import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
import React from "react";
export function Basic() {
return (
{/* Default - General information */}
New features available
Check out our latest updates including dark mode support and improved accessibility
features.
{/* Accent - Important information with action */}
Update available
A new version of the application is available. Please refresh to get the latest features
and bug fixes.
{/* Danger - Error with detailed steps */}
Unable to connect to server
We're experiencing connection issues. Please try the following:
Check your internet connection
Refresh the page
Clear your browser cache
{/* Without description */}
Profile updated successfully
{/* Custom indicator - Loading state */}
Processing your request
Please wait while we sync your data. This may take a few moments.
{/* Without close button */}
Scheduled maintenance
Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for
scheduled maintenance.
);
}
```
### Checkbox & CheckboxGroup
```tsx
import {Checkbox, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
export function Basic() {
return (
Choose all that applyLove building softwareEnjoy creating beautiful interfacesPassionate about content creation
);
}
```
### InputOTP
```tsx
import {InputOTP, Label, Link} from "@heroui/react";
export function Basic() {
return (
We've sent a code to a****@gmail.com
Didn't receive a code?
Resend
);
}
```
### Listbox
```tsx
import {Avatar, Description, Label, ListBox} from "@heroui/react";
export function Default() {
return (
B
bob@heroui.com
F
fred@heroui.com
M
martha@heroui.com
);
}
```
### Select
```tsx
import {Label, ListBox, Select} from "@heroui/react";
export function Default() {
return (
);
}
```
### Slider
```tsx
import {Label, Slider} from "@heroui/react";
export function Default() {
return (
);
}
```
### Surface
```tsx
import {Surface} from "@heroui/react";
export function Variants() {
return (
Default
Surface Content
This is a default surface variant. It uses bg-surface styling.
Secondary
Surface Content
This is a secondary surface variant. It uses bg-surface-secondary styling.
Tertiary
Surface Content
This is a tertiary surface variant. It uses bg-surface-tertiary styling.
Transparent
Surface Content
This is a transparent surface variant. It has no background, suitable for overlays and
cards with custom backgrounds.
);
}
```
### Improved Component APIs
Several components have been refined with better APIs:
* **Link**: Added `underline` and `underlineOffset` props for better customization
```tsx
import {Link} from "@heroui/react";
export function LinkBasic() {
return (
Call to action
);
}
```
* **Card**: Improved variants and styling system
```tsx
import {CircleDollar} from "@gravity-ui/icons";
import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react";
export function WithImages() {
return (
{/* Row 1: Large Product Card - Available Soon */}
Become an ACME Creator!
Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
faucibus etiam.
Only 10 spotsSubmission ends Oct 10.
{/* Row 2 */}
{/* Left Column */}
{/* Top Card */}
PAYMENT
You can now withdraw on crypto
Add your wallet in settings to withdraw
Go to settings
{/* Bottom cards */}
{/* Left Card */}
JK
Indie Hackers
148 members
JK
By John
{/* Right Card */}
AB
AI Builders
362 members
M
By Martha
{/* Right Column */}
{/* Background image */}
{/* Header */}
NEO
Home Robot
{/* Footer */}
Available soon
Get notified
{/* Row 3 */}
{/* Left Column: Card */}
NEO
$499/m
{/* Right Column: Cards Stack */}
{/* 1 */}
Bridging the FutureToday, 6:30 PM
{/* 2 */}
Avocado HackathonWed, 4:30 PM
{/* 3 */}
Sound Electro | Beyond artFri, 8:00 PM
);
}
```
* **Chip**: Enhanced with size variants and improved color system
```tsx
import {Chip} from "@heroui/react";
export function ChipBasic() {
return (
DefaultAccentSuccessWarningDanger
);
}
```
* **Switch**: Redesigned from the ground up with improved visual design and animations
```tsx
import {Label, Switch} from "@heroui/react";
export function Basic() {
return (
);
}
```
* **RadioGroup**: Redesigned from the ground up with better API and styling
```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";
export function Basic() {
return (
Choose the plan that suits you bestIncludes 100 messages per monthIncludes 200 messages per monthUnlimited messages
);
}
```
### Flexible Component Patterns
HeroUI now supports flexible component syntax. Use compound patterns with or without `.Root`, or named exports - all three patterns work identically.
**Available patterns:**
```tsx
import { Avatar } from "@heroui/react"
// 1. Compound pattern (no .Root needed) - recommended
JD
// 2. Compound pattern with .Root - still supported
JD
// 3. Named exports
import { AvatarRoot, AvatarImage, AvatarFallback } from "@heroui/react"
JD
```
**Simple components** like Button work the same way:
```tsx
import { Button } from "@heroui/react"
// No .Root needed
// Or with .Root
Label
// Or named export
import { ButtonRoot } from "@heroui/react"
Label
```
**You can mix compound and named exports** in the same component:
```tsx
import { Avatar, AvatarFallback } from "@heroui/react"
JD
```
This provides:
* **Simpler API**: Main components no longer require `.Root` suffix
* **Flexibility**: Choose between compound pattern, compound with `.Root`, or named exports
* **Backward Compatibility**: The `.Root` pattern still works
* **Naming Consistency**: Standardized naming (e.g., "Container" instead of "Wrapper")
### Global Animation Control
HeroUI now supports easy global animation control through the `data-reduce-motion` attribute. Simply add `data-reduce-motion="true"` to your `` or `` tag to disable all animations across your application.
```html
```
HeroUI automatically respects user motion preferences using the `prefers-reduced-motion` media query and extends Tailwind's `motion-reduce:` variant to support both system preferences and manual control via the data attribute. This provides flexible control over animations while maintaining accessibility best practices.
Learn more about animations and motion preferences in the [Animation documentation](/docs/handbook/animation).
## ⚠️ Breaking Changes
### Design System Variables
#### Panel → Surface & Overlay
The `--panel` variable has been replaced with `--surface` and `--overlay` to better distinguish between non-overlay components (cards, accordions) and floating components (tooltips, popovers, modals).
**Before:**
```css
--panel: var(--white);
--panel-foreground: var(--foreground);
--shadow-panel: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
```
**After:**
```css
--surface: var(--white);
--surface-foreground: var(--foreground);
--overlay: var(--white);
--overlay-foreground: var(--foreground);
--shadow-surface: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
--shadow-overlay: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
```
**Migration:**
* Replace `bg-panel` with `bg-surface` for non-overlay components
* Replace `bg-panel` with `bg-overlay` for floating components
* Replace `shadow-panel` with `shadow-surface` or `shadow-overlay`
* Replace `--color-panel` with `--color-surface` or `--color-overlay`
#### Surface Levels Simplified
The `--surface-1`, `--surface-2`, and `--surface-3` variables have been removed. Surface levels are now automatically calculated from `--surface` using `color-mix`, so you only need to declare the base surface color.
**Before (manual declaration):**
```css
--surface-1: var(--background);
--surface-2: var(--color-neutral-100);
--surface-3: var(--color-neutral-200);
```
**After (auto-calculated):**
```css
/* You only declare the base surface */
--surface: var(--white);
--surface-foreground: var(--foreground);
/* HeroUI automatically calculates these using color-mix */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
```
**Customization:**
You can override the default calculations using Tailwind's `@theme` directive:
```css
@theme inline {
--color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 90%, var(--surface-foreground) 10%);
}
```
**Migration:**
* Replace `bg-surface-1` with `bg-surface` (base surface)
* Replace `bg-surface-2` with `bg-surface-secondary` (auto-calculated)
* Replace `bg-surface-3` with `bg-surface-tertiary` (auto-calculated)
The same auto-calculation pattern applies to:
* **Background shades**: Calculated from `--background` → `background-secondary`, `background-tertiary`, `background-quaternary`
* **Soft colors**: Calculated from status colors → `accent-soft`, `danger-soft`, `warning-soft`, `success-soft`
#### Border Width Default Changed
The default border width has changed from `1px` to `0px`. Borders are now opt-in rather than default.
**Before:**
```css
--border-width: 1px;
```
**After:**
```css
--border-width: 0px; /* no border by default */
```
**Migration:**
* If you rely on default borders, explicitly set `border-width` in your custom styles
* Form fields now use `transparent` borders by default
#### Border Color Default Changed
The default border color opacity has changed from `15%` to `0%` (transparent).
**Before:**
```css
--border: oklch(0 0 0 / 15%);
```
**After:**
```css
--border: oklch(0 0 0 / 0%);
```
**Field Border Default:**
```css
--field-border: transparent; /* no border by default on form fields */
```
#### Shadow System Updates
The shadow system has been completely redesigned with separate shadows for surfaces and overlays.
**Before:**
```css
--panel-shadow: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
--field-shadow: 0 0 0 0 rgba(255, 255, 255, 0.1) inset, 0 1px 2px 0 rgba(0, 0, 0, 0.05);
```
**After (Light):**
```css
--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
```
**After (Dark):**
```css
--surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
--overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
--field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
```
#### Accent Color Updates
The accent color has been updated for better contrast and visual appeal.
**Before:**
```css
--accent: var(--color-neutral-950);
--accent-foreground: var(--snow);
```
**After:**
```css
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
```
#### Status Color Refinements
Success, warning, and danger colors have been refined for better consistency and contrast.
**Success:**
* **Before:** `oklch(0.5503 0.1244 153.56)`
* **After:** `oklch(0.7329 0.1935 150.81)`
* Foreground changed from `var(--snow)` to `var(--eclipse)` in light mode
**Warning:**
* **Before:** `oklch(0.7186 0.1521 64.85)`
* **After:** `oklch(0.7819 0.1585 72.33)` (light), `oklch(0.8203 0.1388 76.34)` (dark)
**Danger:**
* **Before:** `oklch(0.6259 0.1908 29.19)`
* **After:** `oklch(0.6532 0.2328 25.74)` (light), `oklch(0.594 0.1967 24.63)` (dark)
### Component API Changes
#### Chip Component
The Chip component's `type` prop has been renamed to `color`, and a new `size` prop has been added. A new `soft` variant has been introduced.
**Before:**
```tsx
import { Chip } from "@heroui/react";
Label
```
**After:**
```tsx
import { Chip } from "@heroui/react";
Label
```
**Migration:**
* Replace `type` prop with `color` prop
* Use `size` prop (`sm`, `md`, `lg`) to control chip size
* The `soft` variant provides a subtle appearance for less prominent chips
#### Link Component
The Link component now supports `underline` and `underlineOffset` props, and includes `asChild` support.
**Before:**
```tsx
import { Link } from "@heroui/react";
Link text
```
**After:**
```tsx
import { Link } from "@heroui/react";
Link text
```
**New Props:**
* `underline`: `"none" | "hover" | "always"` - Controls underline visibility
* `underlineOffset`: `number` - Controls underline offset from text
#### Type Reference Syntax
Due to the dual pattern implementation, type references through the namespace syntax are no longer supported. Use object-style syntax or named type imports instead.
**Before (no longer works):**
```tsx
type AvatarProps = Avatar.RootProps
```
**After (Option 1 - Object-style syntax):**
```tsx
type AvatarProps = Avatar["RootProps"]
```
**After (Option 2 - Named type imports, recommended):**
```tsx
import type { AvatarRootProps } from "@heroui/react"
type AvatarProps = AvatarRootProps
```
This change affects all compound components when accessing prop types.
#### Tabs Component Renaming
The Tabs component's wrapper element has been renamed for consistency:
* **Compound property**: `Tabs.ListWrapper` → `Tabs.ListContainer`
* **Named export**: `TabListWrapper` → `TabListContainer`
* **CSS class**: `.tabs__list-wrapper` → `.tabs__list-container`
* **Data attribute**: `data-slot="tabs-list-wrapper"` → `data-slot="tabs-list-container"`
**Migration:**
Find and replace all instances of `TabListWrapper` with `TabListContainer`:
```bash
# Component usage
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer
# CSS selectors (if using custom styles)
.tabs__list-wrapper → .tabs__list-container
[data-slot="tabs-list-wrapper"] → [data-slot="tabs-list-container"]
```
#### Removed Variables
The following variables have been removed:
* `--panel` → Use `--surface` or `--overlay`
* `--panel-foreground` → Use `--surface-foreground` or `--overlay-foreground`
* `--surface-1`, `--surface-2`, `--surface-3` → Use background shades or surface levels
* `--accent-soft` → Use `--color-accent-soft` (now calculated)
* `--radius-panel` and `--radius-panel-inner` → Use standard radius values
## Design System Updates
### New Color System
#### Surface vs Overlay Concept
The design system now distinguishes between two types of elevated components:
* **Surface**: Used for non-overlay components like cards, accordions, and disclosure groups that sit on the page
* **Overlay**: Used for floating components like tooltips, popovers, modals, and menus that appear above the page
This distinction provides:
* Better visual hierarchy
* Appropriate shadow depths
* Improved dark mode contrast
* Clearer component semantics
#### Auto-Calculated Color System
HeroUI now automatically calculates shade levels and soft color variants using CSS `color-mix`. You only need to declare the base colors, and HeroUI handles the rest.
**Background Shade Levels**
Background shades are automatically calculated from `--background`:
```css
/* You only declare the base */
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);
/* HeroUI automatically calculates these */
--color-background-secondary: color-mix(in oklab, var(--color-background) 96%, var(--color-foreground) 4%);
--color-background-tertiary: color-mix(in oklab, var(--color-background) 92%, var(--color-foreground) 8%);
--color-background-quaternary: color-mix(in oklab, var(--color-background) 86%, var(--color-foreground) 14%);
```
**Surface Levels**
Surface levels are automatically calculated from `--surface`:
```css
/* You only declare the base */
--surface: var(--white);
--surface-foreground: var(--foreground);
/* HeroUI automatically calculates these */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);
```
**Soft Color Variants**
Soft color variants are automatically calculated from status colors:
```css
/* You declare the base status colors */
--accent: oklch(0.6204 0.195 253.83);
--danger: oklch(0.6532 0.2328 25.74);
--warning: oklch(0.7819 0.1585 72.33);
--success: oklch(0.7329 0.1935 150.81);
/* HeroUI automatically calculates these at 15% opacity */
--color-accent-soft: color-mix(in oklab, var(--color-accent) 15%, transparent);
--color-danger-soft: color-mix(in oklab, var(--color-danger) 15%, transparent);
--color-warning-soft: color-mix(in oklab, var(--color-warning) 15%, transparent);
--color-success-soft: color-mix(in oklab, var(--color-success) 15%, transparent);
```
Each soft variant includes hover states (20% opacity) and foreground colors for proper contrast.
**Customization:**
You can override any auto-calculated values using Tailwind's `@theme` directive:
```css
@theme inline {
/* Adjust surface levels */
--color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
/* Adjust soft colors */
--color-accent-soft: color-mix(in oklab, var(--color-accent) 20%, transparent);
}
```
This auto-calculation system reduces the number of variables you need to manage while providing full customization when needed.
### Shadow System
The shadow system has been redesigned to provide:
* Separate shadows for surfaces and overlays
* Better depth perception
* Dark mode support (transparent shadows)
* Consistent field shadows
Shadows automatically adapt to light and dark modes, providing appropriate depth cues for each theme.
### Focus System
The focus color now uses the accent color for consistency:
```css
--focus: var(--accent);
```
This ensures focus indicators align with your brand colors while maintaining accessibility.
### Typography Tokens
Several typography-related variables have been removed in favor of using Tailwind's typography utilities directly. The design system now focuses on color and spacing tokens, letting Tailwind handle typography.
## Migration Guide
### Step 1: Update Design System Variables
Replace old panel variables with surface/overlay:
```css
/* Before */
.my-card {
background: var(--panel);
box-shadow: var(--shadow-panel);
}
/* After */
.my-card {
background: var(--surface);
box-shadow: var(--shadow-surface);
}
.my-tooltip {
background: var(--overlay);
box-shadow: var(--shadow-overlay);
}
```
### Step 2: Update Surface Levels
Surface levels are now automatically calculated from `--surface`, so you don't need to manually declare them. Simply use the new utility classes:
```css
/* Before */
.bg-surface-1 → .bg-surface (base surface)
.bg-surface-2 → .bg-surface-secondary (auto-calculated)
.bg-surface-3 → .bg-surface-tertiary (auto-calculated)
/* You can also use background shades */
.bg-surface-2 → .bg-background-secondary (auto-calculated from --background)
.bg-surface-3 → .bg-background-tertiary (auto-calculated from --background)
```
**Note:** Surface levels (`surface-secondary`, `surface-tertiary`, etc.) are automatically calculated based on your `--surface` color. No manual CSS variables needed unless you want to customize the calculations.
### Step 3: Update Component Props
Update Chip and Link components:
```tsx
// Chip: type → color, add size if needed
→
// Link: Add underline props if customizing underlines
Text // Still works, underline props are optional
```
### Step 4: Simplify Component Patterns (Optional)
If you adopted the `.Root` suffix from v3.0.0-alpha.35, you can now simplify your code by removing it:
**Before (v3.0.0-alpha.35):**
```tsx
JD
```
**After (simpler):**
```tsx
JD
```
**Note:** The `.Root` syntax still works if you prefer it.
### Step 5: Update Type References
If you're using namespace syntax for types, switch to object-style syntax or named imports:
**Before:**
```tsx
type ButtonProps = Button.RootProps
```
**After (Option 1 - Object-style):**
```tsx
type ButtonProps = Button["RootProps"]
```
**After (Option 2 - Named imports, recommended):**
```tsx
import type { ButtonRootProps } from "@heroui/react"
type ButtonProps = ButtonRootProps
```
### Step 6: Update Tabs Component
Replace `TabListWrapper` with `TabListContainer`:
**Before:**
```tsx
import { Tabs } from "@heroui/react"
HomeContent
```
**After:**
```tsx
import { Tabs } from "@heroui/react"
HomeContent
```
### Step 7: Handle Border Changes
If your custom styles rely on default borders:
```css
/* Add explicit borders where needed */
.my-component {
border-width: 1px;
border-color: var(--color-border);
}
```
### Step 8: Update Status Colors
If you've customized status colors, review the new values and adjust your custom theme if needed:
```css
/* Check if your custom status colors need updates */
--success: oklch(0.7329 0.1935 150.81); /* New value */
--warning: oklch(0.7819 0.1585 72.33); /* New value */
--danger: oklch(0.6532 0.2328 25.74); /* New value */
```
### Automated Migration
For large codebases, you can use find-and-replace:
```bash
# Panel → Surface
--panel → --surface
bg-panel → bg-surface
shadow-panel → shadow-surface
# Panel → Overlay (for floating components)
--panel → --overlay (where appropriate)
bg-panel → bg-overlay (for tooltips, popovers, etc.)
shadow-panel → shadow-overlay (for floating components)
# Chip type prop
type=" → color="
# Surface levels
bg-surface-1 → bg-surface
bg-surface-2 → bg-surface-secondary
bg-surface-3 → bg-surface-tertiary
# Tabs component
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer
# Type references
Component.RootProps → Component["RootProps"] or use named imports
```
## Component Updates
### Card Component
Card component has been refined with improved variants and better semantic structure. The component now uses the new surface system for consistent styling.
### Accordion Component
Accordion now uses the surface system for better visual consistency with other components.
### Form Components
Form components (Input, TextField, TextArea) have been updated to use the new field border system (transparent by default) for a cleaner look while maintaining accessibility.
### Component Pattern Updates
All components now support flexible patterns. Components that support the dual pattern include:
* **Simple components**: Button, Link, Spinner, Chip, Kbd
* **Compound components**: Accordion, Avatar, Card, Disclosure, Fieldset, Popover, RadioGroup, Switch, Tabs, Tooltip
You can use any of the three patterns (compound without `.Root`, compound with `.Root`, or named exports) with all these components.
## HeroUI Pro
HeroUI Pro is being reshaped from the ground up on top of the new design system. The new Pro version will feature:
* New components built on top of HeroUI v3
* Tailwind CSS v4 native support
* CSS native animations
* Enhanced customization options
We'll share more updates soon.
## Roadmap
We're working towards a stable release in **Q4** this year (2025). This beta release brings us significantly closer to that goal with:
* Comprehensive component set
* Refined design system
* Improved developer experience
* Better performance
## Community
The reception on the native side has been phenomenal. Thank you for supporting us as we build HeroUI v3! Your feedback helps us improve every day.
See what the community is saying: [HeroUI Native Reception](https://x.com/hero_ui/status/1985721976220966926)
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [HeroUI Native](https://link.heroui.com/native)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5872](https://github.com/heroui-inc/heroui/pull/5872)
## Contributors
Thanks to everyone who contributed to this release, helping us create a design system that's both beautiful and practical!
# v3.0.0-beta.2
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-2.mdx
> Six new components (AlertDialog, ComboBox, Dropdown, InputGroup, Modal, NumberField), Select API improvements, and component refinements.
November 20, 2025
This release introduces six essential new components, improves the Select component API, and includes various refinements and bug fixes.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### New Components
This release introduces **6 new** essential components:
* **[AlertDialog](#alert-dialog)**: Modal dialog for important decisions that require user confirmation. ([Documentation](/docs/components/alert-dialog))
* **[ComboBox](#combo-box)**: Combines a text input with a listbox, allowing users to filter a list of options. ([Documentation](/docs/components/combo-box))
* **[Dropdown](#dropdown)**: Displays a list of actions or options that a user can choose. ([Documentation](/docs/components/dropdown))
* **[InputGroup](#inputgroup)**: Group related input controls with prefix and suffix elements for enhanced form fields. ([Documentation](/docs/components/input-group))
* **[Modal](#modal)**: Dialog overlay for focused user interactions and important content. ([Documentation](/docs/components/modal))
* **[NumberField](#numberfield)**: Number input with increment/decrement buttons, validation, and internationalized formatting. ([Documentation](/docs/components/number-field))
### AlertDialog
```tsx
"use client";
import {AlertDialog, Button} from "@heroui/react";
export function Default() {
return (
Delete project permanently?
This will permanently delete My Awesome Project and all of its
data. This action cannot be undone.
);
}
```
### ComboBox
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@heroui/react";
export function Default() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Dropdown
```tsx
"use client";
import {Button, Dropdown, Label} from "@heroui/react";
export function Default() {
return (
console.log(`Selected: ${key}`)}>
);
}
```
### Modal
```tsx
"use client";
import {Rocket} from "@gravity-ui/icons";
import {Button, Modal} from "@heroui/react";
export function Default() {
return (
Welcome to HeroUI
A beautiful, fast, and modern React UI library for building accessible and
customizable web applications with ease.
);
}
```
### InputGroup
```tsx
"use client";
import {Globe} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";
export function WithIconPrefixAndTextSuffix() {
return (
.com
);
}
```
### NumberField
```tsx
import {Label, NumberField} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Style Improvements
#### Custom Variants and Theme Compatibility
Enhanced CSS variants and theme system for better customization:
**Motion Preferences**:
* New `motion-safe` variant with `data-reduce-motion="true"` attribute matching
* Enhanced `motion-reduce` now supports ancestor elements and pseudo-elements
**Dark Mode**:
* Class and `data-theme="dark"` attribute selectors now take precedence over `prefers-color-scheme`
* Full support for pseudo-elements in dark mode
**Theme Variables**:
* Expanded light theme scope to support nested themes (`:root`, `.light`, `.default`, `[data-theme="light"]`, `[data-theme="default"]`)
### Component Improvements
#### Select Component API Update
The Select component's API has been improved for better consistency with other components. The `Content` subcomponent has been renamed to `Popover`.
**Before:**
```tsx
```
**After:**
```tsx
```
#### Chip Component Refinements
Chip component sizes have been updated for better consistency:
* **Small (`sm`)**: `px-1 py-0 text-xs`
* **Medium (`md`)**: `text-xs` (now explicitly set)
* **Large (`lg`)**: `px-3 py-1 text-sm font-medium`
#### Separator Component Enhancement
The Separator component now automatically detects when it's placed inside a surface component (one that uses `bg-surface`) and applies the appropriate divider color for better visibility. A new `isOnSurface` prop is also available for manual control.
**New Calculated Variable:**
* `--color-separator-on-surface`: A calculated variable (automatically generated using `color-mix`) that ensures the separator is visible when placed on a surface background. Like other calculated variables, it can be overridden in your theme.
**Usage:**
```tsx
```
The `isOnSurface` prop is automatically applied when the Separator detects a `SurfaceContext` provider (used by components like Card, Alert, Popover, Modal, etc.).
You can also use the calculated variable directly with Tailwind classes:
```tsx
```
#### Animation Improvements
* Loading state spinner color updated for better visibility
* Select and Slider component styles adjusted for improved animations
* Checkbox animation improved (faster transition)
* Better support for `prefers-reduced-motion` with pseudo elements
## ⚠️ Breaking Changes
### Select Component
The `Select.Content` subcomponent has been renamed to `Select.Popover` for consistency with other components like ComboBox and Dropdown.
**Migration:**
Replace all instances of `Select.Content` with `Select.Popover`:
```tsx
// Before
...
// After
...
```
**Type imports:**
```tsx
// Before
import type { SelectContentProps } from "@heroui/react"
// After
import type { SelectPopoverProps } from "@heroui/react"
```
**Named exports:**
```tsx
// Before
import { SelectContent } from "@heroui/react"
// After
import { SelectPopover } from "@heroui/react"
```
### CSS Variables and Utilities: Divider → Separator
All CSS variables and utility classes related to `divider` have been renamed to `separator` for consistency with the Separator component name.
**CSS Variables:**
```css
/* Before */
border-bottom: 1px solid var(--divider);
/* After */
border-bottom: 1px solid var(--separator);
```
**Tailwind Utility Classes:**
```tsx
// Before
// After
```
**Theme Overrides:**
If you have custom themes that override the divider variable, update them:
```css
/* Before */
:root {
--divider: oklch(92% 0.004 286.32);
}
.dark {
--divider: oklch(22% 0.006 286.033);
}
/* After */
:root {
--separator: oklch(92% 0.004 286.32);
}
.dark {
--separator: oklch(22% 0.006 286.033);
}
```
## Bug Fixes
* Fixed loading state spinner color for better visibility
* Fixed bordered focus styles taking precedence over hover states
* Fixed animation stuttering in documentation
* Improved modal form styling
* Enhanced motion reduce support for pseudo elements
* Fixed mobile hover states sticking after touch interactions by wrapping hover styles in `@media (hover: hover)` media queries. Also simplified data attribute selectors by removing unnecessary `="true"` value checks.
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5885](https://github.com/heroui-inc/heroui/pull/5885)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.3
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-3.mdx
> Seven new components, fullWidth and hideSeparator support, style fixes, and breaking changes for AlertDialog/Modal backdrop variants and asChild prop removal.
December 19, 2025
This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form components and `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion), includes style fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variants.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### New Components
This release introduces **7 new** essential components:
* **[ButtonGroup](#button-group)**: Groups related buttons with consistent styling and spacing. ([Documentation](/docs/components/button-group))
* **[DateField](#date-field)**: Date input field with labels, descriptions, and validation built on React Aria DateField. ([Documentation](/docs/components/date-field))
* **[ErrorMessage](#error-message)**: Low-level error message component for displaying errors in non-form components. ([Documentation](/docs/components/error-message))
* **[ScrollShadow](#scroll-shadow)**: Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position. ([Documentation](/docs/components/scroll-shadow))
* **[SearchField](#search-field)**: Search input field with built-in search icon and clear button. ([Documentation](/docs/components/search-field))
* **[TagGroup](#tag-group)**: Focusable list of tags with support for keyboard navigation, selection, and removal. ([Documentation](/docs/components/tag-group))
* **[TimeField](#time-field)**: Time input field with labels, descriptions, and validation built on React Aria TimeField. ([Documentation](/docs/components/time-field))
### ButtonGroup
```tsx
import {
ChevronDown,
ChevronLeft,
ChevronRight,
CodeFork,
Ellipsis,
Picture,
Pin,
QrCode,
Star,
TextAlignCenter,
TextAlignJustify,
TextAlignLeft,
TextAlignRight,
ThumbsDown,
ThumbsUp,
Video,
} from "@gravity-ui/icons";
import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
export function Basic() {
return (
{/* Single button with dropdown */}
All commits from this branch will be added to the base branch
The 14 commits from this branch will be combined into one commit in the base
branch
The 14 commits from this branch will be rebased and added to the base branch
{/* Individual buttons */}
{/* Previous/Next Button Group */}
{/* Content Selection Button Group */}
{/* Text Alignment Button Group */}
{/* Icon-Only Alignment Button Group */}
);
}
```
### DateField
```tsx
"use client";
import {DateField, Label} from "@heroui/react";
export function Basic() {
return (
{(segment) => }
);
}
```
### ErrorMessage
```tsx
"use client";
import type {Key} from "@heroui/react";
import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
import {useMemo, useState} from "react";
export function ErrorMessageBasic() {
const [selected, setSelected] = useState>(new Set());
const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);
return (
setSelected(keys)}
>
NewsTravelGamingShoppingSelect at least one category{!!isInvalid && <>Please select at least one category}
);
}
```
### SearchField
```tsx
import {Label, SearchField} from "@heroui/react";
export function Basic() {
return (
);
}
```
### ScrollShadow
```tsx
import {Card, ScrollShadow} from "@heroui/react";
const images = [
"https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
"https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
"https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
];
export default function Orientation() {
const getRandomImage = (idx: number) => {
return images[idx % images.length];
};
return (
Vertical
{Array.from({length: 10}).map((_, idx) => (
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
quam. Morbi accumsan cursus enim, sed ultricies sapien.
))}
Horizontal
{Array.from({length: 10}).map((_, idx) => (
Bridging the FutureToday, 6:30 PM
))}
);
}
```
### TagGroup
```tsx
"use client";
import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";
export function TagGroupBasic() {
return (
News
Travel
Gaming
Shopping
);
}
```
### TimeField
```tsx
"use client";
import {Label, TimeField} from "@heroui/react";
export function Basic() {
return (
{(segment) => }
);
}
```
### Full-Width Support
Added `fullWidth` support to form and input components, allowing them to span the full width of their container. This is particularly useful for creating consistent form layouts and responsive designs.
**Supported components:**
* [ButtonGroup](/docs/components/button-group)
* [Button](/docs/components/button)
* [ComboBox](/docs/components/combo-box)
* [DateField](/docs/components/date-field)
* [DateInputGroup](/docs/components/date-input-group)
* [InputGroup](/docs/components/input-group)
* [Input](/docs/components/input)
* [NumberField](/docs/components/number-field)
* [SearchField](/docs/components/search-field)
* [Select](/docs/components/select)
* [TextField](/docs/components/text-field)
* [TextArea](/docs/components/textarea)
* [TimeField](/docs/components/time-field)
## Component Improvements
### Separator Control Enhancement
Added `hideSeparator` prop to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) components, allowing you to hide separator lines between items for a cleaner, more minimal appearance.
**Tabs:**
```tsx
OverviewAnalytics
```
**ButtonGroup:**
```tsx
```
**Accordion:**
```tsx
Item 1Content
```
### Documentation Icons Integration
Integrated [@gravity-ui/icons](https://github.com/gravity-ui/icons) into documentation components for consistent icon rendering with improved SSR support and better performance.
## Dependencies
### React Aria Components v1.14.0
Upgraded [react-aria-components](https://react-aria.adobe.com/releases/v1-14-0) to v1.14.0. This release includes:
**Enhancements:**
* SearchField: Added `isReadOnly` and `isRequired` to render props
* Tooltip: Added `shouldCloseOnPress` prop
* Tabs: Support for animated transitions between tab panels
* Miscellaneous: Support for `setState` callback in `useControlledState`
**Fixes:**
* ComboBox: Fixed VoiceOver announcement not respecting `aria-label` of ListBoxItem
* Date and Time: Enhanced error handling for absolute date and date time strings
* NumberField: Prevented incrementing/decrementing when scrolling on mobile
* Overlays: Fixed overlay positioning and flipping when boundary container is set
* Table: Fixed crash in drag and drop when keyboard navigating
* Various other bug fixes and improvements
For the complete list of changes, see the [React Aria Components v1.14.0 release notes](https://react-aria.adobe.com/releases/v1-14-0).
### Other Dependency Upgrades
* `@internationalized/date`: 3.10.0 → 3.10.1
* `@radix-ui/react-avatar`: 1.1.10 → 1.1.11
* `tailwind-merge`: 3.3.1 → 3.4.0
* `tailwind-variants`: 3.1.1 → 3.2.2
## Style Fixes
### Form Component Disabled State
Fixed disabled state styling for [Input](/docs/components/input) and [TextArea](/docs/components/textarea) components.
### Style Optimizations
* **Improved selector precision**: Enhanced CSS selector specificity for better style isolation and performance
* **Enhanced animations**: Improved animation performance and smoothness across components
* **Added no-highlight utility**: Added `no-highlight` utility class to prevent text selection on interactive elements for improved user experience
* **Optimized will-change properties**: Updated `will-change` CSS properties across components for better animation performance
* **Removed global scrollbar styling**: Removed global scrollbar styles to prevent conflicts with custom scrollbar implementations and fix modal/overlay interaction issues
## ⚠️ Breaking Changes
### AlertDialog & Modal Backdrop Variant
Renamed `backdropVariant`/`variant` prop value from `"solid"` to `"opaque"` for better semantic clarity. The term "opaque" more accurately describes the backdrop's visual appearance.
**Migration:**
Update all instances of `backdropVariant="solid"` to `backdropVariant="opaque"` for AlertDialog, and `variant="solid"` to `variant="opaque"` for Modal:
```tsx
// Before
{/* content */}
{/* content */}
// After
{/* content */}
{/* content */}
```
**Available backdrop variants:**
* `"opaque"` - Dark backdrop that completely obscures the background (formerly `"solid"`)
* `"blur"` - Blurred backdrop that softly obscures the background
* `"transparent"` - Transparent backdrop that keeps the background visible
### Removed `asChild` Prop
Removed the `asChild` prop pattern from components for cleaner APIs, improved type safety, and simplified usage.
For more details about component composition patterns, see the [Composition guide](/docs/handbook/composition).
## Bug Fixes
* Fixed `isInvalid` styles when components are used on surface backgrounds
* Fixed AlertDialog and Modal re-rendering issues after close
* Fixed overlay close issue that prevented proper cleanup when closing overlays
* Fixed Storybook links and navigation issues
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5923](https://github.com/heroui-inc/heroui/pull/5923)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.4
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-4
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-4.mdx
> New Theme Builder, three new components (Autocomplete, Breadcrumbs, Toast), Tabs secondary variant, Input/InputGroup variants, and various improvements.
January 20, 2026
**Critical Build Issue Fixed**: This version (beta.4) had a critical build issue that has been fixed in **beta.5**. Please upgrade to `@heroui/styles@3.0.0-beta.5` and `@heroui/react@3.0.0-beta.5` to ensure proper TypeScript declaration generation and export resolution.
This release introduces the new [Theme Builder](/themes) for visual theme customization, three new components ([Autocomplete](/docs/components/autocomplete), [Breadcrumbs](/docs/components/breadcrumbs), [Toast](/docs/components/toast)), adds secondary variant to [Tabs](/docs/components/tabs), primary/secondary variants to [Input](/docs/components/input) and [InputGroup](/docs/components/input-group), TextArea support for InputGroup, and ⚠️ **breaking changes** removing Link's underline variants and the `isInSurface` prop from form components.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### Theme Builder
We're excited to introduce the **[Theme Builder](/themes)** - a powerful visual tool for creating and customizing HeroUI themes. Build your perfect theme with real-time preview and export ready-to-use CSS.
**Key features:**
* **Visual Color Editing**: Adjust colors using OKLCH color pickers with intuitive sliders for lightness, chroma, and hue
* **Real-time Preview**: See your changes instantly on live component previews
* **Custom Accent Colors**: Define your brand colors and watch them propagate across all components
* **Preset Themes**: Start from curated presets like Default, Airbnb, Coinbase, Discord, and more
* **Export Ready**: Generate CSS variables ready to copy into your project
* **Light & Dark Mode**: Customize both themes simultaneously with linked or independent values
* **Keyboard Shortcuts**: Undo/redo support and quick actions for efficient workflow
Try it now at [v3.heroui.com/themes](/themes).
### New Components
This release introduces **3 new** essential components:
* **[Autocomplete](#autocomplete)**: Combines a select with filtering, allowing users to search and select from a list of options. ([Documentation](/docs/components/autocomplete))
* **[Breadcrumbs](#breadcrumbs)**: Navigation breadcrumbs showing the current page's location within a hierarchy. ([Documentation](/docs/components/breadcrumbs))
* **[Toast](#toast)**: Display temporary notifications and messages with automatic dismissal and customizable placement. ([Documentation](/docs/components/toast))
### Autocomplete
```tsx
"use client";
import type {Key} from "@heroui/react";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@heroui/react";
import {useState} from "react";
export default function Default() {
const {contains} = useFilter({sensitivity: "base"});
const [selectedKeys, setSelectedKeys] = useState([]);
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}: any) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item: any) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey: Key) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found}>
{items.map((item) => (
{item.name}
))}
);
}
```
### Breadcrumbs
```tsx
"use client";
import {Breadcrumbs} from "@heroui/react";
export default function BreadcrumbsBasic() {
return (
HomeProductsElectronicsLaptop
);
}
```
### Toast
This component is currently in preview and some features might not work as expected.
```tsx
"use client";
import {HardDrive, Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";
const noop = () => {};
export function Variants() {
return (
);
}
```
## Component Improvements
### Tabs Secondary Variant
Added a new `secondary` variant to [Tabs](/docs/components/tabs) with an underline indicator style. The secondary variant supports both horizontal and vertical orientations.
```tsx
import {Tabs} from "@heroui/react";
export function Secondary() {
return (
Overview
Analytics
Reports
View your project overview and recent activity.
Track your metrics and analyze performance data.
Generate and download detailed reports.
);
}
```
**Usage:**
```tsx
Overview
Analytics
ContentContent
```
### Input Variants
Added `primary` and `secondary` variants to the [Input](/docs/components/input) component:
* **`primary`** (default): Standard styling with shadow, suitable for most use cases
* **`secondary`**: Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
import {Input} from "@heroui/react";
export function Variants() {
return (
);
}
```
### InputGroup Enhancements
The [InputGroup](/docs/components/input-group) component received several improvements:
**TextArea Support**: Use `InputGroup.TextArea` for multiline text inputs with prefix and suffix elements.
```tsx
"use client";
import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons";
import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react";
import {useState} from "react";
export function WithTextArea() {
const [value, setValue] = useState("");
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = () => {
if (!value.trim()) return;
setIsSubmitting(true);
setTimeout(() => {
setIsSubmitting(false);
setValue("");
}, 1000);
};
return (
setValue(event.target.value)}
/>
Add a files and more
Connect apps
Voice input
Send
);
}
```
**Variants**: Added `primary` and `secondary` variants matching the Input component.
```tsx
import {Envelope} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";
export function Variants() {
return (
);
}
```
### Button & ButtonGroup Outline Variants
Added a new `outline` variant to both [Button](/docs/components/button) and [ButtonGroup](/docs/components/button-group) components for outlined styling.
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function OutlineVariant() {
return (
Button
ButtonGroup
);
}
```
### AlertDialog Size Support
Added size support to [AlertDialog](/docs/components/alert-dialog) component, allowing you to control the dialog size.
```tsx
"use client";
import {Rocket} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";
export function Sizes() {
const sizes = ["xs", "sm", "md", "lg", "cover"] as const;
return (
{size === "cover" ? (
<>
This alert dialog uses the cover size variant. It spans the
full screen with margins: 16px on mobile and 40px on desktop. Maintains
rounded corners and standard padding. Perfect for critical confirmations
that need maximum width while preserving alert dialog aesthetics.
) : (
<>
This alert dialog uses the {size} size variant. On mobile
devices, all sizes adapt to near full-width for optimal viewing. On desktop,
each size provides a different maximum width to suit various content needs.
)}
))}
);
}
```
### Checkbox Animation Improvements
Faster animation and increased stroke width for better feedback on [Checkbox](/docs/components/checkbox).
```tsx
import {Checkbox, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Link Text Decoration
The [Link](/docs/components/link) component now uses Tailwind CSS classes for text decoration instead of built-in variants. This provides more flexibility and follows Tailwind conventions.
**Available Tailwind utilities:**
* `underline` - Always visible underline
* `no-underline` - Remove underline
* `hover:underline` - Underline appears on hover
* `decoration-primary`, `decoration-secondary`, etc. - Set underline color
* `decoration-1`, `decoration-2`, `decoration-4` - Control thickness
* `underline-offset-1`, `underline-offset-2`, etc. - Adjust spacing
```tsx
import {Link} from "@heroui/react";
export function LinkUnderlineAndOffset() {
return (
);
}
```
## ⚠️ Breaking Changes
### Link Component - Removed Underline Variants
The Link component's built-in `underline` and `underlineOffset` props have been removed. Use Tailwind CSS classes instead for text decoration.
**Before:**
```tsx
Link text
```
**After:**
```tsx
Link text
```
**Available Tailwind classes:**
* `underline`, `no-underline`, `hover:underline` - Decoration line
* `decoration-primary`, `decoration-muted`, etc. - Decoration color
* `decoration-solid`, `decoration-dashed`, `decoration-dotted` - Decoration style
* `decoration-1`, `decoration-2`, `decoration-4` - Decoration thickness
* `underline-offset-1`, `underline-offset-2`, `underline-offset-4` - Underline offset
For more details, see the [Link documentation](/docs/components/link).
### Form Components - Removed `isInSurface` Prop
The `isInSurface` prop and automatic surface detection have been removed from form-based components. Instead, use the `variant="secondary"` prop when placing form components inside Surface, Card, or other surface-based containers.
**Before:**
```tsx
{/* Input automatically detected surface context */}
```
**After:**
```tsx
{/* Use variant="secondary" for surface backgrounds */}
```
**Affected components:**
* Input
* InputGroup
* TextField
* TextArea
* SearchField
* NumberField
* DateField
* TimeField
* Select
* ComboBox
* Autocomplete
The `secondary` variant provides lower emphasis styling without shadow, which is appropriate for use on surface backgrounds.
## Style Fixes
* **Button**: Updated secondary button colors for improved visual consistency
* **Checkbox**: Optimized animation speed and increased stroke width for better feedback (see [Checkbox Animation Improvements](#checkbox-animation-improvements))
* **Link**: Updated decoration styles and transition timings
* **Focus Visible**: Added `:not(:focus)` to focus-visible selectors to prevent conflicts with hover states
* **Separator**: Fixed styles to only apply to horizontal separator
## Bug Fixes
* Fixed Link with Button variants styling
* Fixed Fieldset flexbox quirk in Safari with BEM styles
* Fixed SearchField empty state to properly disable clear button
* Fixed ButtonGroup context to only apply to direct children
* Fixed ButtonGroup `BUTTON_GROUP_CHILD` re-export for type declarations
## Dependencies
### Direct Exports from React Aria Components
HeroUI now provides direct exports from react-aria-components for easier access to primitives and utilities. These exports are particularly useful for [React Aria Framework setup](https://react-aria.adobe.com/frameworks).
**Providers:**
* `RouterProvider` - Configure React Aria links to use your client-side router
* `I18nProvider` - Set the locale used by React Aria components
**Hooks and Utilities:**
* `isRTL` - Check if a locale is right-to-left
* `useLocale` - Access the current locale and direction
* `useFilter` - Filter and sort collections
**Components:**
* `Collection` - Collection component for managing lists
* `ListBoxLoadMoreItem` - ListBox item for loading more items
**i18n Utilities:**
* `getLocalizationScript` - Get localization script for server-side rendering (from `react-aria-components/i18n`)
All of these can be imported directly from `@heroui/react`:
```tsx
import {
RouterProvider,
I18nProvider,
isRTL,
useLocale,
useFilter,
getLocalizationScript
} from "@heroui/react";
```
## Links
* [Theme Builder](/themes)
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6121](https://github.com/heroui-inc/heroui/pull/6121)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.6
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-6
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-6.mdx
> 6 new color components (ColorPicker, ColorArea, ColorSlider, ColorField, ColorSwatch, ColorSwatchPicker), toast improvements, and various style fixes.
February 6, 2026
This release introduces a comprehensive **Color System** with six new components for color selection and manipulation: [ColorPicker](/docs/components/color-picker), [ColorArea](/docs/components/color-area), [ColorSlider](/docs/components/color-slider), [ColorField](/docs/components/color-field), [ColorSwatch](/docs/components/color-swatch), and [ColorSwatchPicker](/docs/components/color-swatch-picker). Also includes [Separator](/docs/components/separator) variants and various style improvements.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### Color System
We're excited to introduce a comprehensive **Color System** - a complete suite of components for color selection, manipulation, and display. These components are built on React Aria's color primitives and work together seamlessly.
**Key features:**
* **Full Color Space Support**: Work with HSL, HSB, and RGB color spaces
* **Channel-based Editing**: Manipulate individual color channels (hue, saturation, lightness, brightness, red, green, blue, alpha)
* **Accessible by Default**: Full keyboard navigation and screen reader support
* **Composable Design**: Mix and match components to build custom color pickers
### New Components
This release introduces **6 new** color components:
* **[ColorPicker](#colorpicker)**: Complete color picker with trigger, popover, and composable internals. ([Documentation](/docs/components/color-picker))
* **[ColorArea](#colorarea)**: 2D gradient area for selecting two color channels simultaneously. ([Documentation](/docs/components/color-area))
* **[ColorSlider](#colorslider)**: Single-channel slider for precise color adjustments. ([Documentation](/docs/components/color-slider))
* **[ColorField](#colorfield)**: Text input for entering and editing color values. ([Documentation](/docs/components/color-field))
* **[ColorSwatch](#colorswatch)**: Visual color preview with support for transparency. ([Documentation](/docs/components/color-swatch))
* **[ColorSwatchPicker](#colorswatchpicker)**: Grid of selectable color swatches for quick color selection. ([Documentation](/docs/components/color-swatch-picker))
### ColorPicker
The ColorPicker is a compound component that combines all color components into a complete color selection experience.
```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### ColorArea
A 2D gradient area for selecting two color channels at once, typically saturation and brightness.
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaBasic() {
return (
);
}
```
### ColorSlider
A slider for adjusting individual color channels like hue, saturation, lightness, or alpha.
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
**With different channels:**
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Channels() {
const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));
return (
Current color: {color.toString("hsl")}
);
}
```
### ColorField
A text input field for entering color values directly. Supports various color formats.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function Basic() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
);
}
```
### ColorSwatch
A visual display of a color value with support for transparency patterns.
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchBasic() {
return (
);
}
```
### ColorSwatchPicker
A grid of color swatches for quick color selection from a predefined palette.
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Basic() {
return (
{colors.map((color) => (
))}
);
}
```
## Component Improvements
### Toast Enhancements
The [Toast](/docs/components/toast) component has been significantly improved with new features and better stability (#6151):
**New Features:**
* **Loading State**: Added `isLoading` prop to show a spinner instead of the default indicator
* **Default Timeout**: Toasts now auto-dismiss after 4 seconds by default (configurable via `timeout` prop)
* **Width Control**: Added `width` prop to `Toast.Provider` for customizable toast width
* **Adaptive Height**: Toasts now adapt their height based on content
* **Better Stacking**: Fixed layout shifts when toasts stack using absolute positioning and height synchronization
* **Improved Close Handling**: Deferred `onClose` callback to prevent toast transition deadlock
* **Front-most Close Button**: Close button only appears on the front-most toast for cleaner UI
* **Enhanced Promise Support**: Improved `toast.promise()` with better loading states and error handling
**New Demos:**
* Promise & Loading states
* Callbacks and timeout handling
```tsx
"use client";
import {HardDrive, Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";
const noop = () => {};
export function Variants() {
return (
);
}
```
### Separator Variants
Added variants to the [Separator](/docs/components/separator) component for different visual styles.
### Chip Component - Label Slot
The [Chip](/docs/components/chip) component now supports a `Chip.Label` subcomponent for better visual alignment. When removing start or end content (like icons), the label text was too close to the chip edges. Plain text children are automatically wrapped in `` for backward compatibility.
**Usage:**
```tsx
import { Chip } from '@heroui/react';
// Automatic wrapping (backward compatible)
Label text
// Explicit label with custom styling
Custom Label
// Mixing icons and labels
With Icon
```
## Style Fixes
* **Overlay Content**: Fixed blur effect on overlay content (#6136)
* **Invalid Field**: Converted ring to outline for invalid field states (#6184)
* **Link with Button**: Fixed styling for Link components using button variants (#6138)
* **Toast Content**: Fixed vertical alignment of toast content (#6147)
* **Safari SVG**: Fixed SVG shifting issue in Safari (#6149)
* **Placeholder Color**: Aligned placeholder color with input text (#6139)
* **Tooltip**: Removed cursor style from tooltip trigger component
* **CSS Variables**: Made calculated variables depend only on root variables (#6154)
## Bug Fixes
* Fixed page interactivity during view transitions (#6128)
* Fixed markdown URL formatting (#6162)
* Fixed incorrect link to combo box page (#6164)
* Fixed autocomplete styles import order in index.css
* Fixed hyphenated format for CSS classes (#6191)
## ⚠️ Breaking Changes
### Toast Component - Container Renamed to Provider
The `Toast.Container` component has been renamed to `Toast.Provider` for better semantic clarity (#6151).
**Before:**
```tsx
```
**After:**
```tsx
```
**Additional Changes:**
* Default `gap` prop changed from `14` to `12` pixels
* Default `timeout` is now `4000` (4 seconds) instead of requiring explicit timeout
* `Toast.Action` has been renamed to `Toast.ActionButton` for consistency
### CSS Class Naming Convention
CSS classes have been renamed to use hyphenated format for consistency (#6141). This follows BEM conventions more closely and improves compatibility with Tailwind CSS.
**Important Note**: The `textarea` class was initially renamed to `text-area` but was rolled back to `textarea` in PR #6191 due to conflicts with Tailwind's native `textarea` class. No changes are needed for TextArea component classes.
#### Component Class Name Changes
The following CSS class names have been updated. If you have custom CSS targeting these classes directly, update your selectors:
| Component | Old Class Name | New Class Name | Notes |
| ------------------ | -------------------------- | --------------------------- | ------------------------------------------------------ |
| **ComboBox** | `.combobox` | `.combo-box` | All related classes updated |
| | `.combobox__input-group` | `.combo-box__input-group` | |
| | `.combobox__trigger` | `.combo-box__trigger` | |
| | `.combobox__popover` | `.combo-box__popover` | |
| | `.combobox--full-width` | `.combo-box--full-width` | |
| **ListBox** | `.listbox` | `.list-box` | All related classes updated |
| **ListBoxItem** | `.listbox-item` | `.list-box-item` | All related classes updated |
| | `.listbox-item__indicator` | `.list-box-item__indicator` | |
| | `.listbox-item--default` | `.list-box-item--default` | |
| | `.listbox-item--danger` | `.list-box-item--danger` | |
| **ListBoxSection** | `.listbox-section` | `.list-box-section` | All related classes updated |
| **TextArea** | `.textarea` | `.textarea` | **No change** - Rolled back to avoid Tailwind conflict |
#### Migration Guide
**Before:**
```css
/* Custom styles targeting old class names */
.combobox {
/* styles */
}
.listbox-item {
/* styles */
}
```
**After:**
```css
/* Update to new hyphenated class names */
.combo-box {
/* styles */
}
.list-box-item {
/* styles */
}
```
**JavaScript/TypeScript Updates:**
If you're using these class names in JavaScript or TypeScript code:
```tsx
// Before
// After
```
**Note**: Component props and TypeScript types remain unchanged. Only CSS class names have been updated.
### Removed CSS Variables
Several CSS variables have been removed as part of the surface color refactoring (#6204). These variables were either replaced with direct variable references or removed entirely.
#### Surface Color Variables
The following calculated surface color variables have been removed and replaced with direct variable references:
**Removed:**
* `--color-surface-secondary` (was calculated via `color-mix`)
* `--color-surface-tertiary` (was calculated via `color-mix`)
**Replacement:**
These variables now directly reference the base variables defined in `variables.css`:
* `--color-surface-secondary` → Uses `var(--surface-secondary)` directly
* `--color-surface-tertiary` → Uses `var(--surface-tertiary)` directly
The base variables `--surface-secondary` and `--surface-tertiary` are now defined directly in `variables.css` instead of being calculated in `theme.css`.
#### On Surface Color Variables
All `--color-on-surface-*` variables have been removed entirely:
**Removed:**
* `--color-on-surface`
* `--color-on-surface-foreground`
* `--color-on-surface-hover`
* `--color-on-surface-focus`
* `--color-on-surface-secondary`
* `--color-on-surface-secondary-foreground`
* `--color-on-surface-secondary-hover`
* `--color-on-surface-secondary-focus`
* `--color-on-surface-tertiary`
* `--color-on-surface-tertiary-foreground`
* `--color-on-surface-tertiary-hover`
* `--color-on-surface-tertiary-focus`
**Migration:**
If you were using these variables, update your code to use the appropriate surface variables directly:
```css
/* Before */
.element {
background: var(--color-on-surface);
color: var(--color-on-surface-foreground);
}
.element:hover {
background: var(--color-on-surface-hover);
}
/* After */
.element {
background: var(--surface-secondary);
color: var(--surface-secondary-foreground);
}
.element:hover {
background: color-mix(in oklab, var(--surface-secondary) 92%, var(--surface-secondary-foreground) 8%);
}
```
Or use the Tailwind utilities:
```tsx
// Before
// After
```
**Related PR:** [#6204](https://github.com/heroui-inc/heroui/pull/6204)
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6201](https://github.com/heroui-inc/heroui/pull/6201)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.7
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-7
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-7.mdx
> 4 new components (Calendar, RangeCalendar, DatePicker, DateRangePicker) and APIs improvements.
February 19, 2026
This release adds 4 new components: [Calendar](/docs/components/calendar), [RangeCalendar](/docs/components/range-calendar), [DatePicker](/docs/components/date-picker), and [DateRangePicker](/docs/components/date-range-picker). Also new: [Switch.Content](#switchcontent) for grouping label and description, and [Tabs.Separator](#tabsseparator) for opt-in separator lines between tabs.
⚠️ **Breaking changes**: `hideSeparator` removed from Tabs; `DateInputGroup` and `ColorInputGroup` moved under `DateField.Group`, `TimeField.Group`, and `ColorField.Group`.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### Date & Time System
**Date & Time** — Calendar, DatePicker, RangeCalendar, and DateRangePicker built on React Aria date primitives. Supports i18n, time zones, and full keyboard/ARIA accessibility.
**Key features:**
* **Calendar systems**: Gregorian, Buddhist, Persian, and others
* **Year picker**: Overlay for quick year navigation
* **Cell indicators**: Events, availability, or status dots on cells
* **Range selection**: Date ranges with visual highlighting
* **Accessible**: Keyboard nav, screen readers, ARIA
All date values use [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`). Wrap with [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) to override locale; read it with [`useLocale`](https://react-aria.adobe.com/useLocale).
### New Components
* **[Calendar](#calendar)**: Single date selection, year picker, indicators, multi-month. ([Docs](/docs/components/calendar))
* **[RangeCalendar](#rangecalendar)**: Date ranges with range highlighting and multi-month. ([Docs](/docs/components/range-calendar))
* **[DatePicker](#datepicker)**: Date field + popover calendar. ([Docs](/docs/components/date-picker))
* **[DateRangePicker](#daterangepicker)**: Two date fields + popover range calendar. ([Docs](/docs/components/date-range-picker))
### Calendar
Single-date calendar with year picker, cell indicators, multi-month view, and i18n calendars.
```tsx
"use client";
import {Calendar} from "@heroui/react";
export function Basic() {
return (
{(day) => {day}}
{(date) => }
);
}
```
**Year Picker:**
```tsx
"use client";
import {Calendar} from "@heroui/react";
export function YearPicker() {
return (
{(day) => {day}}
{(date) => }
{({year}) => }
);
}
```
**International Calendars:**
```tsx
"use client";
import {Calendar} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";
export function InternationalCalendar() {
return (
{(day) => {day}}
{(date) => }
{({year}) => }
);
}
```
### RangeCalendar
Date range selection with range highlighting and multi-month views.
```tsx
"use client";
import {RangeCalendar} from "@heroui/react";
export function Basic() {
return (
{(day) => {day}}
{(date) => }
);
}
```
**Multiple Months:**
```tsx
"use client";
import {RangeCalendar} from "@heroui/react";
import {getLocalTimeZone} from "@internationalized/date";
import React from "react";
import {RangeCalendarStateContext, useLocale} from "react-aria-components";
function RangeCalendarMonthHeading({offset = 0}: {offset?: number}) {
const state = React.useContext(RangeCalendarStateContext)!;
const {locale} = useLocale();
const startDate = state.visibleRange.start;
const monthDate = startDate.add({months: offset});
const dateObj = monthDate.toDate(getLocalTimeZone());
const monthYear = new Intl.DateTimeFormat(locale, {month: "long", year: "numeric"}).format(
dateObj,
);
return {monthYear};
}
export function MultipleMonths() {
return (
state.setTimeValue(v as TimeValue)}
>
{(segment) => }
)}
)}
);
}
```
### DateRangePicker
Two date fields + popover range calendar.
```tsx
"use client";
import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
export function Basic() {
return (
{(segment) => }
{(segment) => }
{(day) => {day}}
{(date) => }
{({year}) => }
);
}
```
## API Improvements
### Switch.Content
`Switch.Content` groups label and description next to the switch control ([#6240](https://github.com/heroui-inc/heroui/pull/6240)).
**Before:**
```tsx
import { Switch, Label, Description } from '@heroui/react';
Get notified when someone mentions you
```
### Tabs.Separator
The [Tabs](/docs/components/tabs) component now includes an explicit `Tabs.Separator` sub-component for adding visual separator lines between tabs. This replaces the previous automatic CSS pseudo-element separator and the `hideSeparator` prop ([#6243](https://github.com/heroui-inc/heroui/pull/6243)).
Separators are now **opt-in** — add `` inside each `` where you want a separator line.
### Field Sub-Component Consolidation
`DateField`, `TimeField`, and `ColorField` now expose their input group sub-components directly, removing the need to import `DateInputGroup` or `ColorInputGroup` separately. See [Breaking Changes](#-breaking-changes) for migration details.
### Breadcrumbs Fix
Props passed to `Breadcrumbs.Item` are now forwarded to the underlying `Link` ([#6233](https://github.com/heroui-inc/heroui/pull/6233)).
## Style Fixes
* **ListBox Item**: Adjusted hover background color from `bg-default-hover` to `bg-default` for consistency
* **Date Input Group**: Changed segment text from `tabular-nums` to `text-nowrap` for better layout
* **Date Input Group**: Improved focus-within styles to exclude date picker trigger from field focus highlighting
## Dependencies
* **React Aria Components**: Updated from `1.14.0` to `1.15.0` — adds a new [`render` prop](https://react-aria.adobe.com/customization#dom-elements) for customizing the DOM element rendered by any React Aria component (useful for router links, animation libraries like Motion, etc.)
* **@react-aria/utils**: Updated from `3.32.0` to `3.33.0`
* **@react-types/shared**: Updated from `3.32.1` to `3.33.0`
* **@internationalized/date**: Updated from `3.10.1` to `3.11.0` — date fields now constrain on blur instead of as you type
* Added `@react-aria/i18n` and `@react-stately/utils` for calendar i18n
## ⚠️ Breaking Changes
### Tabs — `hideSeparator` Prop Removed
The `hideSeparator` prop has been removed from the Tabs component. Separators are now **opt-in** using the new `` sub-component instead of being automatically generated via CSS pseudo-elements ([#6243](https://github.com/heroui-inc/heroui/pull/6243)).
**Before:**
```tsx
{/* Separators shown by default, hidden via prop */}
Tab 1Tab 2
```
**After:**
```tsx
{/* No separators by default — explicitly add them where needed */}
Tab 1Tab 2
```
**CSS Changes:**
* Tab separator styles moved from pseudo-element (`.tabs__tab:not(:first-child):before`) to a dedicated `.tabs__separator` class
* The `[data-hide-separator]` data attribute has been removed
### Field Sub-Component API Changes
`DateInputGroup` and `ColorInputGroup` are no longer exported directly from `@heroui/react`. Their sub-components have been consolidated under their respective field components (`DateField`, `TimeField`, `ColorField`).
#### DateField Changes
**Before:**
```tsx
import {DateField, Label, DateInputGroup, Description} from '@heroui/react';
...
{(segment) => }
...Pick a date
```
**After:**
```tsx
import {DateField, Label, Description} from '@heroui/react';
...
{(segment) => }
...Pick a date
```
#### TimeField Changes
Same pattern as DateField:
| Before | After |
| ------------------------ | ------------------- |
| `DateInputGroup` | `TimeField.Group` |
| `DateInputGroup.Input` | `TimeField.Input` |
| `DateInputGroup.Segment` | `TimeField.Segment` |
| `DateInputGroup.Prefix` | `TimeField.Prefix` |
| `DateInputGroup.Suffix` | `TimeField.Suffix` |
#### ColorField Changes
| Before | After |
| ------------------------ | ------------------- |
| `ColorInputGroup` | `ColorField.Group` |
| `ColorInputGroup.Input` | `ColorField.Input` |
| `ColorInputGroup.Prefix` | `ColorField.Prefix` |
| `ColorInputGroup.Suffix` | `ColorField.Suffix` |
**Usage:**
```tsx
import {ColorField, Label, ColorInputGroup, ColorSwatch} from '@heroui/react';
```
**After:**
```tsx
import {ColorField, Label, ColorSwatch} from '@heroui/react';
```
> **Note:** The underlying CSS classes (`.date-input-group`, `.color-input-group`, etc.) remain unchanged. Only the JavaScript import paths and component names have changed.
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6237](https://github.com/heroui-inc/heroui/pull/6237)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.8
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-8
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-8.mdx
> 3 new components (Badge, Pagination, Table), DateField improvements, and key API/style fixes.
March 2, 2026
This release adds three new components: [Badge](/docs/components/badge), [Pagination](/docs/components/pagination), and [Table](/docs/components/table), plus new `InputContainer` composition APIs for [DateField](/docs/components/date-field) and [TimeField](/docs/components/time-field).
⚠️ **Breaking changes**: TextField CSS classes were renamed from `.text-field` to `.textfield`.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@beta @heroui/react@beta
```
```bash
pnpm add @heroui/styles@beta @heroui/react@beta
```
```bash
yarn add @heroui/styles@beta @heroui/react@beta
```
```bash
bun add @heroui/styles@beta @heroui/react@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### New Components
* **[Badge](#badge)**: Compact status + count indicator with color, variant, placement, and size options. ([Docs](/docs/components/badge))
* **[Pagination](#pagination)**: Compound pagination primitives with summary, ellipsis, and previous/next controls. ([Docs](/docs/components/pagination))
* **[Table](#table)**: Data table primitives with sorting, selection, resizing, async loading, and footer composition. ([Docs](/docs/components/table))
### Badge
New badge primitives for counters, labels, and anchored overlays with `Badge.Anchor` and `Badge.Label`.
```tsx
import {Avatar, Badge} from "@heroui/react";
const GREEN_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
const ORANGE_AVATAR_URL =
"https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg";
const BLUE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg";
export function BadgeBasic() {
return (
JD
5
AB
New
CD
);
}
```
### Pagination
New navigation component built with composable parts (`Root`, `Content`, `Item`, `Link`, `Previous`, `Next`, `Summary`, `Ellipsis`).
```tsx
"use client";
import {Pagination} from "@heroui/react";
import {useState} from "react";
export function PaginationWithEllipsis() {
const [page, setPage] = useState(1);
const totalPages = 12;
const getPageNumbers = () => {
const pages: (number | "ellipsis")[] = [];
pages.push(1);
if (page > 3) {
pages.push("ellipsis");
}
const start = Math.max(2, page - 1);
const end = Math.min(totalPages - 1, page + 1);
for (let i = start; i <= end; i++) {
pages.push(i);
}
if (page < totalPages - 2) {
pages.push("ellipsis");
}
pages.push(totalPages);
return pages;
};
return (
setPage((p) => p - 1)}>
Previous
{getPageNumbers().map((p, i) =>
p === "ellipsis" ? (
) : (
setPage(p)}>
{p}
),
)}
setPage((p) => p + 1)}>
Next
);
}
```
### Table
Compound data table on React Aria with sortable columns, row selection, custom cells, load-more sentinel rows, and resizable columns.
```tsx
import {Table} from "@heroui/react";
export function Basic() {
return (
Seven new components: [Drawer](/docs/components/drawer), [ToggleButton](/docs/components/toggle-button), [ToggleButtonGroup](/docs/components/toggle-button-group), [Meter](/docs/components/meter), [ProgressBar](/docs/components/progress-bar), [ProgressCircle](/docs/components/progress-circle), and [Toolbar](/docs/components/toolbar). Table and ListBox gain virtualization, ButtonGroup gets a `Separator` sub-component + vertical orientation, and React Aria Components is bumped to v1.16.0.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@rc @heroui/react@rc
```
```bash
pnpm add @heroui/styles@rc @heroui/react@rc
```
```bash
yarn add @heroui/styles@rc @heroui/react@rc
```
```bash
bun add @heroui/styles@rc @heroui/react@rc
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
## What's New
### New Components
* **[Drawer](#drawer)**: Slide-out panel with drag-to-dismiss, 4 placements, backdrop variants, scrollable body ([Docs](/docs/components/drawer))
* **[ToggleButton](#toggle-button)**: Selected/unselected toggle with all button variants + icon-only mode ([Docs](/docs/components/toggle-button))
* **[ToggleButtonGroup](#toggle-button-group)**: Single or multi-select toggle group, attached/detached layouts, orientation ([Docs](/docs/components/toggle-button-group))
* **[Meter](#meter)**: Value within a known range — disk usage, password strength, quotas ([Docs](/docs/components/meter))
* **[ProgressBar](#progress-bar)**: Linear progress, determinate + indeterminate, colors, custom formatting ([Docs](/docs/components/progress-bar))
* **[ProgressCircle](#progress-circle)**: Circular SVG progress with customizable track + fill circles ([Docs](/docs/components/progress-circle))
* **[Toolbar](#toolbar)**: Groups buttons, toggles, and separators with horizontal or vertical orientation ([Docs](/docs/components/toolbar))
### Drawer
Slide-out panel overlay with top/bottom/left/right placement, drag-to-dismiss gestures, and backdrop variants. Compound parts: `Trigger`, `Backdrop`, `Content`, `Dialog`, `Header`, `Heading`, `Body`, `Footer`, `Handle`, `CloseTrigger`.
```tsx
import {Button, Drawer} from "@heroui/react";
export function Basic() {
return (
Drawer Title
This is a bottom drawer built with React Aria's Modal component. It slides up from
the bottom of the screen with a smooth CSS transition.
);
}
```
**Placements:**
```tsx
import {Button, Drawer} from "@heroui/react";
export function Placements() {
const placements = ["bottom", "top", "left", "right"] as const;
return (
This drawer slides in from the {placement} edge of the screen.
{placement === "top" && }
))}
);
}
```
**With Form:**
```tsx
import {Button, Drawer, Input, Label, TextField} from "@heroui/react";
export function WithForm() {
return (
Edit Profile
);
}
```
### Toggle Button
Stateful toggle between selected and unselected. All button variants and sizes, icon-only mode, controlled or uncontrolled.
```tsx
import {Heart} from "@gravity-ui/icons";
import {ToggleButton} from "@heroui/react";
export function Basic() {
return (
Like
);
}
```
**Variants:**
```tsx
import {Heart} from "@gravity-ui/icons";
import {ToggleButton} from "@heroui/react";
export function Variants() {
return (
Default
Ghost
);
}
```
### Toggle Button Group
Single or multi-select toggle group. Attached (connected) and detached layouts, vertical orientation, full-width, and a `Separator` sub-component.
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Basic() {
return (
);
}
```
**Selection Mode:**
```tsx
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function SelectionMode() {
return (
Single selection
Left
Center
Right
Multiple selection
);
}
```
**Attached Mode:**
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Attached() {
return (
Attached (default)
Detached
);
}
```
### Meter
Value within a known range — disk usage, password strength, quotas. Compound parts: `Root`, `Output`, `Track`, `Fill`.
```tsx
import {Label, Meter} from "@heroui/react";
export function Basic() {
return (
);
}
```
**Colors:**
```tsx
import {Label, Meter} from "@heroui/react";
export function Colors() {
return (
);
}
```
### Progress Bar
Linear progress indicator with determinate + indeterminate states, color variants, sizes, and custom value display. Compound parts: `Root`, `Output`, `Track`, `Fill`.
```tsx
import {Label, ProgressBar} from "@heroui/react";
export function Basic() {
return (
);
}
```
**Indeterminate:**
```tsx
import {Label, ProgressBar} from "@heroui/react";
export function Indeterminate() {
return (
);
}
```
### Progress Circle
Circular SVG progress with `TrackCircle` and `FillCircle` sub-components for direct SVG control. Determinate + indeterminate states.
```tsx
import {ProgressCircle} from "@heroui/react";
export function Basic() {
return (
);
}
```
**Custom SVG:**
```tsx
import {ProgressCircle} from "@heroui/react";
export function CustomSvg() {
return (
);
}
```
### Toolbar
Groups buttons, toggle buttons, and separators into an accessible toolbar. Horizontal or vertical orientation, composes with `ButtonGroup` and `ToggleButtonGroup`.
```tsx
import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
import {
Button,
ButtonGroup,
Separator,
ToggleButton,
ToggleButtonGroup,
Toolbar,
} from "@heroui/react";
export function Basic() {
return (
);
}
```
**With Button Group:**
```tsx
import {
ArrowUturnCcwLeft,
ArrowUturnCwRight,
Bold,
Italic,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {
Button,
ButtonGroup,
Separator,
ToggleButton,
ToggleButtonGroup,
Toolbar,
} from "@heroui/react";
export function WithButtonGroup() {
return (
);
}
```
## Component Improvements
### ButtonGroup Enhancements
New `ButtonGroup.Separator` sub-component adds an explicit visual divider between buttons. Works in both horizontal and vertical orientations.
```tsx
import {
ChevronDown,
ChevronLeft,
ChevronRight,
CodeFork,
Ellipsis,
Picture,
Pin,
QrCode,
Star,
TextAlignCenter,
TextAlignJustify,
TextAlignLeft,
TextAlignRight,
ThumbsDown,
ThumbsUp,
Video,
} from "@gravity-ui/icons";
import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
export function Basic() {
return (
{/* Single button with dropdown */}
All commits from this branch will be added to the base branch
The 14 commits from this branch will be combined into one commit in the base
branch
The 14 commits from this branch will be rebased and added to the base branch
Name
Role
Email
{(user) => (
{user.name}{user.role}{user.email}
)}
);
}
```
### ButtonGroup Orientation
`ButtonGroup` accepts an `orientation` prop (`"horizontal"` | `"vertical"`) with correct border-radius handling and separator direction for both axes. The root element was upgraded from `
` to React Aria's `Group` for proper `role="group"` semantics.
```tsx
import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function Orientation() {
return (
Horizontal
Vertical
);
}
```
### ButtonGroup Focus Ring
Focus rings on grouped buttons now use `ring-inset` so they stay within button bounds instead of overlapping neighbors.
### Granular Component Imports
`@heroui/react` now supports per-component subpath entrypoints for more explicit imports ([#6301](https://github.com/heroui-inc/heroui/pull/6301)):
```tsx
// Before — root entrypoint
import { Button } from "@heroui/react";
// After — granular subpath import
import { Button } from "@heroui/react/button";
```
## Dependencies
Upgraded `react-aria-components` from v1.15.1 to v1.16.0 and related packages:
| Package | Old | New |
| ------------------------- | ------- | ------- |
| `react-aria-components` | 1.15.1 | 1.16.0 |
| `@react-aria/i18n` | 3.12.15 | 3.12.16 |
| `@react-aria/utils` | 3.33.0 | 3.33.1 |
| `@react-types/shared` | 3.33.0 | 3.33.1 |
| `@react-types/color` | 3.1.3 | 3.1.4 |
| `@internationalized/date` | 3.11.0 | 3.12.0 |
| `@react-stately/data` | 3.15.1 | 3.15.2 |
## Bug Fixes
* **InputGroup**: Focus styles now trigger only when the actual input/textarea is focused (`:has([data-slot]:focus)`) instead of any focusable child via `:focus-within` ([#6274](https://github.com/heroui-inc/heroui/pull/6274))
* **Avatar**: Fallback element inherits `border-radius` from the parent instead of hardcoding `rounded-full`, so `className` overrides apply correctly ([#6300](https://github.com/heroui-inc/heroui/pull/6300))
* **Modal & AlertDialog**: Backdrop click events no longer propagate through portals to parent elements ([#6297](https://github.com/heroui-inc/heroui/pull/6297))
* **Table**: Fixed header rounding and background color bleeding in Firefox ([#6298](https://github.com/heroui-inc/heroui/pull/6298))
## Links
* [Component Docs](/docs/react/components)
* [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6285](https://github.com/heroui-inc/heroui/pull/6285)
## Contributors
Thanks to everyone who contributed to this release!
# Introducing HeroUI v3
**Category**: react
**URL**: https://www.heroui.com/docs/react/releases/v3-0-0
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0.mdx
> A ground-up rewrite for React and React Native. 75+ web components, 37 native components, Tailwind CSS v4, React Aria, compound architecture, and built for AI-assisted development.
March 2026
Every component rewritten. Every animation moved to CSS. Styles decoupled from implementation. A brand-new React Native library. And tooling that treats AI assistants as a primary development interface.
## Overview
### React (Web)
75+ components. [React Aria Components](https://react-aria.adobe.com/) for accessibility. Tailwind CSS v4 + CSS variables for theming. Styles in a standalone package you can use with any framework.
[Jump to details](#compound-components)
### React Native
37 components with shared design tokens, compound pattern, unified animation API, and adaptive presentation modes. Built native on each platform with [Uniwind](https://uniwind.dev/) for Tailwind CSS v4 support.
[Jump to details](#heroui-native)
### HeroUI Pro
Premium components, templates, and AI tooling for React and React Native. Command palette, Kanban, DataGrid, Dashboard templates, and more. Pre-sale pricing at [heroui.pro](https://heroui.pro).
[Jump to details](#heroui-pro)
## Design Principles
**Composition over configuration:** v2 components were black boxes. v3 adopts compound components: every internal piece is a real element you can style, move, swap, or remove.
**Styles separated from implementation:** `@heroui/styles` is standalone CSS. `@heroui/react` handles behavior. Use the styles with React, plain HTML + Tailwind, or any framework. BEM class names make every slot customizable globally. Swap themes to change not just variables, but how components look and feel.
**Headless when you want it:** Remove the `@heroui/styles` import and you have a headless library. We maintain functionality and accessibility. You focus on your product.
**Performance by default:** v2 used Framer Motion for every animation. v3 replaced it with native CSS transitions and keyframes. Lighter bundles, GPU-accelerated, no JS animation runtime.
**Accessible from the start:** Migrated from React Aria hooks to [React Aria Components](https://react-aria.adobe.com/). Keyboard navigation, focus management, screen readers, and ARIA attributes are built in.
## Compound Components
Here's what the compound pattern looks like in practice:
```tsx
ProductDetails about this product.
Card content goes here.
```
More lines of code. But every piece is a real element you can style, move, or replace. The pattern runs through the entire library, from Accordion to Toast.
```tsx
import {
ArrowsRotateLeft,
Box,
ChevronDown,
CreditCard,
PlanetEarth,
Receipt,
ShoppingBag,
} from "@gravity-ui/icons";
import {Accordion} from "@heroui/react";
const items = [
{
content:
"Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.",
icon: ,
title: "How do I place an order?",
},
{
content:
"Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.",
icon: ,
title: "Can I modify or cancel my order?",
},
{
content: "We accept all major credit cards, including Visa, Mastercard, and American Express.",
icon: ,
title: "What payment methods do you accept?",
},
{
content:
"Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.",
icon: ,
title: "How much does shipping cost?",
},
{
content:
"Yes, we ship to most countries. Please check our shipping rates and policies for more information.",
icon: ,
title: "Do you ship internationally?",
},
{
content:
"If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.",
icon: ,
title: "How do I request a refund?",
},
];
export function Basic() {
return (
{items.map((item, index) => (
{item.icon ? (
{item.icon}
) : null}
{item.title}
{item.content}
))}
);
}
```
Each compound component shares state through React context. The root component creates a style context, and every child consumes it. You never pass classNames down manually:
```tsx
Profile updatedYour changes have been saved.
```
```tsx
import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
import React from "react";
export function Basic() {
return (
{/* Default - General information */}
New features available
Check out our latest updates including dark mode support and improved accessibility
features.
{/* Accent - Important information with action */}
Update available
A new version of the application is available. Please refresh to get the latest features
and bug fixes.
{/* Danger - Error with detailed steps */}
Unable to connect to server
We're experiencing connection issues. Please try the following:
Check your internet connection
Refresh the page
Clear your browser cache
{/* Without description */}
Profile updated successfully
{/* Custom indicator - Loading state */}
Processing your request
Please wait while we sync your data. This may take a few moments.
{/* Without close button */}
Scheduled maintenance
Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for
scheduled maintenance.
);
}
```
### Progressive Disclosure
Components support both simple and compound usage. Start with the one-liner. Add structure when you need it:
```tsx
// One line
// With icon
// Full control
```
```tsx
import {Button} from "@heroui/react";
export function Variants() {
return (
);
}
```
## Tailwind CSS v4 + CSS Variables
Theming runs on Tailwind CSS v4's native CSS variable layer with OKLCH colors. Every design token is a CSS variable:
```css
:root {
--background: oklch(0.9702 0 0);
--foreground: oklch(0.2103 0.0059 285.89);
--accent: oklch(0.6204 0.195 253.83);
--surface: oklch(100% 0 0);
--danger: oklch(0.6532 0.2328 25.74);
--radius: 0.5rem;
}
```
Tailwind's `@theme` directive maps these tokens to utility classes. `bg-accent`, `text-foreground`, `rounded-lg` all resolve to CSS variables. Light and dark mode switch by swapping the values:
```css
.dark, [data-theme="dark"] {
--background: oklch(12% 0.005 285.823);
--foreground: oklch(0.9911 0 0);
--surface: oklch(0.2103 0.0059 285.89);
}
```
No provider component. No JavaScript theme object. One CSS import, two lines:
```css
@import "tailwindcss";
@import "@heroui/styles";
```
### BEM Classes
Override any component globally through standard CSS:
```css
@layer components {
.button {
@apply font-semibold tracking-wide;
}
.button--primary {
@apply bg-blue-600 hover:bg-blue-700;
}
}
```
No className threading. No style prop gymnastics. Your design system overrides happen in CSS, where they belong.
### Custom Themes
Create a theme by defining your own token set. Everything cascades from there:
```css
@layer base {
[data-theme="ocean"] {
--accent: oklch(0.450 0.150 230);
--background: oklch(0.985 0.015 225);
--radius: 0.75rem;
--border: oklch(0.50 0.060 230 / 22%);
}
}
```
Apply it with a single data attribute:
```html
```
The [Theme Builder](/themes) generates these variables visually. Pick colors, adjust radius and spacing, export the CSS.
### Selective Imports
Import the full library or pick individual component styles:
```css
@import "tailwindcss";
@import "@heroui/styles/base" layer(base);
@import "@heroui/styles/themes/default" layer(theme);
@import "@heroui/styles/components/button.css" layer(components);
@import "@heroui/styles/components/card.css" layer(components);
```
Ship only the CSS you use. No unused component styles in production.
## Animation That Respects Users
All component animations use CSS transitions and keyframes tied to data attributes. Popovers fade in with `[data-entering]`. Buttons scale on `[data-pressed]`. Accordions expand with `[aria-hidden="false"]`.
```css
.popover[data-entering] {
@apply animate-in zoom-in-90 fade-in-0 duration-200;
}
.button:active,
.button[data-pressed="true"] {
transform: scale(0.97);
}
```
### Reduce Motion
Some users need animations disabled. HeroUI extends Tailwind's `motion-reduce:` variant to support both the system preference and a data attribute:
```css
.button {
@apply transition-colors motion-reduce:transition-none;
}
```
This responds to the native `prefers-reduced-motion: reduce` media query. It also responds to `data-reduce-motion="true"` on the HTML element, for app-level control:
```html
```
The data attribute overrides the system setting. Set `data-reduce-motion="false"` to force animations on, or remove the attribute to defer to the OS. Every animated component respects this. No opt-in required.
### Bring Your Own Animation Library
Framer Motion, Motion One, or any CSS animation library works alongside HeroUI's built-in transitions:
```tsx
import { motion } from "framer-motion";
import { Button } from "@heroui/react";
const MotionButton = motion(Button);
Animated
```
## 75+ Components for React
### Date & Time
Six components: Calendar, RangeCalendar, DateField, DatePicker, DateRangePicker, and TimeField. Built on React Aria's internationalized date library with Gregorian, Buddhist, Persian, and other calendar systems by default. Keyboard navigation, screen reader labels, and locale-aware formatting come free.
```tsx
"use client";
import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
export function Basic() {
return (
{(segment) => }
{(day) => {day}}
{(date) => }
{({year}) => }
);
}
```
```tsx
"use client";
import {RangeCalendar} from "@heroui/react";
export function Basic() {
return (
{(day) => {day}}
{(date) => }
);
}
```
### Color
Six color components: ColorPicker, ColorArea, ColorSlider, ColorField, ColorSwatch, and ColorSwatchPicker. Pick from a 2D area, adjust hue and alpha sliders, enter hex values, or select from a swatch palette.
```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Data
Need a table with sorting, row selection, column resizing, async loading, and custom cells? Table does all of that. Large datasets get virtualization via React Aria's `Virtualizer`. ListBox shares the same virtualization support.
```tsx
"use client";
import {Table, TableLayout, Virtualizer} from "@heroui/react";
interface User {
id: number;
name: string;
role: string;
email: string;
}
export function Virtualization() {
const roles = [
"Software Engineer",
"Senior Engineer",
"Staff Engineer",
"Product Manager",
"Designer",
"Data Analyst",
"QA Engineer",
"DevOps Engineer",
"Marketing Manager",
"Sales Representative",
];
const firstNames = [
"Emma",
"Liam",
"Olivia",
"Noah",
"Ava",
"James",
"Sophia",
"Oliver",
"Isabella",
"Lucas",
"Mia",
"Ethan",
"Charlotte",
"Mason",
"Amelia",
"Logan",
"Harper",
"Alexander",
"Ella",
"Benjamin",
];
const lastNames = [
"Smith",
"Johnson",
"Williams",
"Brown",
"Jones",
"Garcia",
"Miller",
"Davis",
"Rodriguez",
"Martinez",
"Anderson",
"Taylor",
"Thomas",
"Jackson",
"White",
"Harris",
"Clark",
"Lewis",
"Robinson",
"Walker",
];
function generateUsers(count: number): User[] {
const users: User[] = [];
for (let i = 0; i < count; i++) {
const firstName = firstNames[i % firstNames.length];
const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
const name = `${firstName} ${lastName}`;
users.push({
email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`,
id: i + 1,
name,
role: roles[i % roles.length] || "",
});
}
return users;
}
const virtualizedUsers = generateUsers(1000);
return (
Name
Role
Email
{(user) => (
{user.name}{user.role}{user.email}
)}
);
}
```
### Forms
Thirteen form components: TextField, Select, Autocomplete, ComboBox, Checkbox, CheckboxGroup, RadioGroup, Switch, InputOTP, NumberField, SearchField, Slider, and Fieldset. All integrate with React Aria's form validation. `isRequired`, `isInvalid`, and custom error messages through FieldError work across every one.
```tsx
import {Label, ListBox, Select} from "@heroui/react";
export function Default() {
return (
);
}
```
```tsx
import {InputOTP, Label, Link} from "@heroui/react";
export function Basic() {
return (
We've sent a code to a****@gmail.com
Didn't receive a code?
Resend
);
}
```
### Overlays
Seven overlay components. Drawer supports four placements with drag-to-dismiss gestures. Toast stacks notifications with auto-dismiss and promise support. Menu composes with submenus and sections. Plus Modal, AlertDialog, Popover, and Tooltip.
```tsx
import {Button, Drawer} from "@heroui/react";
export function Basic() {
return (
Drawer Title
This is a bottom drawer built with React Aria's Modal component. It slides up from
the bottom of the screen with a smooth CSS transition.
);
}
```
```tsx
"use client";
import {Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";
export function Default() {
return (
);
}
```
### Navigation
Tabs, Accordion, Breadcrumbs, Pagination, and Link. Tabs support horizontal and vertical orientation. Accordion supports single or multiple expanded panels.
```tsx
import {Tabs} from "@heroui/react";
export function Basic() {
return (
Overview
Analytics
Reports
View your project overview and recent activity.
Track your metrics and analyze performance data.
Generate and download detailed reports.
);
}
```
### Feedback
ProgressBar and ProgressCircle handle determinate + indeterminate states. Meter maps values to semantic colors: green for safe, yellow for cautious, red for critical. Skeleton and Spinner round out the set.
```tsx
import {Label, Meter} from "@heroui/react";
export function Colors() {
return (
);
}
```
```tsx
import {Skeleton} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Buttons & Toggles
Button, ButtonGroup, ToggleButton, ToggleButtonGroup, CloseButton, and Toolbar. ButtonGroup connects buttons with shared borders and supports vertical orientation. Toolbar groups buttons, toggles, and separators into an accessible `role="toolbar"` container.
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Attached() {
return (
Attached (default)
Detached
);
}
```
### Granular Imports
Import from the root or from per-component subpaths. Both work:
```tsx
// Root import
import { Button, Card, Table } from "@heroui/react";
// Subpath import
import { Button } from "@heroui/react/button";
import { Card } from "@heroui/react/card";
import { Table } from "@heroui/react/table";
```
## UI for Agents
More developers build by prompting than by reading API docs. HeroUI v3 accounts for that.
### MCP Server
The HeroUI MCP Server connects AI coding assistants (Cursor, Claude Code, VS Code Copilot, Windsurf, Zed) to component docs, props, source code, CSS styles, and theme variables. The AI reads the source of truth directly instead of guessing from training data.
```json
{
"mcpServers": {
"heroui-react": {
"command": "npx",
"args": ["-y", "@heroui/react-mcp@latest"]
}
}
}
```
Ask your AI assistant "update HeroUI to the latest version" and it will compare versions, review the changelog for breaking changes, and apply the necessary code updates automatically.
### Agent Skills
Installable knowledge packs for Cursor and Claude Code. Component patterns, variant usage, theming instructions, and upgrade guides. Preloaded context so the AI writes correct HeroUI code on the first attempt.
### LLMs.txt
Structured documentation files optimized for AI context windows. Published at `/llms.txt` and `/llms-components.txt`, these give any LLM-powered tool a machine-readable summary of HeroUI's API surface.
MCP server, agent skills, LLMs.txt. Three layers that give AI assistants the same access to HeroUI that human developers get from docs.
## HeroUI Native
HeroUI Native is a brand-new library shipping alongside v3 for the web. Different rendering engine, same mental model. Where the platforms diverge, the APIs adapt to feel native on each.
### Try It on Your Device
Scan the QR code with your device's camera or [Expo Go](https://expo.dev/go) to explore all 37 components live:
**[📱 Open Demo App in Expo Go](https://link.heroui.com/native-demo)**
**Android users:** If scanning the QR code redirects to a browser and shows a 404 error, open Expo Go first and use its built-in QR scanner instead.
### 37 Components
Forms, navigation, overlays, feedback, layout. From Button, Input, and Checkbox to Dialog, BottomSheet, Select, Toast, and InputOTP. Components follow the compound pattern:
```tsx
import { Dialog, Button } from "heroui-native";
```
### Familiar Across Platforms
If you know HeroUI on the web, most of that knowledge carries over. Familiar component names, dot notation, and prop patterns wherever possible. Where the platforms diverge (layout primitives, gestures, navigation), the APIs adapt to feel native. The mental model stays the same:
```tsx
// React (web)
Profile updatedYour changes have been saved.
// React Native — similar API, native behavior
Profile updatedYour changes have been saved.
```
Teams working on both web and mobile share knowledge and patterns. The learning curve between platforms is minimal, even where the components differ.
### Shared Design Tokens
Both platforms read from the same token set. Colors like `accent`, `surface`, `danger`, and `success` resolve identically across web and native. Your brand stays consistent without maintaining two separate systems.
```tsx
import { View, Text } from "react-native";
Card TitleConsistent on web and mobile.
```
Tailwind CSS v4 on both platforms. [Uniwind](https://uniwind.dev/) on native, standard Tailwind on web.
### Unified Animation API
Every animated native component exposes a single `animation` prop. Values, timing, spring configs, enter/exit transitions controlled from one place. Reanimated powers the math, but you never touch it directly:
```tsx
import { Switch } from "heroui-native";
```
Disable animations at any level. Per-component, per-tree, or globally:
```tsx
// Single component
// Entire subtree
...
// App-wide
```
Reduce Motion is automatic. When a user enables it in system settings, all animations stop. No extra code.
### Adaptive Presentation Modes
Popover, Select, and Menu switch between popover, bottom-sheet, and dialog with a single prop. Same component, different presentation depending on context:
```tsx
```
No other React Native component library does this.
### Granular Imports
Each native component has its own entry point. Import only what you use:
```tsx
import { HeroUINativeProvider } from "heroui-native/provider";
import { Button } from "heroui-native/button";
import { Card } from "heroui-native/card";
```
### AI Tooling for Native
HeroUI Native ships with its own MCP Server, agent skills, and LLMs.txt. Same tooling structure as the web library:
```json
{
"mcpServers": {
"heroui-native": {
"command": "npx",
"args": ["-y", "@heroui/native-mcp@latest"]
}
}
}
```
## HeroUI Pro
Alongside v3, the pre-sale of [HeroUI Pro](https://heroui.pro) is live. Premium components, templates, and AI tooling for both React and React Native.
### Pro Components
Components beyond the core library: Command palette, Kanban board, Stats dashboard, Filters, Agenda, DataGrid, and more. Accessibility, animations, and platform edge cases are handled. Will be available for both Web and Native.
### Templates
Full-page, responsive starter templates: Dashboard, Mail, Chat, and Finances. Real layouts with real structure. Start from something that works and customize from there.
### Advanced AI Tooling
Pro licenses include premium MCP servers and agent skills with Pro component docs, usage patterns, and upgrade paths baked in.
Pre-sale pricing is live. v2 Pro customers get an upgrade discount. Use the same email or contact support.
[See plans and pricing at heroui.pro](https://heroui.pro)
## Get Started
### React (Web)
```bash
npm i @heroui/styles @heroui/react
```
```bash
pnpm add @heroui/styles @heroui/react
```
```bash
yarn add @heroui/styles @heroui/react
```
```bash
bun add @heroui/styles @heroui/react
```
Add two lines to your CSS:
```css
@import "tailwindcss";
@import "@heroui/styles";
```
### React Native
```bash
npm install heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
See the [React docs](/docs/react/getting-started/quick-start) and [React Native docs](/docs/native/getting-started/quick-start) for full setup guides (peer dependencies, Uniwind config, and provider setup).
**Coming from HeroUI v2?** Follow the [Migration Guide](/docs/react/migration) for step-by-step upgrade instructions.
## Figma Kit v3
Every component in HeroUI v3 has a 1:1 match in Figma. Same variants, same naming, same structure. The kit uses auto layout throughout, Figma variables that map directly to code tokens (`--accent`, `--surface`, `--radius`), and Figma's new [slots](https://help.figma.com/hc/en-us/articles/38231200344599-Use-slots-to-build-flexible-components-in-Figma) for flexible component composition. Designers rearrange, swap, and customize parts the same way developers do in code.
[Get the Figma Kit](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
## Acknowledgments
[React Aria](https://react-aria.adobe.com/) gave us the accessibility layer we couldn't build as well on our own. Tailwind CSS v4's native CSS variable approach shaped the entire theming system. The compound component pattern was refined by studying how [Radix](https://www.radix-ui.com/), [Ark UI](https://ark-ui.com/), and [Base UI](https://base-ui.com/) solved composition.
Thanks to every community member who filed issues, tested betas, and gave feedback throughout the alpha and RC cycle. The library is better because of you.
## Links
* [React Docs](/docs/react/getting-started/quick-start)
* [React Native Docs](/docs/native/getting-started/quick-start)
* [Theme Builder](/themes)
* [MCP Server](/docs/ui-for-agents/mcp-server)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
# ButtonGroup
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/button-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/button-group.mdx
> Group related buttons together with consistent styling and spacing
## Import
```tsx
import { ButtonGroup, Button } from '@heroui/react';
```
### Usage
```tsx
import {
ChevronDown,
ChevronLeft,
ChevronRight,
CodeFork,
Ellipsis,
Picture,
Pin,
QrCode,
Star,
TextAlignCenter,
TextAlignJustify,
TextAlignLeft,
TextAlignRight,
ThumbsDown,
ThumbsUp,
Video,
} from "@gravity-ui/icons";
import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";
export function Basic() {
return (
{/* Single button with dropdown */}
All commits from this branch will be added to the base branch
The 14 commits from this branch will be combined into one commit in the base
branch
The 14 commits from this branch will be rebased and added to the base branch
{/* Individual buttons */}
{/* Previous/Next Button Group */}
{/* Content Selection Button Group */}
{/* Text Alignment Button Group */}
{/* Icon-Only Alignment Button Group */}
);
}
```
### Anatomy
Import the ButtonGroup component and access all parts using dot notation.
```tsx
import { ButtonGroup, Button } from '@heroui/react';
export default () => (
);
```
> **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.
### Variants
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Variants() {
return (
Primary
Secondary
Tertiary
Outline
Ghost
Danger
);
}
```
### Sizes
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Sizes() {
return (
Small
Medium (default)
Large
);
}
```
### Orientation
Use the `orientation` prop to arrange buttons horizontally or vertically.
```tsx
import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function Orientation() {
return (
Horizontal
Vertical
);
}
```
### With Icons
```tsx
import {Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function WithIcons() {
return (
With icons
Icon only buttons
);
}
```
### Full Width
```tsx
import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function Disabled() {
return (
All buttons disabled
Group disabled, but one button overrides
);
}
```
### Without Separator
Simply omit the `` component from your buttons.
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function WithoutSeparator() {
return (
);
}
```
## Related Components
* **Button**: Allows a user to perform an action
* **Dropdown**: Context menu with actions and options
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
```tsx
import { ButtonGroup, Button } from '@heroui/react';
function CustomButtonGroup() {
return (
);
}
```
### Customizing the component classes
To customize the ButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.button-group {
@apply gap-2 rounded-lg;
}
.button-group__separator {
@apply opacity-25;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):
#### Base Classes
* `.button-group` - Base button group container
* `.button-group--full-width` - Full width modifier
* `.button-group__separator` - Separator element between buttons
The ButtonGroup component automatically applies border radius to buttons:
* First button gets rounded left/start edge
* Last button gets rounded right/end edge
* Middle buttons have no border radius
* Single button gets full border radius on all edges
Add `` inside each Button (except the first) to show dividers between buttons.
## API Reference
### ButtonGroup Props
| Prop | Type | Default | Description |
| ------------- | --------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | Visual style variant applied to all buttons in the group |
| `size` | `'sm' \| 'md' \| 'lg'` | - | Size applied to all buttons in the group |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the button group |
| `fullWidth` | `boolean` | `false` | Whether the button group should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button components to group together |
### ButtonGroup.Separator Props
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### Notes
* ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
* **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
* Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}`
* The component automatically handles border radius between buttons
* Add `` inside each Button (except the first) to show dividers between buttons
* Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance
# Button
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/button.mdx
> A clickable button component with multiple variants and states
## Import
```tsx
import { Button } from '@heroui/react';
```
### Usage
```tsx
"use client";
import {Button} from "@heroui/react";
export function Basic() {
return ;
}
```
### Variants
```tsx
import {Button} from "@heroui/react";
export function Variants() {
return (
);
}
```
### With Icons
```tsx
import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function WithIcons() {
return (
);
}
```
### Icon Only
```tsx
import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function IconOnly() {
return (
);
}
```
### Loading
```tsx
"use client";
import {Button, Spinner} from "@heroui/react";
import React from "react";
export function Loading() {
return (
);
}
```
### Loading State
```tsx
"use client";
import {Paperclip} from "@gravity-ui/icons";
import {Button, Spinner} from "@heroui/react";
import React, {useState} from "react";
export function LoadingState() {
const [isLoading, setLoading] = useState(false);
const handlePress = () => {
setLoading(true);
setTimeout(() => setLoading(false), 2000);
};
return (
);
}
```
### Sizes
```tsx
import {Button} from "@heroui/react";
export function Sizes() {
return (
);
}
```
### Full Width
```tsx
import {Plus} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Social Buttons
```tsx
import {Button} from "@heroui/react";
import {Icon} from "@iconify/react";
export function Social() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {Button} from "@heroui/react";
export function CustomRenderFunction() {
return (
);
}
```
## Related Components
* **Popover**: Displays content in context with a trigger
* **Tooltip**: Contextual information on hover or focus
* **Form**: Form validation and submission handling
## Styling
### Passing Tailwind CSS classes
```tsx
import { Button } from '@heroui/react';
function CustomButton() {
return (
);
}
```
### Customizing the component classes
To customize the Button component classes, you can use the `@layer components` directive.
[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.
```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({
base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
defaultVariants: {
radius: "full",
variant: "primary",
},
extend: buttonVariants,
variants: {
radius: {
full: "rounded-full",
lg: "rounded-lg",
md: "rounded-md",
sm: "rounded-sm",
},
size: {
lg: "h-12 px-8",
md: "h-11 px-6",
sm: "h-10 px-4",
xl: "h-13 px-10",
},
variant: {
primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
},
},
});
type MyButtonVariants = VariantProps;
export type MyButtonProps = Omit &
MyButtonVariants & {className?: string};
function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
return ;
}
export function CustomVariants() {
return Custom Button;
}
```
### Adding Ripple Effect
The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).
```tsx
"use client";
import {Button} from "@heroui/react";
import {Ripple} from "m3-ripple";
import "m3-ripple/ripple.css";
export function RippleEffect() {
return (
);
}
```
### 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--outline`
* `.button--ghost`
* `.button--danger`
#### Modifier Classes
* `.button--icon-only`
* `.button--icon-only.button--sm`
* `.button--icon-only.button--lg`
### Interactive States
The button supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="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' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `fullWidth` | `boolean` | `false` | Whether the button should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
| `isPending` | `boolean` | `false` | Whether the button is in a loading state |
| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### 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 |
# CloseButton
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/close-button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/close-button.mdx
> Button component for closing dialogs, modals, or dismissing content
## Import
```tsx
import { CloseButton } from "@heroui/react";
```
### Usage
```tsx
import {CloseButton} from "@heroui/react";
export function Default() {
return ;
}
```
### With Custom Icon
```tsx
import {CircleXmark, Xmark} from "@gravity-ui/icons";
import {CloseButton} from "@heroui/react";
export function WithCustomIcon() {
return (
Custom Icon
Alternative Icon
);
}
```
### Interactive
```tsx
"use client";
import {CloseButton} from "@heroui/react";
import {useState} from "react";
export function Interactive() {
const [count, setCount] = useState(0);
return (
setCount(count + 1)}
/>
Clicked: {count} times
);
}
```
## Related Components
* **Alert**: Display important messages and notifications
* **AlertDialog**: Critical confirmations requiring user attention
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
```tsx
import {CloseButton} from "@heroui/react";
function CustomCloseButton() {
return Close;
}
```
### Customizing the component classes
To customize the CloseButton component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.close-button {
@apply bg-red-100 text-red-800 hover:bg-red-200;
}
.close-button--custom {
@apply rounded-full border-2 border-red-300;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The CloseButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)):
#### Base Classes
* `.close-button` - Base component styles
#### Variant Classes
* `.close-button--default` - Default variant
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Active/Pressed**: `:active` or `[data-pressed="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`
## API Reference
### CloseButton Props
| Prop | Type | Default | Description |
| ------------ | ----------------------- | --------------- | ------------------------------------------- |
| `variant` | `"default"` | `"default"` | Visual variant of the button |
| `children` | `ReactNode \| function` | `` | Content to display (defaults to close icon) |
| `onPress` | `() => void` | - | Handler called when the button is pressed |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
### React Aria Button Props
CloseButton extends all React Aria Button props. Common props include:
| Prop | Type | Description |
| ------------------ | -------- | --------------------------------------- |
| `aria-label` | `string` | Accessible label for screen readers |
| `aria-labelledby` | `string` | ID of element that labels the button |
| `aria-describedby` | `string` | ID of element that describes the button |
### RenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ------------ | --------- | ------------------------------ |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isPressed` | `boolean` | Whether the button is pressed |
| `isFocused` | `boolean` | Whether the button is focused |
| `isDisabled` | `boolean` | Whether the button is disabled |
# ToggleButtonGroup
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/toggle-button-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/toggle-button-group.mdx
> Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options.
## Import
```tsx
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
```
### Usage
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the ToggleButtonGroup component and access all parts using dot notation.
```tsx
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
export default () => (
First
Second
Third
);
```
### Sizes
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Sizes() {
return (
Small
Medium (default)
Large
);
}
```
### Orientation
```tsx
import {Bold, Italic, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Orientation() {
return (
Horizontal
Vertical
);
}
```
### Detached
Use `isDetached` to separate buttons with gaps instead of connecting them.
```tsx
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Attached() {
return (
Attached (default)
Detached
);
}
```
### Full Width
```tsx
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function FullWidth() {
return (
Left
Center
Right
);
}
```
### Selection Mode
Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles.
```tsx
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
Underline,
} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function SelectionMode() {
return (
Single selection
Left
Center
Right
Multiple selection
);
}
```
### Controlled
```tsx
"use client";
import type {Key} from "@heroui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [selectedKeys, setSelectedKeys] = useState(new Set(["bold"]));
return (
);
}
```
### Anatomy
Import the ListBox component and access all parts using dot notation.
```tsx
import { ListBox, Label, Description, Header } from '@heroui/react';
export default () => (
)
```
### With Sections
```tsx
"use client";
import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
export function WithSections() {
return (
alert(`Selected item: ${key}`)}
>
Actions
Create a new file
N
Make changes
EDanger zone
Move to trash
D
);
}
```
### Multi Select
```tsx
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
export function MultiSelect() {
return (
B
bob@heroui.com
F
fred@heroui.com
M
martha@heroui.com
);
}
```
### With Disabled Items
```tsx
"use client";
import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";
export function WithDisabledItems() {
return (
alert(`Selected item: ${key}`)}
>
Actions
Create a new file
N
Make changes
EDanger zone
Move to trash
D
);
}
```
### Custom Check Icon
```tsx
"use client";
import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
export function CustomCheckIcon() {
return (
B
bob@heroui.com
{({isSelected}) => (isSelected ? : null)}
F
fred@heroui.com
{({isSelected}) => (isSelected ? : null)}
M
martha@heroui.com
{({isSelected}) => (isSelected ? : null)}
);
}
```
### Controlled
```tsx
"use client";
import type {Selection} from "@heroui/react";
import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [selected, setSelected] = useState(new Set(["1"]));
const selectedItems = Array.from(selected);
return (
list.setSelectedKeys(keys)}
>
No team members}
>
{(user) => (
{user.fallback}
{user.name}
)}
Select team members for your project
{list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
Selected:
{Array.from(list.selectedKeys).map((key) => {
const user = list.getItem(key);
if (!user) return null;
return (
{user.fallback}{user.name}
);
})}
)}
);
}
```
### Custom Render Function
```tsx
"use client";
import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
selectionMode="single"
>
News
Travel
Gaming
Shopping
);
}
```
## Related Components
* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **ErrorMessage**: Displays validation error messages for components with validation support
## Styling
### Passing Tailwind CSS classes
```tsx
import { TagGroup, Tag, Label } from '@heroui/react';
function CustomTagGroup() {
return (
Custom Styled
);
}
```
### Customizing the component classes
To customize the TagGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.tag-group {
@apply flex flex-col gap-2;
}
.tag-group__list {
@apply flex flex-wrap gap-2;
}
.tag {
@apply rounded-full px-3 py-1;
}
.tag__remove-button {
@apply ml-1;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)):
#### Base Classes
* `.tag-group` - Base tag group container
* `.tag-group__list` - Container for the list of tags
* `.tag` - Base tag styles
* `.tag__remove-button` - Remove button trigger
#### Slot Classes
* `.tag-group [slot="description"]` - Description slot styles
* `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles
#### Size Classes
* `.tag--sm` - Small size tag
* `.tag--md` - Medium size tag (default)
* `.tag--lg` - Large size tag
#### Variant Classes
* `.tag--default` - Default variant
* `.tag--surface` - Surface variant with surface background
#### State Classes
* `.tag[data-selected="true"]` - Selected tag state
* `.tag[data-disabled="true"]` - Disabled tag state
* `.tag[data-hovered="true"]` - Hovered tag state
* `.tag[data-pressed="true"]` - Pressed tag state
* `.tag[data-focus-visible="true"]` - Focused tag state (keyboard focus)
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on tag
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on tag
* **Pressed**: `:active` or `[data-pressed="true"]` on tag
* **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on tag
* **Disabled**: `:disabled` or `[data-disabled="true"]` on tag
## API Reference
### TagGroup Props
| Prop | Type | Default | Description |
| --------------------- | ----------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | The type of selection that is allowed |
| `selectedKeys` | `Selection` | - | The currently selected keys (controlled) |
| `defaultSelectedKeys` | `Selection` | - | The initial selected keys (uncontrolled) |
| `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes |
| `disabledKeys` | `Iterable` | - | Keys of disabled tags |
| `isDisabled` | `boolean` | - | Whether the tag group is disabled |
| `onRemove` | `(keys: Set) => void` | - | Handler called when tags are removed |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the tags in the group |
| `variant` | `"default" \| "surface"` | `"default"` | Visual variant of the tags |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | TagGroup content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### TagGroup.List Props
| Prop | Type | Default | Description |
| ------------------ | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `items` | `Iterable` | - | The items to display in the tag list |
| `renderEmptyState` | `() => ReactNode` | - | Function to render when the list is empty |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | TagList content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Tag Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `id` | `Key` | - | The unique identifier for the tag |
| `textValue` | `string` | - | A string representation of the tag's content, used for accessibility |
| `isDisabled` | `boolean` | - | Whether the tag is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Tag content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
**Note**: `size`, `variant` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components.
### Tag.RemoveButton Props
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | ----------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Custom remove button content (defaults to close icon) |
**Note**: The `Tag.RemoveButton` component supports customization similar to `SearchField.ClearButton`. When `onRemove` is provided to `TagGroup`:
* **Auto-rendering**: If no custom `Tag.RemoveButton` is included in the `Tag` children, a default remove button is automatically rendered.
* **Custom button**: If a custom `Tag.RemoveButton` is provided as a child of `Tag`, it will be used instead of the auto-rendered button.
* **Custom icon**: You can pass custom content (like icons) to `Tag.RemoveButton` children to customize the appearance.
**Example - Auto-rendered (default)**:
```tsx
News
{/* Remove button is automatically rendered */}
```
**Example - Custom RemoveButton with icon**:
```tsx
News
```
**Example - Custom RemoveButton in render props**:
```tsx
{(renderProps) => (
<>
News
{!!renderProps.allowsRemoving && (
)}
)}
```
### RenderProps
When using render functions with TagGroup.List, these values are provided:
| Prop | Type | Description |
| ---------------- | --------- | ---------------------------------- |
| `isSelected` | `boolean` | Whether the tag is selected |
| `isDisabled` | `boolean` | Whether the tag is disabled |
| `isHovered` | `boolean` | Whether the tag is hovered |
| `isPressed` | `boolean` | Whether the tag is pressed |
| `isFocused` | `boolean` | Whether the tag is focused |
| `isFocusVisible` | `boolean` | Whether the tag has keyboard focus |
# ColorArea
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-area
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-area.mdx
> A 2D color picker that allows users to select colors from a gradient area
## Import
```tsx
import { ColorArea } from '@heroui/react';
```
### Usage
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaBasic() {
return (
);
}
```
### Anatomy
```tsx
import { ColorArea } from '@heroui/react';
export default () => (
);
```
### With Dots
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaWithDots() {
return (
);
}
```
### Controlled
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";
import {useState} from "react";
export function ColorAreaControlled() {
const [color, setColor] = useState(parseColor("#9B80FF"));
return (
Current color:{" "}
{color ? color.toString("hex") : "(empty)"}
);
}
```
### Color Space & Channels
Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel` props to customize which color channels are displayed on each axis.
```tsx
"use client";
import type {ColorSpace, Key} from "@heroui/react";
import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";
import {useState} from "react";
type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue";
interface ChannelOption {
id: ColorChannel;
name: string;
}
const colorSpaces: Array<{id: ColorSpace; name: string}> = [
{id: "rgb", name: "RGB"},
{id: "hsl", name: "HSL"},
{id: "hsb", name: "HSB"},
];
const channelsBySpace: Record = {
hsb: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "brightness", name: "Brightness"},
],
hsl: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "lightness", name: "Lightness"},
],
rgb: [
{id: "red", name: "Red"},
{id: "green", name: "Green"},
{id: "blue", name: "Blue"},
],
};
export function ColorAreaSpaceAndChannels() {
const [colorSpace, setColorSpace] = useState("hsb");
const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));
const channels = channelsBySpace[colorSpace];
const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
const defaultY =
colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";
const [xChannel, setXChannel] = useState(defaultX);
const [yChannel, setYChannel] = useState(defaultY);
const handleColorSpaceChange = (newSpace: Key | null) => {
if (!newSpace) return;
const space = newSpace as ColorSpace;
setColorSpace(space);
// Reset channels to appropriate defaults for the new color space
if (space === "rgb") {
setXChannel("blue");
setYChannel("green");
} else if (space === "hsl") {
setXChannel("saturation");
setYChannel("lightness");
} else {
setXChannel("saturation");
setYChannel("brightness");
}
};
// Filter out the other channel from options (can't have same channel on both axes)
const xChannelOptions = channels.filter((c) => c.id !== yChannel);
const yChannelOptions = channels.filter((c) => c.id !== xChannel);
return (
{/* Controls */}
{/* Color Space Select */}
{/* X Channel Select */}
{/* Y Channel Select */}
{/* Color Area */}
{/* Color Value Display */}
{color.toString(colorSpace)}
);
}
```
### Disabled
```tsx
import {ColorArea} from "@heroui/react";
export function ColorAreaDisabled() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorArea} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
} />
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorArea } from '@heroui/react';
function CustomColorArea() {
return (
);
}
```
### Customizing the component classes
To customize the ColorArea component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-area {
@apply rounded-3xl;
}
.color-area__thumb {
@apply size-5 border-4;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorArea component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)):
#### Base Classes
* `.color-area` - Base styles with gradient background and inner shadow
* `.color-area--show-dots` - Adds dot grid overlay for precision picking
#### Element Classes
* `.color-area__thumb` - Draggable thumb indicator
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Disabled**: `[data-disabled="true"]`
* **Focus**: `[data-focus-visible="true"]`
* **Dragging**: `[data-dragging="true"]` (thumb only)
## API Reference
### ColorArea Props
Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).
| Prop | Type | Default | Description |
| -------------- | ---------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes while dragging |
| `onChangeEnd` | `(color: Color) => void` | - | Handler called when the user stops dragging |
| `xChannel` | `ColorChannel` | `"saturation"` | Color channel for the horizontal axis |
| `yChannel` | `ColorChannel` | `"brightness"` | Color channel for the vertical axis |
| `colorSpace` | `ColorSpace` | - | The color space for the channels |
| `isDisabled` | `boolean` | `false` | Whether the color area is disabled |
| `showDots` | `boolean` | `false` | Whether to show the dot grid overlay |
| `className` | `string` | - | Additional CSS classes |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorArea.Thumb Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
# ColorField
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-field.mdx
> Color input field with labels, descriptions, and validation built on React Aria ColorField
## Import
```tsx
import { ColorField, parseColor } from '@heroui/react';
```
### Usage
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function Basic() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
);
}
```
### Anatomy
```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
export default () => (
)
```
> **ColorField** combines label, color input, description, and error into a single accessible component.
### With Description
```tsx
import {ColorField, Description, Label} from "@heroui/react";
export function WithDescription() {
return (
Enter your brand's primary colorUsed for highlights and CTAs
);
}
```
### Required Field
```tsx
import {ColorField, Description, Label} from "@heroui/react";
export function Required() {
return (
Required field
);
}
```
### Validation
Use `isInvalid` together with `FieldError` to surface validation messages.
```tsx
import {ColorField, FieldError, Label} from "@heroui/react";
export function Invalid() {
return (
Please enter a valid hex colorInvalid color format. Use hex (e.g., #FF5733)
);
}
```
### Channel Editing
ColorField supports editing individual color channels (hue, saturation, lightness, red, green, blue, alpha) by setting the `colorSpace` and `channel` props.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function ChannelEditing() {
const [color, setColor] = useState(parseColor("#7F007F"));
return (
);
}
```
### Controlled
Control the value to synchronize with other components or state management.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function Controlled() {
const [value, setValue] = useState(parseColor("#0485F7"));
return (
Current value: {value ? value.toString("hex") : "(empty)"}
);
}
```
### Disabled State
```tsx
"use client";
import {ColorField, Description, Label} from "@heroui/react";
export function Disabled() {
return (
This color field is disabledThis color field is disabled
);
}
```
### Full Width
```tsx
import {ColorField, Label} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### Variants
The ColorField.Group component supports two visual variants:
* **`primary`** (default) - Standard styling with shadow, suitable for most use cases
* **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
import {ColorField, Label} from "@heroui/react";
export function Variants() {
return (
);
}
```
### On Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
import {ColorField, Description, Label, Surface} from "@heroui/react";
export function OnSurface() {
return (
Select your theme color
);
}
```
### Form Example
Complete form example with validation and submission handling.
```tsx
"use client";
import type {Color} from "@heroui/react";
import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";
import {useState} from "react";
export function FormExample() {
const [value, setValue] = useState(null);
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (!value) {
return;
}
setIsSubmitting(true);
// Simulate API call
setTimeout(() => {
console.log("Color submitted:", {color: value.toString("hex")});
setValue(null);
setIsSubmitting(false);
}, 1500);
};
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import type {Color} from "@heroui/react";
import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";
export function CustomRenderFunction() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
}
value={color}
onChange={setColor}
>
}>
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover
## Styling
### Passing Tailwind CSS classes
```tsx
import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';
function CustomColorField() {
return (
Select your brand's primary color.
);
}
```
### Customizing the component classes
ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.
```css
@layer components {
.color-field {
@apply flex flex-col gap-1;
&[data-invalid="true"],
&[aria-invalid="true"] {
[data-slot="description"] {
@apply hidden;
}
}
[data-slot="label"] {
@apply w-fit;
}
[data-slot="description"] {
@apply px-1;
}
}
}
```
### CSS Classes
* `.color-field` – Root container with minimal styling (`flex flex-col gap-1`)
> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. ColorField.Group styling is documented below in the API Reference section.
### Interactive States
ColorField automatically manages these data attributes based on its state:
* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Required**: `[data-required="true"]` - Applied when `isRequired` is true
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
## API Reference
### ColorField Props
ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.
#### Base Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | Child components (Label, ColorField.Group, etc.) or render function. |
| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
| `fullWidth` | `boolean` | `false` | Whether the color field should take full width of its container |
| `id` | `string` | - | The element's unique identifier. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
#### Value Props
| Prop | Type | Default | Description |
| -------------- | -------------------------------- | ------- | -------------------------------------- |
| `value` | `Color \| null` | - | Current value (controlled). |
| `defaultValue` | `Color \| null` | - | Default value (uncontrolled). |
| `onChange` | `(color: Color \| null) => void` | - | Handler called when the value changes. |
#### Channel Props
| Prop | Type | Default | Description |
| ------------ | -------------- | ------- | ---------------------------------------------------------------------------- |
| `colorSpace` | `ColorSpace` | - | The color space that the color field operates in when `channel` is provided. |
| `channel` | `ColorChannel` | - | The color channel to edit. If not provided, edits hex value. |
#### Validation Props
| Prop | Type | Default | Description |
| -------------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
#### State Props
| Prop | Type | Default | Description |
| ----------------- | --------- | ------- | -------------------------------------------------- |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
| `isWheelDisabled` | `boolean` | - | Whether to disable changing the value with scroll. |
#### Form Props
| Prop | Type | Default | Description |
| ----------- | --------- | ------- | ---------------------------------------------------- |
| `name` | `string` | - | Name of the input element, for HTML form submission. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
#### Accessibility Props
| Prop | Type | Default | Description |
| ------------------ | -------- | ------- | ----------------------------------------------------- |
| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
| `aria-labelledby` | `string` | - | ID of elements that label this field. |
| `aria-describedby` | `string` | - | ID of elements that describe this field. |
| `aria-details` | `string` | - | ID of elements with additional details. |
### Composition Components
ColorField works with these separate components that should be imported and used directly:
* **Label** - Field label component from `@heroui/react`
* **ColorField.Group** - Color input group component (documented below)
* **ColorField.Input** - Input element within ColorField.Group
* **ColorField.Prefix** / **ColorField.Suffix** - Prefix and suffix slots for the input group
* **ColorSwatch** - Color preview component from `@heroui/react`
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`
Each of these components has its own props API. Use them directly within ColorField for composition:
```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';
Select your brand's primary color.Please enter a valid color.
```
### Color Types
ColorField uses `Color` objects from React Aria Components:
```tsx
import {parseColor} from '@heroui/react';
// Parse from hex string
const color = parseColor('#3B82F6');
// Get hex string from color
const hex = color.toString('hex'); // "#3b82f6"
// Get RGB values
const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"
// Use in ColorField
{/* ... */}
```
### ColorFieldRenderProps
When using render props with `className`, `style`, or `children`, these values are available:
| Prop | Type | Description |
| ---------------- | --------- | ----------------------------------------------- |
| `isDisabled` | `boolean` | Whether the field is disabled. |
| `isInvalid` | `boolean` | Whether the field is currently invalid. |
| `isReadOnly` | `boolean` | Whether the field is read-only. |
| `isRequired` | `boolean` | Whether the field is required. |
| `isFocused` | `boolean` | Whether the field is currently focused. |
| `isFocusWithin` | `boolean` | Whether any child element is focused. |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
### ColorField.Group Props
ColorField.Group accepts all props from React Aria's `Group` component plus the following:
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `fullWidth` | `boolean` | `false` | Whether the color input group should take full width of its container |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorField.Input Props
ColorField.Input accepts all props from React Aria's `Input` component plus the following:
| Prop | Type | Default | Description |
| ------------- | -------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `placeholder` | `string` | - | Placeholder text shown when empty. |
### ColorField.Prefix Props
ColorField.Prefix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the prefix slot. |
### ColorField.Suffix Props
ColorField.Suffix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the suffix slot. |
## ColorField.Group Styling
### Customizing the component classes
The base classes power every instance. Override them once with `@layer components`.
```css
@layer components {
.color-input-group {
@apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
&:hover,
&[data-hovered="true"] {
@apply bg-field-hover;
}
&[data-focus-within="true"],
&:focus-within {
@apply status-focused-field;
}
&[data-invalid="true"] {
@apply status-invalid-field;
}
&[data-disabled="true"],
&[aria-disabled="true"] {
@apply status-disabled;
}
}
.color-input-group__input {
@apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
}
.color-input-group__prefix,
.color-input-group__suffix {
@apply shrink-0 text-field-placeholder flex items-center;
}
}
```
### ColorField.Group CSS Classes
* `.color-input-group` – Root container styling
* `.color-input-group__input` – Input wrapper styling
* `.color-input-group__prefix` – Prefix element styling
* `.color-input-group__suffix` – Suffix element styling
### ColorField.Group Interactive States
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
* **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
* **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
# ColorPicker
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-picker.mdx
> A composable color picker that synchronizes color value between multiple color components
## Import
```tsx
import {
ColorPicker,
ColorArea,
ColorSlider,
ColorSwatch,
ColorField,
ColorSwatchPicker,
} from '@heroui/react';
```
### Usage
```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
The ColorPicker is a composable component that combines multiple color components:
```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
export default () => (
);
```
### Controlled
```tsx
"use client";
import {
Button,
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
parseColor,
} from "@heroui/react";
import {Icon} from "@iconify/react";
import {useState} from "react";
export function Controlled() {
const [color, setColor] = useState(parseColor("#325578"));
const colorPresets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
const shuffleColor = () => {
const randomHue = Math.floor(Math.random() * 360);
const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
};
return (
{colorPresets.map((preset) => (
))}
Selected: {color.toString("hex")}
);
}
```
### With Swatches
```tsx
import {
ColorArea,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
} from "@heroui/react";
export function WithSwatches() {
const presets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
return (
{presets.map((preset) => (
))}
);
}
```
### With Fields
Use `ColorField` to allow users to edit individual color channel values with a `Select` to switch between color spaces.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@heroui/react";
import {
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
Label,
ListBox,
Select,
} from "@heroui/react";
import {useState} from "react";
export function WithFields() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness"],
hsl: ["hue", "saturation", "lightness"],
rgb: ["red", "green", "blue"],
};
return (
);
}
```
### With Sliders
Use multiple `ColorSlider` components to adjust each channel of a color value.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@heroui/react";
import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react";
import {useState} from "react";
export function WithSliders() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness", "alpha"],
hsl: ["hue", "saturation", "lightness", "alpha"],
rgb: ["red", "green", "blue", "alpha"],
};
return (
{colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
// @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
))}
);
}
```
## Related Components
* **ColorArea**: 2D color picker for selecting colors from a gradient area
* **ColorSlider**: Slider for adjusting individual color channel values
* **ColorSwatch**: Visual preview of a color value
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';
function CustomColorPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorPicker component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-picker {
@apply inline-flex;
}
.color-picker__trigger {
@apply inline-flex items-center gap-4 rounded-lg;
}
.color-picker__popover {
@apply p-4 rounded-xl;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)):
#### Base Classes
* `.color-picker` - Base container
* `.color-picker__trigger` - Trigger button
* `.color-picker__popover` - Popover container
### 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 `[data-disabled="true"]`
## API Reference
### ColorPicker Props
Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------ | ------- | ---------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes |
| `children` | `React.ReactNode` | - | Content of the color picker (Trigger, Popover, etc.) |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Trigger Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------- | ------- | ------------------------------ |
| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | Trigger content or render prop |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Popover Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | --------------- | ------------------------ |
| `placement` | `Placement` | `"bottom left"` | Placement of the popover |
| `children` | `React.ReactNode` | - | Popover content |
| `className` | `string` | - | Additional CSS classes |
### Related Types
#### Color
Represents a color value. See [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color) for full API.
| Method | Description |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `toString(format)` | Converts the color to a string in the given format (hex, rgb, hsl, hsb, css) |
| `toFormat(format)` | Converts the color to the given format and returns a new Color object |
| `getChannelValue(channel)` | Returns the numeric value for a given channel |
| `withChannelValue(channel, value)` | Sets the numeric value for a channel and returns a new Color |
#### parseColor
```tsx
import { parseColor } from 'react-aria-components';
// Parse from string
const color = parseColor('#ff0000');
const hslColor = parseColor('hsl(0, 100%, 50%)');
```
# ColorSlider
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-slider.mdx
> A color slider allows users to adjust an individual channel of a color value
## Import
```tsx
import { ColorSlider, Label } from '@heroui/react';
```
### Usage
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the ColorSlider component and access all parts using dot notation.
```tsx
import { ColorSlider, Label } from '@heroui/react';
export default () => (
)
```
### Vertical
```tsx
import {ColorSlider} from "@heroui/react";
export function Vertical() {
return (
);
}
```
### Disabled
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Controlled
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Controlled() {
const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));
return (
Current color: {color.toString("hsl")}
);
}
```
### HSL Channels
Use multiple ColorSliders to control different channels of a color value. The sliders can share the same color value to create a complete color picker.
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Channels() {
const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));
return (
Current color: {color.toString("hsl")}
);
}
```
### Alpha Channel
The alpha channel slider shows a transparency checkerboard pattern to help visualize the transparency level.
```tsx
import {ColorSlider, Label} from "@heroui/react";
export function AlphaChannel() {
return (
);
}
```
### RGB Channels
You can also use RGB color space with red, green, and blue channels.
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function RGBChannels() {
const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));
return (
Current color: {color.toString("rgb")}
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSlider, Label} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorSlider, Label } from '@heroui/react';
function CustomColorSlider() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSlider component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-slider {
@apply flex flex-col gap-2;
}
.color-slider__output {
@apply text-muted text-sm;
}
.color-slider__track {
@apply relative h-5 w-full rounded-full;
}
.color-slider__thumb {
@apply size-4 rounded-full border-3 border-white shadow-overlay;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSlider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)):
#### Base Classes
* `.color-slider` - Base slider container
* `.color-slider__output` - Output element displaying current value
* `.color-slider__track` - Track element with color gradient
* `.color-slider__thumb` - Thumb element showing current color
#### State Classes
* `.color-slider[data-disabled="true"]` - Disabled slider state
* `.color-slider[data-orientation="vertical"]` - Vertical orientation
* `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
* `.color-slider__thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.color-slider__thumb[data-disabled="true"]` - Disabled thumb state
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on thumb
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
* **Dragging**: `[data-dragging="true"]` on thumb
* **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
## API Reference
### ColorSlider Props
Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `channel` | `ColorChannel` | - | The color channel that the slider manipulates (hue, saturation, lightness, brightness, alpha, red, green, blue) |
| `colorSpace` | `ColorSpace` | - | The color space (hsl, hsb, rgb). Defaults to the color space of the value |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when the value changes during dragging |
| `onChangeEnd` | `(value: Color) => void` | - | Handler called when dragging ends |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
| `isDisabled` | `boolean` | - | Whether the slider is disabled |
| `name` | `string` | - | The name of the input element for form submission |
| `aria-label` | `string` | - | Accessibility label for the slider |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSlider.Output Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | --------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
### ColorSlider.Track Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
### ColorSlider.Thumb Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
### RenderProps
When using render functions, these values are provided:
| Prop | Type | Description |
| ------------- | ---------------------------- | ------------------------------ |
| `state` | `ColorSliderState` | The state of the color slider |
| `color` | `Color` | The current color value |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
| `isDisabled` | `boolean` | Whether the slider is disabled |
## Accessibility
The ColorSlider component implements the ARIA slider pattern and provides:
* Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
* Screen reader announcements for value changes
* Proper focus management
* Support for disabled states
* HTML form integration via hidden input elements
* Internationalization support with locale-aware value formatting
For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
# ColorSwatchPicker
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-swatch-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-swatch-picker.mdx
> A list of color swatches that allows users to select a color from a predefined palette.
## Import
```tsx
import { ColorSwatchPicker, parseColor } from '@heroui/react';
```
### Usage
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Basic() {
return (
{colors.map((color) => (
))}
);
}
```
### Anatomy
Import the ColorSwatchPicker component and access all parts using dot notation.
```tsx
import { ColorSwatchPicker } from '@heroui/react';
export default () => (
);
```
### Variants
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Variants() {
return (
);
}
```
### Disabled
```tsx
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Disabled() {
return (
{colors.map((color) => (
))}
);
}
```
### Custom Indicator
```tsx
import {HeartFill} from "@gravity-ui/icons";
import {ColorSwatchPicker} from "@heroui/react";
export function CustomIndicator() {
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
return (
{colors.map((color) => (
))}
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSwatchPicker} from "@heroui/react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function CustomRenderFunction() {
return (
}>
{colors.map((color) => (
))}
);
}
```
## Related Components
* **ColorSwatch**: Visual preview of a color value
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area
## Styling
### Passing Tailwind CSS classes
You can customize the ColorSwatchPicker using className props:
```tsx
import { ColorSwatchPicker } from '@heroui/react';
function CustomColorSwatchPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSwatchPicker component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-swatch-picker {
@apply gap-4;
}
.color-swatch-picker__item {
@apply shadow-md;
}
.color-swatch-picker__swatch {
@apply border-2 border-white;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSwatchPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)):
#### Base & Structure
* `.color-swatch-picker` - Base container (flex layout)
* `.color-swatch-picker__item` - Individual swatch item wrapper
* `.color-swatch-picker__swatch` - The color swatch visual element
#### Size Classes
* `.color-swatch-picker--xs` - Extra small (16px)
* `.color-swatch-picker--sm` - Small (24px)
* `.color-swatch-picker--md` - Medium (32px, default)
* `.color-swatch-picker--lg` - Large (36px)
* `.color-swatch-picker--xl` - Extra large (40px)
#### Shape Variants
* `.color-swatch-picker--circle` - Circle shape (default)
* `.color-swatch-picker--square` - Square shape with rounded corners
#### Layout Classes
* `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
* `.color-swatch-picker--stack` - Vertical stacked layout
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` - Scale up to 1.1 (only when not selected)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Focus ring
* **Selected**: `[data-selected="true"]` - Inner border with same color as swatch
* **Disabled**: `[data-disabled="true"]` - Reduced opacity
## API Reference
### ColorSwatchPicker Props
Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current selected color (controlled) |
| `defaultValue` | `string \| Color` | - | The default selected color (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when selection changes |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatches |
| `variant` | `"circle" \| "square"` | `"circle"` | Shape of the swatches |
| `layout` | `"grid" \| "stack"` | `"grid"` | Layout direction |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Item elements |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Item Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- |
| `color` | `string \| Color` | **Required** | The color of the swatch |
| `isDisabled` | `boolean` | `false` | Whether the item is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch element |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Swatch Props
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### parseColor
The `parseColor` function is re-exported from React Aria Components for convenience:
```tsx
import { parseColor } from '@heroui/react';
// Parse hex color
const red = parseColor('#ff0000');
// Parse RGB
const green = parseColor('rgb(0, 255, 0)');
// Parse HSL
const blue = parseColor('hsl(240, 100%, 50%)');
```
# ColorSwatch
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/color-swatch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-swatch.mdx
> A visual preview of a color value with accessibility support
## Import
```tsx
import { ColorSwatch } from '@heroui/react';
```
### Usage
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchBasic() {
return (
);
}
```
### Sizes
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchSizes() {
return (
);
}
```
### Shapes
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchShapes() {
return (
);
}
```
### Transparency
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchTransparency() {
return (
);
}
```
### Custom Styles with Render Props
You can use the `style` render props to access the color value and create custom visual effects.
```tsx
"use client";
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchCustomStyles() {
const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];
return (
);
}
```
### Accessibility
Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.
```tsx
import {ColorSwatch} from "@heroui/react";
export function ColorSwatchAccessibility() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSwatch} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
/>
}
/>
}
/>
}
/>
}
/>
);
}
```
## Related Components
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area
## Styling
### Passing Tailwind CSS classes
```tsx
import {ColorSwatch} from '@heroui/react';
function CustomColorSwatch() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSwatch component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-swatch {
@apply border-2 border-white;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSwatch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)):
#### Base Classes
* `.color-swatch` - Base swatch styles with checkered background for transparency
#### Shape Classes
* `.color-swatch--circle` - Circular shape (default)
* `.color-swatch--square` - Square shape with rounded corners
#### Size Classes
* `.color-swatch--xs` - Extra small (16px)
* `.color-swatch--sm` - Small (24px)
* `.color-swatch--md` - Medium (32px, default)
* `.color-swatch--lg` - Large (36px)
* `.color-swatch--xl` - Extra large (40px)
## API Reference
### ColorSwatch Props
| Prop | Type | Default | Description |
| ------------ | ------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------- |
| `color` | `string \| Color` | - | The color value to display (hex, rgb, hsl, etc.) |
| `colorName` | `string` | - | Accessible name for the color (overrides auto-generated description) |
| `className` | `string` | - | Additional CSS classes |
| `shape` | `"circle" \| "square"` | `"circle"` | Shape of the swatch |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatch |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function with access to color |
| `aria-label` | `string` | - | Accessible label for the swatch |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Style Render Props
When using the `style` prop as a function, you receive render props with access to the color:
```tsx
({
boxShadow: `0 4px 14px ${color.toString("css")}80`,
})}
/>
```
The `color` object provides methods like:
* `color.toString("css")` - Returns CSS color string
* `color.toString("hex")` - Returns hex color string
* `color.getChannelValue("alpha")` - Returns alpha channel value
# Slider
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(controls)/slider.mdx
> A slider allows a user to select one or more values within a range
## Import
```tsx
import { Slider } from '@heroui/react';
```
### Usage
```tsx
import {Label, Slider} from "@heroui/react";
export function Default() {
return (
);
}
```
### Anatomy
Import the Slider component and access all parts using dot notation.
```tsx
import { Slider, Label } from '@heroui/react';
export default () => (
)
```
### Range Slider Anatomy
```tsx
import { Slider, Label } from '@heroui/react';
export default () => (
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
)
```
### Vertical
```tsx
import {Label, Slider} from "@heroui/react";
export function Vertical() {
return (
);
}
```
### Range
```tsx
"use client";
import {Label, Slider} from "@heroui/react";
export function Range() {
return (
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
);
}
```
### Disabled
```tsx
import {Label, Slider} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {Label, Slider} from "@heroui/react";
export function CustomRenderFunction() {
return (
}
>
);
}
```
## Related Components
* **Label**: Accessible label for form controls
* **Form**: Form validation and submission handling
* **Description**: Helper text for form fields
## Styling
### Passing Tailwind CSS classes
```tsx
import { Slider, Label } from '@heroui/react';
function CustomSlider() {
return (
);
}
```
### Customizing the component classes
To customize the Slider component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.slider {
@apply flex flex-col gap-2;
}
.slider__output {
@apply text-muted-fg text-sm;
}
.slider-track {
@apply relative h-2 w-full rounded-full bg-surface-secondary;
}
.slider-fill {
@apply absolute h-full rounded-full bg-accent;
}
.slider-thumb {
@apply size-4 rounded-full bg-accent border-2 border-background;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)):
#### Base Classes
* `.slider` - Base slider container
* `.slider__output` - Output element displaying current value(s)
* `.slider-track` - Track element containing fill and thumbs
* `.slider-fill` - Fill element showing selected range
* `.slider-thumb` - Individual thumb element
#### State Classes
* `.slider[data-disabled="true"]` - Disabled slider state
* `.slider[data-orientation="vertical"]` - Vertical orientation
* `.slider-thumb[data-dragging="true"]` - Thumb being dragged
* `.slider-thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.slider-thumb[data-disabled="true"]` - Disabled thumb state
* `.slider-track[data-fill-start="true"]` - Fill starts at beginning
* `.slider-track[data-fill-end="true"]` - Fill ends at end
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
* **Hover**: `:hover` or `[data-hovered="true"]` on thumb
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
* **Dragging**: `[data-dragging="true"]` on thumb
* **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
## API Reference
### Slider Props
| Prop | Type | Default | Description |
| ----------------- | ------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value` | `number \| number[]` | - | The current value (controlled) |
| `defaultValue` | `number \| number[]` | - | The default value (uncontrolled) |
| `onChange` | `(value: number \| number[]) => void` | - | Handler called when the value changes |
| `onChangeEnd` | `(value: number \| number[]) => void` | - | Handler called when dragging ends |
| `minValue` | `number` | `0` | The slider's minimum value |
| `maxValue` | `number` | `100` | The slider's maximum value |
| `step` | `number` | `1` | The slider's step value |
| `formatOptions` | `Intl.NumberFormatOptions` | - | The display format of the value label |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
| `isDisabled` | `boolean` | - | Whether the slider is disabled |
| `aria-label` | `string` | - | Accessibility label for the slider |
| `aria-labelledby` | `string` | - | ID of element that labels the slider |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Output Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Track Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Slider.Fill Props
| Prop | Type | Default | Description |
| ----------- | --------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties` | - | Inline styles |
### Slider.Thumb Props
| Prop | Type | Default | Description |
| ------------ | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- |
| `index` | `number` | `0` | Index of the thumb within the slider |
| `isDisabled` | `boolean` | - | Whether this thumb is disabled |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### RenderProps
When using render functions with Slider.Output or Slider.Track, these values are provided:
| Prop | Type | Description |
| -------------------- | ---------------------------- | -------------------------------------------------------- |
| `state` | `SliderState` | The state of the slider |
| `values` | `number[]` | Values managed by the slider by thumb index |
| `getThumbValueLabel` | `(index: number) => string` | Returns the string label for the specified thumb's value |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
| `isDisabled` | `boolean` | Whether the slider is disabled |
## Examples
### Basic Usage
```tsx
import { Slider, Label } from '@heroui/react';
```
### Range Slider
```tsx
import { Slider, Label } from '@heroui/react';
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
```
### Controlled Value
```tsx
import { Slider, Label } from '@heroui/react';
import { useState } from 'react';
function ControlledSlider() {
const [value, setValue] = useState(25);
return (
<>
Current value: {value}
);
}
```
### Custom Value Formatting
```tsx
import { Slider, Label } from '@heroui/react';
```
### Vertical Orientation
```tsx
import { Slider, Label } from '@heroui/react';
```
### Custom Output Display
```tsx
import { Slider, Label } from '@heroui/react';
{({state}) =>
state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ')
}
{({state}) => (
<>
{state.values.map((_, i) => (
))}
)}
```
## Accessibility
The Slider component implements the ARIA slider pattern and provides:
* Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
* Screen reader announcements for value changes
* Proper focus management
* Support for disabled states
* HTML form integration via hidden input elements
* Internationalization support with locale-aware value formatting
* Right-to-left (RTL) language support
For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html).
# Switch
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/switch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(controls)/switch.mdx
> A toggle switch component for boolean states
## Import
```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';
```
### Usage
```tsx
import {Label, Switch} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the Switch component and access all parts using dot notation.
```tsx
import { Switch, Label, Description } from '@heroui/react';
export default () => (
{/* Optional */}
{/* Optional */}
);
```
For grouping multiple switches, use the `SwitchGroup` component:
```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';
export default () => (
);
```
### Disabled
```tsx
import {Label, Switch} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### Default Selected
```tsx
import {Label, Switch} from "@heroui/react";
export function DefaultSelected() {
return (
);
}
```
### Controlled
```tsx
"use client";
import {Label, Switch} from "@heroui/react";
import React from "react";
export function Controlled() {
const [isSelected, setIsSelected] = React.useState(false);
return (
Switch is {isSelected ? "on" : "off"}
);
}
```
### Without Label
```tsx
import {Switch} from "@heroui/react";
export function WithoutLabel() {
return (
);
}
```
### Sizes
```tsx
import {Label, Switch} from "@heroui/react";
export function Sizes() {
return (
);
}
```
### Label Position
```tsx
import {Label, Switch} from "@heroui/react";
export function LabelPosition() {
return (
);
}
```
### With Icons
```tsx
"use client";
import {
BellFill,
BellSlash,
Check,
Microphone,
MicrophoneSlash,
Moon,
Power,
Sun,
VolumeFill,
VolumeSlashFill,
} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";
export function WithIcons() {
const icons = {
check: {
off: Power,
on: Check,
selectedControlClass: "bg-green-500/80",
},
darkMode: {
off: Moon,
on: Sun,
selectedControlClass: "",
},
microphone: {
off: Microphone,
on: MicrophoneSlash,
selectedControlClass: "bg-red-500/80",
},
notification: {
off: BellSlash,
on: BellFill,
selectedControlClass: "bg-purple-500/80",
},
volume: {
off: VolumeFill,
on: VolumeSlashFill,
selectedControlClass: "bg-blue-500/80",
},
};
return (
);
}
```
### Sizes
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeSizes() {
const sizes = ["sm", "md", "lg"] as const;
return (
{sizes.map((size) => (
JD
5
))}
);
}
```
### Variants
```tsx
import {Avatar, Badge, Separator} from "@heroui/react";
import React from "react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeVariants() {
const variants = ["primary", "secondary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
{variants.map((variant, index) => (
{variant}
{colors.map((color) => (
JD
5
))}
{index < variants.length - 1 && }
))}
);
}
```
### Placements
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgePlacements() {
const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
return (
{placements.map((placement) => (
JD{placement}
))}
);
}
```
### With Content
Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.
```tsx
import {Bell} from "@gravity-ui/icons";
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeWithContent() {
return (
JD
5
JD
New
JD
99+
JD
);
}
```
### Dot Badge
Empty badges act as status indicators — useful for online/offline states or activity signals.
```tsx
import {Avatar, Badge} from "@heroui/react";
const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg";
export function BadgeDot() {
const colors = ["accent", "success", "warning", "danger"] as const;
return (
{colors.map((color) => (
JD
))}
);
}
```
## Related Components
* **Avatar**: Display user profile images
* **Chip**: Compact elements for tags and filters
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import {Badge, Avatar} from '@heroui/react';
function CustomBadge() {
return (
99+
);
}
```
### Customizing the component classes
To customize the Badge component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.badge {
@apply rounded-full text-xs;
}
.badge__label {
@apply font-semibold;
}
.badge--accent {
@apply shadow-sm;
}
}
```
HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Badge component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)):
#### Base Classes
* `.badge` - Base badge container styles
* `.badge__label` - Label text slot styles
* `.badge-anchor` - Positioning wrapper for the anchored element
#### Color Classes
* `.badge--accent` - Accent color variant
* `.badge--danger` - Danger color variant
* `.badge--default` - Default color variant
* `.badge--success` - Success color variant
* `.badge--warning` - Warning color variant
#### Variant Classes
* `.badge--primary` - Primary variant with filled background
* `.badge--secondary` - Secondary variant with default background
* `.badge--soft` - Soft variant with lighter background
#### Size Classes
* `.badge--sm` - Small size
* `.badge--md` - Medium size (default)
* `.badge--lg` - Large size
#### Placement Classes
* `.badge--top-right` - Position at top-right corner (default)
* `.badge--top-left` - Position at top-left corner
* `.badge--bottom-right` - Position at bottom-right corner
* `.badge--bottom-left` - Position at bottom-left corner
#### Compound Variant Classes
Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:
**Primary Variants:**
* `.badge--primary.badge--accent` - Primary accent with filled background
* `.badge--primary.badge--default` - Primary default with filled background
* `.badge--primary.badge--success` - Primary success with filled background
* `.badge--primary.badge--warning` - Primary warning with filled background
* `.badge--primary.badge--danger` - Primary danger with filled background
**Soft Variants:**
* `.badge--soft.badge--accent` - Soft accent with lighter background
* `.badge--soft.badge--default` - Soft default with lighter background
* `.badge--soft.badge--success` - Soft success with lighter background
* `.badge--soft.badge--warning` - Soft warning with lighter background
* `.badge--soft.badge--danger` - Soft danger with lighter background
## API Reference
### Badge Props
| Prop | Type | Default | Description |
| ----------- | -------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the badge (text, number, or icon). When omitted, renders as a dot. |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the badge |
| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |
### Badge.Anchor Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | --------------------------------------------------------- |
| `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
| `className` | `string` | - | Additional CSS classes for the anchor wrapper |
### Badge.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# Chip
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/chip
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(data-display)/chip.mdx
> Small informational badges for displaying labels, statuses, and categories
## Import
```tsx
import { Chip } from '@heroui/react';
```
## Anatomy
Import the Chip component and access all parts using dot notation.
> Plain-text children are automatically wrapped in ``.
```tsx
Label text
```
### Usage
```tsx
import {Chip} from "@heroui/react";
export function ChipBasic() {
return (
DefaultAccentSuccessWarningDanger
);
}
```
### Variants
```tsx
import {CircleDashed} from "@gravity-ui/icons";
import {Chip, Separator} from "@heroui/react";
import React from "react";
export function ChipVariants() {
const sizes = ["lg", "md", "sm"] as const;
const variants = ["primary", "secondary", "tertiary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
{sizes.map((size, index) => (
{size}
{/* Color labels header */}
{colors.map((color) => (
{color}
))}
{variants.map((variant) => (
{variant}
{colors.map((color) => (
Label
))}
))}
{index < sizes.length - 1 && }
))}
);
}
```
### With Icons
```tsx
import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";
export function ChipWithIcon() {
return (
InformationCompletedPendingFailedLabel
);
}
```
### Statuses
```tsx
import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";
export function ChipStatuses() {
return (
DefaultActivePendingInactive
New FeatureAvailableBetaDeprecated
);
}
```
## Related Components
* **Avatar**: Display user profile images
* **CloseButton**: Button for dismissing overlays
* **Separator**: Visual divider between content
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import {Chip} from '@heroui/react';
function CustomChip() {
return (
Custom Styled
);
}
```
### Customizing the component classes
To customize the Chip component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.chip {
@apply rounded-full text-xs;
}
.chip__label {
@apply font-medium;
}
.chip--accent {
@apply border-accent/20;
}
.chip--accent .chip__label {
@apply text-accent;
}
}
```
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 container styles
* `.chip__label` - Label text slot 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
* `.chip--soft` - Soft variant with lighter background
#### Size Classes
* `.chip--sm` - Small size
* `.chip--md` - Medium size (default)
* `.chip--lg` - Large size
#### Compound Variant Classes
Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:
**Primary Variants:**
* `.chip--primary.chip--accent` - Primary accent combination with filled background
* `.chip--primary.chip--success` - Primary success combination with filled background
* `.chip--primary.chip--warning` - Primary warning combination with filled background
* `.chip--primary.chip--danger` - Primary danger combination with filled background
**Soft Variants:**
* `.chip--accent.chip--soft` - Soft accent combination with lighter background
* `.chip--success.chip--soft` - Soft success combination with lighter background
* `.chip--warning.chip--soft` - Soft warning combination with lighter background
* `.chip--danger.chip--soft` - Soft danger combination with lighter background
**Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS.
## API Reference
### Chip Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------- | ------------- | ------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the chip |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the chip |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip |
### Chip.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# Table
**Category**: react
**URL**: https://www.heroui.com/docs/react/components/table
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(data-display)/table.mdx
> Tables display structured data in rows and columns with support for sorting, selection, column resizing, and infinite scrolling.
## Import
```tsx
import { Table } from '@heroui/react';
```
### Usage
```tsx
import {Table} from "@heroui/react";
export function Basic() {
return (
);
}
```
### Anatomy
Import the Table component and access all parts using dot notation.
```tsx
import { Table } from '@heroui/react';
export default () => (
{/* Header */}
