HeroUI v3: a React component library built on React Aria and Tailwind CSS v4

What HeroUI solves, and for whom

HeroUI is a React component library. The repository README states it combines React Aria with Tailwind CSS v4, and that it ships a compound component API such as Card.Header, Card.Content and Select.Item. The problem it addresses is the gap between accessibility behaviour and styling: React Aria supplies keyboard, focus and screen-reader primitives, and Tailwind supplies the visual layer, so an application does not need to hand-build either. The README lists the target audience explicitly: SaaS applications, dashboards and admin panels, e-commerce storefronts, marketing sites, and any React or Next.js project that values design quality and accessibility. That is a broad list, which is itself a signal. A library that claims to fit marketing pages and data-dense admin panels is optimising for range rather than for one workload. The more specific claim in the README is that no Provider wrapper is required, in contrast to Chakra and MUI, and that the library works out of the box with React 19 and Next.js. Those two points are the ones worth checking against your own stack, because they determine how much wiring you remove.

Compound components, React Aria and Tailwind v4 as one mechanism

The architecture visible in the repository is a pnpm monorepo driven by Turbo, with apps/ and packages/ at the top level and a v3 default branch. The root package.json is private and its build script filters to two workspace packages, @heroui/styles and @heroui/react, which tells you the shipped surface is narrower than the monorepo contents. The README describes three layers that meet in the published package. React Aria provides the accessibility behaviour. Tailwind CSS v4 provides styling with no CSS-in-JS runtime, which the README frames as smaller output and faster builds. The compound component API provides composition, so a card is assembled from Card.Header and Card.Content rather than configured through nested props. The README also notes per-component packages such as @heroui/button and @heroui/modal for tree-shakeable imports, so a consumer can import a single component instead of the full bundle. One design decision deserves scrutiny: dropping the Provider wrapper removes boilerplate, but it also removes the single place where a library usually centralises theme context. The README does not explain how theme state is shared across components without that wrapper, so if your application switches themes at runtime, that is a question to answer from the documentation rather than from the README.

Installing HeroUI and rendering a first component

The README gives one install command and then points to the quick-start page at heroui.com/docs/react/getting-started/quick-start for the rest. Install the full bundle with npm:

npm install @heroui/react

The README also lists @heroui/styles for styles and theme only, and individual packages such as @heroui/button and @heroui/modal for per-component imports. The README does not show the Tailwind v4 configuration or the import path for a single component, so the quick-start page is the place to confirm both. The repository does document one command aimed at AI-assisted workflows. Running the CLI installs agent skills for editors such as Cursor and Claude Code:

npx heroui-cli agents-md

The README states this works with Cursor, Claude Code, Windsurf, GitHub Copilot, and any tool that supports MCP or llms.txt. It also lists an MCP server published as @heroui/react-mcp, which the README says can be installed in Cursor, Claude Code, Windsurf, or any MCP-compatible editor, and a structured context file at heroui.com/llms.txt. If you want to see components before installing anything, the README points to storybook-v3.heroui.com, and the design kit is published as the HeroUI Figma Kit (v3).

Where HeroUI stops: React only, and a v2 to v3 split

The clearest limitation is the platform. HeroUI is a React component library, and the README describes React 19 and Next.js support. There is no Vue or React Native package in the packages table, which lists only @heroui/react, @heroui/styles, and per-component packages such as @heroui/button and @heroui/modal. If your application is not React, this library is not a candidate. The second limitation is versioning. The README documents two documentation sites, heroui.com for v3 and v2.heroui.com for v2, and the repository's default branch is v3. That split means existing NextUI or HeroUI v2 codebases face a migration question, and the README does not describe a migration path, a codemod, or a compatibility layer. The release history shows v3.2.5 on 2026-09-10, v3.2.4 on 2026-08-07, and v3.2.3 on 2026-07-31, so the v3 line is receiving patch releases, but the README stays silent on how a v2 application gets there. The third gap is licensing. The README's License section links to the MIT license text, while the repository metadata and the LICENSE entry in the top-level file list indicate Apache-2.0. Those are different terms, and anyone making an adoption decision should read the LICENSE file in the repository rather than the badge line.

HeroUI vs shadcn/ui, MUI and Mantine

The README's own comparison table is the starting point. Against shadcn/ui, it draws the line at ownership of the design system: HeroUI is described as batteries-included with a consistent design system, while shadcn/ui is described as copy-paste-customize. That is a real difference in approach. With shadcn/ui you receive source files that live in your repository and you maintain them; with HeroUI you receive a versioned dependency and you upgrade it. The first model gives you total control and no upstream upgrade path. The second gives you upgrades and less control. Against MUI, the README claims HeroUI is lighter and Tailwind-native with no CSS-in-JS runtime overhead. That claim rests on the styling mechanism rather than on published measurements, and the README does not include any. Against Chakra UI, the README cites React Aria for accessibility primitives and Tailwind v4 for performance. Against Mantine, the README points to the AI tooling (MCP, llms.txt) and Tailwind-first styling as the differentiators. If accessibility semantics are the deciding factor, the React Aria foundation is the substantive difference here, because it is a dependency choice rather than a styling preference. If your team already runs Tailwind v4, the styling layer is not a differentiator at all.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-10, one week before this writing. The v3.2.5 release landed the same day, with v3.2.4 on 2026-08-07 and v3.2.3 on 2026-07-31 before it. That cadence suggests patch-level maintenance on the v3 line rather than a dormant project. The monorepo tooling is conventional: pnpm workspaces, Turbo for task orchestration, ESLint, Prettier, Husky and lint-staged, with commitlint configured. For a consumer this matters only in that the published packages are built by the same pipeline that runs the repository's own docs and storybook apps, which the root scripts confirm. Upgrade cost is the open question. The README documents v3 and v2 as separate documentation sites but does not describe what changed between them, so the cost of moving an existing v2 application to v3 cannot be estimated from the README alone. On licensing, the discrepancy between the README's MIT link and the repository's Apache-2.0 designation is the item to resolve before adoption. Apache-2.0 and MIT both permit commercial use, but Apache-2.0 adds an explicit patent grant and notice requirements. That is a factual difference, not legal advice; have your own counsel read the LICENSE file.

Editorial conclusion

Adopt HeroUI if you are starting a React 19 or Next.js app and want React Aria accessibility behaviour plus Tailwind CSS v4 styling without writing a design system from scratch. Do not adopt it if you need a component library outside React, or if you depend on packages the v3 branch has not ported yet, since the README points v2 users to v2.heroui.com rather than describing a migration path. Before committing, verify three things yourself: that the packages you need resolve from @heroui/react or the individual @heroui/button and @heroui/modal packages, that the README's MIT licence line matches the LICENSE file in the repository, which is Apache-2.0, and that your Tailwind setup is on v4, because the README states v4 as the engine.

Frequently asked questions

Official sources

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