# All Components
**Category**: react
**URL**: https://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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-primary` | `border-accent` | Accent border |
**Note:** v3 doesn't have numbered color scales (`-50`, `-100`, `-200`, etc.). Use semantic variants like `-soft`, `-hover`, or custom Tailwind classes.
### Secondary Color Removed
v2 provided a `secondary` semantic color (purple). This has been removed in v3. Component variants named "secondary" now use different colors.
**v2 Secondary Color:**
```tsx
// v2 - Secondary as a semantic color (purple)
Secondary background
Light secondary
Secondary text
```
**v3 Secondary Variant:**
```tsx
// v3 - Secondary is a variant, not a color
Default background (used by secondary variant)
Accent text
```
**Migration:**
| v2 Class | v3 Equivalent | Notes |
| ------------------ | --------------- | ------------------------------------ |
| `bg-secondary` | `bg-default` | Secondary variant uses default color |
| `text-secondary` | `text-accent` | Use accent for emphasis |
| `bg-secondary-50` | `bg-default` | Use default color |
| `border-secondary` | `border-accent` | Use accent border |
**Note:** In v3, "secondary" refers to a component variant style (like `button--secondary`), not a color token. The secondary variant typically uses `bg-default` and `text-accent-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
**Category**: native
**URL**: https://v3.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
# Introduction
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/getting-started
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/getting-started/index.mdx
> An open-source UI component library for building beautiful and accessible user interfaces.
HeroUI Native is a React Native component library built on [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.
## HeroUI Ecosystem
* **🌐 HeroUI v3** (web) — React components with Tailwind CSS v4
* **📱 HeroUI 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
## FAQ
**Is HeroUI Native free?**
Yes, completely free and open source under the Apache License 2.0.
**Is it production-ready?**
Yes, HeroUI Native is production-ready and actively used in production apps.
**Can I customize the components?**
Yes! Update default styles, animations 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?**
Accessibility follows mobile development best practices with proper focus management, touch accessibility, and screen reader support built into every component.
**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-native/discussions)
* [Discord](https://discord.gg/9b6yyZKmH4)
* [X/Twitter](https://x.com/hero_ui)
* [Contributing Guidelines](https://github.com/heroui-inc/heroui-native/blob/main/CONTRIBUTING.md)
HeroUI Native is released under the [Apache License 2.0](https://github.com/heroui-inc/heroui-native/blob/main/LICENSE).
# Beta 10
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/beta-10
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/beta-10.mdx
> Bottom Sheet component, PressableFeedback refactor, Animation API State Prop extension, use-theme-color multiple colors selection, and bug fixes.
December 30, 2025
This release introduces the new [Bottom Sheet](/docs/native/components/bottom-sheet) component, refactors [PressableFeedback](/docs/native/components/pressable-feedback) with improved API, extends the Animation API with State Prop support, enhances the `use-theme-color` hook to handle multiple colors selection, and includes various bug fixes and documentation improvements.
## Installation
Update to the latest version:
```bash
npm i heroui-native@beta
```
```bash
pnpm add heroui-native@beta
```
```bash
yarn add heroui-native@beta
```
```bash
bun add heroui-native@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## What's New
### New Components
#### Bottom Sheet
This release introduces the **Bottom Sheet** component, a versatile overlay component that slides up from the bottom of the screen with animated transitions and swipe-to-dismiss gestures.
**Features:**
* Smooth animated transitions with gesture support
* Multiple snap points for flexible sizing
* Detached mode for custom positioning
* Customizable overlay with blur effects
* Full accessibility support
* Built on [@gorhom/bottom-sheet](https://gorhom.dev/react-native-bottom-sheet)
**Usage:**
```tsx
import { BottomSheet, Button } from 'heroui-native';
TitleDescription
```
For complete documentation and examples, see the [Bottom Sheet component page](/docs/native/components/bottom-sheet).
**Related PR:** [#174](https://github.com/heroui-inc/heroui-native/pull/174)
## Component Improvements
### PressableFeedback Refactor
The [PressableFeedback](/docs/native/components/pressable-feedback) component has been refactored with an improved API and better animation control.
**Improvements:**
* Enhanced animation configuration API
* Better support for custom animation states
* Improved performance and smoother animations
* More flexible feedback positioning options
The component maintains backward compatibility while providing more control over press feedback animations.
**Related PR:** [#182](https://github.com/heroui-inc/heroui-native/pull/182)
## API Enhancements
### Animation API State Prop Extension
The Animation API has been extended with a new `state` prop that allows you to disable animations while customizing properties. This provides more granular control over animation behavior.
**New Capability:**
```tsx
```
The `state` prop can be:
* `'disabled'`: Disable animations while still allowing property customization
* `'disable-all'`: Disable all animations including children
* `boolean`: Simple enable/disable control
This enhancement makes it easier to customize animation properties without enabling animations, useful for fine-tuning component behavior.
**Related PR:** [#176](https://github.com/heroui-inc/heroui-native/pull/176)
### use-theme-color Multiple Colors Selection
The `use-theme-color` hook has been refactored to handle multiple colors selection, making it more flexible and powerful for theme customization.
**Enhancement:**
* Support for selecting multiple colors at once
* Improved color selection logic
* Better performance when working with multiple color values
This improvement makes it easier to work with complex theming scenarios where multiple colors need to be selected and applied together.
**Related PR:** [#170](https://github.com/heroui-inc/heroui-native/pull/170)
## Documentation
### Animated Styles Guide Comments
Added comprehensive comments and documentation to the Animated Styles Guide, making it easier for developers to understand and use animation features effectively.
**Improvements:**
* Enhanced code examples with detailed comments
* Better explanation of animation patterns
* Clearer guidance on when to use different animation approaches
**Related PR:** [#179](https://github.com/heroui-inc/heroui-native/pull/179)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #173](https://github.com/heroui-inc/heroui-native/issues/173)**: Fixed issue where `classNames={{container:"bg-x"}}` was not working for styling the backgroundColor of TextField.Input container
* **[Issue #177](https://github.com/heroui-inc/heroui-native/issues/177)**: Fixed button scale animation issue where the scale would sometimes stay at 0.9x and not bounce back after being pressed
* **[Issue #178](https://github.com/heroui-inc/heroui-native/issues/178)**: Fixed bug affecting component functionality
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Animation Guide](/docs/native/getting-started/animation) - Updated with Animation API State Prop documentation
* [Colors Guide](/docs/native/getting-started/colors) - Updated with use-theme-color multiple colors selection information
* [PressableFeedback Component](/docs/native/components/pressable-feedback) - Updated with refactored API documentation
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# Beta 11
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/beta-11
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/beta-11.mdx
> Enhanced Bottom Sheet close coordination, Dialog swipe-to-dismiss fixes, TextField improvements, and PortalHost export for advanced use cases
January 6, 2026
Beta 11 focuses on improving component reliability and developer experience across several key areas. This release enhances Bottom Sheet close coordination to ensure consistent behavior across all close mechanisms, fixes Dialog swipe-to-dismiss gesture handling issues, resolves TextField styling and functionality problems, and introduces a new PortalHost export for advanced portal mounting scenarios. These improvements make interactions smoother and provide developers with more control over component behavior.
## Installation
Update to the latest version:
```bash
npm i heroui-native@beta
```
```bash
pnpm add heroui-native@beta
```
```bash
yarn add heroui-native@beta
```
```bash
bun add heroui-native@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## Component Improvements
### Bottom Sheet Close Coordination Enhancement
The [Bottom Sheet](/docs/native/components/bottom-sheet) component has been enhanced with improved close coordination across all close mechanisms.
**Improvements:**
* Enhanced synchronization between swipe-to-dismiss, overlay press, close button, and programmatic close actions
* Improved state management to prevent race conditions during close operations
* More reliable `onOpenChange` callback firing across all close scenarios
* Better coordination between animation progress and close state transitions
The Bottom Sheet component supports multiple ways to close: swiping down, pressing the overlay, clicking the close button, or programmatically calling close. Previously, these mechanisms could sometimes conflict or produce inconsistent behavior. This update ensures all close mechanisms work harmoniously together, providing a smoother and more predictable user experience.
**Related PR:** [#201](https://github.com/heroui-inc/heroui-native/pull/201)
### Dialog Swipe-to-Dismiss Gesture Handling Fix
The [Dialog](/docs/native/components/dialog) component has been fixed to properly handle swipe-to-dismiss gestures.
**Improvements:**
* Fixed gesture detection and handling for swipe-to-dismiss functionality
* Improved gesture state management during swipe interactions
* Enhanced animation coordination during gesture release
* More reliable dismissal when swiping beyond the threshold
The Dialog component supports swipe-to-dismiss functionality, allowing users to dismiss dialogs by swiping down. This fix resolves issues where gesture handling could become unresponsive or produce unexpected behavior during swipe interactions.
**Related PR:** [#193](https://github.com/heroui-inc/heroui-native/pull/193)
### TextField Styling and Functionality Fixes
The [TextField](/docs/native/components/text-field) component has been fixed to resolve styling and functionality issues.
**Improvements:**
* Fixed input styling inconsistencies
* Resolved animation state management issues
* Improved focus and blur state handling
* Enhanced error state visual feedback
* Fixed placeholder and selection color application
These fixes ensure the TextField component displays correctly across all states (focused, blurred, invalid) and provides consistent visual feedback to users.
**Related PR:** [#202](https://github.com/heroui-inc/heroui-native/pull/202)
## API Enhancements
### PortalHost Export for Advanced Use Cases
The `PortalHost` component is now exported from the main provider module, enabling advanced portal host mounting scenarios.
**New Capability:**
```tsx
import { HeroUINativeProvider, PortalHost } from "@heroui/native";
export function CustomLayout() {
return (
<>
{/* Your app content */}
{/* Manually mount PortalHost in a custom location */}
);
}
```
This enhancement allows developers to manually mount portal hosts in custom layouts, which is particularly useful for scenarios where you need portals to render in specific locations (e.g., within BottomSheet, Modal, or other overlay components). By default, `HeroUINativeProvider` includes a `PortalHost` for standard use cases, but now you can create additional hosts with custom names for advanced scenarios.
**Use Cases:**
* Mounting portals within BottomSheet components
* Creating portal hosts in Modal components
* Custom overlay rendering scenarios
* Multi-host portal architectures
**Related PR:** [#185](https://github.com/heroui-inc/heroui-native/pull/185)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #187](https://github.com/heroui-inc/heroui-native/issues/187)**: Fixed an issue where multiple presses were required to re-open a bottom sheet or dialog after it was dismissed via swipe gesture. The internal state now properly synchronizes with the close animation, allowing immediate reopening regardless of how the component was closed.
* **[Issue #189](https://github.com/heroui-inc/heroui-native/issues/189)**: Fixed app freezing when swiping to dismiss dialogs containing text inputs.
* **[Issue #196](https://github.com/heroui-inc/heroui-native/issues/196)**: Fixed TextField multiline input behavior to match React Native's TextInput multiline functionality.
* **[Issue #199](https://github.com/heroui-inc/heroui-native/issues/199)**: Fixed placeholder text positioning within TextField Input component.
**Related PRs:**
* [#201](https://github.com/heroui-inc/heroui-native/pull/201)
* [#202](https://github.com/heroui-inc/heroui-native/pull/202)
* [#193](https://github.com/heroui-inc/heroui-native/pull/193)
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# Beta 12
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/beta-12
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/beta-12.mdx
> InputOTP, Label, and Description components, Popover close fixes, controlled state improvements, border radius fixes, and variant style prop support
January 13, 2026
Beta 12 introduces three essential form components—InputOTP, Label, and Description—that enhance form building capabilities in React Native applications. This release also includes critical fixes for Popover close behavior, popup controlled state management, border radius configuration, and adds variant style prop support across multiple form components. These improvements provide developers with more robust form components and better control over component styling and behavior.
## Installation
Update to the latest version:
```bash
npm i heroui-native@beta
```
```bash
pnpm add heroui-native@beta
```
```bash
yarn add heroui-native@beta
```
```bash
bun add heroui-native@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **3 new** essential form components:
* **[InputOTP](/docs/native/components/input-otp)**: Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support.
* **[Label](/docs/native/components/label)**: Text component for labeling form fields and other UI elements with support for required indicators and validation states.
* **[Description](/docs/native/components/description)**: Text component for providing accessible descriptions and helper text for form fields and other UI elements.
#### InputOTP
The InputOTP component provides a complete solution for one-time password input scenarios, such as two-factor authentication, verification codes, and PIN entry. It features individual character slots with smooth animations, customizable grouping, separators, and comprehensive validation support.
**Features:**
* Individual character slots with smooth animations and caret indicators
* Flexible grouping with separators for visual organization
* Pattern-based input restriction (digits, characters, or custom regex)
* Controlled and uncontrolled value management
* Validation state support with visual feedback
* Customizable placeholder characters per slot position
* Paste support with transformer function
* Complete accessibility support
**Usage:**
```tsx
import { InputOTP, Label, Description } from "heroui-native";
export function Example() {
return (
<>
console.log(code)}>
We've sent a code to your email
);
}
```
For complete documentation and examples, see the [InputOTP component page](/docs/native/components/input-otp).
**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
#### Label
The Label component provides accessible labeling for form fields with built-in support for required indicators, validation states, and disabled states. It automatically displays an asterisk for required fields and adapts its styling based on the field's validation state.
**Features:**
* Automatic required field indicator (asterisk)
* Invalid state styling for validation errors
* Disabled state support
* Compound component architecture for custom layouts
* Full accessibility support with nativeID linking
* Customizable styling via className, classNames, and styles props
**Usage:**
```tsx
import { Label, TextField } from "heroui-native";
export function Example() {
return (
);
}
```
For complete documentation and examples, see the [Label component page](/docs/native/components/label).
**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
#### Description
The Description component provides accessible helper text and descriptions for form fields. It features muted styling by default and supports linking to form fields via nativeID for screen reader support.
**Features:**
* Muted text styling optimized for helper text
* Accessibility linking via nativeID and aria-describedby
* Seamless integration with form components
* Customizable styling support
**Usage:**
```tsx
import { Description, TextField } from "heroui-native";
export function Example() {
return (
Email address
We'll never share your email with anyone else.
);
}
```
For complete documentation and examples, see the [Description component page](/docs/native/components/description).
**Related PR:** [#214](https://github.com/heroui-inc/heroui-native/pull/214)
## Component Improvements
### Popover Close via Ref Fix
The [Popover](/docs/native/components/popover) component has been fixed to properly handle programmatic close operations via ref.
**Improvements:**
* Fixed ref-based close method to properly trigger close animations
* Improved state synchronization between ref calls and component state
* Enhanced reliability of programmatic close operations
This fix ensures that when developers call `popoverRef.current?.close()`, the popover closes reliably with proper animation and state management.
**Related PR:** [#207](https://github.com/heroui-inc/heroui-native/pull/207)
### Popup Controlled State Fix
Popup components (including Dialog, Bottom Sheet, and Popover) have been fixed to properly handle controlled state via the `isOpen` prop.
**Improvements:**
* Fixed controlled state synchronization for popup components
* Improved handling of external state changes
* Enhanced reliability when using controlled mode
This fix ensures that popup components correctly respond to external state changes when using controlled mode, providing developers with more predictable behavior when managing popup state externally.
**Related PR:** [#215](https://github.com/heroui-inc/heroui-native/pull/215)
### Button, Chip, and Tabs Border Radius Fix
The [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Tabs](/docs/native/components/tabs) components have been fixed to properly respect global border radius configuration.
**Improvements:**
* Fixed border radius configuration application for Button component
* Fixed border radius configuration application for Chip component
* Fixed border radius configuration application for Tabs component
* Improved consistency across components using global theme configuration
These fixes ensure that global border radius settings defined in the theme configuration are properly applied to Button, Chip, and Tabs components, providing consistent styling across the application.
**Related PR:** [#218](https://github.com/heroui-inc/heroui-native/pull/218)
### TextField.Input Props Cleanup
The [TextField](/docs/native/components/text-field) component's Input subcomponent has been cleaned up by removing the `animation` and `isAnimatedStyleActive` props.
**Changes:**
* Removed `animation` prop from TextField.Input
* Removed `isAnimatedStyleActive` prop from TextField.Input
* Simplified component API for better maintainability
These props were removed to streamline the TextField.Input API and reduce complexity. Animation behavior is now handled internally by the component, providing a more consistent and predictable experience without requiring manual animation configuration.
**Related PR:** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
## API Enhancements
### HeroUINativeProvider devInfo Configuration
The `HeroUINativeProvider` component now supports `devInfo` configuration options for enhanced development experience.
**New Capability:**
```tsx
import { HeroUINativeProvider } from "heroui-native";
export function App() {
return (
{/* Your app content */}
);
}
```
This enhancement provides developers with additional configuration options for development and debugging scenarios, making it easier to troubleshoot and optimize applications during development.
**Related PR:** [#217](https://github.com/heroui-inc/heroui-native/pull/217)
### Variant Style Prop Support
The [Checkbox](/docs/native/components/checkbox), [Radio](/docs/native/components/radio), [TextField](/docs/native/components/text-field), and [InputOTP](/docs/native/components/input-otp) components now support the `variant` style prop for easier variant customization.
**New Capability:**
```tsx
import { Checkbox, Radio, TextField, InputOTP } from "heroui-native";
// Apply variant styles directly via style prop
Option 1
Option 2
```
This enhancement provides developers with more flexibility when customizing component variants, allowing variant changes to be applied via the style prop in addition to the component's variant prop.
**Related PR:** [#220](https://github.com/heroui-inc/heroui-native/pull/220)
## Style Fixes
### Border Radius Configuration
Fixed global border radius configuration not applying correctly to certain components.
**Fixes:**
* Fixed Button component not respecting global border radius configuration
* Fixed Chip component border radius application
* Fixed Tabs component border radius application
### Style Optimizations
* **Border Radius Consistency**: Improved consistency of border radius application across Button, Chip, and Tabs components
* **Theme Configuration**: Enhanced theme configuration propagation to ensure all components respect global settings
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #93](https://github.com/heroui-inc/heroui-native/issues/93)**: Fixed global border radius configuration not applying to Button component in hero-ui-native using Unwind. The Button component now properly respects border radius settings defined in the global theme configuration, ensuring consistent styling across the application.
* **[Issue #213](https://github.com/heroui-inc/heroui-native/issues/213)**: Fixed Select controlled mode (`isOpen`) not working. The Select component now properly handles controlled state when the `isOpen` prop is provided, allowing developers to manage Select open/close state externally with predictable behavior.
**Related PRs:**
* [#218](https://github.com/heroui-inc/heroui-native/pull/218)
* [#215](https://github.com/heroui-inc/heroui-native/pull/215)
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# Beta 13
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/beta-13
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/beta-13.mdx
> TextArea component, Button outline variant, Tabs improvements, form component decomposition, popup animation refactor, style class exports, and critical bug fixes
February 3, 2026
Beta 13 introduces the TextArea component for multiline text input, adds Button outline variant, and exports style class names for all components. This release also includes significant improvements to Tabs with better animations and clearer variant naming, decomposes form components into standalone primitives for better flexibility, refactors popup animation system for improved consistency and Android compatibility, and fixes critical issues including Chinese character input handling, theme color calculations, Uniwind Pro compatibility, BottomSheet opening issues, and tree-shaking support. These updates enhance developer experience and component reliability across the library.
## Installation
Update to the latest version:
```bash
npm i heroui-native@beta
```
```bash
pnpm add heroui-native@beta
```
```bash
yarn add heroui-native@beta
```
```bash
bun add heroui-native@beta
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **3 new** essential components:
* **[TextArea](/docs/native/components/text-area)**: Multiline text input component with styled border and background for collecting longer user input.
* **[Input](/docs/native/components/input)**: Single-line text input component with styled border and background, now available as a standalone component separate from TextField.
* **[CloseButton](/docs/native/components/close-button)**: Reusable button component for closing dialogs, modals, or dismissing content with consistent styling across overlay components.
#### TextArea
The TextArea component provides a complete solution for multiline text input scenarios, such as comments, messages, descriptions, and longer form fields. It features seamless integration with TextField for complete form structure, validation state support, and customizable variants for different visual contexts.
**Features:**
* Multiline text input with customizable rows
* Seamless integration with TextField component
* Validation state support with visual feedback
* Primary and secondary variants for different contexts
* Disabled and read-only states
* Customizable styling via className and styles props
* Complete accessibility support
**Usage:**
```tsx
import { Description, Label, TextArea, TextField } from "heroui-native";
export function Example() {
return (
Please provide as much detail as possible.
);
}
```
For complete documentation and examples, see the [TextArea component page](/docs/native/components/text-area).
**Related PR:** [#254](https://github.com/heroui-inc/heroui-native/pull/254)
#### Input
The Input component is now available as a standalone component, providing single-line text input functionality with styled border and background. Previously available only as `TextField.Input`, Input can now be used independently or integrated with form components like TextField and ControlField.
**Features:**
* Single-line text input with styled border and background
* Standalone usage or integration with form components
* Validation state support with visual feedback
* Primary and secondary variants for different contexts
* Disabled and read-only states
* Customizable styling via className and styles props
* Complete accessibility support
**Usage:**
```tsx
import { Description, Input, Label, TextField } from "heroui-native";
export function Example() {
return (
We'll never share your email.
);
}
```
For complete documentation and examples, see the [Input component page](/docs/native/components/input).
**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
#### CloseButton
The CloseButton component provides a reusable solution for closing dialogs, modals, popovers, and other overlay components. It features consistent styling across all overlay components, customizable icon properties, and seamless integration with Dialog, Popover, Select, and Bottom Sheet components.
**Features:**
* Consistent close button styling across overlay components
* Customizable icon size and color
* Support for custom children to replace default icon
* Disabled state support
* Seamless integration with Dialog, Popover, Select, and Bottom Sheet
* Default styling optimized for overlay contexts
**Usage:**
```tsx
import { CloseButton } from "heroui-native";
// Standalone usage
// As part of Dialog, Popover, Select, Bottom Sheet
```
For complete documentation and examples, see the [CloseButton component page](/docs/native/components/close-button).
**Related PR:** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
### New Subcomponents
#### Tabs.Separator
The Tabs component now includes a new `Separator` subcomponent that provides animated visibility control between tab triggers. This allows developers to create visual separators that automatically show or hide based on the active tab state.
**Features:**
* Animated visibility transitions based on active tab
* Configurable visibility via `betweenValues` prop
* Customizable animation timing and opacity
* Always visible option for static separators
**Usage:**
```tsx
import { Tabs } from "heroui-native";
GeneralNotifications
```
**Related PR:** [#228](https://github.com/heroui-inc/heroui-native/pull/228)
## Component Improvements
### Button Outline Variant
The [Button](/docs/native/components/button) component now includes an `outline` variant that provides a bordered style with transparent background, offering more visual variety for button designs.
**Improvements:**
* New `outline` variant for bordered button style
* Consistent styling with other Button variants
* Proper hover and focus states for outline variant
* Seamless integration with existing Button API
**Usage:**
```tsx
import { Button } from "heroui-native";
```
**Related PR:** [#235](https://github.com/heroui-inc/heroui-native/pull/235)
### Tabs Indicator Animation Refactor
The [Tabs](/docs/native/components/tabs) component's indicator animation has been refactored to use `translateX` transforms instead of width/height animations, resulting in smoother and more performant tab indicator transitions.
**Improvements:**
* Migrated indicator animation to `translateX` transforms
* Improved animation performance and smoothness
* Better visual consistency during tab transitions
* Reduced layout recalculations during animations
**Related PR:** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
### Popover Arrow Sizing and Visual Connection
The [Popover](/docs/native/components/popover) component has been improved with better arrow sizing and visual connection to the popover content, creating a more cohesive visual appearance.
**Improvements:**
* Improved arrow sizing relative to popover content
* Enhanced visual connection between arrow and popover
* Better alignment and spacing
* More polished overall appearance
**Related PR:** [#243](https://github.com/heroui-inc/heroui-native/pull/243)
### Form Components Decomposition
Form components have been decomposed into standalone primitives, providing developers with more flexibility and better control over component composition.
**Improvements:**
* Decomposed form components into standalone primitives
* Improved component reusability and composition
* Better separation of concerns
* Enhanced flexibility for custom form layouts
**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
### Input Android Shadow Fix
The [Input](/docs/native/components/input) component now includes platform-specific shadow styling for Android, ensuring consistent visual appearance across platforms.
**Improvements:**
* Added platform-specific shadow for Android
* Improved visual consistency across iOS and Android
* Better elevation appearance on Android devices
* Enhanced component appearance on Android platform
**Related PR:** [#248](https://github.com/heroui-inc/heroui-native/pull/248)
### Popup Animation System Refactor
The animation system for popup components (Popover, Select, Dialog, BottomSheet) has been refactored to improve entering/exiting animation logic, overlay composition, and content animation handling. This change standardizes animation behavior across all popup components and fixes Android pointer events issues.
**Improvements:**
* Standardized entering/exiting animations using FadeInDown/FadeOutDown for dialog presentations
* Refactored overlay animation hooks to support both progress-based and entering/exiting animations
* Improved overlay composition using Dialog.Overlay and Popover.Overlay components instead of Pressable wrappers
* Fixed Android pointer events issue affecting popup interactions
* Made presentation prop explicit in examples (popover, dialog, bottom-sheet)
* Simplified animation API for better maintainability and consistency
**Related PR:** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
## API Enhancements
### Granular Exports for Bundle Optimization
The library now provides granular exports for each component, allowing developers to reduce bundle size by importing only the components they need.
**New Capability:**
```tsx
// Granular imports - use when you need only a few components
import { HeroUINativeProvider } from "heroui-native/provider";
import { Button } from "heroui-native/button";
import { Card } from "heroui-native/card";
// General import - imports the whole library, use when you're using many components
import { Button, Card } from "heroui-native";
```
Granular imports are ideal when you only need a few components, as they help keep your bundle size smaller. General imports from `heroui-native` will include the entire library, which is convenient when you're using many components throughout your app.
**Available granular exports:**
* `heroui-native/provider` - Provider component
* `heroui-native/[component-name]` - Individual components
* `heroui-native/portal` - Portal utilities
* `heroui-native/utils` - Utility functions
* `heroui-native/hooks` - Custom hooks
**Important**: To keep the bundle size under control, you must follow the pattern with granular imports consistently. Even one general import from `heroui-native` will break this optimization strategy.
**Related PR:** [#233](https://github.com/heroui-inc/heroui-native/pull/233)
### Style Class Names Export
All components now export their style class names, enabling developers to reference component styles programmatically and create custom styling solutions.
**New Capability:**
```tsx
import { buttonClassNames } from "heroui-native";
// Access component class names programmatically
const customStyles = {
base: buttonClassNames.base,
variant: buttonClassNames.variant,
};
```
This enhancement provides developers with programmatic access to component class names, enabling advanced styling scenarios and custom theme implementations.
**Related PR:** [#252](https://github.com/heroui-inc/heroui-native/pull/252)
## Style Fixes
### Style Optimizations
* **Quaternary Variant Removal**: Removed quaternary variant and polished component styles for better consistency
* **Component Style Polish**: Enhanced styling across multiple components for improved visual consistency
* **Shadow and Border Radius Updates**: Improved shadow and border radius consistency across components
* **Theme Variable Cleanup**: Simplified theme variables and removed redundant color-mix calculations
**Related PR:** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
## ⚠️ Breaking Changes
### Tabs Variant Prop Rename
The Tabs component's `variant` prop has been renamed from `pill`/`line` to `primary`/`secondary` for better clarity and consistency with other components.
**Migration:**
Update all instances of Tabs variant prop:
```tsx
// Before
{/* content */}
{/* content */}
// After
{/* content */}
{/* content */}
```
**Available options:**
* `"primary"` - Primary variant (previously `"pill"`)
* `"secondary"` - Secondary variant (previously `"line"`)
**Related PR:** [#236](https://github.com/heroui-inc/heroui-native/pull/236)
### Tabs Indicator Animation Refactor
The [Tabs](/docs/native/components/tabs) component's indicator animation has been refactored to use `translateX` transforms instead of `left` positioning for GPU-accelerated performance. This change improves animation performance but requires updates to custom animation configurations.
**Migration:**
If you have customized the Tabs indicator animation, update your animation configuration:
```tsx
// Before
{/* content */}
// After
{/* content */}
```
**What Changed:**
* Animation API changed from `left` to `translateX` in `TabsIndicatorAnimation` configuration
* Indicator positioning now uses `translateX` transform for GPU-accelerated animations
* Added `left-0` base class to indicator styles to maintain initial positioning
* Visual behavior remains identical, only the underlying implementation has changed
**Related PR:** [#227](https://github.com/heroui-inc/heroui-native/pull/227)
### Divider Component Rename
The `Divider` component has been renamed to `Separator` for better consistency with naming conventions and to avoid confusion with other divider implementations.
**Migration:**
Update all imports and usages:
```tsx
// Before
import { Divider } from "heroui-native";
// After
import { Separator } from "heroui-native";
```
**Related PR:** [#238](https://github.com/heroui-inc/heroui-native/pull/238)
### Quaternary Variant Removal
The `quaternary` variant has been removed from [Surface](/docs/native/components/surface) and [Card](/docs/native/components/card) components to simplify the design system and improve consistency.
**Migration:**
Update any components using the `quaternary` variant:
```tsx
// Before
{/* content */}
{/* content */}
// After
// Use default, secondary, or tertiary variants, or apply custom styling
{/* content */}
{/* content */}
// Or use custom styling for specific needs
{/* content */}
```
**Available variants:**
* `"default"` - Default surface styling
* `"secondary"` - Secondary surface styling
* `"tertiary"` - Tertiary surface styling
**Related PR:** [#246](https://github.com/heroui-inc/heroui-native/pull/246)
### Form Component Decomposition
As part of the form component decomposition, several components have been renamed and restructured to provide better flexibility and composition patterns.
**Component Renames:**
* `FormField` has been renamed to `ControlField`
* `ErrorView` has been renamed to `FieldError`
**Migration:**
Update all imports and usages:
```tsx
// Before
import { FormField, ErrorView, TextField } from "heroui-native";
Error message
// After
import { ControlField, FieldError, Input, TextField } from "heroui-native";
Error message
```
**TextField.Input Removal:**
The `TextField.Input` subcomponent has been removed. Use the standalone `Input` component instead:
```tsx
// Before
import { TextField } from "heroui-native";
// After
import { Input, TextField } from "heroui-native";
```
**Component Composition Changes:**
`RadioGroup`, `TextField`, and `ControlField` now use `Label`, `Description`, and `FieldError` components directly, providing more flexible composition:
```tsx
import { ControlField, Description, FieldError, Input, Label, RadioGroup, TextField } from "heroui-native";
// TextField with Label, Description, and FieldError
We'll never share your email.Invalid email address
// RadioGroup with Label, Description, and FieldError
Option 1Choose one optionPlease select an option
// ControlField with Label, Description, and FieldError
Additional informationValidation error
```
**Related PR:** [#247](https://github.com/heroui-inc/heroui-native/pull/247)
### CloseButton Component and asChild Removal
A new reusable `CloseButton` component has been introduced, and all close button implementations across Dialog, Popover, Select, and BottomSheet components have been refactored to use this shared component. The `asChild` prop has been removed from all Close components.
**Migration:**
Update any usage of `asChild` prop on Close components:
```tsx
// Before
import { Button, Dialog } from "heroui-native";
// After
import { Button, Dialog } from "heroui-native";
const [isOpen, setIsOpen] = useState(false);
```
**What Changed:**
* New `CloseButton` component added with default `variant="tertiary"`, `size="sm"`, and `isIconOnly={true}`
* `Dialog.Close`, `Popover.Close`, `Select.Close`, and `BottomSheet.Close` now extend `CloseButton` internally
* The `asChild` prop has been removed from all Close components
* Close components still support all Button props including `variant`, `size`, `iconProps`, and custom `children`
* You must now handle close logic manually when using custom buttons instead of Close components
**Related PR:** [#237](https://github.com/heroui-inc/heroui-native/pull/237)
### Popup Animation System Refactor
The animation system for popup components has been refactored, resulting in several API changes that require code updates.
**Migration:**
* Remove `closeDelay` and `isDismissKeyboardOnClose` props from `Dialog.Root`
* Remove custom `entering`/`exiting` animation configs from `Dialog.Root` animation prop (now only supports disable flags). Custom animations should be configured using Keyframe animations directly on `Dialog.Content` component
* Remove `isAnimatedStyleActive` and `onLayout` props from `Dialog.Content`
* Remove `isDismissKeyboardOnClose` prop from `BottomSheet.Root`
* Update `BottomSheet.Overlay` animation prop to remove `entering`/`exiting` properties (no longer supported)
* Make `presentation` prop explicit on all `Popover.Content` and `Select.Content` components (changed from optional to required)
* Update animation hooks usage: `useBottomSheetAnimation()` no longer returns `bottomSheetState`, `useDialogAnimation()` no longer returns `dialogState`
**What Changed:**
* `Dialog.Root`: Removed `closeDelay` and `isDismissKeyboardOnClose` props
* `Dialog.Root`: Animation prop type changed from `DialogRootAnimation` (supported custom entering/exiting) to `AnimationRootDisableAll` (disable flags only)
* `Dialog.Content`: Removed `isAnimatedStyleActive` and `onLayout` props
* `BottomSheet.Root`: Removed `isDismissKeyboardOnClose` prop
* `BottomSheet.Overlay`: Animation prop no longer supports `entering`/`exiting` properties
* `Popover.Content`: `presentation` prop is now required (was optional, defaulted to `"popover"`)
* `Select.Content`: `presentation` prop is now required (was optional, defaulted to `"popover"`)
* Animation hooks: `useBottomSheetAnimation()` no longer returns `bottomSheetState`, `useDialogAnimation()` no longer returns `dialogState`
**Related PR:** [#263](https://github.com/heroui-inc/heroui-native/pull/263)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #181](https://github.com/heroui-inc/heroui-native/issues/181)**: Fixed TextField error when inputting Chinese characters. The TextField component now properly handles multibyte characters and international input, ensuring smooth text entry for all languages including Chinese, Japanese, and Korean.
* **[Issue #219](https://github.com/heroui-inc/heroui-native/issues/219)**: Fixed Button `childrenToString()` returning `"[object Object]"` for multiple children. The function now properly handles React elements and complex children structures, preventing stringification issues when rendering button content.
* **[Issue #232](https://github.com/heroui-inc/heroui-native/issues/232)**: Fixed HeroUINativeProvider breaking with the recently released Uniwind Pro. The provider now properly handles Uniwind Pro compatibility, ensuring smooth integration with the latest Uniwind version.
* **[Issue #259](https://github.com/heroui-inc/heroui-native/issues/259)**: Fixed BottomSheet issue where opening quickly and starting a meeting would prevent it from opening again. The refactored animation system resolves this issue by improving the entering/exiting animation logic.
* **[Issue #261](https://github.com/heroui-inc/heroui-native/issues/261)**: Fixed `@gorhom/bottom-sheet` not being tree-shaken. The library now properly supports tree-shaking for unused dependencies.
**Additional Fixes:**
* Fixed theme calculated colors issue that was causing incorrect color values in certain scenarios
* Fixed `childrenToString` function to prevent React elements from being stringified incorrectly
**Related PRs:**
* [#226](https://github.com/heroui-inc/heroui-native/pull/226)
* [#239](https://github.com/heroui-inc/heroui-native/pull/239)
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# create-heroui-native-app
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/create-heroui-native-app
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/create-heroui-native-app.mdx
> New CLI for scaffolding a preconfigured HeroUI Native + Expo Router project — Expo SDK 56, React Native 0.85, Uniwind, all peer dependencies wired up, two starter templates (single-screen and tabs).
June 4, 2026
🎉 A new CLI — [`create-heroui-native-app`](https://www.npmjs.com/package/create-heroui-native-app) — is now the fastest way to start a HeroUI Native project. One command scaffolds a complete Expo Router app with HeroUI Native, Uniwind, Tailwind CSS, every required peer dependency, and the provider wiring already in place. No manual setup of `global.css`, `metro.config.js`, or `app/_layout.tsx`.
## Quick Start
```bash
npx create-heroui-native-app@latest my-app
```
```bash
pnpm create heroui-native-app@latest my-app
```
```bash
yarn create heroui-native-app my-app
```
```bash
bun create heroui-native-app@latest my-app
```
Then start the dev server:
```bash
cd my-app
npm run start
```
That's it. Skip ahead to the [Quick Start guide](/docs/native/getting-started/quick-start) for the full walkthrough.
## Starter Templates
The CLI ships with two templates. Pick one in the interactive picker, or pass a flag to skip the prompt.
| Flag | Template | Description |
| ------------- | ----------- | ---------------------------------------------------------------- |
| `--expo` | `expo` | Single-screen Expo Router app with a HeroUI `Button` demo. |
| `--expo-tabs` | `expo-tabs` | Expo Router tabs layout with two tabs (`Button` + `Card` demos). |
```bash
npx create-heroui-native-app@latest my-app --expo
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
```
## What You Get
Every scaffolded project ships preconfigured with:
* **Expo SDK 56** + **Expo Router** with typed routes enabled
* **React 19.2** + **React Native 0.85.2** + Hermes v1 (default in SDK 56)
* **HeroUI Native** wrapped in `HeroUINativeProvider` and `GestureHandlerRootView` inside `app/_layout.tsx`
* **Uniwind** + **Tailwind CSS** wired through `metro.config.js` and `global.css`
* All HeroUI Native **mandatory peer dependencies** pinned to compatible versions: `react-native-reanimated`, `react-native-gesture-handler`, `react-native-worklets`, `react-native-safe-area-context`, `react-native-svg`, `tailwind-variants`, `tailwind-merge`
* `react-native-screens` so HeroUI overlay components (`Dialog`, `Menu`, `Popover`, `Select`, `BottomSheet`, `Toast`) work out of the box
* `@expo/metro-runtime` (required peer for Expo Router on SDK 56)
* A `babel.config.js` using just `babel-preset-expo` (worklets handled by the preset)
* **TypeScript** with `strict: true` and the `@/*` path alias
## CLI Reference
```text
create-heroui-native-app [project-name] [options]
```
| Option | Description |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `[project-name]` | Directory name to create. Prompted if omitted. Must be a valid npm package name. |
| `--expo` | Use the single-screen Expo template. |
| `--expo-tabs` | Use the Expo + tabs template. |
| `--template ` | Use the template with the given id (`expo` or `expo-tabs`). |
| `--use-npm` / `--use-yarn` / `--use-pnpm` / `--use-bun` | Force a specific package manager (otherwise auto-detected). |
| `--skip-install` | Don't run the package manager install step. |
| `--skip-git` | Don't initialize a git repository. |
| `-h`, `--help` | Print usage and exit. |
### Examples
```bash
# Fully interactive — prompts for both project name and template
npx create-heroui-native-app@latest
# Project name supplied, template picker still shown
npx create-heroui-native-app@latest my-app
# Fully non-interactive
npx create-heroui-native-app@latest my-app --expo
# Tabs template, install with pnpm
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm
# Scaffold only, no install, no git
npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git
```
## Requirements
* **Node.js 20.19.4+** (required by Expo SDK 56 / React Native 0.85)
* **iOS 16.4+** when building native iOS (Expo SDK 56 deployment target)
* macOS, Linux, or Windows
**Already have an app?** The CLI is for new projects. To add HeroUI Native to an existing React Native or Expo app, follow [Option 2 in the Quick Start](/docs/native/getting-started/quick-start#option-2-add-to-an-existing-project).
## Links
* [Quick Start guide](/docs/native/getting-started/quick-start)
* [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server)
# All Releases
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/index.mdx
> All updates and changes to HeroUI Native, including new features, fixes, and breaking changes.
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Latest Release
### `create-heroui-native-app`
**June 2026**
🎉 A new CLI for scaffolding a HeroUI Native project in one command. `npx create-heroui-native-app@latest my-app` generates a complete Expo Router app with HeroUI Native, Uniwind, Tailwind CSS, every required peer dependency, and the provider wiring already in place — pick between a single-screen or tabs starter template.
[Read full release notes →](/docs/native/releases/create-heroui-native-app)
### v1.0.4
**May 2026**
This patch release renames the `Text` typography component to `Typography` (with deprecated `Text` exports preserved for backward compatibility), refines soft-foreground theme tokens across `Alert`, `Avatar`, `Button`, `Chip`, and `Toast` with an optional `heroui-native/styles/vibrant` palette, documents the iOS native modal offset workaround for `Menu`, `Popover`, and `Select`, and upgrades the example app to Expo 56 / React Native 0.85 while bumping the `@gorhom/bottom-sheet` peer to `^5.2.9`.
[Read full release notes →](/docs/native/releases/v1-0-4)
### v1.0.3
**May 2026**
This patch release introduces the new `Text` typography component with `Heading`, `Paragraph`, and `Code` sub-components, fixes `ScrollShadow` support for inverted lists and `Tabs` indicator alignment in RTL layouts, and unifies the `Select.TriggerIndicator` animation when using custom children. It also makes `Avatar`'s `alt` prop optional, refines `Button`, `Chip`, and `Input` styles, and corrects inner padding behavior for `TextField` and `SearchField`.
[Read full release notes →](/docs/native/releases/v1-0-3)
### v1.0.2
**April 2026**
This patch release introduces the `asChild` slot pattern for PressableFeedback and Surface, adds VoiceOver modal containment support across all portal-based overlays, fixes an Android-specific Button outline variant styling issue, and refines Input and Select visual styles.
[Read full release notes →](/docs/native/releases/v1-0-2)
### v1.0.1
**April 2026**
This patch release fixes a race condition in the Toast provider where the `total` SharedValue drifted from the actual toast count, corrects disabled-state styling across seven components to use the native `disabled:` modifier, and introduces the `--backdrop` theme variable for overlay components.
[Read full release notes →](/docs/native/releases/v1-0-1)
### v1.0.0
**March 2026**
🎉 HeroUI Native reaches its first stable release, graduating from beta and release candidate stages. This milestone includes the new LinkButton component, sub-menu conflict resolution, an optional `@gorhom/bottom-sheet` peer dependency, and improved type safety for `useThemeColor`.
[Read full release notes →](/docs/native/releases/v1-0-0)
### RC 4
**March 2026**
This release introduces the SubMenu compound component for nested expandable menus with animated expand/collapse, refactors Slider Output composition with slot-based styling and `textProps` forwarding, and fixes PressableFeedback ripple animation blink on rapid presses.
[Read full release notes →](/docs/native/releases/rc-4)
### RC 3
**February 2026**
This release introduces three new components—TagGroup, Menu, and InputGroup—adds Android hardware back button support for all bottom-sheet-based overlays, and achieves Expo 55 compatibility with a critical `combineStyles` fix that preserves Reanimated animated style bindings.
[Read full release notes →](/docs/native/releases/rc-3)
### RC 2
**February 2026**
This release introduces three new components—SearchField, ListGroup, and Slider—adds multi-selection mode to Select with type-safe generics, and refactors the Button feedback API into a unified `feedbackVariant` + `animation` prop pattern. Peer dependency constraints are relaxed for broader Expo SDK 55 compatibility, and several Select and Avatar bugs are fixed.
[Read full release notes →](/docs/native/releases/rc-2)
### RC 1
**February 2026**
This release introduces the Alert compound component with five status variants and accessibility primitives, extracts Radio into a standalone component with dual-mode operation, and adds the animated Select.TriggerIndicator subcomponent. It also delivers HeroUINativeProviderRaw for bundle optimization, a `disableFullWindowOverlay` prop for iOS debugging, unified `styles` prop support across six components, and theme surface variable refactoring with explicit per-theme definitions.
[Read full release notes →](/docs/native/releases/rc-1)
### Beta 13
**February 2026**
This release introduces the TextArea component for multiline text input, adds Button outline variant, exports style class names for all components, and includes a reusable CloseButton component. The release also refactors Tabs with improved animations and variant naming, decomposes form components into standalone primitives, and adds granular exports for bundle optimization. Critical bug fixes for theme colors and component stringification are also included.
[Read full release notes →](/docs/native/releases/beta-13)
### Beta 12
**January 2026**
This release introduces three essential form components—InputOTP, Label, and Description—that enhance form building capabilities in React Native applications. The release also includes critical fixes for Popover close behavior, popup controlled state management, border radius configuration, and adds variant style prop support across multiple form components.
[Read full release notes →](/docs/native/releases/beta-12)
### Beta 11
**January 2026**
This release enhances component reliability and developer experience with improved close coordination for Bottom Sheet, fixes for Dialog swipe-to-dismiss gestures, TextField styling improvements, and a new PortalHost export for advanced portal mounting scenarios. These updates ensure smoother interactions and provide more flexibility for custom layouts.
[Read full release notes →](/docs/native/releases/beta-11)
### Beta 10
**December 2025**
This release introduces the new [Bottom Sheet](/docs/native/components/bottom-sheet) component, refactors [PressableFeedback](/docs/native/components/pressable-feedback) with improved API, extends the Animation API with State Prop support, enhances the `use-theme-color` hook to handle multiple colors selection, and includes various bug fixes and documentation improvements.
[Read full release notes →](/docs/native/releases/beta-10)
## Release Schedule
HeroUI Native follows a regular release cycle:
* **Stable releases**: v1.0.0 shipped Q1 2026
* **Patch releases**: Bug fixes and minor improvements as needed
## Contributing
Found an issue or want to contribute? Check out our [GitHub repository](https://github.com/heroui-inc/heroui-native).
# RC 1
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/rc-1
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/rc-1.mdx
> Alert component, standalone Radio component, Select TriggerIndicator, HeroUINativeProviderRaw, disableFullWindowOverlay prop, styles prop expansion, theme surface refactor
February 12, 2026
RC 1 marks the first Release Candidate for HeroUI Native, signaling that the library is approaching production readiness. This release introduces the Alert compound component with accessibility-first design and status variants, extracts Radio into a standalone component with dual-mode operation, and adds the animated Select.TriggerIndicator subcomponent. It also delivers a lightweight HeroUINativeProviderRaw for bundle optimization, a new `disableFullWindowOverlay` prop for iOS debugging, unified `styles` prop support across six components, and a theme refactor that replaces calculated surface colors with explicit theme-defined variables. Several critical bug fixes—including InputOTP in BottomSheet, toast text clipping, and element inspector compatibility—round out the release.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **1 new** component:
* **[Alert](/docs/native/components/alert)**: Accessible alert component with five status variants and compound sub-components for flexible content composition.
#### Alert
The Alert component provides accessible alert messaging with built-in support for five status variants: default, accent, success, warning, and danger. It follows the compound component pattern with `Alert.Indicator`, `Alert.Content`, `Alert.Title`, and `Alert.Description` sub-components, giving developers full control over layout and customization. The primitive layer provides `role="alert"`, `aria-labelledby`, and `aria-describedby` accessibility associations automatically.
**Features:**
* Five status variants: default, accent, success, warning, and danger
* Default SVG status icons with theme-aware colors via `useStatusColor` hook
* Compound component architecture with Indicator, Content, Title, and Description sub-components
* Custom indicator support (e.g., replace default icon with a Spinner)
* Accessibility primitives with `role="alert"`, `aria-labelledby`, and `aria-describedby`
* `asChild` slot support on all sub-components
* Ref forwarding and `className` prop support on all parts
**Usage:**
```tsx
import { Alert } from "heroui-native";
export function Example() {
return (
Payment successful
Your payment has been processed successfully.
);
}
```
For complete documentation and examples, see the [Alert component page](/docs/native/components/alert).
**Related PR:** [#284](https://github.com/heroui-inc/heroui-native/pull/284)
### New Subcomponents
#### Select.TriggerIndicator
The [Select](/docs/native/components/select) component now includes a `TriggerIndicator` subcomponent that displays an animated chevron icon to visually indicate the open/close state. The indicator rotates smoothly when the select opens or closes, using React Native Reanimated spring physics.
**Features:**
* Animated chevron icon that rotates on open/close transitions
* Customizable animation configuration via `animation` prop with rotation values and spring config
* Icon customization through `iconProps` (size, color)
* Support for custom children to replace the default chevron
* Automatic state synchronization with Select open/close state
**Usage:**
```tsx
import { Select } from "heroui-native";
```
**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
## Component Improvements
### Toast Styling and Stacking Refactor
The [Toast](/docs/native/components/toast) component styling has been refactored to replace the border-based padding approach with proper padding and vertical placeholder views, improving content visibility when toasts stack.
**Improvements:**
* Replaced `border-[16px]` padding workaround with proper `p-4` padding
* Added `useVerticalPlaceholderStyles` hook for placeholder view styling
* Added absolute positioned placeholder Views at top and bottom to prevent content visibility when toasts stack
* Updated shadow system to use `shadow-overlay` token
* Standardized overlay shadow values across all themes (alpha, mint, sky) with lighter opacity
This refactor ensures content remains properly hidden when toasts of different heights stack together, while providing a more maintainable and predictable styling approach.
**Related PR:** [#229](https://github.com/heroui-inc/heroui-native/pull/229)
### Dialog Overlay Animation Fix
The [Dialog](/docs/native/components/dialog) component's popup animation timing has been fixed when closing via gesture. The progress value is now properly sequenced with delays to ensure the closing animation completes before resetting.
**Improvements:**
* Progress value now transitions to 2 after a 300ms delay when closing via gesture
* Progress resets to 0 after 350ms to ensure animation completion
* Removed immediate `progress.set(2)` call when `isOpen` becomes false
* Smooth closing animations now play correctly when dismissing popups via swipe gestures
**Related PR:** [#277](https://github.com/heroui-inc/heroui-native/pull/277)
### Theme Surface Variables Refactor
The theme system has been refactored to replace calculated surface colors with explicit theme-defined variables, providing more control and consistency across themes.
**Improvements:**
* `surface-secondary` and `surface-tertiary` (with foregrounds) are now defined explicitly in each theme (alpha, lavender, mint, sky, variables.css)
* Base theme uses `var(--surface-secondary)` and `var(--surface-tertiary)` instead of `color-mix` calculations
* Removed `on-surface`, `on-surface-secondary`, and `on-surface-tertiary` palettes from theme.css
* Updated theming documentation with the new variable structure and examples
This change gives theme authors direct control over surface color values rather than relying on `color-mix` calculations, resulting in more predictable and consistent surface styling across all themes.
**Related PR:** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
## API Enhancements
### Unified `styles` Prop for Multiple Components
Six components now support the unified `styles` prop for slot-based styling, providing a consistent pattern for applying styles to component internals.
**Supported components:**
* **Accordion**: `container` and `separator` slots
* **AvatarFallback**: `container` and `text` slots
* **FieldError**: `container` and `text` slots
* **Label**: `text` and `asterisk` slots (also fixed `style` prop handling)
* **PressableFeedback Ripple**: `container` and `ripple` slots (replaces `containerStyle` and `rippleStyle`)
* **SelectContentDialog**: `wrapper` and `content` slots
**New Capability:**
```tsx
import { Accordion, Label } from "heroui-native";
// Apply styles to specific slots
{/* Accordion items */}
```
All changes maintain backward compatibility with existing `style` props and properly merge styles when both are provided.
**Related PR:** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
### `disableFullWindowOverlay` Prop
Portal-based components now support a `disableFullWindowOverlay` prop that enables React Native element inspector support on iOS during development.
**Supported components:**
* `BottomSheet.Portal`
* `Dialog.Portal`
* `Popover.Portal`
* `Select.Portal`
* `ToastProvider`
**New Capability:**
```tsx
import { Dialog } from "heroui-native";
// Enable element inspector support on iOS
```
On iOS, `FullWindowOverlay` uses a separate native window that blocks the React Native element inspector. Setting `disableFullWindowOverlay` to `true` renders content in the main window instead, enabling the inspector during development. The tradeoff is that overlays will no longer appear above native modals or the keyboard. This prop has no effect on Android.
For Toast, the prop is passed via `config.toast` when using `HeroUINativeProvider`.
**Related PR:** [#283](https://github.com/heroui-inc/heroui-native/pull/283)
### HeroUINativeProviderRaw
A new lightweight provider variant, `HeroUINativeProviderRaw`, excludes `ToastProvider` and `PortalHost` to give consumers full control over which dependencies are bundled.
**New Capability:**
```tsx
import { HeroUINativeProviderRaw } from "heroui-native/provider-raw";
// Lightweight provider without Toast and Portal dependencies
export function App() {
return (
{/* Your app content */}
);
}
```
This makes `react-native-screens`, `@gorhom/bottom-sheet`, and `react-native-svg` fully optional dependencies. The raw provider includes only `SafeAreaListener`, `GlobalAnimationSettingsProvider`, and `TextComponentProvider`. Consumers who need toast or portal features can compose them manually.
**Related PR:** [#285](https://github.com/heroui-inc/heroui-native/pull/285)
### Select.Trigger `variant` Prop
The `Select.Trigger` component now supports a `variant` prop with `"default"` and `"unstyled"` options, enabling better composition with custom trigger components like Button.
**New Capability:**
```tsx
import { Button, Select } from "heroui-native";
// Default variant (pre-styled trigger)
// Unstyled variant for custom compositions
```
**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
### ControlField Radio Variant
The [ControlField](/docs/native/components/control-field) component now supports a `"radio"` variant in `ControlField.Indicator`, rendering a standalone Radio component alongside the existing `"switch"` and `"checkbox"` variants.
**New Capability:**
```tsx
import { ControlField } from "heroui-native";
Radio option
```
**Related PR:** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
## ⚠️ Breaking Changes
### PressableFeedback Ripple: Unified `styles` Prop
The PressableFeedback Ripple component's individual style props (`containerStyle` and `rippleStyle`) have been replaced with a unified `styles` prop.
**Migration:**
Update all instances of individual style props to the unified `styles` prop:
```tsx
// Before
// After
```
**Related PR:** [#271](https://github.com/heroui-inc/heroui-native/pull/271)
### Select.Trigger Default Styles
`Select.Trigger` now defaults to `variant="default"`, which applies default container styles (`flex-row items-center justify-between h-12 px-4 rounded-2xl bg-surface shadow-surface`). Users with custom styled triggers need to add `variant="unstyled"` to prevent default styles from being applied.
**Migration:**
```tsx
// Before (custom styled trigger)
{/* content */}
// After (add variant="unstyled" to preserve custom styling)
{/* content */}
```
**Related PR:** [#274](https://github.com/heroui-inc/heroui-native/pull/274)
### Surface Theme Variables Restructured
The `on-surface`, `on-surface-secondary`, and `on-surface-tertiary` CSS variables and their hover/focus variants have been removed from the base theme. Surface secondary and tertiary colors are now defined explicitly in each theme file.
**Migration:**
If you reference `on-surface`, `on-surface-secondary`, or `on-surface-tertiary` variables in custom styles, replace them with the appropriate surface foreground variables defined in your theme.
```css
/* Before */
color: var(--on-surface);
color: var(--on-surface-secondary);
/* After */
color: var(--surface-foreground);
color: var(--surface-secondary-foreground);
```
**Related PR:** [#281](https://github.com/heroui-inc/heroui-native/pull/281)
### RadioGroup Indicator Removed
`RadioGroup.Indicator` and `RadioGroup.IndicatorThumb` have been removed in favor of the new standalone `Radio` component. The related types `RadioGroupIndicatorProps`, `RadioGroupIndicatorThumbProps`, and `RadioGroupIndicatorThumbAnimation` are also removed from exports.
**Migration:**
Replace all `RadioGroup.Indicator` and `RadioGroup.IndicatorThumb` usages with the `Radio` component:
```tsx
// Before
import { RadioGroup } from "heroui-native";
Option 1
// After
import { Radio, RadioGroup } from "heroui-native";
Option 1
```
**Related PR:** [#286](https://github.com/heroui-inc/heroui-native/pull/286)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #229](https://github.com/heroui-inc/heroui-native/issues/229)**: Fixed InputOTP not working inside BottomSheet. The InputOTP component now functions correctly when rendered within a BottomSheet overlay, resolving input focus and interaction issues that previously prevented OTP entry in bottom sheet contexts.
* **[Issue #265](https://github.com/heroui-inc/heroui-native/issues/265)**: Fixed the first letter of Toast description text being clipped. The toast styling refactor replaces the border-based padding approach with proper padding and placeholder views, ensuring all text content is fully visible regardless of toast stacking configuration.
* **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**: Fixed FullWindowOverlay blocking the React Native element inspector on iOS. The new `disableFullWindowOverlay` prop on portal components allows developers to render overlay content in the main window during development, restoring element inspector functionality.
**Related PRs:**
* [#229](https://github.com/heroui-inc/heroui-native/pull/229)
* [#283](https://github.com/heroui-inc/heroui-native/pull/283)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Alert](/docs/native/components/alert) - New component documentation with usage examples and API reference
* [Radio](/docs/native/components/radio) - New standalone Radio component documentation
* [Radio Group](/docs/native/components/radio-group) - Updated to reflect RadioGroup.Indicator removal and Radio integration
* [Control Field](/docs/native/components/control-field) - Updated with new radio variant documentation
* [Select](/docs/native/components/select) - TriggerIndicator subcomponent and Trigger variant documentation
* [Toast](/docs/native/components/toast) - Updated styling approach documentation
* [Bottom Sheet](/docs/native/components/bottom-sheet) - Added disableFullWindowOverlay documentation
* [Dialog](/docs/native/components/dialog) - Added disableFullWindowOverlay documentation
* [Popover](/docs/native/components/popover) - Added disableFullWindowOverlay documentation
* [Provider](/docs/native/getting-started/provider) - HeroUINativeProviderRaw documentation and provider hierarchy
* [Theming](/docs/native/getting-started/theming) - Updated surface variable structure and examples
* [Accordion](/docs/native/components/accordion) - Added styles prop documentation
* [Avatar](/docs/native/components/avatar) - Added styles prop documentation
* [Label](/docs/native/components/label) - Added styles prop documentation
* [Field Error](/docs/native/components/field-error) - Added styles prop documentation
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# RC 2
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/rc-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/rc-2.mdx
> SearchField, ListGroup, and Slider components, Select multi-selection mode, Button feedback API refactor, peer dependency relaxation
February 20, 2026
RC 2 continues the march toward production readiness with three new components—SearchField, ListGroup, and Slider—and a powerful multi-selection mode for Select backed by type-safe generics. The Button feedback API has been refactored into a cleaner unified `feedbackVariant` + `animation` prop pattern, and peer dependency constraints are relaxed for broader compatibility with Expo SDK 55. Several Select and Avatar bug fixes round out the release.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **3 new** components:
* **[Slider](/docs/native/components/slider)**: Slider component with single-value and range modes, horizontal/vertical orientation, custom number formatting, and spring-animated thumb feedback.
* **[ListGroup](/docs/native/components/list-group)**: Surface-based grouped list component with pressable items, prefix/suffix slots, and default chevron navigation indicator.
* **[SearchField](/docs/native/components/search-field)**: Compound component for filtering and querying content with built-in search icon, clearable input, and auto-hide clear button.
#### Slider
The Slider component supports single-value and range (multi-thumb) modes, horizontal and vertical orientation, custom number formatting via `Intl.NumberFormat`, and spring-animated thumb feedback. The primitive layer handles all gesture and value logic independently, making it reusable for alternative styled implementations.
**Features:**
* Compound sub-components: `Slider.Output`, `Slider.Track`, `Slider.Fill`, `Slider.Thumb`
* Range slider: pass an array as `defaultValue`/`value` and use a render-function on `Slider.Track` to render multiple thumbs
* Vertical orientation via `orientation="vertical"`
* Custom formatting with `formatOptions` accepting `Intl.NumberFormatOptions` (currency, percent, unit, etc.)
* Gesture-handler-based drag and tap-to-position on track
* Value clamping, stepping, and multi-thumb support
* Spring-animated thumb scale via configurable `animation` prop
* Accessibility: each thumb receives `role="slider"` with full `accessibilityValue` (min, max, now, text)
* `useSlider` hook exposes slider context for advanced use cases
**Usage:**
```tsx
import { Slider } from "heroui-native";
export function BasicSlider() {
return (
);
}
export function RangeSlider() {
return (
{({ thumbs }) => (
<>
{thumbs.map((_, i) => (
))}
)}
);
}
```
For complete documentation and examples, see the [Slider component page](/docs/native/components/slider).
**Related PR:** [#305](https://github.com/heroui-inc/heroui-native/pull/305)
#### ListGroup
The ListGroup component renders grouped list items inside a Surface container, providing a polished navigation-list pattern commonly used in settings screens, menus, and content browsers. Each item supports prefix, content (title + description), and suffix slots with a default chevron-right navigation indicator.
**Features:**
* Surface-based container with rounded corners and consistent spacing
* Compound sub-components: `ListGroup.Item`, `ListGroup.ItemPrefix`, `ListGroup.ItemContent`, `ListGroup.ItemTitle`, `ListGroup.ItemDescription`, `ListGroup.ItemSuffix`
* Default chevron-right icon in `ItemSuffix` via internal `ChevronRightIcon`
* Pressable items with PressableFeedback integration
* Fully customizable slots for icons, badges, and other content
**Usage:**
```tsx
import { ListGroup } from "heroui-native";
export function Example() {
return (
console.log("Profile")}>
ProfileManage your account console.log("Settings")}>
SettingsApp preferences
);
}
```
For complete documentation and examples, see the [ListGroup component page](/docs/native/components/list-group).
**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
#### SearchField
The SearchField component provides a dedicated input for search and filtering scenarios, built with the same compound-component pattern used by TextField. It includes a search icon, clearable input, and an auto-hiding clear button that disappears when the input is empty.
**Features:**
* Compound sub-components: `SearchField.Group`, `SearchField.SearchIcon`, `SearchField.Input`, `SearchField.ClearButton`
* `ClearButton` auto-hides when value is empty and clears search text on press
* `SearchIcon` supports custom children to replace the default magnifying glass SVG
* Validation state support with visual feedback
* Disabled state support
* Seamless integration with Label, Description, and FieldError
**Usage:**
```tsx
import { Label, SearchField } from "heroui-native";
export function Example() {
return (
);
}
```
For complete documentation and examples, see the [SearchField component page](/docs/native/components/search-field).
**Related PR:** [#299](https://github.com/heroui-inc/heroui-native/pull/299)
### Select Multi-Selection Mode
The [Select](/docs/native/components/select) component now supports multi-item selection via a new `selectionMode` prop. The `RootProps` type is now generic on `SelectionMode`, so TypeScript correctly resolves `value` and `onValueChange` types per mode—`SelectOption` for single, `SelectOption[]` for multiple.
**Features:**
* `selectionMode="multiple"` enables toggling multiple items; `closeOnPress` defaults to `false` in multiple mode
* Type-safe generics: `RootProps` resolves `value` and `onValueChange` types via `SelectValueType`
* `Select.Value` formats multiple labels as "Apple, Banana and Cherry" using `formatSelectedLabels`
* Single mode remains fully backward-compatible (default)
**Usage:**
```tsx
import { Select } from "heroui-native";
export function MultiSelect() {
return (
);
}
```
**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
### New Subcomponents
#### PressableFeedback.Scale
A new compound sub-component for opt-in scale animation composability. `PressableFeedback.Scale` lets you add scale press animations to any pressable element—such as `ListGroup.Item`—without needing the root `PressableFeedback` to manage scale.
**Usage:**
```tsx
import { PressableFeedback } from "heroui-native";
{/* item content */}
```
**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
## Component Improvements
### Select Trigger and State Fixes
The [Select](/docs/native/components/select) component has been improved with several targeted fixes to the trigger and controllable state system.
**Improvements:**
* Custom `className` is now correctly forwarded to the trigger's style computation, resolving cases where user-provided classes were silently dropped
* `useControllableState` now resets internal state when transitioning from controlled to uncontrolled, preventing stale selections from persisting
* Trigger measures position via `onLayout` to properly support `isDefaultOpen`
* Updated trigger styles to use `gap-3`, `py-3.5` padding, and `flex-1` on the value text for improved layout
**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
### Avatar asChild Image Fix
The [Avatar](/docs/native/components/avatar) component's `AvatarImage` now correctly separates `source`, `style`, and `asChild` from rest props when forwarding to the underlying primitive, fixing an issue where all props were incorrectly spread to the image component when using `asChild`.
**Related PR:** [#298](https://github.com/heroui-inc/heroui-native/pull/298)
## API Enhancements
### Button Feedback API Refactor
The [Button](/docs/native/components/button) component's pressable feedback API has been refactored into a unified, type-safe `feedbackVariant` + `animation` prop pattern, replacing the previous multi-prop approach.
**New Capability:**
```tsx
import { Button } from "heroui-native";
// Scale + highlight (default)
// Scale + ripple
// Scale only
// Custom animation configuration
```
The `animation` prop is a discriminated union typed per variant, providing full type-safety for each feedback configuration.
New utility helpers `resolveAnimationObject` and `isAnimationDisabled` in `button.utils.ts` centralise animation prop resolution.
**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
## Dependencies
### Relaxed Peer Dependency Constraints
Peer dependency version constraints have been relaxed to use caret (`^`) and range (`>=`) specifiers instead of restrictive tilde (`~`) or pinned versions. This improves compatibility for consumers on newer dependency versions, particularly those using Expo SDK 55.
**Changes:**
* `react-native-reanimated`: `~4.1.1` → `^4.1.1` (allows minor updates)
* `react-native-safe-area-context`: `~5.6.0` → `^5.6.0` (allows minor updates)
* `react-native-svg`: `15.12.1` → `^15.12.1` (allows patch/minor updates)
* `react-native-worklets`: `0.5.1` → `>=0.5.1` (allows any version 0.5.1+)
No runtime code changes are included—existing projects with previously valid versions continue to work without modification.
**Related PR:** [#306](https://github.com/heroui-inc/heroui-native/pull/306)
## ⚠️ Breaking Changes
### Button Feedback API
The `pressableFeedbackVariant`, `pressableFeedbackHighlightProps`, and `pressableFeedbackRippleProps` props on Button have been removed. Consumers must migrate to `feedbackVariant` and the unified `animation` prop.
**Migration:**
Update all Button feedback prop usages:
```tsx
// Before
// After
```
**Variant mapping:**
* `"highlight"` → `"scale-highlight"` (default)
* `"ripple"` → `"scale-ripple"`
* `"none"` → `"scale"` or `"none"`
**Available options:**
* `"scale-highlight"` - Scale down with highlight overlay (default)
* `"scale-ripple"` - Scale down with ripple effect
* `"scale"` - Scale down only
* `"none"` - No feedback animation
**Related PR:** [#302](https://github.com/heroui-inc/heroui-native/pull/302)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #291](https://github.com/heroui-inc/heroui-native/issues/291)**: Fixed `Select.Trigger` variant prop being overwritten by `className`. Custom class names passed to the trigger are now correctly forwarded to the style computation instead of being silently dropped.
* **[Issue #294](https://github.com/heroui-inc/heroui-native/issues/294)**: Resolved compatibility with `react-native-worklets` 0.7.x and `react-native-reanimated` 4.2.x (Expo SDK 55). Peer dependency constraints have been relaxed to accept these newer versions without producing resolution warnings.
**Related PRs:**
* [#298](https://github.com/heroui-inc/heroui-native/pull/298)
* [#306](https://github.com/heroui-inc/heroui-native/pull/306)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [SearchField](/docs/native/components/search-field) - New component documentation with usage examples and API reference
* [ListGroup](/docs/native/components/list-group) - New component documentation with usage examples and API reference
* [Slider](/docs/native/components/slider) - New component documentation with usage examples and API reference
* [Select](/docs/native/components/select) - Multi-selection mode, trigger className fix, and controllable state improvements
* [Button](/docs/native/components/button) - Updated feedback API documentation with new `feedbackVariant` and `animation` props
* [Avatar](/docs/native/components/avatar) - Fixed `asChild` image prop spreading documentation
* [PressableFeedback](/docs/native/components/pressable-feedback) - New `PressableFeedback.Scale` subcomponent documentation
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# RC 3
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/rc-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/rc-3.mdx
> TagGroup, Menu, and InputGroup components, Bottom Sheet Android back press fix, Expo 55 compatibility
February 26, 2026
RC 3 delivers three new components—TagGroup for selectable tag management, Menu for popover/bottom-sheet-based dropdown menus, and InputGroup for decorated text inputs with auto-measuring prefix/suffix slots. This release also brings Android hardware back button support for all bottom-sheet-based overlays, Expo 55 compatibility with a critical `combineStyles` fix that preserves Reanimated animated style bindings, and several dependency upgrades.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **3 new** components:
* **[TagGroup](/docs/native/components/tag-group)**: Compound component for displaying and managing selectable tags with optional removal, single/multiple selection, and form field integration.
* **[Menu](/docs/native/components/menu)**: Dropdown menu system with popover and bottom-sheet presentation modes, single/multiple selection, item variants, and animated press feedback.
* **[InputGroup](/docs/native/components/input-group)**: Decorated text input with absolutely-positioned prefix/suffix slots that auto-measure widths and apply matching padding to the input.
#### TagGroup
The TagGroup component provides a compound component pattern for rendering selectable tag groups with optional removal support. It supports single and multiple selection modes, controlled and uncontrolled APIs, two visual variants (default and surface), three sizes, disabled states, and full form field integration with Label, Description, and FieldError.
**Features:**
* Compound sub-components: `TagGroup.List`, `TagGroup.Item`, `TagGroup.ItemLabel`, `TagGroup.ItemRemoveButton`
* Single and multiple selection modes with controlled/uncontrolled APIs
* Two visual variants: `default` and `surface`
* Three sizes: `sm`, `md`, `lg`
* Per-item disabled state and `disabledKeys` support
* Remove functionality via `onRemove` callback and `TagGroup.ItemRemoveButton`
* Empty state rendering via `renderEmptyState` on `TagGroup.List`
* Form field integration with Label, Description, FieldError, `isInvalid`, and `isRequired`
* `useTagGroup` and `useTagGroupItem` hooks for advanced use cases
**Usage:**
```tsx
import { TagGroup } from "heroui-native";
export function BasicTagGroup() {
return (
ReactVueSvelte
);
}
export function RemovableTagGroup() {
const [items, setItems] = useState(["React", "Vue", "Svelte"]);
return (
setItems((prev) => prev.filter((i) => !keys.has(i)))}>
{items.map((item) => (
{item}
))}
);
}
```
For complete documentation and examples, see the [TagGroup component page](/docs/native/components/tag-group).
**Related PR:** [#309](https://github.com/heroui-inc/heroui-native/pull/309)
#### Menu
The Menu component provides a dropdown menu system built on a compound component pattern, supporting both popover and bottom-sheet presentation modes. It includes full Reanimated-based press animations, single and multiple selection modes, item variants (default and danger), indicator styles, and configurable placement.
**Features:**
* Compound sub-components: `Menu.Trigger`, `Menu.Portal`, `Menu.Overlay`, `Menu.Content`, `Menu.Label`, `Menu.Group`, `Menu.Item`, `Menu.ItemTitle`, `Menu.ItemDescription`, `Menu.ItemIndicator`
* Two presentation modes: `popover` and `bottom-sheet` with configurable placement (`top`, `bottom`, `left`, `right`)
* Single and multiple selection via `Menu.Group` with `selectedKeys`/`onSelectionChange`
* Item press animations (scale + background color) via Reanimated with full customization through the `animation` prop
* Item variants: `default` and `danger`
* Indicator variants: `checkmark`, `dot`, and custom content
* `Menu.Label` for section headings
* `shouldCloseOnSelect` control per group
**Usage:**
```tsx
import { Menu } from "heroui-native";
export function BasicMenu() {
return (
);
}
export function MenuWithSections() {
return (
);
}
```
For complete documentation and examples, see the [Menu component page](/docs/native/components/menu).
**Related PR:** [#312](https://github.com/heroui-inc/heroui-native/pull/312)
#### InputGroup
The InputGroup component provides a decorated text input with absolutely-positioned `Prefix` and `Suffix` sub-components that automatically measure their widths via `onLayout` and apply matching padding to the Input. It features a convenient `isDecorative` prop that handles accessibility and pointer-event boilerplate for decorative addons in a single boolean, and a root `isDisabled` prop that cascades disabled state to all children via context.
**Features:**
* Compound sub-components: `InputGroup.Prefix`, `InputGroup.Suffix`, `InputGroup.Input`
* Auto-padding: Prefix/Suffix widths are measured via `onLayout` and automatically applied as `paddingLeft`/`paddingRight` on the Input
* `isDecorative` prop on Prefix/Suffix handles `pointerEvents="none"`, `accessibilityElementsHidden`, and `importantForAccessibility` in a single boolean
* Root `isDisabled` cascades to all children via context (Prefix/Suffix opacity + pointer-events, Input editability)
* `InputGroup.Input` is a direct pass-through — consumers manage `value`/`onChangeText` directly on the Input
**Usage:**
```tsx
import { InputGroup } from "heroui-native";
export function SearchInput() {
return (
);
}
export function DisabledInput() {
return (
);
}
```
For complete documentation and examples, see the [InputGroup component page](/docs/native/components/input-group).
**Related PR:** [#313](https://github.com/heroui-inc/heroui-native/pull/313)
## Component Improvements
### Bottom Sheet Android Back Press Support
The [Bottom Sheet](/docs/native/components/bottom-sheet) shared container now handles the Android hardware back button, dismissing any open bottom sheet when pressed. The `BackHandler` listener is only active while the sheet is open, preventing closed instances from consuming the event. This fix applies globally to all bottom-sheet-based components.
**Supported components:**
* [Bottom Sheet](/docs/native/components/bottom-sheet)
* [Popover](/docs/native/components/popover)
* [Select](/docs/native/components/select)
The fix uses React Native's `BackHandler` API which is a no-op on iOS, so no platform-specific handling is needed.
**Related PR:** [#308](https://github.com/heroui-inc/heroui-native/pull/308)
### Slot `combineStyles` Fix
The Slot primitive's `combineStyles` function now returns style arrays instead of using `StyleSheet.flatten`, which was destroying Reanimated `SharedValue` and `useAnimatedStyle` bindings by deep-copying style objects into plain objects.
**Improvements:**
* `combineStyles` preserves Reanimated animated style bindings by returning arrays
* React Native handles nested style arrays natively, so consumer behavior is unchanged
* Fixes animation breakages across components that compose via the Slot primitive
**Related PR:** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
## Dependencies
### Expo 55 Compatibility
Dependency versions have been updated for Expo SDK 55 compatibility:
* `uniwind`: 1.2.7 → 1.3.2
* `@gorhom/bottom-sheet`: ^5 → ^5.2.8
The `combineStyles` fix described above is the primary code change enabling Expo 55 support, as the previous `StyleSheet.flatten` approach broke Reanimated style bindings in the new SDK.
**Related PR:** [#314](https://github.com/heroui-inc/heroui-native/pull/314)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #272](https://github.com/heroui-inc/heroui-native/issues/272)**: Resolved `FullWindowOverlay` interfering with the React Native element inspector.
* **[Issue #280](https://github.com/heroui-inc/heroui-native/issues/280)**: Fixed Avatar component and other Reanimated-dependent components breaking under Expo 55. The `combineStyles` function was destroying Reanimated animated style bindings via `StyleSheet.flatten`; it now returns style arrays to preserve `SharedValue` and `useAnimatedStyle` bindings.
**Related PRs:**
* [#308](https://github.com/heroui-inc/heroui-native/pull/308)
* [#314](https://github.com/heroui-inc/heroui-native/pull/314)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [TagGroup](/docs/native/components/tag-group) - New component documentation with usage examples and API reference
* [Menu](/docs/native/components/menu) - New component documentation with usage examples and API reference
* [InputGroup](/docs/native/components/input-group) - New component documentation with usage examples and API reference
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# RC 4
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/rc-4
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/rc-4.mdx
> SubMenu component, Slider Output composition, PressableFeedback ripple fix, Bottom Sheet back handler fix
March 6, 2026
RC 4 introduces the SubMenu compound component for nested expandable menus with spring-animated expand/collapse, refactors Slider Output with slot-based styling and `textProps` forwarding, and adds `disallowEmptySelection` to Menu.Group for radio-group behavior. This release also resolves the PressableFeedback ripple blink on rapid presses with a dual-layer buffer system, fixes the Bottom Sheet Android back handler to respect `enablePanDownToClose`.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### SubMenu Component
The [Menu](/docs/native/components/menu) component now supports nested expandable sub-menus via the new `SubMenu` compound component. SubMenu nests inside `Menu.Content` and reveals additional items on press with spring-based expand/collapse animations and indicator rotation.
**Features:**
* Compound sub-components: `SubMenu`, `SubMenu.Trigger`, `SubMenu.TriggerIndicator`, `SubMenu.Content`
* Spring-based expand/collapse animation with indicator rotation
* Headless primitive layer with context, controlled/uncontrolled open state, and accessibility attributes (`role`, `aria-expanded`, `aria-disabled`)
* Parent menu coordination: popover scales to 0.98, shadow is removed, and non-SubMenu items fade to 40% opacity with `pointer-events-none` when a SubMenu is open
* Menu content switches to `FadeOut` exit animation when a SubMenu is open to avoid conflicting scale animations
* `useSubMenu` hook for advanced use cases
**Usage:**
```tsx
import { Menu, SubMenu } from "heroui-native";
export function MenuWithSubMenu() {
return (
);
}
```
For complete documentation and examples, see the [Menu component page](/docs/native/components/menu).
**Related PR:** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
## Component Improvements
### Slider Output Composition Refactor
The [Slider](/docs/native/components/slider) Output component has been refactored to use a proper slot-based architecture with `container` and `text` slots, and introduces `textProps` for forwarding props to the inner text element.
**Improvements:**
* Slot-based styling: `output` class split into `container` and `text` slots with a new `classNames` prop (`classNames={{ container, text }}`) for granular style targeting
* Composition fix: `HeroText` now only renders for default content; custom children render directly without an extra text wrapper
* New `textProps` prop on `Slider.Output` for forwarding arbitrary props (e.g., `maxFontSizeMultiplier`) to the inner text element
* `OutputSlots` type exported from the styles module for external consumption
**Related PR:** [#328](https://github.com/heroui-inc/heroui-native/pull/328)
### Menu.Group `disallowEmptySelection`
The [Menu](/docs/native/components/menu) `Menu.Group` component now supports a `disallowEmptySelection` prop that prevents deselecting the last item in `single` selection mode, enabling radio-group behavior.
**Usage:**
```tsx
List ViewGrid View
```
**Related PR:** [#331](https://github.com/heroui-inc/heroui-native/pull/331)
### Bottom Sheet `enablePanDownToClose` Consistency
The [Bottom Sheet](/docs/native/components/bottom-sheet) component now correctly respects the `enablePanDownToClose` prop for Android hardware back button behavior. Previously, the back button would close the sheet even when `enablePanDownToClose` was set to `false`.
**Improvements:**
* The `enablePanDownToClose` prop is threaded through to `BottomSheetContentContainer` (defaults to `true`)
* The `BackHandler` event listener is only registered when both `isOpen` and `enablePanDownToClose` are `true`
* Bottom sheets with `enablePanDownToClose={false}` are no longer dismissible via the Android back button
**Related PR:** [#327](https://github.com/heroui-inc/heroui-native/pull/327)
## ⚠️ Breaking Changes
### Chip Component Sizing
The [Chip](/docs/native/components/chip) component's size variants have been migrated from fixed heights to padding-based sizing to accommodate dynamic text scaling at larger accessibility font sizes.
**Migration:**
Custom styles relying on the previous `h-5`/`h-6`/`h-7` chip heights should be updated to use the new padding-based approach:
```tsx
// Before — Fixed height sizing
// Chip used h-5 (sm), h-6 (md), h-7 (lg)
// After — Padding-based sizing
// Chip uses py-0.5 (sm), py-[3px] (md), py-1 (lg)
// Border radius updated: rounded-xl → rounded-2xl/rounded-3xl
```
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Menu](/docs/native/components/menu) - SubMenu component documentation with anatomy, usage examples, full API reference, and `useSubMenu` hook docs
* [Slider](/docs/native/components/slider) - Updated Output component documentation with slot-based styling and `textProps`
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# v1.0.0
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/v1-0-0
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/v1-0-0.mdx
> LinkButton component, sub-menu conflict resolution, optional @gorhom/bottom-sheet, ThemeColorValue branded type
March 19, 2026
🎉 HeroUI Native reaches v1.0.0 — the first stable release, marking the library's graduation from beta and release candidate stages into a production-ready foundation for React Native apps. Alongside this milestone, the release includes the new LinkButton component, sub-menu conflict resolution, an optional `@gorhom/bottom-sheet` peer dependency, and improved type safety for `useThemeColor`.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### LinkButton Component
The new [LinkButton](/docs/native/components/button) compound component renders a ghost-variant button with no highlight feedback, designed for inline link-style interactions such as "Terms of Service" or "Privacy Policy" links. It delegates entirely to the existing Button infrastructure while enforcing ghost variant and disabled highlight internally.
**Features:**
* Compound sub-component: `LinkButton.Label` for styled text content
* Ghost variant enforced internally — no `variant` prop exposed
* Highlight feedback disabled by default via `resolveAnimationObject`
* `h-auto p-0` base class removes default button height and padding for inline use
* Consumer animation config merged while preserving `highlight: false`
**Usage:**
```tsx
import { LinkButton } from "heroui-native";
export function TermsLink() {
return (
openURL("https://example.com/terms")}>
Terms of Service
);
}
```
**Related PR:** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
## Component Improvements
### Sub-Menu Single-Open Enforcement and Backdrop Close
The [Menu](/docs/native/components/menu) sub-menu system has been refactored to track the active sub-menu by ID instead of a simple boolean, enforcing single-open behavior across sibling sub-menus. A backdrop pressable overlay now renders over the menu content area when a sub-menu is open, allowing users to dismiss it by tapping outside.
**Improvements:**
* `openSubMenuId` replaces the boolean flag — only one sub-menu can be active at a time; opening a new one automatically closes the previous
* A `Pressable` overlay renders over the menu content when a sub-menu is open, allowing tap-to-dismiss
* Non-active sub-menu triggers receive `opacity-40` and `pointer-events-none` via the new `isOtherSubMenuOpen` style variant
* Open sub-menu content uses `z-50`; closed uses `z-40` to avoid stacking issues
* New "Two Sub Menus" example added to the demo app showcasing multiple sub-menus in a single menu
**Related PR:** [#343](https://github.com/heroui-inc/heroui-native/pull/343)
### Button Label Ref Type Fix
The `ButtonLabel` ref type has been corrected from `View` to `TextRef`, and an unused `View` import has been removed from `button.tsx`. This fix aligns the ref type with the actual rendered element.
**Related PR:** [#341](https://github.com/heroui-inc/heroui-native/pull/341)
## API Enhancements
### `ThemeColorValue` Branded Type for `useThemeColor`
The `useThemeColor` hook now returns a `ThemeColorValue` branded type for single-color calls, making misuse of array destructuring immediately visible as a `never` type in the IDE. The non-null assertion operator (`!`) has also been replaced with a safe nullish coalescing fallback.
**New behavior:**
```tsx
import { useThemeColor } from "heroui-native";
// Correct — direct assignment
const mutedColor = useThemeColor("muted");
// Incorrect — IDE immediately surfaces `never` type
const [color] = useThemeColor("muted"); // color: never
```
`ThemeColorValue` extends `string`, so it is assignable everywhere a `string` is expected. Existing call sites are unaffected at runtime. The `_colorValueBrand` symbol is declared with `declare const` so it has zero runtime footprint.
**Related PR:** [#337](https://github.com/heroui-inc/heroui-native/pull/337)
### `useBottomSheetAwareHandlers` Public Hook
The `useBottomSheetAwareHandlers` hook is now exported as a public API, giving consumers explicit control over keyboard avoidance wiring inside bottom sheets. This replaces the implicit `isBottomSheetAware` prop that was previously available on `Input` and `InputOTP`.
**Usage:**
```tsx
import { useBottomSheetAwareHandlers, Input } from "heroui-native";
export function BottomSheetInput() {
const { onFocus, onBlur } = useBottomSheetAwareHandlers();
return ;
}
```
**Related PR:** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
## ⚠️ Breaking Changes
### `Input` and `InputOTP` Inside Bottom Sheet
The `isBottomSheetAware` prop has been removed from `Input` and `InputOTP`. Previously, keyboard avoidance inside bottom sheets was handled automatically under the hood. Now you must explicitly use the `useBottomSheetAwareHandlers` hook and pass the handlers yourself. This change keeps the Input component lighter by removing the implicit `@gorhom/bottom-sheet` import, allowing the package to be an optional peer dependency for projects that don't use bottom sheet features.
**Migration:**
```tsx
// Before
// After
import { useBottomSheetAwareHandlers } from "heroui-native";
const { onFocus, onBlur } = useBottomSheetAwareHandlers();
```
This applies to any `Input` or `InputOTP` rendered inside a `BottomSheet`. Components used outside of bottom sheets are unaffected.
**Related PR:** [#347](https://github.com/heroui-inc/heroui-native/pull/347)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #330](https://github.com/heroui-inc/heroui-native/issues/330)**: Resolved `Input` unconditionally importing `@gorhom/bottom-sheet` at the module level even when `isBottomSheetAware` was `false`. The package is now loaded lazily via an optional `try/catch` wrapper, so projects that don't use bottom sheet features no longer need it installed.
* **[Issue #340](https://github.com/heroui-inc/heroui-native/issues/340)**: Fixed sub-menu content appearing behind sibling sub-menu triggers. The sub-menu system now tracks the active sub-menu by ID, enforces single-open behavior, and applies correct z-index layering (`z-50` for open, `z-40` for closed).
**Related PRs:**
* [#347](https://github.com/heroui-inc/heroui-native/pull/347)
* [#343](https://github.com/heroui-inc/heroui-native/pull/343)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [LinkButton](/docs/native/components/link-button) - LinkButton compound component documentation with anatomy, usage examples, and API reference
* [Menu](/docs/native/components/menu) - Updated sub-menu documentation with single-open enforcement and backdrop close behavior
* [Input](/docs/native/components/input) - Updated bottom sheet usage examples with `useBottomSheetAwareHandlers` hook pattern
* [InputOTP](/docs/native/components/input-otp) - Updated bottom sheet usage examples with `useBottomSheetAwareHandlers` hook pattern
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# v1.0.1
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/v1-0-1
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/v1-0-1.mdx
> Toast race condition fix, disabled state styling with disabled modifier, backdrop style variable
April 1, 2026
HeroUI Native v1.0.1 is a patch release focused on reliability and developer experience. It resolves a race condition in the Toast provider that caused stale animation values, corrects disabled-state styling across seven components to use the native `disabled:` modifier, and introduces a new `--backdrop` theme variable for overlay components.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## API Enhancements
### `--backdrop` Theme Variable
A new `--backdrop` top-level style variable has been added to the theme system, providing a dedicated color token for the dimming layer behind overlay components such as Dialog and Bottom Sheet. The default value is `oklch(0% 0 0 / 20%)` for a subtle but visible backdrop effect.
**New capability:**
```tsx
import { Dialog } from "heroui-native";
// Dialog and Bottom Sheet overlays now use bg-backdrop automatically
```
The `--backdrop` variable is included in all built-in themes for both light and dark modes, and the corresponding `bg-backdrop` Tailwind utility is available for use in custom component styles.
**Related PR:** [#366](https://github.com/heroui-inc/heroui-native/pull/366)
## Style Fixes
### Disabled State Modifier
Updated disabled-state styling across seven components to use the `disabled:` modifier prefix instead of applying styles unconditionally. This ensures disabled styles (`opacity-disabled`, `pointer-events-none`) are only applied when the component is in an actual disabled state, respecting the native `disabled` modifier from Uniwind.
**Affected components:**
* [Button](/docs/native/components/button)
* [Checkbox](/docs/native/components/checkbox)
* [Input](/docs/native/components/input)
* [Menu](/docs/native/components/menu)
* [Switch](/docs/native/components/switch)
* [Tabs](/docs/native/components/tabs)
* [TagGroup](/docs/native/components/tag-group)
All `isDisabled` variant classes now use the `disabled:` modifier prefix (e.g., `disabled:opacity-disabled disabled:pointer-events-none`), ensuring proper scoping to the disabled pseudo-state and eliminating styling conflicts when the disabled state is toggled dynamically.
**Related PR:** [#361](https://github.com/heroui-inc/heroui-native/pull/361)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #359](https://github.com/heroui-inc/heroui-native/issues/359)**: Fixed a race condition in the Toast provider where the `total` SharedValue could drift out of sync with the actual toast count. The manual increment/decrement approach was prone to stale-closure mismatches when `hide` and `show` ran in the same tick or when auto-dismiss raced with a manual hide. The `total` value is now derived from `toasts.length` via a `useEffect`, ensuring animated interpolations (opacity, scale, translateY) always reflect the real toast count.
* **[Issue #356](https://github.com/heroui-inc/heroui-native/issues/356)**: Resolved disabled-state styles being applied unconditionally when `isDisabled` was true, preventing developers from theming or customizing the disabled appearance. All seven affected components now use the `disabled:` modifier prefix, correctly scoping styles to the disabled pseudo-state.
**Related PRs:**
* [#360](https://github.com/heroui-inc/heroui-native/pull/360)
* [#361](https://github.com/heroui-inc/heroui-native/pull/361)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Colors](/docs/native/getting-started/colors) - Added the new `--backdrop` variable to the color reference
* [Theming](/docs/native/getting-started/theming) - Updated theming guide with the new `--backdrop` variable documentation
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# v1.0.2
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/v1-0-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/v1-0-2.mdx
> asChild slot pattern for PressableFeedback and Surface, Portal accessibility modal prop, Button Android variant fix, Input and Select style refinements
April 15, 2026
HeroUI Native v1.0.2 introduces the `asChild` slot pattern for PressableFeedback and Surface components, adds VoiceOver modal containment support across all portal-based overlay components, and fixes an Android-specific Button variant styling issue. This release also refines Input and Select visual styles and improves RadioGroup documentation with inline API references.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## API Enhancements
### `asChild` Slot Pattern for PressableFeedback and Surface
The [PressableFeedback](/docs/native/components/pressable-feedback) and [Surface](/docs/native/components/surface) components now support the `asChild` prop, enabling the Slot pattern for polymorphic rendering. When `asChild` is `true`, each component merges its behavior and styling onto a single child element instead of wrapping it in an additional node.
**PressableFeedback** uses `Animated.createAnimatedComponent(Slot.Pressable)` to merge press handling and animated styles onto the child element. **Surface** uses `Slot.View` to merge surface styling (elevation, background, className) onto the child element.
**New capability:**
```tsx
import { PressableFeedback, Surface } from "heroui-native";
// PressableFeedback merges press handling onto the child
console.log("pressed")}>
// Surface merges surface styling onto the child
```
The `asChild` prop defaults to `false`, preserving existing behavior. No migration is required. The child must be a single React element when `asChild` is enabled. Both implementations follow the established Slot primitive pattern already used in the codebase.
**Related PR:** [#380](https://github.com/heroui-inc/heroui-native/pull/380)
### `unstable_accessibilityContainerViewIsModal` for Portal Components
A new `unstable_accessibilityContainerViewIsModal` prop has been added to all portal-based overlay components, giving consumers control over whether iOS VoiceOver treats the overlay window as a modal container. When enabled, VoiceOver focus is restricted to elements inside the overlay, preventing navigation to content behind it.
**Supported components:**
* [BottomSheet](/docs/native/components/bottom-sheet) (`BottomSheet.Portal`)
* [Dialog](/docs/native/components/dialog) (`Dialog.Portal`)
* [Menu](/docs/native/components/menu) (`Menu.Portal`)
* [Popover](/docs/native/components/popover) (`Popover.Portal`)
* [Select](/docs/native/components/select) (`Select.Portal`)
* [Toast](/docs/native/components/toast) (`ToastProvider`)
**New capability:**
```tsx
import { Dialog } from "heroui-native";
```
The prop defaults to `false`, preserving existing behavior. It is marked `unstable` because it maps directly to the native `accessibilityViewIsModal` on `FullWindowOverlay` from `react-native-screens` and may change with future releases of that library.
**Related PR:** [#383](https://github.com/heroui-inc/heroui-native/pull/383)
## Style Fixes
### Input and Select Visual Refinements
Refined the visual styling of the [Input](/docs/native/components/input) and [Select](/docs/native/components/select) components for a cleaner, more balanced appearance.
**Fixes:**
* **Input**: Border width reduced from `border-2` (2px) to `border-[1.5px]` for a subtler, less heavy border appearance
* **Select**: Trigger vertical padding reduced from `py-3.5` to `py-3` for tighter, more compact spacing
These are purely cosmetic adjustments with no API or behavioral changes. Visual regression testing is recommended to confirm the updated styles render as expected across iOS and Android.
**Related PR:** [#381](https://github.com/heroui-inc/heroui-native/pull/381)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #363](https://github.com/heroui-inc/heroui-native/issues/363)**: Fixed the Button outline variant on Android where the border would persist when switching to another variant via a conditional prop. React Native on Android sometimes retains the `borderWidth` property during variant transitions. All button variants except `outline` now include explicit `border-0` classes to ensure `borderWidth` is reset to `0` whenever the variant changes.
* **[Issue #357](https://github.com/heroui-inc/heroui-native/issues/357)**: Resolved the request for `asChild` support on Card for pressable card patterns. The new `asChild` slot pattern on PressableFeedback and Surface enables developers to compose pressable card layouts by merging press handling and surface styling onto a single child element without additional wrapper nodes.
**Related PRs:**
* [#370](https://github.com/heroui-inc/heroui-native/pull/370)
* [#380](https://github.com/heroui-inc/heroui-native/pull/380)
## Documentation
### RadioGroup Inline API Reference
The [RadioGroup](/docs/native/components/radio-group) documentation now embeds full API reference tables for `Radio`, `Radio.Indicator`, and `Radio.IndicatorThumb` directly within the page. This removes the need for readers to navigate to a separate Radio doc file to understand the props available when composing radios inside a `RadioGroup.Item`.
**Improvements:**
* Full prop tables for `Radio`, `Radio.Indicator`, and `Radio.IndicatorThumb` embedded inline
* Added documentation for `RadioRenderProps`, `RadioRootAnimation`, and `RadioIndicatorThumbAnimation` types
* Replaced external markdown links with inline code formatting for consistency
**Related PR:** [#384](https://github.com/heroui-inc/heroui-native/pull/384)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [RadioGroup](/docs/native/components/radio-group) - Inline API reference tables for Radio, Radio.Indicator, and Radio.IndicatorThumb
* [PressableFeedback](/docs/native/components/pressable-feedback) - Added `asChild` prop documentation
* [Surface](/docs/native/components/surface) - Added `asChild` prop documentation
* [BottomSheet](/docs/native/components/bottom-sheet) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
* [Dialog](/docs/native/components/dialog) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
* [Menu](/docs/native/components/menu) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
* [Popover](/docs/native/components/popover) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
* [Select](/docs/native/components/select) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
* [Toast](/docs/native/components/toast) - Added `unstable_accessibilityContainerViewIsModal` prop documentation
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# v1.0.3
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/v1-0-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/v1-0-3.mdx
> New Text typography component, ScrollShadow inverted support, Tabs RTL indicator fix, optional Avatar alt prop, Select indicator unification, and form field style refinements
May 11, 2026
HeroUI Native v1.0.3 introduces the new `Text` typography primitive with a compound API for headings, paragraphs, and inline code, while delivering important fixes for `ScrollShadow` with inverted lists, `Tabs` indicator alignment in RTL layouts, and `Select.TriggerIndicator` animation when using custom children. This release also refines visual styles across `Button`, `Chip`, and `Input`, makes the `Avatar` `alt` prop optional, and corrects inner padding behavior for `TextField` and `SearchField`.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### New Components
This release introduces **1 new** typography component:
* **[Text](/docs/native/components/text)**: Primitive typography component with semantic `type` variants and `Heading`, `Paragraph`, and `Code` sub-components. ([Documentation](/docs/native/components/text))
#### Text
The `Text` component is a typography primitive that renders styled text via semantic presets. It exposes a compound API with `Text.Heading`, `Text.Paragraph`, and `Text.Code` sub-components, and layers orthogonal `align`, `color`, `weight`, and `truncate` props on top of `tailwind-variants` so typography can be composed without bespoke styles on every call site.
**Features:**
* Semantic `type` variants: `h1`–`h6`, `body`, `body-sm`, `body-xs`, and `code`
* `Text.Heading` automatically sets `accessibilityRole="header"` and narrows `type` to heading levels
* `Text.Paragraph` narrows `type` to body variants for readable copy
* `Text.Code` renders chip-styled, inline monospaced text with a platform-appropriate `fontFamily` (Menlo on iOS, `monospace` elsewhere)
* RTL-aware `align` prop with `start`, `center`, `end`, and `justify` (iOS-only justification)
* Semantic `color` presets (`default`, `muted`) with `className` escape hatch for other theme colors
* `weight` override that wins over `type`'s implied weight via `tailwind-merge`
* `truncate` boolean shortcut for `numberOfLines={1}`; an explicit `numberOfLines` always takes precedence
**Usage:**
```tsx
import { Text } from "heroui-native";
import { View } from "react-native";
export function Example() {
return (
WelcomeGetting Started
This is a body paragraph rendered with the Text component.
Smaller supporting text for captions or footnotes.
npm install heroui-native
);
}
```
For complete documentation and examples, see the [Text component page](/docs/native/components/text).
**Related PR:** [#400](https://github.com/heroui-inc/heroui-native/pull/400)
## Component Improvements
### ScrollShadow Inverted Child Support
The [ScrollShadow](/docs/native/components/scroll-shadow) component now correctly handles inverted scrollable children such as `` or ``.
**Improvements:**
* `ScrollShadowRoot` now reads the `inverted` prop from its scrollable child, mirroring the existing `childHorizontal` auto-detection pattern
* Swaps which animated style drives each visual edge so shadows render at the correct side
* No public API changes — the fix activates only when the child has `inverted={true}`, which previously rendered the gradients on the wrong edges
Previously, wrapping an inverted list would render the gradient shadow on the top edge while scrollable content was below, and omit the bottom shadow even when more content was available. Indicators now point in the correct visual direction for inverted feeds, chat lists, and similar reverse-ordered scroll surfaces.
**Related PR:** [#398](https://github.com/heroui-inc/heroui-native/pull/398)
### Tabs RTL Indicator Alignment
The [Tabs](/docs/native/components/tabs) component's indicator now positions correctly when React Native is running in RTL mode.
**Improvements:**
* Tab strip width is now tracked through the tabs measurements context
* `Tabs.List` layout width is used for fixed tab layouts
* `Tabs.ScrollView` content width is used for scrollable tab layouts
* The indicator's `translateX` is mirrored only when `I18nManager.isRTL` is enabled
The indicator uses an absolute `left` anchor combined with a measured `translateX`. In RTL, React Native swaps the absolute anchor automatically, but the measured transform still needed to be mirrored — this is now handled internally. Both fixed and scrollable tab lists are fixed, and the public API is unchanged.
**Related PR:** [#396](https://github.com/heroui-inc/heroui-native/pull/396)
### Select Trigger Indicator Unified Rendering
The [Select](/docs/native/components/select) component's `Select.TriggerIndicator` now applies the open/close rotation animation consistently, regardless of whether the default icon or custom `children` are rendered.
**Improvements:**
* Custom `children` now receive the same animated container style as the default icon
* `ChevronDownIcon` is rendered as a fallback via `children ?? `
* Collapsed the previously separate render branches into a single, unified render path
Previously, passing custom `children` to `Select.TriggerIndicator` bypassed the animated rotation transform, leaving the indicator static on open/close. The unified branch ensures the rotation animation always plays without changing the public API.
**Related PR:** [#409](https://github.com/heroui-inc/heroui-native/pull/409)
## API Enhancements
### Optional `alt` Prop on Avatar
The [Avatar](/docs/native/components/avatar) component's `alt` prop is now optional and defaults to `'Avatar'`, reducing boilerplate for decorative or contextually obvious avatars while preserving accessibility support.
**New Capability:**
```tsx
import { Avatar } from "heroui-native";
JD;
```
Existing code that passes an explicit `alt` continues to work unchanged — the prop simply gains a sensible default when omitted. The `RootProps` type now reflects `alt?: string` with a JSDoc `@default 'Avatar'`, and the component documentation has been updated to match.
**Related PR:** [#404](https://github.com/heroui-inc/heroui-native/pull/404)
## Style Fixes
### Button, Chip, and Input Style Refinements
Refined sizing and color styling across [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Input](/docs/native/components/input) to standardize on Tailwind utility classes and semantic soft color tokens.
**Fixes:**
* **Button**: Sizes now use Tailwind height utilities (`h-10`, `h-12`, `h-14`) instead of arbitrary pixel values; the `sm` height is adjusted from 36px to 40px for better tap-target ergonomics
* **Chip**: Vertical padding for `md`/`lg` refined (`py-[3px]` → `py-1`, `py-1` → `py-1.5`) for more balanced spacing
* **Chip**: Soft variants now use semantic `bg-{color}-soft` tokens instead of opacity-based `bg-{color}/15` backgrounds
* **Input**: Switched from `py-3.5` to `min-h-12` so the field maintains consistent height regardless of content
* **Input**: Primary variant border now correctly uses the `border-field-border` token instead of `border-field`
Minor pixel-level differences in Button `sm` size (+4px) and Chip `md`/`lg` paddings should be reviewed visually. No API changes were made — only style tokens in `button.styles.ts`, `chip.styles.ts`, and `input.styles.ts` were updated.
**Related PR:** [#406](https://github.com/heroui-inc/heroui-native/pull/406)
### TextField and SearchField Inner Padding Fix
The [TextField](/docs/native/components/text-field) and [SearchField](/docs/native/components/search-field) components no longer apply extra horizontal padding to nested `Label`, `Description`, and `FieldError` components.
**Fixes:**
* `TextField` now provides `hasFieldPadding: false` to its `FormFieldContext`
* `SearchField` now provides `hasFieldPadding: false` to its `FormFieldContext`
* `Label`, `Description`, and `FieldError` rendered inside these fields no longer pick up the extra `px-1.5` side padding
* Visual alignment is now consistent across all form field containers (`ControlField`, `RadioGroup`, `TagGroup` already used `hasFieldPadding: false`)
The change is isolated to two `useMemo` values that provide `FormFieldContext`. Consumers that previously relied on the unintended inner padding can restore the spacing by adding `className="px-1.5"` to the affected child components.
**Related PR:** [#407](https://github.com/heroui-inc/heroui-native/pull/407)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #334](https://github.com/heroui-inc/heroui-native/issues/334)**: Resolved `Tabs.Indicator` mispositioning in RTL layouts. The indicator combines an absolute `left` anchor with a measured `translateX`; React Native swaps the anchor automatically in RTL but the transform still needed to be mirrored. The tabs measurements context now tracks the tab strip width and mirrors `translateX` only when `I18nManager.isRTL` is enabled, fixing both fixed and scrollable tab lists.
* **[Issue #393](https://github.com/heroui-inc/heroui-native/issues/393)**: Fixed `ScrollShadow` ignoring its child's `inverted` prop. `ScrollShadowRoot` now reads `inverted` from the scrollable child (mirroring the existing `childHorizontal` auto-detection) and swaps which animated style drives each visual edge so the gradients render on the correct sides for inverted feeds and chat-style lists.
**Related PRs:**
* [#396](https://github.com/heroui-inc/heroui-native/pull/396)
* [#398](https://github.com/heroui-inc/heroui-native/pull/398)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Text](/docs/native/components/text) - New component documentation, anatomy, usage, and full API reference
* [Avatar](/docs/native/components/avatar) - `alt` prop documented as optional with default `'Avatar'`
* [All Components](/docs/native/components) - Added the new Typography category alongside the existing categories
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# v1.0.4
**Category**: native
**URL**: https://v3.heroui.com/en/docs/native/releases/v1-0-4
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/native/releases/v1-0-4.mdx
> Typography component renames Text, refined soft-foreground theme tokens with optional vibrant palette, iOS native modal offset guidance, Expo 56 / React Native 0.85 example upgrade
May 26, 2026
HeroUI Native v1.0.4 renames the `Text` typography primitive to `Typography` to free up React Native's `Text` name and align with semantic typography usage, while keeping the existing `Text` exports as deprecated aliases for a seamless upgrade. This release also refines soft-foreground color tokens across Alert, Avatar, Button, Chip, and Toast for better contrast on soft backgrounds, ships a new optional `heroui-native/styles/vibrant` palette, documents the iOS native-modal offset workaround for Menu, Popover, and Select, and upgrades the example app to Expo 56 / React Native 0.85.
## Installation
Update to the latest version:
```bash
npm i heroui-native
```
```bash
pnpm add heroui-native
```
```bash
yarn add heroui-native
```
```bash
bun add heroui-native
```
**Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server).
## Try It on Your Device
## What's New
### Typography Component (Renamed from `Text`)
The library's typography primitive has been renamed from `Text` to `Typography` to avoid clashing with React Native's built-in `Text` and to better describe its purpose as a semantic typography system. The component's API, variants, and behavior are unchanged — only the public name moves.
```tsx
import { Typography } from "heroui-native";
import { View } from "react-native";
export function Example() {
return (
WelcomeGetting Started
This is a body paragraph rendered with the Typography component.
Smaller supporting text for captions or footnotes.
npm install heroui-native
);
}
```
**What changed:**
* Primary export is now `Typography`, with sub-components `Typography.Heading`, `Typography.Paragraph`, and `Typography.Code`
* New `typographyClassNames` style API and `Typography*` type aliases replace the prior `Text*` naming
* The existing `Text`, `textClassNames`, and `Text*` types are kept as **deprecated** re-exports for backward compatibility
* Example screen renamed from `text` to `typography` in the component catalog
* JSDoc and component docs updated to reference Typography and the new docs URL
**No migration required.** Existing `import { Text } from "heroui-native"` continues to work via deprecated re-exports. Migrate to `Typography` at your convenience before a future major release removes the deprecated aliases.
**Related PR:** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
### Vibrant Theme Palette (Optional)
A new optional `heroui-native/styles/vibrant` stylesheet is available for apps that prefer more saturated brand colors on soft variants. It keeps the readability improvements from the refined soft-foreground tokens while preserving high color saturation for icons and text on soft backgrounds.
**Usage:**
```ts
// Default refined soft-foreground palette
import "heroui-native/styles";
// Or, opt into the vibrant palette
import "heroui-native/styles";
import "heroui-native/styles/vibrant";
```
Import `heroui-native/styles/vibrant` after the base styles to override soft-foreground tokens with the more saturated values. No component code changes are required to opt in.
**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
## Component Improvements
### Refined Soft-Foreground Colors Across Components
The [Alert](/docs/native/components/alert), [Avatar](/docs/native/components/avatar), [Button](/docs/native/components/button), [Chip](/docs/native/components/chip), and [Toast](/docs/native/components/toast) components now use the new `*-soft-foreground` theme tokens for labels and icons on soft backgrounds, producing better contrast and a more cohesive look across light and dark themes.
**Improvements:**
* Soft foreground tokens (`accent-soft-foreground`, `success-soft-foreground`, `warning-soft-foreground`, `danger-soft-foreground`, `default-soft-foreground`) are computed via `color-mix` in `theme.css` for improved readability on soft backgrounds
* Alert, Avatar, Button, Chip, and Toast styles (and their internal hooks) consume the new soft-foreground tokens instead of raw semantic colors like `text-accent` or `text-success`
* A new optional `heroui-native/styles/vibrant` export preserves saturated brand colors on soft variants for apps that want a more vivid look
* Example app demos for Alert, Avatar, Button, Chip, and Toast were updated to match the refined color usage
Component props and public APIs are unchanged — only the color values applied to soft variants. Apps relying on the default theme will see softer, more legible icon and label colors on soft variants out of the box.
**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
### TextArea Vertical Padding Fix
The [TextArea](/docs/native/components/text-area) component now applies proper inner vertical padding so multiline content no longer hugs the top edge of the field.
**Improvements:**
* `TextArea` now uses `h-32 py-2` for consistent inner spacing
* No API changes — the fix is a styling-only update inside the component
**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
## API Enhancements
### `useThemeColor` Token Updates
The [`useThemeColor`](/docs/native/hooks/use-theme-color) hook now exposes additional surface and soft tokens, and renames the overlay backdrop token for clarity.
**New Capability:**
```tsx
import { useThemeColor } from "heroui-native";
const colors = useThemeColor([
"default-soft",
"default-soft-foreground",
"surface-foreground",
"backdrop",
]);
```
**Changes:**
* Added `default-soft` and `default-soft-foreground` tokens
* Added surface foreground tokens (e.g. `surface-foreground`) for explicit access to surface text colors
* Renamed `overlay-backdrop` to `backdrop` for consistency with the underlying CSS variable name
Apps using removed `useThemeColor` keys (`on-surface-*`) or the previous `overlay-backdrop` key should migrate to the updated token names. Component props and visual defaults are unchanged.
**Related PR:** [#420](https://github.com/heroui-inc/heroui-native/pull/420)
## Dependencies
### `@gorhom/bottom-sheet` Peer Range Updated
The peer dependency range for `@gorhom/bottom-sheet` has been bumped from `^5.2.8` to `^5.2.9`. Apps that use HeroUI Native's [BottomSheet](/docs/native/components/bottom-sheet) component (or any of `Menu` / `Popover` / `Select` with `presentation="bottom-sheet"`) should ensure they are on a compatible version:
```bash
npm i @gorhom/bottom-sheet@^5.2.9
```
This is the only peer-dep change affecting consumers. The library's `react` (`>=19.0.0`) and `react-native` (`>=0.81.0`) peer ranges are unchanged.
**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
### Example App Upgraded to Expo 56 / React Native 0.85
The example app shipped in the repository has been upgraded to the latest Expo and React Native toolchain. This does not affect consumers of the library directly, but contributors running the example will benefit from the upgrades:
* Expo `56`
* React Native `0.85.3`
* React `19.2.3`
* React Native Reanimated `4.3.1`
* `react-native-worklets` `0.8.3`
* Uniwind `^1.6.3`
Additional housekeeping included in this upgrade:
* `metro.config.js` rewritten to pin peer-dep resolution to the example's `node_modules`, fixing Hermes "Maximum call stack size exceeded" crashes when `uniwind` or `react` resolved to two copies from the workspace root
* Replaced deprecated `StyleSheet.absoluteFillObject` with `StyleSheet.absoluteFill` in input-otp and showcases
* Migrated `useFocusEffect` / `useHeaderHeight` imports to `expo-router`
* Removed unused `example/src/components/safe-area-view.tsx`, `eas.json`, and stale `newArchEnabled` / `edgeToEdgeEnabled` flags
* Example app slug/bundle renamed to `heroui-native-oss`; Android `WithStateToggle` padding adjusted
**Related PR:** [#421](https://github.com/heroui-inc/heroui-native/pull/421)
## Documentation
### iOS Native Modal Offset Guidance for Menu, Popover, and Select
The [Menu](/docs/native/components/menu), [Popover](/docs/native/components/popover), and [Select](/docs/native/components/select) documentation now includes a **Native Modal (iOS)** section that explains why overlay content can render shifted upward when a trigger lives inside a screen presented as a native modal (`presentation: "modal" | "formSheet" | "pageSheet"`), and how to compensate.
**Improvements:**
* Each component's docs now describe the Fabric / `FullWindowOverlay` coordinate mismatch: trigger coordinates are modal-relative while the overlay is window-anchored
* Documents the recommended `offset={insets.top}` workaround using `useSafeAreaInsets` from `react-native-safe-area-context`
* Links to the example app files (`popover-native-modal.tsx`, `select-native-modal.tsx`) for full usage patterns
**Usage example:**
```tsx
import { useSafeAreaInsets } from "react-native-safe-area-context";
import { Popover } from "heroui-native";
const insets = useSafeAreaInsets();
{/* ... */}
;
```
This is a documentation-only change — no API or runtime behavior was modified.
**Related PR:** [#419](https://github.com/heroui-inc/heroui-native/pull/419)
## Bug Fixes
This release includes fixes for the following issues:
* **[Issue #405](https://github.com/heroui-inc/heroui-native/issues/405)**: Documented the workaround for `Menu` rendering misaligned when opened inside a React Navigation native modal. The new **Native Modal (iOS)** section in the Menu docs explains the Fabric / `FullWindowOverlay` coordinate mismatch and shows how to compensate via `offset={insets.top}` with `useSafeAreaInsets`.
* **[Issue #418](https://github.com/heroui-inc/heroui-native/issues/418)**: Resolved Hermes crashes ("Maximum call stack size exceeded") and the invisible `BottomSheet` content seen after upgrading the example app to Expo 56. The example's `metro.config.js` now pins peer-dep resolution (`react`, `react-native`, `uniwind`, etc.) to the example's local `node_modules`, preventing duplicate copies from being loaded from the workspace root.
**Related PRs:**
* [#419](https://github.com/heroui-inc/heroui-native/pull/419)
* [#421](https://github.com/heroui-inc/heroui-native/pull/421)
## Deprecations
### `Text` Typography Exports
The `Text` component and related exports are now **deprecated** in favor of `Typography`. Existing imports continue to work and will not produce runtime errors — only TypeScript / IDE deprecation hints are emitted. Plan to migrate before a future major release removes the deprecated aliases.
**Deprecated → Recommended:**
```tsx
// Deprecated (still works)
import { Text, textClassNames, type TextProps } from "heroui-native";
Welcome;
// Recommended
import {
Typography,
typographyClassNames,
type TypographyProps,
} from "heroui-native";
Welcome;
```
**Related PR:** [#417](https://github.com/heroui-inc/heroui-native/pull/417)
## Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
* [Typography](/docs/native/components/typography) - Component renamed from Text; full API, anatomy, and usage reference updated
* [Menu](/docs/native/components/menu) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
* [Popover](/docs/native/components/popover) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
* [Select](/docs/native/components/select) - Added **Native Modal (iOS)** section with `offset={insets.top}` workaround
* [Quick Start](/docs/native/getting-started/quick-start) - Updated `@gorhom/bottom-sheet` optional peer dependency to `^5.2.9`
## Links
* [Component Documentation](../components)
* [GitHub Repository](https://github.com/heroui-inc/heroui-native)
## Contributors
Thanks to everyone who contributed to this release!
# All Releases
**Category**: react
**URL**: https://v3.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.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://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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";
const noop = () => {};
export function Variants() {
return (
);
}
```
## Component Improvements
### Tabs Secondary Variant
Added a new `secondary` variant to [Tabs](/docs/components/tabs) with an underline indicator style. The secondary variant supports both horizontal and vertical orientations.
```tsx
import {Tabs} from "@heroui/react";
export function Secondary() {
return (
Overview
Analytics
Reports
View your project overview and recent activity.
Track your metrics and analyze performance data.
Generate and download detailed reports.
);
}
```
**Usage:**
```tsx
Overview
Analytics
ContentContent
```
### Input Variants
Added `primary` and `secondary` variants to the [Input](/docs/components/input) component:
* **`primary`** (default): Standard styling with shadow, suitable for most use cases
* **`secondary`**: Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
import {Input} from "@heroui/react";
export function Variants() {
return (
);
}
```
### InputGroup Enhancements
The [InputGroup](/docs/components/input-group) component received several improvements:
**TextArea Support**: Use `InputGroup.TextArea` for multiline text inputs with prefix and suffix elements.
```tsx
"use client";
import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons";
import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react";
import {useState} from "react";
export function WithTextArea() {
const [value, setValue] = useState("");
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = () => {
if (!value.trim()) return;
setIsSubmitting(true);
setTimeout(() => {
setIsSubmitting(false);
setValue("");
}, 1000);
};
return (
setValue(event.target.value)}
/>
Add a files and more
Connect apps
Voice input
Send
);
}
```
**Variants**: Added `primary` and `secondary` variants matching the Input component.
```tsx
import {Envelope} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";
export function Variants() {
return (
);
}
```
### Button & ButtonGroup Outline Variants
Added a new `outline` variant to both [Button](/docs/components/button) and [ButtonGroup](/docs/components/button-group) components for outlined styling.
```tsx
import {Button, ButtonGroup} from "@heroui/react";
export function OutlineVariant() {
return (
Button
ButtonGroup
);
}
```
### AlertDialog Size Support
Added size support to [AlertDialog](/docs/components/alert-dialog) component, allowing you to control the dialog size.
```tsx
"use client";
import {Rocket} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";
export function Sizes() {
const sizes = ["xs", "sm", "md", "lg", "cover"] as const;
return (
{size === "cover" ? (
<>
This alert dialog uses the cover size variant. It spans the
full screen with margins: 16px on mobile and 40px on desktop. Maintains
rounded corners and standard padding. Perfect for critical confirmations
that need maximum width while preserving alert dialog aesthetics.
) : (
<>
This alert dialog uses the {size} size variant. On mobile
devices, all sizes adapt to near full-width for optimal viewing. On desktop,
each size provides a different maximum width to suit various content needs.
)}
))}
);
}
```
### Checkbox Animation Improvements
Faster animation and increased stroke width for better feedback on [Checkbox](/docs/components/checkbox).
```tsx
import {Checkbox} 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://v3.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";
const noop = () => {};
export function Variants() {
return (
);
}
```
### Separator Variants
Added variants to the [Separator](/docs/components/separator) component for different visual styles.
### Chip Component - Label Slot
The [Chip](/docs/components/chip) component now supports a `Chip.Label` subcomponent for better visual alignment. When removing start or end content (like icons), the label text was too close to the chip edges. Plain text children are automatically wrapped in `` for backward compatibility.
**Usage:**
```tsx
import { Chip } from '@heroui/react';
// Automatic wrapping (backward compatible)
Label text
// Explicit label with custom styling
Custom Label
// Mixing icons and labels
With Icon
```
## Style Fixes
* **Overlay Content**: Fixed blur effect on overlay content (#6136)
* **Invalid Field**: Converted ring to outline for invalid field states (#6184)
* **Link with Button**: Fixed styling for Link components using button variants (#6138)
* **Toast Content**: Fixed vertical alignment of toast content (#6147)
* **Safari SVG**: Fixed SVG shifting issue in Safari (#6149)
* **Placeholder Color**: Aligned placeholder color with input text (#6139)
* **Tooltip**: Removed cursor style from tooltip trigger component
* **CSS Variables**: Made calculated variables depend only on root variables (#6154)
## Bug Fixes
* Fixed page interactivity during view transitions (#6128)
* Fixed markdown URL formatting (#6162)
* Fixed incorrect link to combo box page (#6164)
* Fixed autocomplete styles import order in index.css
* Fixed hyphenated format for CSS classes (#6191)
## ⚠️ Breaking Changes
### Toast Component - Container Renamed to Provider
The `Toast.Container` component has been renamed to `Toast.Provider` for better semantic clarity (#6151).
**Before:**
```tsx
```
**After:**
```tsx
```
**Additional Changes:**
* Default `gap` prop changed from `14` to `12` pixels
* Default `timeout` is now `4000` (4 seconds) instead of requiring explicit timeout
* `Toast.Action` has been renamed to `Toast.ActionButton` for consistency
### CSS Class Naming Convention
CSS classes have been renamed to use hyphenated format for consistency (#6141). This follows BEM conventions more closely and improves compatibility with Tailwind CSS.
**Important Note**: The `textarea` class was initially renamed to `text-area` but was rolled back to `textarea` in PR #6191 due to conflicts with Tailwind's native `textarea` class. No changes are needed for TextArea component classes.
#### Component Class Name Changes
The following CSS class names have been updated. If you have custom CSS targeting these classes directly, update your selectors:
| Component | Old Class Name | New Class Name | Notes |
| ------------------ | -------------------------- | --------------------------- | ------------------------------------------------------ |
| **ComboBox** | `.combobox` | `.combo-box` | All related classes updated |
| | `.combobox__input-group` | `.combo-box__input-group` | |
| | `.combobox__trigger` | `.combo-box__trigger` | |
| | `.combobox__popover` | `.combo-box__popover` | |
| | `.combobox--full-width` | `.combo-box--full-width` | |
| **ListBox** | `.listbox` | `.list-box` | All related classes updated |
| **ListBoxItem** | `.listbox-item` | `.list-box-item` | All related classes updated |
| | `.listbox-item__indicator` | `.list-box-item__indicator` | |
| | `.listbox-item--default` | `.list-box-item--default` | |
| | `.listbox-item--danger` | `.list-box-item--danger` | |
| **ListBoxSection** | `.listbox-section` | `.list-box-section` | All related classes updated |
| **TextArea** | `.textarea` | `.textarea` | **No change** - Rolled back to avoid Tailwind conflict |
#### Migration Guide
**Before:**
```css
/* Custom styles targeting old class names */
.combobox {
/* styles */
}
.listbox-item {
/* styles */
}
```
**After:**
```css
/* Update to new hyphenated class names */
.combo-box {
/* styles */
}
.list-box-item {
/* styles */
}
```
**JavaScript/TypeScript Updates:**
If you're using these class names in JavaScript or TypeScript code:
```tsx
// Before
// After
```
**Note**: Component props and TypeScript types remain unchanged. Only CSS class names have been updated.
### Removed CSS Variables
Several CSS variables have been removed as part of the surface color refactoring (#6204). These variables were either replaced with direct variable references or removed entirely.
#### Surface Color Variables
The following calculated surface color variables have been removed and replaced with direct variable references:
**Removed:**
* `--color-surface-secondary` (was calculated via `color-mix`)
* `--color-surface-tertiary` (was calculated via `color-mix`)
**Replacement:**
These variables now directly reference the base variables defined in `variables.css`:
* `--color-surface-secondary` → Uses `var(--surface-secondary)` directly
* `--color-surface-tertiary` → Uses `var(--surface-tertiary)` directly
The base variables `--surface-secondary` and `--surface-tertiary` are now defined directly in `variables.css` instead of being calculated in `theme.css`.
#### On Surface Color Variables
All `--color-on-surface-*` variables have been removed entirely:
**Removed:**
* `--color-on-surface`
* `--color-on-surface-foreground`
* `--color-on-surface-hover`
* `--color-on-surface-focus`
* `--color-on-surface-secondary`
* `--color-on-surface-secondary-foreground`
* `--color-on-surface-secondary-hover`
* `--color-on-surface-secondary-focus`
* `--color-on-surface-tertiary`
* `--color-on-surface-tertiary-foreground`
* `--color-on-surface-tertiary-hover`
* `--color-on-surface-tertiary-focus`
**Migration:**
If you were using these variables, update your code to use the appropriate surface variables directly:
```css
/* Before */
.element {
background: var(--color-on-surface);
color: var(--color-on-surface-foreground);
}
.element:hover {
background: var(--color-on-surface-hover);
}
/* After */
.element {
background: var(--surface-secondary);
color: var(--surface-secondary-foreground);
}
.element:hover {
background: color-mix(in oklab, var(--surface-secondary) 92%, var(--surface-secondary-foreground) 8%);
}
```
Or use the Tailwind utilities:
```tsx
// Before
// After
```
**Related PR:** [#6204](https://github.com/heroui-inc/heroui/pull/6204)
## Links
* [Component Documentation](/docs/react/components)
* [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #6201](https://github.com/heroui-inc/heroui/pull/6201)
## Contributors
Thanks to everyone who contributed to this release!
# v3.0.0-beta.7
**Category**: react
**URL**: https://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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://v3.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 6, 2026
Calendar gains week and day views, a reworked year picker, and range demos built on React Aria 1.18. [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 the patch fixes shipped alongside React Aria 1.18 (`Table.SortableColumnHeader`, toast and fieldset fixes, scroll and RTL style fixes).
⚠️ **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 */}
