heroui README

The project's README from github.com/heroui-inc/heroui. As one markdown file: README.md.

HeroUI v3 logo

License npm downloads

Why HeroUI?

HeroUI (previously NextUI) is a production-ready React component library that combines the accessibility rigor of React Aria with the utility-first styling of Tailwind CSS v4. It ships a clean compound component API (Card.Header, Card.Content, Select.Item, …), requires no <Provider> wrapper, and works out of the box with React 19 and Next.js.

Packages

Package Description
@heroui/react Full component bundle
@heroui/styles Styles / theme only
Individual packages e.g. @heroui/button, @heroui/modal — tree-shakeable per-component imports

Getting Started

Visit heroui.com/docs/react/getting-started/quick-start to get started with HeroUI.

npm install @heroui/react

Who Is This For?

HeroUI is a good fit if you are building:

AI-Powered Development

HeroUI is built for the AI-assisted development workflow.

Tool What it does
MCP Server (@heroui/react-mcp) Components that understand your theme — install the server in Cursor, Claude Code, Windsurf, or any MCP-compatible editor
llms.txt Available at heroui.com/llms.txt — structured context for LLMs about every component
Agent Skills Run npx heroui-cli agents-md to install skills for Cursor, Claude Code, and more

Works with Cursor, Claude Code, Windsurf, GitHub Copilot, and any tool that supports MCP or llms.txt.

Compared To

Library How HeroUI differs
shadcn/ui HeroUI is batteries-included with a consistent design system; shadcn is copy-paste-customize
MUI HeroUI is lighter, Tailwind-native, no CSS-in-JS runtime overhead
Chakra UI HeroUI uses React Aria (stronger a11y primitives) and Tailwind v4 (better perf)
Mantine HeroUI has AI tooling (MCP, llms.txt), Tailwind-first styling

Documentation

Storybook

Visit storybook-v3.heroui.com to view the storybook for all components.

Roadmap

Visit herouiv3.featurebase.app/roadmap to view the roadmap for HeroUI v3.

Figma

Visit the HeroUI Figma Kit (v3) to view the design kit.

Community

We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!

Contributing

Contributions are always welcome!

See CONTRIBUTING.md for ways to get started.

Please adhere to this project's CODE_OF_CONDUCT.

License

MIT

heroui (heroui-inc/heroui)

storybook
Searching Database…

31K ·GitHub
What is this?HeroUI (formerly NextUI) is a production-ready React component library that combines React Aria's accessibility primitives with Tailwind CSS v4 styling.
Is this a UI library or a full framework?It's a component library you install into your own React or Next.js app, not a standalone framework. It ships a compound component API (e.g. Card.Header, Select.Item) and needs no wrapping Provider.
How do I add it to a project?Follow the quick-start guide at heroui.com/docs; you can install the full bundle via the @heroui/react package or pull individual tree-shakeable packages like @heroui/button or @heroui/modal.
Do I need Tailwind CSS already set up?Yes, HeroUI's styling is built on Tailwind CSS v4 rather than a CSS-in-JS runtime, and it's designed to work with React 19 and Next.js out of the box.
Is this the same project as NextUI?Yes, HeroUI is the renamed continuation of NextUI, so existing NextUI apps and docs map directly to it; note that v2 and v3 docs live on separate sites (v2.heroui.com vs heroui.com).
What kind of apps is HeroUI meant for?SaaS apps, dashboards/admin panels, e-commerce storefronts, and marketing sites — basically any React/Next.js project that wants accessible, polished UI.
What AI-assisted dev tooling does it include?HeroUI ships an MCP server (@heroui/react-mcp) for editors like Cursor, Claude Code and Windsurf, a structured llms.txt at heroui.com/llms.txt, and installable agent skills via npx heroui-cli agents-md.
How is it different from shadcn/ui or MUI?Unlike shadcn's copy-paste-customize model, HeroUI is batteries-included with a consistent design system; compared to MUI it's lighter and Tailwind-native with no CSS-in-JS runtime overhead.
Can I import just one component instead of the whole library?Yes, beyond the full @heroui/react bundle, every component is also published as its own tree-shakeable package (e.g. @heroui/button, @heroui/modal).
Is there a design kit or live demo to explore components?Yes — a Figma Kit for v3 is available, and a Storybook with all components can be browsed at storybook-v3.heroui.com.
Creator
heroui-inc
Size
110.4 MB
Stars
31K
Age
5y
Commits · 90 Days