1.0.0-beta.9

This release adds HoloCard, a 3D tilting card with a pointer-tracked holographic glare for membership cards, passes, and collectibles, and PromptInput.TokenInput for prompts with inline @mention and /command tokens. It rebuilds HoverCard and ContextMenu on the new React Aria PreviewTrigger and contextMenu trigger primitives, adds a secondary surface variant to the Rich Text Editor for overlays, and moves TextShimmer to a GPU-composited mask animation that substantially reduces CPU usage. ListView and Sidebar links now route through React Aria RouterProvider, and a round of fixes lands for the Rich Text Editor slash menu, Sheet overlays in Safari, Glass theme table headers, DataGrid row headers, and the Sidebar keyboard shortcut. It also bumps the @heroui/react peer to 3.2.5 and react-aria-components to 1.21.0.

⚠️ Breaking change:

• @heroui/react and @heroui/styles peer dependency minimums are now >=3.2.5, and react-aria-components is now >=1.21.0.
• react-aria (>=3.52.0), react-stately (>=3.50.0), and @react-aria/interactions (>=3.28.1) are new peer dependencies. All three already ship with react-aria-components, so most apps only need to declare them if they use strict peer resolution.
• HoverCard.Content no longer accepts defaultOpen or onOpenChange (it already rejected isOpen and triggerRef). Open state lives on the HoverCard root.

What's New

New Components

• HoloCard: 3D tilting card with a pointer-tracked holographic glare and texture overlay, content parallax, and reduced-motion support. (Docs)

HoloCard

