Version-matched docs inside @heroui/react, a heroui-theming agent skill, tailwind-variants 4, ToggleButton fullWidth, Sheet stacking inside modals, wrapping overlay footers, an easier Table column resizer, RTL progress and skeleton animations, and fixes for Checkbox, Menu, ListBox, blur backdrops, and ScrollShadow.
Patch release: @heroui/react now ships version-matched Markdown docs for coding agents, and the new heroui-theming skill lets an agent restyle HeroUI or author a complete theme (Theming with Agents). @heroui/react and @heroui/styles move to tailwind-variants@4.0.2. ToggleButton gains a fullWidth prop, Sheet now stacks on the shared overlay z-index so it opens above a Modal, and footer actions in Modal, AlertDialog, Drawer, and Sheet wrap instead of overflowing. ProgressBar and Skeleton animations now sweep in the reading direction in RTL. This release also widens the Table column resizer hit area, stops the Checkbox indeterminate fill from flashing, keeps icons and long labels in shape in Dropdown menu and ListBox items, keeps variant="blur" backdrops blurred on touch devices, and clears a stale ScrollShadow fade when content stops overflowing.
Installation
Update to the latest version:
npm i @heroui/styles@latest @heroui/react@latesttailwind-variants 4. @heroui/react and @heroui/styles re-export tv, cn, and VariantProps from tailwind-variants, which this release upgrades from 3.3.1 to 4.0.2. In v4, passing a non-empty twMergeConfig to the root tv() throws a TypeError at runtime. If you pass twMergeConfig to tv(), import tv from tailwind-variants/config instead. v4's stricter types can also reject some tv() configurations that v3 accepted.
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.
Dependencies
- tailwind-variants: Upgrade
@heroui/reactand@heroui/stylestotailwind-variants@4.0.2. HeroUI's internaltvwrapper is nowcreateTV({twMerge: false}), so class merging stays off as before, and the unusedtailwind-mergeRollup external is removed. If you passtwMergeConfigtotv(), whether imported from HeroUI or fromtailwind-variants, importtvfromtailwind-variants/configinstead; the root entry now throws aTypeError(#6996, #7010). - Tooling: Bump Tailwind CSS to
4.3.5, Vitest to5.1.1, Storybook to10.6.8, and other development dependencies (#7004, d7f820d, #7035). - Security: Remove the vulnerable
deepmergepackage from the build toolchain (GHSA-gcqx-w48m-w2h4) and the unused@vercel/ogdependency from the docs (GHSA-wx4j-mvgx-mqwp) (#6997). Move development tooling to patchedminimatch@11andglob@14(GHSA-g3hv-75wg-m249, GHSA-3g3m-2fjr-6pw4) (#7029).
What's New
- Docs inside the package:
@heroui/reactnow ships its documentation as Markdown undernode_modules/@heroui/react/docs/— anllms.txtindex plus component and guide pages — generated from the docs site at publish time. Coding agents read the docs for the version installed in your project, with no network access. Point your agent atdocs/llms.txtfromAGENTS.mdorCLAUDE.md; see LLMs.txt (#7017). - heroui-theming skill: A new agent skill for global customization and full theme authoring with tokens, BEM overrides, and named light and dark themes, on React or any framework. Install it with
curl -fsSL https://heroui.com/install | bash -s heroui-theming; see Theming with Agents (#7017). - heroui-react skill: Read component docs and guides from the installed
@heroui/reactpackage when the project depends on it, falling back to heroui.com otherwise (#7017). - ToggleButton: Add
fullWidthto stretch the button to the width of its container. It works with everyvariantandsize, and maps to thetoggle-button--full-widthmodifier (#7012).
Bug Fixes
- Checkbox: Keep the indeterminate indicator mounted so its fill fades instead of flashing when the indeterminate state changes, including the select-all checkbox in Table (#7019).
- Menu and ListBox items: Keep icons from shrinking, and let long labels (including labels inside a label-and-description wrapper) wrap instead of overflowing the item in Menu, Dropdown, ListBox, and Select (#7034).
- Blur backdrops: On touch devices, skip
backdrop-filteronly while the backdrop of Modal, AlertDialog, or Drawer is entering or exiting, sovariant="blur"no longer looks opaque once the overlay has opened (#7025). - Sheet: Stack the overlay on the shared
--z-index-overlayvalue used by Modal, AlertDialog, and Drawer instead ofz-50, so a Sheet opened from inside a Modal renders above it (#7006). - Overlay footers: Wrap footer actions that do not fit on one row in AlertDialog, Modal, Drawer, and Sheet instead of overflowing the panel (#7001).
- Table: Make the column resizer a 24px-wide, full-height hit area lifted above the next header, so its far half is no longer covered. The visible line now draws with
::beforeand stays centered on the column edge in RTL (#7007). - ScrollShadow: Clear the scroll-driven fade when content that overflowed, was scrolled, and then shrank to fit stops overflowing. Chromium and WebKit kept the last fade values on the inactive scroll timeline, leaving a stale edge fade (#7015).
Styles
- RTL animations: ProgressBar's indeterminate sweep and Skeleton's shimmer now run right to left in RTL. One keyframe per animation is scaled by a direction sign set with
:dir(rtl), so reduced motion, custom--animate-skeletonvalues, and nesteddir="ltr"subtrees keep working (#7023).
Documentation
- Docs redesign: A new docs shell with header actions and an appearance switcher, a sidebar grouped by category, interactive prop controls next to component previews, and a redesigned Cmd+K search with filters. The components index lists free and Pro components together, and the showcase pages are removed; old
/showcaselinks redirect to getting started (#7020). - Theming with Agents: Add a guide to customizing HeroUI globally and authoring complete themes with a coding agent, and document the packaged docs on the LLMs.txt and Agent Skills pages (#7017).
- DESIGN.md: Publish default-theme
DESIGN.mdfiles for React and Native, and document the CLI'sdesign-mdcommand. See DESIGN.md and CLI (#6905, #6992, #6994). - Web and Native switch: Keep the current page when switching between Web and Native docs (#7011).
- Search: List Ask AI first when a search reads as a question, and remove separators from the search dialog (#6990, #6991).
Storybook
- Theming stories: Add a Theming/Themes story with two example themes, Arcade and Ledger, that restyle components through tokens and BEM overrides (#7017).
- Locales: Add Persian and Urdu to the locale switcher. Both fall back to English React Aria strings (#7023).
Links
Contributors
Thanks to everyone who contributed to this release!