# v3.0.0-beta.4 · HeroUI

> New Theme Builder, three new components (Autocomplete, Breadcrumbs, Toast), Tabs secondary variant, Input/InputGroup variants, and various improvements.

- Page: https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

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](https://heroui.com/themes) for visual theme customization, three new components ([Autocomplete](/systems/heroui/docs/components/autocomplete), [Breadcrumbs](/systems/heroui/docs/components/breadcrumbs), [Toast](/systems/heroui/docs/components/toast)), adds secondary variant to [Tabs](/systems/heroui/docs/components/tabs), primary/secondary variants to [Input](/systems/heroui/docs/components/input) and [InputGroup](/systems/heroui/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:


  

#### npm


    ```bash
    npm i @heroui/styles@beta @heroui/react@beta
    ```
  
  

#### pnpm


    ```bash
    pnpm add @heroui/styles@beta @heroui/react@beta
    ```
  
  

#### yarn


    ```bash
    yarn add @heroui/styles@beta @heroui/react@beta
    ```
  
  

#### bun


    ```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](https://heroui.com/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](https://heroui.com/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](/systems/heroui/docs/components/autocomplete))
- **[Breadcrumbs](#breadcrumbs)**: Navigation breadcrumbs showing the current page's location within a hierarchy. ([Documentation](/systems/heroui/docs/components/breadcrumbs))
- **[Toast](#toast)**: Display temporary notifications and messages with automatic dismissal and customizable placement. ([Documentation](/systems/heroui/docs/components/toast))

### Autocomplete


> Example `autocomplete-default`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### Breadcrumbs


> Example `breadcrumbs-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### Toast


> 
  This  component is currently in preview and some features might not work as expected.


> Example `toast-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


## Component Improvements

### Tabs Secondary Variant

Added a new `secondary` variant to [Tabs](/systems/heroui/docs/components/tabs) with an underline indicator style. The secondary variant supports both horizontal and vertical orientations.


> Example `tabs-secondary`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


**Usage:**

```tsx
<Tabs variant="secondary">
  <Tabs.ListContainer>
    <Tabs.List aria-label="Options">
      <Tabs.Tab id="overview">
        Overview
        <Tabs.Indicator />
      </Tabs.Tab>
      <Tabs.Tab id="analytics">
        Analytics
        <Tabs.Indicator />
      </Tabs.Tab>
    </Tabs.List>
  </Tabs.ListContainer>
  <Tabs.Panel id="overview">Content</Tabs.Panel>
  <Tabs.Panel id="analytics">Content</Tabs.Panel>
</Tabs>
```

### Input Variants

Added `primary` and `secondary` variants to the [Input](/systems/heroui/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


> Example `input-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### InputGroup Enhancements

The [InputGroup](/systems/heroui/docs/components/input-group) component received several improvements:

**TextArea Support**: Use `InputGroup.TextArea` for multiline text inputs with prefix and suffix elements.


> Example `input-group-with-textarea`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


**Variants**: Added `primary` and `secondary` variants matching the Input component.


> Example `input-group-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### Button & ButtonGroup Outline Variants

Added a new `outline` variant to both [Button](/systems/heroui/docs/components/button) and [ButtonGroup](/systems/heroui/docs/components/button-group) components for outlined styling.


> Example `button-outline-variant`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### AlertDialog Size Support

Added size support to [AlertDialog](/systems/heroui/docs/components/alert-dialog) component, allowing you to control the dialog size.


> Example `alert-dialog-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### Checkbox Animation Improvements

Faster animation and increased stroke width for better feedback on [Checkbox](/systems/heroui/docs/components/checkbox).


> Example `checkbox-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


### Link Text Decoration

The [Link](/systems/heroui/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


> Example `link-underline-and-offset`: interactive preview on https://jiguang132.com/systems/heroui/docs/releases/v3-0-0-beta-4


## ⚠️ 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 href="#" underline="hover" underlineOffset={4}>
  Link text
</Link>
```

**After:**
```tsx
<Link href="#" className="hover:underline underline-offset-4">
  Link text
</Link>
```

**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](/systems/heroui/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
<Surface>
  {/* Input automatically detected surface context */}
  <Input isInSurface />
</Surface>
```

**After:**
```tsx
<Surface>
  {/* Use variant="secondary" for surface backgrounds */}
  <Input variant="secondary" />
</Surface>
```

**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](https://heroui.com/themes)
- [Component Documentation](/systems/heroui/docs/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!

---

Index of all JGuang resources: https://jiguang132.com/llms.txt