HoloCard is a compound component for membership cards, passes, and collectibles. The card tilts toward the pointer, scales on hover, and drifts its HoloCard.Content layers against the tilt while a holographic HoloCard.Shine overlay follows the pointer (#925).

import {HoloCard} from "@heroui-pro/react";

<HoloCard gradient="linear-gradient(140deg, #3a3730 0%, #1a1b22 78%, #12131c 100%)">
  <HoloCard.Rotator>
    <HoloCard.Frame>
      <HoloCard.Surface>
        <HoloCard.Inset />
        <HoloCard.Pattern />
        <HoloCard.Content className="flex-col items-center justify-center">
          <span className="text-3xl font-bold text-white">Marcus Wong</span>
        </HoloCard.Content>
        <HoloCard.Content className="items-end justify-center pb-10">
          <span className="text-sm text-white/40">Member #0999</span>
        </HoloCard.Content>
        <HoloCard.Shine />
      </HoloCard.Surface>
    </HoloCard.Frame>
  </HoloCard.Rotator>
</HoloCard>;

Key features:

• Layered anatomy - Rotator, Frame, and Surface are required; Inset (hairline border), Pattern (static texture), Content, and Shine are optional layers you stack in any order
• Pointer-tracked motion - Motion springs drive the tilt, hover scale, and glare position; parallaxStrength controls how far Content layers drift, and parallax={false} pins a layer in place
• Themeable surface - gradient, patternSrc, and patternSize props map to --holo-card-* CSS variables alongside width, height, radius, perspective, and overlay opacity tokens, so the holographic texture can be swapped for any CSS image
• Static and accessible - isInteractive={false} or isDisabled freezes the card flat and unlit, and it stays static automatically under prefers-reduced-motion; on touch devices horizontal drags tilt the card while vertical drags keep scrolling the page

Prompt Input Token Input

PromptInput.TokenInput is a drop-in alternative to PromptInput.TextArea for prompts that carry inline @mention and /command tokens (#933). It is built on the React Aria Components TokenField, so the value is a TokenFieldValue segment list rather than a string, and it renders a contenteditable element in the same slot with the same box model. usePromptInputTokens owns the value and resolves the trigger the caret sits in, PromptInput.TokenSuggestions anchors a popover to that caret, PromptInput.Tokens routes arrow keys and Enter into the menu while the caret stays in the field, and PromptInput.Token renders the inline pill. The menu closes when the caret leaves the trigger or the field loses focus, and PromptInput.Send, the compact and inline layouts, and the run lock work the same as they do for the textarea.

import {Menu} from "@heroui/react";
import {PromptInput, TokenFieldValue, usePromptInputTokens} from "@heroui-pro/react";

function Composer() {
  const tokens = usePromptInputTokens({triggers: ["@"]});
  const items = users.filter((user) => user.username.startsWith(tokens.query));

  return (
    <PromptInput onSubmit={() => tokens.setValue(new TokenFieldValue([]))}>
      <PromptInput.Shell>
        <PromptInput.Tokens>
          <PromptInput.Content>
            <PromptInput.TokenInput tokens={tokens} />
          </PromptInput.Content>
          <PromptInput.TokenSuggestions tokens={tokens}>
            <Menu items={items}>
              {(item) => (
                <Menu.Item id={item.id} onAction={() => tokens.insertToken(`@${item.username}`)}>
                  {item.name}
                </Menu.Item>
              )}
            </Menu>
          </PromptInput.TokenSuggestions>
        </PromptInput.Tokens>
        <PromptInput.Toolbar>
          <PromptInput.ToolbarEnd>
            <PromptInput.Send />
          </PromptInput.ToolbarEnd>
        </PromptInput.Toolbar>
      </PromptInput.Shell>
    </PromptInput>
  );
}

Key features:

• Drop-in for the textarea - Same slot, box model, run lock, and compact/inline expand behavior as PromptInput.TextArea; the token field flattens its value into a string so PromptInput.Send works unchanged
• Caret-anchored suggestions - PromptInput.TokenSuggestions follows the caret with full keyboard navigation (arrows, Enter, Escape) and virtual-focus announcements, and closes when the caret leaves the trigger or the field blurs
• Composable token state - usePromptInputTokens exposes value, query, trigger, insertToken, and close, and TokenFieldValue is re-exported from @heroui-pro/react

TokenField is an alpha React Aria Components API; its behavior and props may change in a future release.

Rich Text Editor Secondary Variant

RichTextEditor accepts variant="primary" | "secondary" (default primary) so the editor shell can match HeroUI field surfaces when it sits on a Surface, Modal, Sheet, or Drawer (#1032). The secondary variant uses the --default fill with no shadow, exposes data-variant on the root, and switches ActionButton and CommandButton to the outline variant by default so toolbar controls stay visible on the secondary fill.

import {RichTextEditor} from "@heroui-pro/react/rich-text-editor";

<Modal.Body>
  <RichTextEditor defaultValue={draft} variant="secondary">
    <RichTextEditor.Shell>
      <RichTextEditor.Toolbar>{/* … */}</RichTextEditor.Toolbar>
      <RichTextEditor.Content />
    </RichTextEditor.Shell>
  </RichTextEditor>
</Modal.Body>;

HoverCard on PreviewTrigger

HoverCard is now built on React Aria's PreviewTrigger, replacing the hand-rolled timers and open/close state (#915). Pointer, keyboard, and touch all open the card consistently: hovering opens after openDelay with a safe area between trigger and card, focusing the trigger opens it and Tab moves into it, and long press opens it on touch. Open delays are coordinated globally with other hover cards and tooltips, so once one has opened the next opens immediately.

The root gains an isDisabled prop, Escape closes a pointer-opened card even when focus is elsewhere, and the card renders with role="dialog". See Breaking Changes for the HoverCard.Content prop change.

ContextMenu on React Aria

ContextMenu uses React Aria's trigger="contextMenu" support instead of custom right-click, long-press, and cursor-anchoring logic (#924). The compound API is unchanged. The menu now has an accessible name, focuses its first item on open, closes when you right-click the trigger again, chains a caller's own onContextMenu handler instead of replacing it, and closes submenus with the root. On iOS, long press goes through React Aria's usePress. The popover's zoom-in animation now grows from the click point via transform-origin: var(--trigger-anchor-point).

Improvements

• TextShimmer - Replaced the paint-heavy background-position animation with a GPU-composited CSS mask whose highlight layer animates only translate, substantially reducing CPU usage while keeping the same shimmer look (#1015). Text color utilities passed through className now compose with the shimmer instead of disabling it (#921)
• ListView and Sidebar routing - ListView.Item and Sidebar.MenuItem links route through the active React Aria RouterProvider, with native navigation as the fallback, and navigate exactly once (#944)
• Sheet - Popovers and dropdowns rendered inside a Sheet are anchored to the viewport in Safari, so footer menus open where expected (#947)
• Glass theme - Table and DataGrid headers follow the card's rounded corners instead of painting a square backdrop-filter layer (#1134)
• DataGrid - Falls back to the first visible column as the row header when no column declares isRowHeader, so toggling columns off no longer crashes the grid (#808)
• Rich Text Editor - Slash-command SuggestionMenu items now confirm with Enter, Tab, and mouse clicks (previously Enter split the block and clicks were ignored), arrow-key navigation keeps the highlighted row scrolled into view in long lists without a resting pointer or wheel scrolling disturbing the highlight, and the menu shows its "No results" state for non-matching queries and no longer clips the last row (#1145). Applying a link rejects syntactically invalid URLs, preventing window.open errors from malformed href values (#834)
• Sidebar and AppLayout - Toggle shortcuts ignore synthetic keydown events that carry no key (for example Microsoft Edge form autofill) instead of throwing (#1005)
• Sidebar mobile overlays - useSidebar exposes mobileOverlayContainer, and overlays rendered inside Sidebar.Mobile portal into the sheet so dropdowns open in view on mobile Safari instead of off screen (#978)
• Map - New workerUrl prop passes an explicit MapLibre worker URL for bundlers that cannot resolve the ESM worker automatically, and the docs examples use a keyless basemap provider (#1097)
• ChatConversation - Scrolling up while a response is streaming is respected: a growing conversation no longer pulls the viewport back to the bottom, and scrollToBottom accepts a force flag for explicit jumps
• CodeBlock - Highlighted code renders from Shiki tokens as React elements instead of injected HTML (#863)

Dependencies

• @heroui/react and @heroui/styles bumped to 3.2.5; peer minimums bumped to >=3.2.5 (#887, #1195)
• react-aria-components bumped to 1.21.0; peer minimum bumped to >=1.21.0 (#1046)
• react-aria (>=3.52.0) and react-stately (>=3.50.0) added as peer dependencies for ContextMenu (#924)
• @react-aria/interactions (>=3.28.1) added as a peer dependency for HoverCard (#915)
• @internationalized/date bumped to 3.12.4 and @internationalized/number to 3.6.8
• maplibre-gl bumped to 6.4.1; peer minimum stays >=6.0.0
• @tiptap/* pins bumped to 3.31.3; peer minimums stay >=3.23.6

Breaking Changes

Peer dependency minimums bumped

@heroui/react and @heroui/styles now require >=3.2.5, and react-aria-components requires >=1.21.0. react-aria, react-stately, and @react-aria/interactions are declared as peers:

- "@heroui/react": ">=3.2.2"
- "@heroui/styles": ">=3.2.2"
- "react-aria-components": ">=1.19.0"
+ "@heroui/react": ">=3.2.5"
+ "@heroui/styles": ">=3.2.5"
+ "@react-aria/interactions": ">=3.28.1"
+ "react-aria": ">=3.52.0"
+ "react-aria-components": ">=1.21.0"
+ "react-stately": ">=3.50.0"

Update the packages together:

npm install @heroui/react@latest @heroui/styles@latest react-aria-components@latest react-aria@latest react-stately@latest @react-aria/interactions@latest

react-aria, react-stately, and @react-aria/interactions are already dependencies of react-aria-components, so the lockfile gains no new packages. Only apps with strict peer dependency resolution need to add them explicitly.

HoverCard open state moves to the root

HoverCard.Content no longer accepts defaultOpen or onOpenChange. Passing them there detached the popover from the trigger's state, so they now live on the HoverCard root alongside open:

- <HoverCard>
+ <HoverCard defaultOpen onOpenChange={handleOpenChange}>
    <HoverCard.Trigger>@heroui</HoverCard.Trigger>
-   <HoverCard.Content defaultOpen onOpenChange={handleOpenChange}>
+   <HoverCard.Content>
      {/* … */}
    </HoverCard.Content>
  </HoverCard>

ContextMenu behavior changes

The public API is unchanged, but a few behaviors now come from React Aria:

• The menu focuses its first item on open and exposes an accessible name via aria-labelledby.
• Right-clicking the trigger while its menu is open closes the menu instead of repositioning it.
• A caller's onContextMenu on ContextMenu.Trigger is chained with the internal handler; previously it replaced it and prevented the menu from opening.
• The trigger renders an id and is not focusable by default. Pass tabIndex={0} to enable the platform keyboard shortcuts (Shift + F10, Control + Enter).

Upgrade

npx heroui-pro

Select Update HeroUI Pro React to x.x.x (latest) from the interactive menu.