# All Components (React)
**Category**: react
**URL**: https://heroui.com/en/docs/react/components
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/getting-started
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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 Apache License 2.0.
**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/vMYXzKPyUx).
**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 [Apache License 2.0](https://github.com/heroui-inc/heroui/blob/main/LICENSE).
# Migration (for AI assistants)
**Category**: react
**URL**: https://heroui.com/en/docs/react/migration/agent-index
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/migration/hooks
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/migration
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/migration/styling
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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. v3 now exposes standards-only scrollbar utilities from `@heroui/styles`: `scrollbar`, `scrollbar-thin`, `scrollbar-default`, and `scrollbar-none`. Use `data-scrollbar="thin"`, `data-scrollbar="default"`, or `data-scrollbar="none"` on an ancestor for subtree-level control.
**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-accent` | `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-soft-foreground`.
### 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 Components (Native)
**Category**: native
**URL**: https://heroui.com/en/docs/native/components
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/components/index.mdx
> Explore the full list of components available in HeroUI Native. More are on the way.
## Buttons
## Collections
## Controls
## Forms
## Navigation
## Overlays
## Feedback
## Layout
## Media
## Data Display
## Typography
## Utilities
# All Releases
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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.2.5
**September 8, 2026**
Patch release: [Toast](/docs/components/toast) collapses notifications into a stack that expands on hover, [Select](/docs/components/select) gains a `ClearButton`, [Tabs](/docs/components/tabs) adds an `align` variant, `@heroui/react` re-exports `Pressable`, `Focusable`, `OverlayTriggerStateContext`, and `DisclosureStateContext`, and React Aria is upgraded to `1.21.0` (`react-aria@3.52.0`). Also fixes theme tokens in nested `data-theme` scopes and shadow DOM, native `:focus-visible` rings on exported variants, and modal-level overlays being covered by closing popovers, plus [ScrollShadow](/docs/components/scroll-shadow), [Table](/docs/components/table), [Drawer](/docs/components/drawer), [NumberField](/docs/components/number-field), [Accordion](/docs/components/accordion), [Label](/docs/components/label), and [Tag](/docs/components/tag).
[Read full release notes →](/docs/react/releases/v3-2-5)
### v3.2.4
**August 4, 2026**
Patch release: the [Autocomplete](/docs/components/autocomplete) popover no longer clips its last options, backdrop clicks dismiss a [Modal](/docs/components/modal) with `scroll="outside"` again, [Tabs](/docs/components/tabs) chevron scrolling lands flush on the edges, `tailwind-variants` is upgraded to `3.3.1` to fix variant modifiers falling back to the wrong class after a re-render, React Aria is upgraded to `1.20.0` (`react-aria@3.51.0`), and `@heroui/react` gains a behavioral test suite.
[Read full release notes →](/docs/react/releases/v3-2-4)
### v3.2.3
**July 30, 2026**
Patch release: [ComboBox](/docs/components/combo-box) adds multiple selection, styles adopt logical CSS properties for better RTL support, `tailwind-variants` is upgraded to `3.3.0`, plus fixes for `ScrollShadow`, `Spinner`, `InputOTP`, `Table`, and accent `Button` focus styling.
[Read full release notes →](/docs/react/releases/v3-2-3)
### v3.2.2
**June 19, 2026**
Patch release: upgrades to React Aria `1.19.0` (`react-aria@3.50.0`), adds overflow scrolling to `Tabs.ListContainer`, fixes clear/close buttons accidentally submitting their surrounding form, and prevents visually hidden inputs in `Checkbox`, `Radio`, and `Switch` from causing overflow scroll.
[Read full release notes →](/docs/react/releases/v3-2-2)
### v3.2.1
**June 17, 2026**
Patch release: `@heroui/react` no longer bundles its own copy of `react-aria`. The `react-aria` subpaths are externalized in the Rollup build, so consumers resolve to the single `react-aria` installed in their project instead of a vendored copy. Also fixes `SwitchGroup` horizontal layout.
[Read full release notes →](/docs/react/releases/v3-2-1)
### v3.2.0
**June 6, 2026**
Calendar week and day views, a reworked year picker, and range demos on React Aria 1.18, plus tooltip delay theme variables and the patch fixes shipped with it. Breaking: `Radio`, `Checkbox`, and `Switch` move to an explicit `*.Content` composition (control nests inside `*.Content`; the label is plain text, no nested `
# v3.0.0-alpha.32
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-0-0-alpha-32
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/releases/v3-0-0-alpha-33
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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 {Switch} from "@heroui/react";
export function Sizes() {
return (
Small
Medium
Large
);
}
```
### 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://heroui.com/en/docs/react/releases/v3-0-0-alpha-34
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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 best
Basic Plan
Includes 100 messages per month
Premium Plan
Includes 200 messages per month
Business Plan
Unlimited 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://heroui.com/en/docs/react/releases/v3-0-0-alpha-35
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/releases/v3-0-0-beta-1
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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} from "@heroui/react";
export function Basic() {
return (
Accept terms and conditions
);
}
```
```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
export function Basic() {
return (
Choose all that apply
Coding
Love building software
Design
Enjoy creating beautiful interfaces
Writing
Passionate 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 {Switch} from "@heroui/react";
export function Basic() {
return (
Enable notifications
);
}
```
* **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 best
Basic Plan
Includes 100 messages per month
Premium Plan
Includes 200 messages per month
Business Plan
Unlimited 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://heroui.com/en/docs/react/releases/v3-0-0-beta-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/releases/v3-0-0-beta-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/releases/v3-0-0-beta-4
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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";
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} from "@heroui/react";
export function Basic() {
return (
Accept terms and conditions
);
}
```
### 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://heroui.com/en/docs/react/releases/v3-0-0-beta-6
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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";
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://heroui.com/en/docs/react/releases/v3-0-0-beta-7
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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";
export function MultipleMonths() {
return (
state.setTimeValue(v as TimeValue)}
>
{(segment) => }
)}
)}
Hide timezone
Force leading zeros
);
}
```
### 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://heroui.com/en/docs/react/releases/v3-0-0-beta-8
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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://heroui.com/en/docs/react/releases/v3-0-0
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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)
# v3.0.2
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-0-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/releases/v3-0-2.mdx
> Bug fixes, smoother Drawer transitions, new --backdrop theme variable, and style refinements for triggers, arrows, and tags.
April 3, 2026
Patch release with bug fixes, style refinements, and a new `--backdrop` theme variable. Drawer transitions are rewritten to native CSS for smoother animations. Overlay triggers now display as `inline-block`, and the default arrow shape for Tooltip + Popover is updated.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@latest @heroui/react@latest
```
```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```
```bash
yarn add @heroui/styles@latest @heroui/react@latest
```
```bash
bun add @heroui/styles@latest @heroui/react@latest
```
**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
### `--backdrop` Theme Variable
New `--backdrop` CSS variable for overlay backdrops ([#6375](https://github.com/heroui-inc/heroui/pull/6375)). Light theme defaults to `rgba(0, 0, 0, 0.5)`, dark to `rgba(0, 0, 0, 0.6)`. [Modal](/docs/components/modal), [AlertDialog](/docs/components/alert-dialog), and [Drawer](/docs/components/drawer) now reference this variable instead of hardcoded values.
Override it globally:
```css
:root {
--backdrop: rgba(0, 0, 0, 0.7);
}
```
Or use the utility class directly: `bg-backdrop`.
## Style Improvements
### Trigger `inline-block` Display
Trigger elements across Popover, Tooltip, Dropdown, Modal, AlertDialog, Drawer, and Disclosure now apply `inline-block` to prevent layout collapse when the trigger wraps inline content ([#6373](https://github.com/heroui-inc/heroui/pull/6373)).
### Tooltip & Popover Arrow
Default arrow SVG path updated from a quadratic curve to a cubic bezier for a smoother, more natural shape ([#6372](https://github.com/heroui-inc/heroui/pull/6372)).
### Tag Spacing
Increased horizontal padding on `sm` (`px-1` to `px-2`) and `md` (`px-1.5` to `px-2`) Tag sizes for better readability ([#6315](https://github.com/heroui-inc/heroui/pull/6315)).
## Bug Fixes
* **Autocomplete**: `--trigger-width` CSS variable on the popover now tracks the trigger element's width via `useResizeObserver`, fixing misaligned dropdown widths ([#6374](https://github.com/heroui-inc/heroui/pull/6374))
* **Drawer**: Panel transitions rewritten from Tailwind `animate-in`/`animate-out` to native CSS `translate` transitions for smoother open/close animations across all placements ([#6393](https://github.com/heroui-inc/heroui/pull/6393))
* **InputGroup**: Secondary variant focus background now triggers only when the actual input or textarea is focused, not on any focusable child within the group ([#6362](https://github.com/heroui-inc/heroui/pull/6362))
* **Tag**: `CloseButton` inside Tag now has an explicit `aria-label="Remove tag"` for screen readers ([#6341](https://github.com/heroui-inc/heroui/pull/6341))
## 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 #6364](https://github.com/heroui-inc/heroui/pull/6364)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.3
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-0-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/releases/v3-0-3.mdx
> RAC 1.17 with 90% fewer deps, expandable Table rows, Apache 2.0 license, useTheme hook, DOM polymorphic render-prop API, and bug fixes.
April 17, 2026
Patch release: React Aria Components 1.17 with 90% fewer dependencies, expandable Table rows, Apache 2.0 license, the `useTheme` hook for Vite and CRA apps, a DOM polymorphic utility for render-prop element swaps, and bug fixes.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@latest @heroui/react@latest
```
```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```
```bash
yarn add @heroui/styles@latest @heroui/react@latest
```
```bash
bun add @heroui/styles@latest @heroui/react@latest
```
**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 Aria Components 1.17
This release upgrades React Aria Components to [v1.17.0](https://react-aria.adobe.com/releases/v1-17-0). The highlight: dependency consolidation drops **90% of RAC's transitive dependencies**, resulting in faster installs and builds. See the full [RAC 1.17 release notes](https://react-aria.adobe.com/releases/v1-17-0) for details.
### Expandable Table rows
Table now supports expandable rows for tree-style data. Set a `treeColumn` and render a chevron in those cells to expand and collapse child rows — perfect for file browsers, nested categories, and hierarchical data.
```tsx
"use client";
import type {Selection} from "@heroui/react";
import {Button, Table, cn} from "@heroui/react";
import {Icon} from "@iconify/react";
import {useState} from "react";
export function ExpandableRows() {
type Row = {
children: Row[];
date: string;
id: string;
title: string;
type: string;
};
const data: Row[] = [
{
children: [
{
children: [
{children: [], date: "7/10/2025", id: "3", title: "Weekly Report", type: "File"},
{children: [], date: "8/20/2025", id: "4", title: "Budget", type: "File"},
],
date: "8/2/2025",
id: "2",
title: "Project",
type: "Directory",
},
],
date: "10/20/2025",
id: "1",
title: "Documents",
type: "Directory",
},
{
children: [
{children: [], date: "1/23/2026", id: "6", title: "Image 1", type: "File"},
{children: [], date: "2/3/2026", id: "7", title: "Image 2", type: "File"},
],
date: "2/3/2026",
id: "5",
title: "Photos",
type: "Directory",
},
];
const [expandedKeys, setExpandedKeys] = useState(() => new Set(["1"]));
const renderExpandableRow = (item: Row) => {
return (
{({hasChildItems, isDisabled, isExpanded, isTreeColumn}) => (
{hasChildItems && isTreeColumn ? (
) : null}
{item.title}
)}
{item.type}{item.date}{renderExpandableRow}
);
};
return (
Patch release: new `Typography` compound component ported from HeroUI Pro, a docs theme selector for previewing components in different themes, `min()`-capped border-radius tokens across 45+ component CSS files, reworked Table focus rings, and fixes for Checkbox, Autocomplete, Tooltip, and form field padding.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@latest @heroui/react@latest
```
```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```
```bash
yarn add @heroui/styles@latest @heroui/react@latest
```
```bash
bun add @heroui/styles@latest @heroui/react@latest
```
**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
### Typography Component
New compound component for structured typography, ported from HeroUI Pro ([#6479](https://github.com/heroui-inc/heroui/pull/6479)). Renders the right HTML element automatically — `
`–`
`, `
`, or `` — based on the sub-component or `type` prop.
```tsx
import {Typography} from "@heroui/react";
const scale = [
{
label: "h1",
meta: "36px / 600 / 1.11 / tight",
sample: "Build better interfaces",
type: "h1" as const,
},
{
label: "h2",
meta: "30px / 600 / 1.17 / tight",
sample: "Built for the intelligence age",
type: "h2" as const,
},
{
label: "h3",
meta: "24px / 600 / 1.25 / tight",
sample: "Pricing on your terms",
type: "h3" as const,
},
{
label: "h4",
meta: "20px / 600 / 1.33 / tight",
sample: "Apply to the startup program",
type: "h4" as const,
},
{
label: "h5",
meta: "18px / 600 / 1.39 / tight",
sample: "Card titles",
type: "h5" as const,
},
{
label: "h6",
meta: "16px / 600 / 1.50 / tight",
sample: "Smaller feature headers",
type: "h6" as const,
},
{
label: "body",
meta: "16px / 400 / 1.75",
sample: "Primary body text used across documentation, marketing copy, and descriptions.",
type: "body" as const,
},
{
label: "body-sm",
meta: "14px / 400 / 1.50",
sample: "Secondary body, table cells, navigation, and sidebar items.",
type: "body-sm" as const,
},
{
label: "body-xs",
meta: "12px / 400 / 1.25",
sample: "Captions, badges, helper text, and fine print.",
type: "body-xs" as const,
},
{
label: "code",
meta: "14px / mono",
sample: "pnpm add @heroui/react",
type: "code" as const,
},
] as const;
export const TypographyScale = () => {
return (
{scale.map((row) => (
{row.label}{row.meta}
{row.sample}
))}
);
};
```
Sub-components: `Typography.Heading`, `Typography.Paragraph`, `Typography.Code`, `Typography.Prose`.
Props on all sub-components: `align`, `color`, `weight`, `truncate`. `Typography.Heading` accepts `level` (1–6). `Typography.Paragraph` accepts `size` (`"base"`, `"sm"`, `"xs"`).
Wrap mixed content in `Typography.Prose` for automatic prose spacing:
```tsx
Getting StartedInstall the package and import the component.
```
### Docs Theme Selector
The documentation site now includes a theme selector that lets you preview every component in different themes — light, dark, brutalism, and more. Your choice is saved to `localStorage` so it persists across sessions ([#6471](https://github.com/heroui-inc/heroui/pull/6471)).
### Border-Radius Design Tokens
All `rounded-full` and hardcoded `border-radius` values across \~45 component CSS files now use `min()` to cap the computed radius ([#6465](https://github.com/heroui-inc/heroui/pull/6465)). Components no longer look broken when users set very large custom radius themes — the radius stops growing once it would exceed the element's dimensions.
### Table Focus Ring Rework
Table row focus indicators are split across individual cells using per-cell inset shadows instead of a single `box-shadow` on the row. The ring now looks continuous across all cells and works correctly with virtualized table wrappers.
## Bug Fixes
* **Checkbox**: removed hardcoded `accent-hover` background from selected/indeterminate indicator state ([#6487](https://github.com/heroui-inc/heroui/pull/6487))
* **Autocomplete**: `isDisabled` now propagates from root to `Trigger` and `ClearButton` via context ([#6443](https://github.com/heroui-inc/heroui/pull/6443))
* **Description**: removed unnecessary horizontal padding from description text in form fields (textfield, color-field, date-field, number-field, search-field, time-field) ([#6484](https://github.com/heroui-inc/heroui/pull/6484))
* **Tooltip**: changed padding from `px-2 py-1` to `p-2` and switched border-radius to design token ([#6481](https://github.com/heroui-inc/heroui/pull/6481))
* **Theme Builder**: fixed swapped `accent-foreground` values ([#6401](https://github.com/heroui-inc/heroui/pull/6401))
* **Soft color contrast**: `accent-soft-foreground` now uses a darker shade for light accent themes (Sky, Lavender, Mint), fixing barely-visible text on secondary buttons, chips, and badges. The shared theme now reads from `--accent-soft-foreground` with a fallback to `--accent`
## 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 #6483](https://github.com/heroui-inc/heroui/pull/6483)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.5
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-0-5
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/releases/v3-0-5.mdx
> Text renamed to Typography (breaking), color tokens refactored to unprefixed source variables, Checkbox + Radio border fixes, and a new CLI docs page.
May 15, 2026
Patch release: `Text` is renamed to `Typography` to resolve a `tailwind-merge` collision that silently dropped variant classes. Derived color tokens (`hover`, `soft`, `border-secondary`, …) moved from `@theme inline` aliases into `variables.css` as unprefixed source tokens, so component CSS can reference them directly. Plus Checkbox and Radio border alignment fixes, an `accent-soft-foreground` hover refinement for Calendar, and a new CLI docs page.
⚠️ **Breaking change**: `Text` → `Typography`. The BEM block changes from `text` to `typography` (e.g. `text--body-sm` → `typography--body-sm`).
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@latest @heroui/react@latest
```
```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```
```bash
yarn add @heroui/styles@latest @heroui/react@latest
```
```bash
bun add @heroui/styles@latest @heroui/react@latest
```
**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).
## ⚠️ Breaking Changes
### `Text` → `Typography`
The component shipped in [v3.0.4](/docs/react/releases/v3-0-4) used `text-*` BEM modifiers, which collide with Tailwind's `text-*` utility family. `tailwind-variants` runs `tailwind-merge` on every variant composition and dedupes `text--body-sm`, `text--color-muted`, `text--weight-normal` to a single class — silently dropping the others.
Renaming the block to `typography` permanently fixes the collision ([#6505](https://github.com/heroui-inc/heroui/pull/6505), closes [#6497](https://github.com/heroui-inc/heroui/issues/6497)).
**Before:**
```tsx
import {Text} from "@heroui/react";
Hello world
;
```
**After:**
```tsx
import {Typography} from "@heroui/react";
Hello world
;
```
Sub-components rename the same way:
| Before | After |
| ---------------- | ---------------------- |
| `Text` | `Typography` |
| `Text.Heading` | `Typography.Heading` |
| `Text.Paragraph` | `Typography.Paragraph` |
| `Text.Code` | `Typography.Code` |
| `Text.Prose` | `Typography.Prose` |
CSS BEM classes change too: `.text` → `.typography`, `.text--body-sm` → `.typography--body-sm`, etc. See the [Typography docs](/docs/components/typography) for the full class reference.
```tsx
import {Typography} from "@heroui/react";
const scale = [
{
label: "h1",
meta: "36px / 600 / 1.11 / tight",
sample: "Build better interfaces",
type: "h1" as const,
},
{
label: "h2",
meta: "30px / 600 / 1.17 / tight",
sample: "Built for the intelligence age",
type: "h2" as const,
},
{
label: "h3",
meta: "24px / 600 / 1.25 / tight",
sample: "Pricing on your terms",
type: "h3" as const,
},
{
label: "h4",
meta: "20px / 600 / 1.33 / tight",
sample: "Apply to the startup program",
type: "h4" as const,
},
{
label: "h5",
meta: "18px / 600 / 1.39 / tight",
sample: "Card titles",
type: "h5" as const,
},
{
label: "h6",
meta: "16px / 600 / 1.50 / tight",
sample: "Smaller feature headers",
type: "h6" as const,
},
{
label: "body",
meta: "16px / 400 / 1.75",
sample: "Primary body text used across documentation, marketing copy, and descriptions.",
type: "body" as const,
},
{
label: "body-sm",
meta: "14px / 400 / 1.50",
sample: "Secondary body, table cells, navigation, and sidebar items.",
type: "body-sm" as const,
},
{
label: "body-xs",
meta: "12px / 400 / 1.25",
sample: "Captions, badges, helper text, and fine print.",
type: "body-xs" as const,
},
{
label: "code",
meta: "14px / mono",
sample: "pnpm add @heroui/react",
type: "code" as const,
},
] as const;
export const TypographyScale = () => {
return (
{scale.map((row) => (
{row.label}{row.meta}
{row.sample}
))}
);
};
```
## Style Refactor
### Unprefixed source color tokens
All derived color tokens — `*-hover`, `*-soft`, `*-soft-foreground`, `border-secondary`, etc. — moved from `@theme inline` aliases in `theme.css` into `variables.css` as unprefixed source variables, and 24 component CSS files now reference source tokens directly ([#6499](https://github.com/heroui-inc/heroui/pull/6499)).
**1. `color-mix` formulas moved from `theme.css` to `variables.css`**
Before — the calculation lived inside the `@theme inline` block:
```css
/* packages/styles/themes/shared/theme.css */
--color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
--color-accent-soft: var(--accent-soft, color-mix(in oklab, var(--accent) 15%, transparent));
--color-accent-soft-foreground: var(--accent-soft-foreground, var(--accent));
--color-border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
```
After — `theme.css` is pure aliases; the formulas live in `variables.css`:
```css
/* packages/styles/themes/default/variables.css */
--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
--accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
--accent-soft-foreground: var(--accent);
--border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%);
/* packages/styles/themes/shared/theme.css */
--color-accent-hover: var(--accent-hover);
--color-accent-soft: var(--accent-soft);
--color-accent-soft-foreground: var(--accent-soft-foreground);
--color-border-secondary: var(--border-secondary);
```
**2. Component CSS uses source tokens directly**
Before — `var(--color-*)` references everywhere:
```css
/* packages/styles/components/button.css */
.button--primary {
--button-bg: var(--color-accent);
--button-bg-hover: var(--color-accent-hover);
--button-fg: var(--color-accent-foreground);
}
.button--secondary {
--button-bg: var(--color-default);
--button-bg-hover: var(--color-default-hover);
--button-fg: var(--color-accent-soft-foreground);
}
```
After — unprefixed source tokens:
```css
/* packages/styles/components/button.css */
.button--primary {
--button-bg: var(--accent);
--button-bg-hover: var(--accent-hover);
--button-fg: var(--accent-foreground);
}
.button--secondary {
--button-bg: var(--default);
--button-bg-hover: var(--default-hover);
--button-fg: var(--accent-soft-foreground);
}
```
The `@theme inline` block still exposes every `--color-*` Tailwind utility as an alias, so user-land class usage (`bg-accent`, `text-accent`, …) is unaffected.
**3. Theme builder consolidated**
Three derived-token helpers (`getAccentDerivedVariables`, `getSemanticDerivedVariables`, `getFieldDerivedVariables`) collapsed into a single `getDerivedColorVariables()` that emits the full unprefixed set, including the `darkenForSoftForeground` logic that keeps soft-foreground text readable on light accent themes.
## Style Fixes
* **Calendar / Range Calendar**: default day-cell hover now uses `accent-soft-foreground` instead of `accent`, so hovered cells stay legible on light accent themes. The docs search tag selected state was aligned the same way ([#6500](https://github.com/heroui-inc/heroui/pull/6500)).
* **Checkbox**: `.checkbox__control` now carries the same `border`, `border-field-border`, and `[border-width:var(--border-width-field)]` base styling that `.radio__control` already used, with `border-color` added to the transition list ([#6521](https://github.com/heroui-inc/heroui/pull/6521)).
* **Radio**: `.radio__control` default border now uses `border-field-border` instead of the generic Tailwind `border` color, matching Input, Select, TextArea, and NumberField ([#6522](https://github.com/heroui-inc/heroui/pull/6522)).
## Docs
### CLI page
New [CLI docs page](/docs/react/getting-started/cli) covers installation, `init`, `install`, `upgrade`, `uninstall`, `list`, `doctor`, and `env` with example outputs ([#6498](https://github.com/heroui-inc/heroui/pull/6498)).
## Dependencies
Bumped across packages ([#6529](https://github.com/heroui-inc/heroui/pull/6529)):
* **`react` / `react-dom`**: `19.2.3` → `19.2.6`
* **`@types/react`**: `19.2.7` → `19.2.14`
* **`next`** (docs): `16.1.1` → `16.2.6`
* **CI actions**: `actions/checkout@v6`, `actions/setup-node@v6`, `actions/cache@v5`, `pnpm/action-setup@v6`
## 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 #6503](https://github.com/heroui-inc/heroui/pull/6503)
## Contributors
Thanks to everyone who contributed to this release!
# v3.1.0
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-1-0
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/releases/v3-1-0.mdx
> Chinese React docs, accessible soft foreground tokens, shared scrollbar styling, useTheme SSR fixes, Toast cleanup, Link underline updates, and RTL layout refinements.
import {HandPointUp} from "@gravity-ui/icons";
May 25, 2026
Minor release: HeroUI React docs now ship with Chinese pages and localized demos, soft color tokens were expanded for better readability, scroll containers share a single themeable scrollbar system, and several runtime and layout fixes landed for `useTheme`, Toast, Link, Fieldset, overlays, and RTL layouts.
## Installation
Update to the latest version:
```bash
npm i @heroui/styles@latest @heroui/react@latest
```
```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```
```bash
yarn add @heroui/styles@latest @heroui/react@latest
```
```bash
bun add @heroui/styles@latest @heroui/react@latest
```
**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
### Chinese React Docs
The documentation site now supports localized React docs, migration guides, release notes, and demos in Chinese ([#6533](https://github.com/heroui-inc/heroui/pull/6533)). The docs app was restructured around locale-aware content paths and localized demo registries, so React component pages, getting-started guides, and migration references can ship in both English and Chinese.
### Accessible Soft Foreground Tokens
Soft foreground colors now use dedicated theme tokens instead of raw semantic colors, improving contrast for soft badges, chips, alerts, toasts, avatars, and calendar range states ([#6548](https://github.com/heroui-inc/heroui/pull/6548)).
New tokens include:
* `--default-soft`
* `--default-soft-foreground`
* `--default-soft-hover`
* updated `--accent-soft-foreground`, `--danger-soft-foreground`, `--warning-soft-foreground`, and `--success-soft-foreground`
The default palette now uses soft foreground colors with accessibility-compliant contrast. Teams that prefer the previous, more saturated palette can opt into the vibrant palette with `data-vibrant-palette="true"`, but that palette has lower contrast. The theme builder and docs theme selector were updated to preserve this preference.
```tsx
import {Chip, Separator} from "@heroui/react";
const variants = ["primary", "secondary", "tertiary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
function ChipMatrix({isVibrant, title}: {isVibrant?: boolean; title: string}) {
return (
{title}
{colors.map((color) => (
{color}
))}
{variants.map((variant) => (
{variant}
{colors.map((color) => (
{color}
))}
))}
);
}
export function ChipVibrantPalette() {
return (
);
}
```
### Shared Scrollbar System
Scroll containers now use a shared, standards-based scrollbar system with theme variables and per-subtree control through `data-scrollbar` ([#6545](https://github.com/heroui-inc/heroui/pull/6545)). Instead of maintaining separate scrollbar CSS in each component, scroll slots now read the same `--scrollbar-*` variables and use the shared scrollbar utilities, so scroll areas look more consistent across light mode, dark mode, overlays, tables, and custom overflow regions.
Supported modes:
* HeroUI thin: leave `data-scrollbar` unset, or set `data-scrollbar="thin"` to force the themed thin scrollbar inside a subtree.
* Browser default: set `data-scrollbar="default"` to use the OS/browser scrollbar.
* Hidden: set `data-scrollbar="none"` to hide the visible scrollbar while keeping the content scrollable.
```html
);
}
```
Components such as Select, ComboBox, Autocomplete, Dropdown, DatePicker, DateRangePicker, ColorPicker, Table, Tabs, Modal, Drawer, and ScrollShadow now share the same scrollbar utilities instead of maintaining one-off scrollbar CSS.
Use the `scrollbar` utility on any scrollable slot that should follow the active `data-scrollbar` mode. It reads `--scrollbar-width`, `--scrollbar-color`, and `--scrollbar-gutter`, so the same slot can render as HeroUI thin, browser default, or hidden depending on the nearest `data-scrollbar` ancestor.
```css
.alert-dialog__body {
@apply min-h-0 flex-1 scrollbar;
}
```
The theme variables also moved from a single fixed `--scrollbar` color to a small scrollbar token set:
```css
/* before */
--scrollbar: oklch(70.5% 0.015 286.067);
/* after */
--scrollbar: var(--scrollbar-thumb);
--scrollbar-thumb: color-mix(in oklch, var(--foreground) 15%, transparent);
--scrollbar-track: transparent;
--scrollbar-gutter: auto;
--scrollbar-width: thin;
--scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
```
`--scrollbar` now stays as a compatibility alias, while the new thumb, track, gutter, width, and color tokens control the rendered scrollbar.
To return to normal browser scrollbars, set `data-scrollbar="default"` on the root ``, your app ``, or any nested container. The mode cascades through descendant HeroUI scroll slots and custom elements using the scrollbar utilities. If you set the root to browser defaults but want one area to use HeroUI styling again, add `data-scrollbar="thin"` on that nested element.
```html
```
## Component and Runtime Fixes
* **Fieldset**: `disabled` now cascades through descendant field labels and explicitly disables React Aria `RadioGroup` and `Slider`, matching native fieldset behavior more closely ([#6547](https://github.com/heroui-inc/heroui/pull/6547)).
* **Toast**: non-frontmost toasts are removed from keyboard tab order, and measured toast heights are cleaned up when toasts unmount so long-running sessions do not accumulate stale height entries ([#6510](https://github.com/heroui-inc/heroui/pull/6510), [#6512](https://github.com/heroui-inc/heroui/pull/6512)).
* **`useTheme`**: the hook no longer reads browser-only APIs during SSR, derives `resolvedTheme` without circular state updates, and uses `useSyncExternalStore` to subscribe to system color-scheme changes ([#6561](https://github.com/heroui-inc/heroui/pull/6561)).
* **Link**: the default underline is now hidden at rest, appears on hover with a 50% decoration color, and becomes full opacity on active or pressed states. The underline decoration color transition was removed for a crisper interaction ([#6570](https://github.com/heroui-inc/heroui/pull/6570), [#6571](https://github.com/heroui-inc/heroui/pull/6571)).
## Layout, Overlay, and RTL Fixes
* **Overlay positioning**: entering overlays now limit transition properties to `opacity` and `transform`, preventing React Aria placement values from animating and producing incorrect popover placement during open animations ([#6549](https://github.com/heroui-inc/heroui/pull/6549)).
* **Dialog and Modal focus**: Modal and AlertDialog content now use clipping that prevents focus from programmatically scrolling the dialog, while body focus rings are no longer cut off by container overflow ([#6448](https://github.com/heroui-inc/heroui/pull/6448), [#6557](https://github.com/heroui-inc/heroui/pull/6557)).
* **RTL table corners**: Table rounded corners now use logical border-radius properties so outer corners remain correct in right-to-left layouts ([#6568](https://github.com/heroui-inc/heroui/pull/6568)).
* **RTL picker and menu indicators**: Select, ListBox.Item, Autocomplete, ComboBox, and MenuItem now use logical inline start/end utilities for chevrons, value text, checkmarks, triggers, and submenu indicators ([#6573](https://github.com/heroui-inc/heroui/pull/6573)).
## Docs and Dependencies
* Theme docs now match the current `theme.css` and `variables.css` token model, including soft foreground tokens and scrollbar variables.
* Docs release and migration pages were synced with the Link behavior update.
* Docs gained `@fumadocs/language` and upgraded `fumadocs-core` / `fumadocs-ui` to `16.9.0` for localized routing.
* Tailwind tooling for docs and styles moved to `4.3.0`.
## Links
* [Component Docs](/docs/react/components)
* [Theming Docs](/docs/react/getting-started/theming)
* [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6576](https://github.com/heroui-inc/heroui/pull/6576)
## Contributors
Thanks to everyone who contributed to this release!
# v3.2.0
**Category**: react
**URL**: https://heroui.com/en/docs/react/releases/v3-2-0
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/releases/v3-2-0.mdx
> Calendar week/day views and year picker on React Aria 1.18, plus breaking Radio, Checkbox, and Switch composition changes.
June 15, 2026
Calendar gains week and day views, a reworked year picker, and range demos built on React Aria 1.18. [Autocomplete](/docs/components/autocomplete) adds a Virtualizer example for large option lists. [Tooltip](/docs/components/tooltip) adds theme variables for global show and hide delays. The toggles (`Radio`, `Checkbox`, `Switch`) move to React Aria's `*Field` + `*Button` composition. This release also rolls in patch fixes for virtualized lists, grouped-field autofill, toast and fieldset behavior, and scroll and RTL styles.
⚠️ **Breaking changes**: `Radio`, `Checkbox`, and `Switch` move to an explicit `*.Content` composition — `*.Control` nests inside `*.Content`, the label is plain text inside `*.Content` (no nested `
{/* Header */}
