HeroUI v3: React Aria Accessibility With Tailwind v4 Styling
🚀 Beautiful, fast and modern React UI library. (Previously NextUI)
At a glance
- What is it?
- HeroUI, formerly NextUI, is a TypeScript React component library that pairs React Aria behaviour with Tailwind CSS v4 styling and a compound component API. The pitch is real, but the v3 branch, the licence mismatch in the README, and the missing install steps are things you should check before committing.
- Who is it for?
- Adopt HeroUI v3 if you are starting a React 19 or Next.js app where accessibility behaviour and Tailwind v4 styling both matter, and if you are willing to track a v3 branch that shipped three patch releases between late July and early September 2026. Do not adopt it if you need a stable v2-compatible surface or an unambiguous licence, because the repository metadata says Apache-2.0 while the README links to an MIT badge and an MIT licence page.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem HeroUI Solves Is Accessibility Wiring, Not Visual Design
Most React teams can style a button. What they cannot do cheaply is make a select, a combobox, a modal and a menu all behave correctly under keyboard navigation, focus management and screen readers. HeroUI's answer is to build on React Aria, the Adobe library whose stated purpose is WCAG-compliant keyboard, focus and screen-reader behaviour, and then style the result with Tailwind CSS v4. The README describes this as combining the accessibility rigor of React Aria with the utility-first styling of Tailwind CSS v4.
The target audience is stated fairly explicitly: SaaS applications with forms, tables, overlays and notifications; dashboards and admin panels with data-dense layouts; e-commerce storefronts; marketing pages; and any React or Next.js project where design quality and accessibility are priorities. That list is broad, and broad lists usually mean the library is a general-purpose one rather than a specialist tool. The more useful signal is the omission of a Provider wrapper. Chakra and MUI both require one, and HeroUI's README calls that out directly: no Provider wrapper needed, unlike Chakra and MUI. If you have ever debugged a theme that only applied inside the wrong provider boundary, that is a concrete difference rather than a marketing line.
Compound Components and Where the Styling Actually Lives
The API shape is the second half of the pitch. HeroUI ships what the README calls a clean compound component API, with examples such as Card.Header, Card.Content and Select.Item. The alternative, which the README characterises as deeply nested props, is the pattern where you pass a header string, a footer node and a body node into a single component and hope the internal layout matches your design. Compound components push that composition into your JSX instead.
The styling mechanism is Tailwind CSS v4. The README frames this as modern engine, no CSS-in-JS runtime, smaller output, faster builds. That is a claim about build characteristics rather than a benchmark, and no numbers are given, so treat it as a direction of travel rather than a measured result. What is verifiable is the packaging: the repository lists @heroui/react as the full component bundle, @heroui/styles as styles and theme only, and individual packages such as @heroui/button and @heroui/modal for tree-shakeable per-component imports. That three-tier split matters if bundle size is a constraint, because it lets you import a single component package instead of the whole bundle.
The AI tooling is a distinct layer. HeroUI ships an MCP server published as @heroui/react-mcp, an llms.txt file at heroui.com/llms.txt, and agent skills installed with npx heroui-cli agents-md. The README lists Cursor, Claude Code, Windsurf and GitHub Copilot as supported editors. Whether that matters to you depends entirely on whether your team already works inside one of those tools.
Installing HeroUI: One Command Documented, the Rest Is a Link
This is where the repository material runs thin. The README gives exactly one install command:
npm install @heroui/react
Everything after that is a pointer. The Getting Started section says to visit heroui.com/docs/react/getting-started/quick-start, and no Tailwind configuration, no theme setup and no import example appears in the README itself. Since the library is Tailwind CSS v4 based, you should expect to configure Tailwind in your project, but the README does not state which keys or which file. Do not assume a tailwind.config.js snippet from a v2 tutorial still applies on the v3 branch.
The AI tooling commands are more concrete. npx heroui-cli agents-md installs agent skills for Cursor, Claude Code and similar tools, and the MCP server is distributed as @heroui/react-mcp. The README says to install the server in Cursor, Claude Code, Windsurf or any MCP-compatible editor, but it does not print the JSON configuration block. You will need the MCP server's own documentation for the exact config shape.
Two other entry points are listed. Storybook lives at storybook-v3.heroui.com, which is useful for inspecting component states before you install anything. The v2 documentation is kept separately at v2.heroui.com, which tells you the v3 API is not a drop-in continuation of v2.
The v3 Branch Is a Migration, Not a Patch Release
The repository's default branch is v3, and the release history on that branch shows v3.2.3 on 31 July 2026, v3.2.4 on 7 August 2026 and v3.2.5 on 10 September 2026. That is a steady patch cadence over roughly six weeks, which suggests active maintenance rather than a stalled rewrite.
What the material does not tell you is what changed between v2 and v3. The README keeps a separate v2 documentation site, which is the standard signal that the two versions are not interchangeable. The comparison table in the README positions HeroUI against shadcn/ui, MUI, Chakra UI and Mantine, but it does not compare HeroUI v3 against HeroUI v2. If you are already running NextUI or HeroUI v2, the migration cost is the single largest unknown in this review, and nothing in the supplied material quantifies it.
The naming history adds a smaller wrinkle. The project was previously called NextUI, and the README still leans on that history with the phrase trusted by thousands of production apps. That is an unverifiable claim in this context, and it is the kind of line that should not influence a technical decision either way.
The Licence Signal in This Repository Is Contradictory
The repository metadata supplied for this review lists Apache-2.0. The README does not agree. Its licence badge points at an npm licence image for @heroui/react, and the Licence section links to the MIT licence page on choosealicense.com under the label MIT. So the two sources in front of you name two different licences.
This is not a subtlety you can wave away, because Apache-2.0 and MIT differ on patent grants and notice requirements, and those differences matter to legal review at some companies. I cannot resolve the conflict from the material available. The only honest guidance is procedural: read the actual LICENSE file on the branch you intend to install from, at github.com/heroui-inc/heroui/blob/main/LICENSE, rather than trusting either the badge or the repository metadata. If your organisation requires an approved licence identifier before a dependency is added, get that resolved first. Nothing here is legal advice, and the discrepancy is exactly the sort of thing that should go to whoever handles licensing on your team.
Where HeroUI Is the Wrong Choice
The README's own comparison table is the most useful part of the document, because it states the trade-off rather than hiding it. Against shadcn/ui, HeroUI is described as batteries-included with a consistent design system, while shadcn/ui is copy-paste-customize. That is a real fork in the road. With shadcn/ui you own the component source and can edit it freely. With HeroUI you depend on a package and its release cycle. If your design language diverges sharply from HeroUI's defaults, the copy-paste model is easier to bend, and HeroUI will fight you.
Against MUI, the README says HeroUI is lighter and Tailwind-native with no CSS-in-JS runtime overhead. If your team is already deep in MUI's theming system, or relies on MUI's enterprise data grid, switching means giving up that ecosystem rather than gaining a like-for-like replacement.
The harder limitation is versioning. A library whose default branch is v3, whose v2 docs live at a separate domain, and whose README documents one install command and defers everything else to a website is a library that expects you to read its docs site. Teams that pin dependencies and upgrade rarely will find that the v2 to v3 transition lands on them all at once. There is also no stated support window for v2 in the material provided, so you cannot plan a migration timeline from this README alone.
Maintenance Cost and What to Verify Before You Commit
The upgrade surface has three parts. First, the React and Next.js baseline: the README says HeroUI works out of the box with React 19 and Next.js, so a project still on React 18 needs to confirm support before adopting. Second, Tailwind CSS v4, which is a major version with its own migration path if you are currently on v3 of Tailwind. Third, the HeroUI packages themselves, which the release history shows moving on a roughly monthly patch rhythm.
There is also a tooling dependency that is easy to overlook. If you adopt the MCP server or the agent skills, those become part of your development environment and need updating alongside the library. The npx heroui-cli agents-md command pulls skills into your editor configuration, and those files will drift from the component API over time unless you re-run the command after upgrades.
Before adopting, verify four things. Confirm the licence by reading the LICENSE file on your target branch. Read the quick start page at heroui.com/docs/react/getting-started/quick-start in full, because the README does not contain the Tailwind setup. Check the v3 Storybook at storybook-v3.heroui.com for the specific components your product needs, rather than trusting the package list. And if you are on v2 or NextUI today, find the migration guide before you plan any work, because this README does not contain one.
Editorial conclusion
Adopt HeroUI v3 if you are starting a React 19 or Next.js app where accessibility behaviour and Tailwind v4 styling both matter, and if you are willing to track a v3 branch that shipped three patch releases between late July and early September 2026. Do not adopt it if you need a stable v2-compatible surface or an unambiguous licence, because the repository metadata says Apache-2.0 while the README links to an MIT badge and an MIT licence page. Before writing any component code, open the quick start page at heroui.com/docs/react/getting-started/quick-start, confirm which licence file actually sits on the branch you install from, and run the MCP server or llms.txt step only after you have decided to standardise on this library.
Community notes