# v3.0.0-beta.4 **Category**: react **URL**: https://www.heroui.com/docs/react/releases/v3-0-0-beta-4 **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-4.mdx > New Theme Builder, three new components (Autocomplete, Breadcrumbs, Toast), Tabs secondary variant, Input/InputGroup variants, and various improvements. ***
January 20, 2026
**Critical Build Issue Fixed**: This version (beta.4) had a critical build issue that has been fixed in **beta.5**. Please upgrade to `@heroui/styles@3.0.0-beta.5` and `@heroui/react@3.0.0-beta.5` to ensure proper TypeScript declaration generation and export resolution. This release introduces the new [Theme Builder](/themes) for visual theme customization, three new components ([Autocomplete](/docs/components/autocomplete), [Breadcrumbs](/docs/components/breadcrumbs), [Toast](/docs/components/toast)), adds secondary variant to [Tabs](/docs/components/tabs), primary/secondary variants to [Input](/docs/components/input) and [InputGroup](/docs/components/input-group), TextArea support for InputGroup, and ⚠️ **breaking changes** removing Link's underline variants and the `isInSurface` prop from form components. ## Installation Update to the latest version: ```bash npm i @heroui/styles@beta @heroui/react@beta ``` ```bash pnpm add @heroui/styles@beta @heroui/react@beta ``` ```bash yarn add @heroui/styles@beta @heroui/react@beta ``` ```bash bun add @heroui/styles@beta @heroui/react@beta ``` **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server). ## What's New ### Theme Builder We're excited to introduce the **[Theme Builder](/themes)** - a powerful visual tool for creating and customizing HeroUI themes. Build your perfect theme with real-time preview and export ready-to-use CSS. **Key features:** - **Visual Color Editing**: Adjust colors using OKLCH color pickers with intuitive sliders for lightness, chroma, and hue - **Real-time Preview**: See your changes instantly on live component previews - **Custom Accent Colors**: Define your brand colors and watch them propagate across all components - **Preset Themes**: Start from curated presets like Default, Airbnb, Coinbase, Discord, and more - **Export Ready**: Generate CSS variables ready to copy into your project - **Light & Dark Mode**: Customize both themes simultaneously with linked or independent values - **Keyboard Shortcuts**: Undo/redo support and quick actions for efficient workflow Try it now at [v3.heroui.com/themes](/themes). ### New Components This release introduces **3 new** essential components: - **[Autocomplete](#autocomplete)**: Combines a select with filtering, allowing users to search and select from a list of options. ([Documentation](/docs/components/autocomplete)) - **[Breadcrumbs](#breadcrumbs)**: Navigation breadcrumbs showing the current page's location within a hierarchy. ([Documentation](/docs/components/breadcrumbs)) - **[Toast](#toast)**: Display temporary notifications and messages with automatic dismissal and customizable placement. ([Documentation](/docs/components/toast)) ### Autocomplete ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export default function Default() { const {contains} = useFilter({sensitivity: "base"}); const [selectedKeys, setSelectedKeys] = useState([]); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; const onRemoveTags = (keys: Set) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( setSelectedKeys(keys as Key[])} > {({defaultChildren, isPlaceholder, state}: any) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item: any) => item.key); return ( {selectedItemsKeys.map((selectedItemKey: Key) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( {item.name} ); })} ); }} No results found}> {items.map((item) => ( {item.name} ))} ); } ``` ### Breadcrumbs ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsBasic() { return ( Home Products Electronics Laptop ); } ``` ### 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 Content Content ``` ### 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 (
{sizes.map((size) => ( Size: {size.charAt(0).toUpperCase() + size.slice(1)}

{size === "cover" ? ( <> This alert dialog uses the cover size variant. It spans the full screen with margins: 16px on mobile and 40px on desktop. Maintains rounded corners and standard padding. Perfect for critical confirmations that need maximum width while preserving alert dialog aesthetics. ) : ( <> This alert dialog uses the {size} size variant. On mobile devices, all sizes adapt to near full-width for optimal viewing. On desktop, each size provides a different maximum width to suit various content needs. )}

))}
); } ``` ### Checkbox Animation Improvements Faster animation and increased stroke width for better feedback on [Checkbox](/docs/components/checkbox). ```tsx import {Checkbox, Label} from "@heroui/react"; export function Basic() { return ( ); } ``` ### Link Text Decoration The [Link](/docs/components/link) component now uses Tailwind CSS classes for text decoration instead of built-in variants. This provides more flexibility and follows Tailwind conventions. **Available Tailwind utilities:** - `underline` - Always visible underline - `no-underline` - Remove underline - `hover:underline` - Underline appears on hover - `decoration-primary`, `decoration-secondary`, etc. - Set underline color - `decoration-1`, `decoration-2`, `decoration-4` - Control thickness - `underline-offset-1`, `underline-offset-2`, etc. - Adjust spacing ```tsx import {Link} from "@heroui/react"; export function LinkUnderlineAndOffset() { return (

Always visible underline

Underline always visible

Underline visible on hover

Hover to see the underline

No underline

Link without any underline

Changing the underline offset

Offset 1 (1px space) Offset 2 (2px space) Offset 3 (3px space) Offset 4 (4px space)
); } ``` ## ⚠️ 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!