HeroUI v3: React Aria behavior, Tailwind CSS v4 styling and compound components, formerly NextUI

React Aria handles behavior, Tailwind CSS v4 handles looks

HeroUI, previously NextUI, splits the work of a component library in two. Behavior comes from React Aria, Adobe's accessibility layer, which supplies keyboard handling, focus management and screen reader behavior aimed at WCAG compliance. Styling comes from Tailwind CSS v4 utility classes, with no CSS-in-JS runtime.

That combination is the main reason to pick it. You do not write focus traps or ARIA attributes for a select or a modal yourself, and the visual layer is plain Tailwind you can read and override. The trade is that HeroUI is Tailwind first: adopting it means adopting Tailwind CSS v4, so a project built on CSS modules, styled-components or an older Tailwind major takes on a styling migration along with the components.

Compound components and no Provider wrapper

The API is compound: you compose `Card.Header` and `Card.Content`, or `Select.Item`, instead of passing deeply nested props into one component. Each part is a component you can place, reorder or wrap.

HeroUI also requires no `<Provider>` wrapper at the root of your app, a point the project contrasts directly with Chakra and MUI. It works with React 19 and Next.js without that setup step. For an existing app, that lowers the cost of trying a single component on one page, since nothing has to be threaded through the whole tree first.

Two packages, with per component subpaths inside the bundle

HeroUI publishes two npm packages. `@heroui/react` is the full component bundle, and `@heroui/styles` carries styles and theme only. Both go in together:

npm install @heroui/styles @heroui/react

Inside the main package, component subpaths such as `@heroui/react/button` and `@heroui/react/modal` give per component imports. These are paths into the published `@heroui/react` package, not separate packages, so there is still one version to track. The monorepo builds exactly these two packages with Turbo, and the root package.json is at version 3.2.7, matching the latest release, v3.2.7, published on 2026-10-28.

v2 and v3 are separate documentation sites

The repository's default branch is v3, and the v3 line lives at heroui.com. The v2 documentation stays at v2.heroui.com. The Storybook at storybook-v3.heroui.com, the roadmap on herouiv3.featurebase.app and the Figma kit are all labelled v3.

The consequence is that code written for NextUI or HeroUI v2 does not map directly onto the v3 compound API, and search results mix both versions. Before copying an example, check which site it came from. If you are on v2 and not ready to move, keep using v2.heroui.com; the v3 docs will describe components and patterns your installed version does not have.

The comparison table is the vendor's own claim

HeroUI positions itself against four libraries. Against shadcn/ui, it calls itself batteries included with a consistent design system, where shadcn is copy, paste and customize. Against MUI, it claims to be lighter and Tailwind native with no CSS-in-JS runtime overhead. Against Chakra UI, it points to React Aria for stronger accessibility primitives and Tailwind v4 for better performance. Against Mantine, it cites its AI tooling and Tailwind first styling.

These are the maintainers' statements, presented without benchmark figures beside them, and the battle tested label rests on an unquantified claim of thousands of production apps. The architectural differences, React Aria and no runtime CSS-in-JS, are checkable facts. The performance and lightness claims are not something you can verify from the table, so measure bundle size and render behavior in your own app before treating them as settled.

MCP server, llms.txt and agent skills for coding assistants

HeroUI ships tooling aimed at AI coding assistants. The `@heroui/react-mcp` MCP server installs into Cursor, Claude Code, Windsurf or any MCP compatible editor and exposes components that understand your theme. A structured context file for every component is published at heroui.com/llms.txt.

To pull the React v3 documentation into your project as an AGENTS.md file:

npx heroui-cli@latest agents-md --react

To install agent skills for supported coding agents:

npx skills add heroui-inc/heroui

The agents-md command fetches docs for React v3 specifically, which ties back to the version split: an assistant fed v3 docs will write v3 code, so use it only once your project is on v3. The project is not archived; its last push was on 2026-10-03, and releases v3.2.5, v3.2.6 and v3.2.7 shipped between September and late October 2026.

Editorial conclusion

HeroUI v3 suits React 19 and Next.js projects that already use, or are ready to adopt, Tailwind CSS v4 and want accessible components without a Provider wrapper. It is a poor fit for teams committed to another styling system, and for v2 or NextUI codebases that are not ready for a version jump. Before adopting it, confirm which major version your existing code and tutorials target, and test the components you need in the v3 Storybook rather than relying on the project's own comparison claims.

Frequently asked questions

Official sources

1. heroui-inc/heroui on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases