HeroUI

HeroUI (formerly NextUI) is a production-ready React component library that pairs the accessibility rigor of React Aria with the utility-first styling of Tailwind CSS v4. It ships a compound component API — Card.Header, Card.Content, Select.Item, and similar patterns — instead of deeply nested prop objects, and it requires no top-level <Provider> wrapper to start rendering. The library targets React 19 and Next.js out of the box, and bundles over 80 components spanning forms, overlays, navigation, and data display.

Beyond the component set, HeroUI leans into AI-assisted development: it ships an official MCP server, an llms.txt context file, and installable agent skills so tools like Claude Code and Cursor can generate correct usage without hallucinating props. Styling is handled by a dedicated @heroui/styles package built on tailwind-variants, keeping the component logic and the Tailwind class generation cleanly separated.

What You Get

• Over 80 accessible React components (buttons, forms, overlays, tables, calendars, navigation) built on React Aria Components for WCAG-compliant keyboard and screen-reader behavior
• A compound component API (Card.Header, Card.Content, Select.Item) that composes cleanly instead of relying on large flat prop objects
• Tailwind CSS v4 styling via a separate @heroui/styles package powered by tailwind-variants, with no CSS-in-JS runtime and no required <Provider> wrapper
• AI-assisted development tooling: an official MCP server (@heroui/react-mcp), a published llms.txt, and installable agent skills for Claude Code, Cursor, and Windsurf
• Individually installable per-component packages (@heroui/button, @heroui/modal, etc.) for teams that want tree-shakeable, à-la-carte imports instead of the full @heroui/react bundle

Common Use Cases

• Building SaaS application UI — forms, tables, overlays, and toast notifications with accessible defaults out of the box
• Constructing dashboards and admin panels that need consistent design tokens across data-dense layouts
• Shipping marketing sites and landing pages that want polished, accessible UI without a heavyweight CSS-in-JS runtime
• Migrating off NextUI (HeroUI’s predecessor) or off a component library like MUI/Chakra where Tailwind-native styling and lighter bundle weight are priorities

Under The Hood

Architecture — HeroUI is a Turborepo-managed pnpm monorepo. packages/react is the public-facing bundle: its src/index.ts re-exports from components/ (87 component directories, one per primitive, e.g. button/button.tsx) and hooks/ (ten focused hooks like use-overlay-state and use-media-query), plus tv/cn helpers re-exported from tailwind-variants. Styling is deliberately decoupled into a sibling packages/styles package that owns the Tailwind plugin and per-component *Variants functions (e.g. buttonVariants); packages/react imports these variant functions and merges them with react-aria-components primitives (Button as ButtonPrimitive) via a composeTwRenderProps utility, so a component like button.tsx is essentially a thin adapter layer over React Aria plus a Tailwind class function. Compound components use React context (ButtonGroupContext) with an explicit escape hatch — direct props always take precedence over inherited group context — rather than the deep prop-drilling common in older component libraries.

Tech Stack — Built for React 19 and Tailwind CSS v4 specifically (both are hard peer dependencies, >=19.0.0 and >=4.0.0), with react-aria/react-aria-components (Adobe’s accessibility primitives) and tailwind-variants as the two foundational dependencies. The build pipeline uses Rollup for bundling, TypeScript throughout with strict typing on exported prop interfaces, and a shared @heroui/vitest config package for whichever packages do have test suites. Package publishing goes through a clean-package step that strips workspace-only fields before npm publish.

Code Quality — Code is consistently typed and formatted (ESLint + Prettier enforced via lint-staged/husky pre-commit hooks, commitlint for conventional commits), and naming is uniform across the 87 component modules (<name>.tsx root + supporting files in each directory). The notable gap: a shallow clone of the packages/react source tree turned up zero *.test.* files, despite the monorepo maintaining a dedicated @heroui/vitest shared-config package — test coverage for the component logic itself appears thin or lives outside the public package boundary. Partially offsetting this, 67 of the 87 components ship a corresponding *.stories.tsx Storybook file, giving strong manual/visual coverage even without automated assertions.

API Design — The developer experience is the standout: no <HeroUIProvider> wrapper is required just to render a component (a real friction point in Chakra UI and MUI), props are typed via ComponentPropsWithRef extension so IDE autocomplete surfaces the full underlying React Aria prop set, and the compound API (Card.Header/Card.Content) reads close to plain JSX nesting. The AI-tooling investment (MCP server, llms.txt, CLI-installable agent skills via npx heroui-cli agents-md) is unusual for a component library and specifically targets reducing prop-hallucination when code is written by an AI assistant rather than a human reading docs.