heroui Documentation

Apps Docs Content Docs En React Getting Started Index (`apps/docs/content/docs/en/react/getting-started/index.mdx`) Copy Section

title: Introduction icon: book-open image: https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg Copy Chapter

HeroUI is a React component library built on Tailwind CSS v4 and React Aria Components. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable.

Why HeroUI? Copy Chapter

Beautiful by default — Professional look out of the box, no extra styling needed.

Accessible — Built on React Aria Components with focus management, keyboard navigation, and screen reader support.

Flexible — Each component is made of customizable parts. Change what you need, leave the rest.

Developer-friendly — Fully typed APIs, predictable patterns, and excellent autocompletion.

Maintained — We handle updates, bug fixes, and new features. Just update the package.

Lightweight — Tree-shaken. Only what you use goes into your app.

Future-proof — Built for React 19 and Tailwind v4, designed for AI-assisted development.

A Living Library, Not Copy-Paste Copy Chapter

Copy-paste code works until it breaks. You're left maintaining outdated dependencies that stop evolving.

HeroUI is different. It's a living library that grows with you:

• Automatic updates and fixes
• New features without extra work
• Components stay current with React, Tailwind, and browsers
• Deep customization, not shallow theme tweaks
• AI-friendly APIs for code generation

HeroUI v3 is not a snapshot—it's a garden that keeps growing. 🌱

HeroUI Ecosystem Copy Chapter

• 🌐 HeroUI v3 (web) — You're here! React components with Tailwind CSS v4
• 📱 HeroUI Native (mobile) — Beautiful components for React Native
• 🤖 HeroUI Chat (text-to-app) — Create apps with natural language
• 🧠 UI for LLMs — New platform & MCPs coming soon

Why React Aria? We chose React Aria for accessibility at scale. We've used it since HeroUI v2, and v3 keeps familiar API conventions like isDisabled and onPress. Thanks to Devon Govett and the Adobe team.

FAQ Copy Chapter

Is HeroUI free?
Yes, completely free and open source under the Apache License 2.0.

Is it production-ready?
Yes. HeroUI v3 is stable and ready for production use.

Can I customize the components?
Yes! Use Tailwind utilities, CSS variables, BEM modifiers, or compose component parts differently. Every slot is customizable.

Does it work with TypeScript?
Fully typed with excellent IDE support and autocompletion.

What about accessibility?
Built on React Aria Components for WCAG compliance. Keyboard navigation, focus management, and screen reader support included.

Can I use the styles without React?
Yes, the CSS can be applied to plain HTML. See our Tailwind Play example.

Is there a Figma file?
Yes! Access our design system at HeroUI Figma Kit V3.

Get Involved Copy Chapter

Join the community, share feedback, or contribute:

• GitHub Discussions
• Discord
• X/Twitter
• Contributing Guidelines

HeroUI is released under the Apache License 2.0.

Apps Docs Content Docs En React Migration Agent Index (`apps/docs/content/docs/en/react/migration/agent-index.mdx`) Copy Section

title: Migration (for AI assistants) index: false Copy Chapter

For AI assistants: use this as the entry point when helping migrate HeroUI v2 → v3.

Entry Copy Chapter

Choose a migration strategy:

• Full migration (project will be broken during migration) → read (workflows)/agent-guide-full.mdx.
• Incremental (v2 and v3 coexist) → read (workflows)/agent-guide-incremental.mdx.

Reference in this bundle Copy Chapter

• Cross-cutting guides: hooks.mdx, styling.mdx.
• The workflow guides above already inline the "major changes", "key API changes", component reference table, and "new components" sections.
• Per-component guides: (components)/<component>.mdx (e.g. (components)/button.mdx, (components)/select.mdx). Use the component reference table in the workflow guides to find the right file.

Apps Docs Content Docs En React Migration Index (`apps/docs/content/docs/en/react/migration/index.mdx`) Copy Section

title: Migration index: true Copy Chapter

For AI Assistants Copy Chapter

Below are three approaches for AI assistants to access migration documentation. We recommend using the HeroUI Migration MCP server and leveraging its prompts and tools, but all options provide agents with the complete documentation.

Major Changes Copy Chapter

Item identity and accessibility (key, id, textValue) Copy Section

In v2, collection components (Dropdown, Listbox, Select, Accordion, etc.) used React's key as the item identity. The same value drove both React's list reconciliation and the component's selection/expand state. In v3, which uses React Aria Components, those roles are split:

• id — v3 uses an explicit id prop on each item for selection state, focus, and callbacks (e.g. selectedKeys, expandedKeys, onSelectionChange). Use the same (or equivalent) value you used for key in v2 so that state and callbacks continue to refer to the correct item.
• textValue — v3 requires textValue on items when the visible content is not plain text (e.g. when using Label, icons, or Description). It is used for screen reader announcements and type-ahead.
• key — Keep using React's key on list items. It is still required for React's reconciliation and is independent of id.

When migrating: add id (and textValue where needed) for v3's API, but keep key for React.

Migration Strategies Copy Chapter

HeroUI v2 and v3 cannot coexist in the same project without special setup. You have two migration approaches to choose from:

Full Migration Copy Section

Best for: Projects that can dedicate focused time to complete migration in one go.

How it works:

• Migrate all component code first (project will be broken during this phase)
• Switch dependencies to v3
• Complete styling migration

Advantages:

• Simpler setup - no complex coexistence configuration
• Cleaner transition - only one version active at a time
• Supported by Migration MCP prompts

Disadvantages:

• Project is broken during migration
• All components should be migrated before switching dependencies

Get started: Full Migration Guide

Incremental Migration Copy Section

Best for: Projects that need to stay functional during migration, teams migrating gradually over time, large codebases migrating feature-by-feature.

How it works:

• Set up coexistence using pnpm aliases or component packages
• Migrate components one-by-one while keeping project functional
• Complete migration and remove v2 dependencies

Advantages:

• Project remains functional during migration
• Can migrate gradually over time
• Can test v3 components alongside v2

Disadvantages:

• More complex initial setup
• Potential styling conflicts
• Requires managing two versions simultaneously

Get started: Incremental Migration Guide

Component Migration Reference Copy Chapter

New Components in v3 Copy Chapter

Additional Migration Guides Copy Chapter

• Hooks Migration Guide: Detailed guide for migrating hooks from v2 to v3
• Styling Migration Guide: Comprehensive guide for updating utility classes, color tokens, and component styling

Getting Help Copy Chapter

If you encounter issues during migration:

1. Check the v3 documentation
2. Review component-specific migration guides
3. Check the GitHub Discussions
4. Join the Discord community

Apps Docs Content Docs En React Releases Index (`apps/docs/content/docs/en/react/releases/index.mdx`) Copy Section

title: All Releases Copy Chapter

Latest Release Copy Chapter

v3.2.6 Copy Section

September 17, 2026

Patch release: AvatarGroup returns as a dedicated component, focus rings are keyboard-only again on ListBox, Dropdown, Select, and overlay triggers after a mouse-driven open, @internationalized/date moves to peerDependencies while tailwind-merge and @react-aria/i18n are dropped, ColorSlider no longer warns on every render in production, bare .tag markup keeps its default padding, Breadcrumbs sit back on the spacing grid, and React Aria is upgraded to 1.21.1 ([email protected]). Context values are also memoized across 43 components, so consumers no longer re-render on every root render.

Read full release notes →

v3.2.5 Copy Section

September 8, 2026

Patch release: Toast collapses notifications into a stack that expands on hover, Select gains a ClearButton, Tabs adds an align variant, @heroui/react re-exports Pressable, Focusable, OverlayTriggerStateContext, and DisclosureStateContext, and React Aria is upgraded to 1.21.0 ([email protected]). Also fixes theme tokens in nested data-theme scopes and shadow DOM, native :focus-visible rings on exported variants, and modal-level overlays being covered by closing popovers, plus ScrollShadow, Table, Drawer, NumberField, Accordion, Label, and Tag.

Read full release notes →

v3.2.4 Copy Section

August 4, 2026

Patch release: the Autocomplete popover no longer clips its last options, backdrop clicks dismiss a Modal with scroll="outside" again, Tabs chevron scrolling lands flush on the edges, tailwind-variants is upgraded to 3.3.1 to fix variant modifiers falling back to the wrong class after a re-render, React Aria is upgraded to 1.20.0 ([email protected]), and @heroui/react gains a behavioral test suite.

Read full release notes →

v3.2.3 Copy Section

July 30, 2026

Patch release: ComboBox adds multiple selection, styles adopt logical CSS properties for better RTL support, tailwind-variants is upgraded to 3.3.0, plus fixes for ScrollShadow, Spinner, InputOTP, Table, and accent Button focus styling.

Read full release notes →

v3.2.2 Copy Section

June 19, 2026

Patch release: upgrades to React Aria 1.19.0 ([email protected]), adds overflow scrolling to Tabs.ListContainer, fixes clear/close buttons accidentally submitting their surrounding form, and prevents visually hidden inputs in Checkbox, Radio, and Switch from causing overflow scroll.

Read full release notes →

v3.2.1 Copy Section

June 17, 2026

Patch release: @heroui/react no longer bundles its own copy of react-aria. The react-aria subpaths are externalized in the Rollup build, so consumers resolve to the single react-aria installed in their project instead of a vendored copy. Also fixes SwitchGroup horizontal layout.

Read full release notes →

v3.2.0 Copy Section

June 6, 2026

Calendar week and day views, a reworked year picker, and range demos on React Aria 1.18, plus tooltip delay theme variables and the patch fixes shipped with it. Breaking: Radio, Checkbox, and Switch move to an explicit *.Content composition (control nests inside *.Content; the label is plain text, no nested <Label>; help text becomes a sibling).

Read full release notes →

v3.1.0 Copy Section

May 25, 2026

Minor release: Chinese React docs and localized demos, accessible soft foreground tokens with a vibrant palette opt-in, a shared scrollbar system, fixes for useTheme, Toast, Fieldset, Link, overlays, and improved RTL support across Table, pickers, and MenuItem.

Read full release notes →

v3.0.5 Copy Section

May 15, 2026

Patch release: Text is renamed to Typography to resolve a tailwind-merge collision (⚠️ breaking change), derived color tokens are refactored into unprefixed source variables, Checkbox and Radio get aligned field-border styling, Calendar hover uses accent-soft-foreground for readability, and a new CLI docs page is added.

Read full release notes →

v3.0.4 Copy Section

May 2026

Patch release: new Text compound component ported from HeroUI Pro, docs theme selector, min()-capped border-radius tokens across 45+ component CSS files, reworked Table focus rings, and fixes for Checkbox, Autocomplete, Tooltip, and form field padding.

Read full release notes →

v3.0.3 Copy Section

April 17, 2026

Patch release: React Aria Components 1.17 (dependencies consolidation, faster installs, Table expandable rows), the useTheme hook for Vite and CRA, a DOM polymorphic render prop for lightweight components, and fixes for NumberField resets and nested Tabs styling.

Read full release notes →

v3.0.2 Copy Section

April 3, 2026

Bug fixes, smoother Drawer transitions, new --backdrop theme variable, and style refinements for triggers, arrows, and tags. Autocomplete popover width tracking fixed, overlay triggers now inline-block, and Tag gets improved spacing + accessibility.

Read full release notes →

v3.0.0 Copy Section

March 2026

A ground-up rewrite for React and React Native. 75+ web components, 37 native components, Tailwind CSS v4, React Aria, compound component architecture, CSS-first theming with OKLCH tokens, data-reduce-motion animation control, and built for AI-assisted development with MCP servers, agent skills, and LLMs.txt.

Read the full announcement →

HeroUI Pro Copy Section

Premium components, templates, and AI tooling for React and React Native. Pre-sale pricing is live.

See plans and pricing at heroui.pro →

v3.0.0-rc.1 Copy Section

March 14, 2026

Seven new components (Drawer, ToggleButton, ToggleButtonGroup, Meter, ProgressBar, ProgressCircle, Toolbar), virtualization for Table and ListBox, ButtonGroup.Separator + vertical orientation for ButtonGroup, and React Aria Components bumped to v1.16.0.

Read full release notes →

v3.0.0-beta.8 Copy Section

March 2, 2026

This release adds three new components (Badge, Pagination, Table) and new InputContainer composition APIs for DateField + TimeField. ⚠️ Breaking changes: TextField CSS classes were renamed from .text-field to .textfield.

Read full release notes →

v3.0.0-beta.7 Copy Section

February 18, 2026

This release introduces a comprehensive Date & Time system with four new components (Calendar, RangeCalendar, DatePicker, DateRangePicker), new Switch.Content sub-component, explicit Tabs.Separator for opt-in separator lines, and ⚠️ breaking changes removing hideSeparator from Tabs and consolidating DateInputGroup/ColorInputGroup under their respective field components.

Read full release notes →

v3.0.0-beta.6 Copy Section

February 6, 2026

This release introduces a comprehensive Color System with six new components (ColorPicker, ColorArea, ColorSlider, ColorField, ColorSwatch, ColorSwatchPicker), major Toast improvements with loading states and promise support, Separator variants, and ⚠️ breaking changes renaming Toast.Container to Toast.Provider and updating CSS class names to hyphenated format.

Read full release notes →

v3.0.0-beta.5 Copy Section

• Fixed build issue

v3.0.0-beta.4 Copy Section

January 20, 2026

This release introduces the new Theme Builder for visual theme customization, three new components (Autocomplete, Breadcrumbs, Toast), secondary variant for Tabs, primary/secondary variants for Input and InputGroup, and ⚠️ breaking changes removing Link's underline variants and isInSurface prop from form components.

Read full release notes →

v3.0.0-beta.3 Copy Section

December 19, 2025

This release introduces seven new components (ButtonGroup, DateField, ErrorMessage, ScrollShadow, SearchField, TagGroup, TimeField), adds fullWidth support for form and input components, introduces hideSeparator to Tabs, ButtonGroup, and Accordion for cleaner layouts, includes styling fixes, and ⚠️ breaking changes removing the asChild prop and updating AlertDialog & Modal backdrop variant.

Read full release notes →

v3.0.0-beta.2 Copy Section

November 20, 2025

This release introduces six essential new components (AlertDialog, ComboBox, Dropdown, InputGroup, Modal, NumberField), enhances theme compatibility and motion preferences, improves the Select component API with a ⚠️ breaking change, plus various refinements and bug fixes.

Read full release notes →

v3.0.0-beta.1 Copy Section

November 6, 2025

This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components have been redesigned, 8 new components added (Alert, Checkbox, InputOTP, ListBox, Select, Slider, Surface), and the design system has been completely overhauled with better color tokens, shadows, and architecture. Includes breaking changes to design system variables, component APIs, and flexible component patterns.

Read full release notes →

Previous Releases Copy Chapter

v3.0.0-alpha.35 Copy Section

October 21, 2025

React Server Components Support

• Fixed critical issue where compound components didn't work in React Server Components (RSC)
• Moved compound pattern logic from components to index files, resolving "use client" conflicts
• (⚠️ Breaking change): Main component now requires .Root suffix (e.g., <Avatar> → <Avatar.Root>)
• Named exports remain unchanged and fully supported

React 19 Improvements

• Removed forwardRef (now native in React 19)
• Simplified Context usage (Context.Provider → React 19)

Switch Component Refactoring

• (⚠️ Breaking change): Split Switch and SwitchGroup into separate components
• Cleaner API: <SwitchGroup> replaces <Switch.Group> and <Switch.GroupItems>
• Matches Radio/RadioGroup pattern for consistency
• Separate styles, types, and implementations

Affected Components

All compound components now require .Root suffix: Accordion, Avatar, Card, Disclosure, Fieldset, Kbd, Link, Popover, Radio, Switch, Tabs, Tooltip

Read full release notes →

v3.0.0-alpha.34 Copy Section

October 15, 2025

• Added Form-based components: Description, FieldError, Fieldset, Form, Input, Label, RadioGroup, TextField, and TextArea.
• Introduced form field tokens --field-*
• Reorganized Storybook by category
• (Breaking change): Renamed --skeleton-default-animation-type to --skeleton-animation in Skeleton
• Aligned data-slot markers across components
• Improved documentation

Read full release notes →

v3.0.0-alpha.33 Copy Section

October 5, 2025

• Upgraded RAC with October 2, 2025 Release
• Reordered Tabs Indicator (Breaking change)
• Updated Tabs component to use React Aria's SelectionIndicator, now supports SSR
• Updated Disclosure and Disclosure Group components to use RAC CSS variables for the expand and collapse animations
• Updated Switch component styles and animations
• Added size variants and added demo in Switch
• Added related showcases in Button, Tabs, Disclosure, Disclosure Group
• Improved documentation

Read full release notes →

v3.0.0-alpha.32 Copy Section

October 1, 2025

Card component redesigned with new variants, added CloseButton component, MCP Server for AI coding assistants, and improved documentation.

Read full release notes →

v3.0.0-alpha.31 Copy Section

September 22, 2025

• 🎨 Showcases page - Gallery of sites built with HeroUI
• 🌀 DisclosureGroup component - Groups multiple disclosures together
• 📇 Card component (preview) - First version of card component
• 🔀 Switch component (preview) - Toggle switch for settings

Release Schedule Copy Chapter

HeroUI v3 is now stable. Future releases follow a regular cycle:

• Patch releases: Bug fixes and minor improvements as needed
• Minor releases: New components and features, typically monthly
• Major releases: Architectural changes with migration guides

Contributing Copy Chapter

Found an issue or want to contribute? Check out our GitHub repository.

Apps Docs AGENTS (`apps/docs/AGENTS.md`) Copy Section

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

Apps Docs Package.Json (`apps/docs/package.json`) Copy Section

{
"name": "@heroui/docs",
"version": "0.0.0",
"private": true,
"type": "module",
"scripts": {
"predev": "node scripts/build-skills.mjs && node scripts/build-theme-presets.mjs",
"dev": "next dev",
"prebuild": "node scripts/build-skills.mjs && node scripts/build-theme-presets.mjs",
"build": "next build",
"start": "next start",
"test": "vitest run",
"lint": "eslint --max-warnings=0",
"lint:fix": "eslint --fix",
"typecheck": "tsc --noEmit",
"typegen": "next typegen",
"postinstall": "fumadocs-mdx",
"test:skills": "node test_skills_scripts.mjs",
"test:skills:dev": "node test_skills_scripts.mjs --env dev",
"test:skills:staging": "node test_skills_scripts.mjs --env staging",
"test:skills:prod": "node test_skills_scripts.mjs --env production"
},
"dependencies": {
"@fumadocs/language": "0.0.1",
"@gravity-ui/icons": "2.22.0",
"@heroui/agent": "1.0.0-beta.14",
"@heroui/react": "workspace:",
"@iconify-json/gravity-ui": "1.2.14",
"@iconify/react": "6.0.2",
"@internationalized/date": "3.12.4",
"@lglab/react-qr-code": "1.7.3",
"@react-aria/overlays": "3.32.1",
"@react-stately/data": "3.16.1",
"@t3-oss/env-nextjs": "0.13.11",
"@tailwindcss/typography": "0.5.20",
"@tanstack/react-table": "9.2.4",
"@vercel/analytics": "1.6.1",
"@vercel/og": "0.8.6",
"calligraph": "1.4.1",
"clsx": "2.1.1",
"color-convert": "3.1.3",
"color2k": "2.0.4",
"culori": "4.0.2",
"feed": "5.1.0",
"fumadocs-core": "16.9.3",
"fumadocs-mdx": "14.2.14",
"fumadocs-typescript": "5.0.1",
"fumadocs-ui": "16.9.3",
"lucide-react": "0.562.0",
"m3-ripple": "1.1.3",
"motion": "12.23.28",
"next": "16.4.2",
"next-mdx-remote": "6.0.0",
"next-themes": "0.4.6",
"nuqs": "2.10.1",
"posthog-node": "5.52.6",
"react": "19.3.0",
"react-aria-components": "1.21.1",
"react-dom": "19.3.0",
"remark": "15.0.1",
"remark-gfm": "4.0.1",
"remark-mdx": "3.1.1",
"shiki": "3.20.0",
"tailwind-merge": "3.7.0",
"tailwind-variants": "3.3.1",
"ts-morph": "27.0.2",
"usehooks-ts": "3.1.1",
"yaml": "2.9.0",
"zod": "4.6.5"
},
"devDependencies": {
"@heroui/standard": "workspace:",
"@heroui/styles": "workspace:*",
"@tailwindcss/postcss": "4.3.3",
"@types/color-convert": "2.0.4",
"@types/culori": "4.0.1",
"@types/mdx": "2.0.14",
"@types/react": "19.3.0",
"@types/react-dom": "19.3.0",
"babel-plugin-react-compiler": "1.0.0",
"postcss": "8.5.28",
"source-map-support": "0.5.21",
"tailwindcss": "4.3.3",
"tar": "7.5.22",
"typescript": "5.9.3",
"vitest": "4.1.11"
}
}

Apps Docs Tsconfig.Json (`apps/docs/tsconfig.json`) Copy Section

{
"$schema": "https://json.schemastore.org/tsconfig",
"extends": "@heroui/standard/tsconfig/next.json",
"compilerOptions": {
"jsx": "preserve",
"paths": {
"@/.source": ["./.source/server.ts"],
"@/.source/": ["./.source/"],
"@/": ["./src/"],
"~env": ["./env.ts"]
}
},
"include": ["/*.ts", "/.tsx", "env.ts", "next-env.d.ts", ".next/types/**/.ts"],
"exclude": ["node_modules"]
}

Apps Docs Public .Well Known Assetlinks.Json (`apps/docs/public/.well-known/assetlinks.json`) Copy Section

[
{
"relation": [
"delegate_permission/common.handle_all_urls",
"delegate_permission/common.get_login_creds"
],
"target": {
"namespace": "android_app",
"package_name": "com.herouinative.android",
"sha256_cert_fingerprints": [
"62:D8:E2:37:B2:F1:18:99:A5:08:6B:65:95:53:24:3F:5B:A2:A8:95:78:9E:AA:A3:D2:82:55:1F:83:74:7F:2E",
"77:AC:EE:FC:3F:03:A2:E7:5F:5F:08:B1:53:C9:F1:25:8C:31:0A:F1:D9:63:C9:DE:FE:F8:31:CE:F1:9A:37:9E"
]
}
}
]

Apps Docs Content Blog Cn Best React Ui Component Libraries (`apps/docs/content/blog/cn/best-react-ui-component-libraries.mdx`) Copy Section

title: "2026 年 12 个最佳 React UI 组件库" date: "2026-05-16" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["react", "ui-libraries", "comparison"] image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png" darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png" Copy Chapter

选择合适的 React UI 组件库，会直接影响你的开发体验。2026 年最佳的 React UI 组件库都提供了开箱即用、可访问性良好的生产级组件，让你专注于产品功能，而不是第 N 次重新实现下拉菜单。

我从样式方案、可访问性基础、组件广度、AI 工作流支持和授权许可这几个维度，对比了 12 个库。各项目的组件数量与定价随时可能变化，因此请将本文视为一份实用的速查指南，最终决策前请查阅各自的官方文档。

速览对比

1. HeroUI Copy Chapter

HeroUI 将 React Aria 的可访问性能力与 Tailwind CSS v4 样式系统、以及复合组件 API（Card.Header、Table.Column、Modal.Body）结合在一起。组件原生支持 React 19 与 Next.js App Router。

核心优势：

• 可访问性优先的架构。 每个组件都构建在 React Aria 之上 —— Adobe 经过大规模生产验证的可访问性原语。这意味着屏幕阅读器支持、键盘导航和 ARIA 属性都是开箱即用、正确实现的，而不是事后再补上的功能。
• 原生支持 Tailwind CSS v4。 HeroUI 的样式系统采用基于 CSS 的主题方案，通过 @theme 与设计 token 实现，避免了 CSS-in-JS 的运行时开销。
• 复合组件 API。 组件采用可组合的模式（Card.Header、Card.Content、Card.Footer），让你在不牺牲易用性的前提下完全掌控标签结构与布局。
• AI 工具支持。 HeroUI 提供了 MCP 服务器、llms.txt 和 agent skills，让 AI 编码助手能查到最新的 HeroUI API，而不必只依赖训练数据。
• 对服务端组件友好。 组件在设计时就考虑了 React Server Components —— 客户端边界精简且文档清晰。

适用场景： 你需要一个现代化、可访问性良好的组件库，搭配 Tailwind CSS 样式系统和一流的 AI 工具支持。非常适合使用 Next.js、React 19 与 Tailwind v4 的新项目。

2. shadcn/ui Copy Chapter

shadcn/ui 并不是传统意义上的组件库 —— 它是基于 Radix UI 与 Tailwind CSS 的一组可复制粘贴的组件。你不需要安装某个 npm 包，而是把组件源码直接加入项目。

核心优势：

• 完全的所有权。 组件代码就在你的代码库里，可以随意修改，无需对抗库的抽象，也不必等待上游变更。
• 基于 Radix UI 的可访问性。 底层原语稳定地处理了弹出层、下拉选择、对话框等复杂交互的可访问性。
• CLI 工具。 shadcn CLI 可以将组件、依赖与文件结构一键脚手架到你的项目中。
• 面向 AI 的文档。 shadcn/ui 同时发布了 llms.txt、skills 以及 MCP 服务器，供 AI 代理使用。
• 庞大的生态。 社区围绕 shadcn 的模式构建了数百个扩展、主题与集成方案。

适用场景： 你希望对组件代码拥有最大控制权，并愿意自己维护这些被复制进来的组件。适合需要大量定制化的团队。

权衡点： 你拥有代码，也就拥有了 bug。上游的修复和改进都需要手动重新合并，没有集中式的升级机制。此外，shadcn/ui 建立在 Radix UI 之上，存在一定的不确定性 —— 原 Radix 团队已将重心转向 Base UI，Radix 基础组件的长期维护状态在社区中仍是一个悬而未决的问题。

3. Material UI (MUI) Copy Chapter

Material UI 是最成熟的 React 组件库，已在生产环境中使用了十年。MUI 稳定的样式路径仍然以 Emotion 与 sx prop 为核心；Pigment CSS 则作为零运行时的实验性方向存在，并非默认选项。

核心优势：

• 组件数量庞大。 拥有超过 70 个组件，几乎覆盖了你能想到的所有 UI 模式 —— 从基础按钮到复杂的数据网格。
• 遵循 Material Design。 如果你的设计系统基于 Material Design，MUI 可以提供像素级精准的实现。
• 企业级生态。 MUI X 提供高级组件（数据网格、日期选择器、图表），并附带企业级支持与 SLA。
• 成熟且久经考验。 数以千计的生产应用运行在 MUI 之上，多年来许多边缘场景都已被发现并修复。

适用场景： 你正在构建一个大型企业级应用，需要遵循 Material Design 规范，或者需要使用 MUI X 的高级数据网格和日期选择器组件。

权衡点： Material Design 的美学风格非常鲜明。把它改造成完全不同的外观虽然可行，但需要相当大的投入。包体积也比大多数同类方案更大。

4. Chakra UI Copy Chapter

Chakra UI 在 React 中率先推广了 "style props" 模式，让你能用 bg="blue.500"、p={4} 这样的 props 来设置样式。Chakra 当前的主题文档描述了一套围绕 Panda CSS API 构建的体系，包含 defineConfig、createSystem、recipes、slot recipes、tokens 与语义化 tokens。

核心优势：

• 直观的样式 API。 Style props 让你不必离开 JSX，就能快速完成设计的原型与迭代。
• 设计 token 体系。 通过 theme 对象集中管理颜色、间距、字体和断点。
• 良好的可访问性默认值。 组件遵循 WAI-ARIA 模式并内置键盘导航支持。
• 基于 recipe 的样式方案。 Chakra 使用 recipe、slot recipe 与基于 token 的体系来组织组件样式。
• AI 支持。 Chakra 提供了用于 AI 辅助工作流的 MCP 服务器文档。

适用场景： 你更喜欢通过 props 而非 class 名来设置样式，并且希望拥有一套默认值统一的设计系统。

权衡点： 对于复杂组件，style props 模式会让 JSX 显得比较冗杂。从 v2 升级到 v3 需要较多改动，因为组件与主题 API 都发生了变化。

5. Mantine Copy Chapter

Mantine 是一个功能非常齐全的 React 组件库，组件目录非常宽广，还附带一个 hooks 包以及丰富的扩展生态。Mantine 官网当前将该库描述为提供 120+ 个组件和 70+ 个 hooks。

核心优势：

• 覆盖面无可匹敌。 Mantine 拥有大量组件和扩展，几乎涵盖各种产品需求 —— 日期选择器、通知、Spotlight 搜索、图表、表单等等。
• 庞大的 hooks 包。 除了组件之外，Mantine 还提供了 localStorage、媒体查询、剪贴板、空闲检测等大量常用模式的 hooks。
• 基于 CSS 的样式方案。 Mantine 组件基于 CSS 文件构建，可通过 Styles API 进行自定义。
• AI 工具支持。 Mantine 提供了 LLM 文档、skills 与 MCP 服务器。
• 表单库。 @mantine/form 提供了状态管理与校验的能力，可以与 Mantine 输入组件无缝集成。

适用场景： 你想要一个开箱即用、包罗万象的库，几乎任何使用场景都能找到对应组件，而无需再引入第三方包。

权衡点： 巨大的表面积意味着如果不仔细做 tree-shaking，包体积会迅速膨胀。组件设计风格虽然简洁，但相对鲜明。

6. Radix UI (Primitives) Copy Chapter

Radix UI 提供了一组无样式、可访问的 UI 基础组件，由你自行决定如何赋予样式。它是 shadcn/ui 以及许多其他组件库的底层基础。

核心优势：

• 可访问性标杆。 每个基础组件都按照 WAI-ARIA 规范构建，键盘导航、焦点管理与屏幕阅读器支持都极其完善。
• 默认无样式。 不预设任何设计立场，也就不必和库的美学风格博弈。把你自己的样式体系带上即可。
• 可组合的 API。 基础组件采用复合组件模式，通过基于 slot 的组合方式，让你对每一个被渲染的元素都有掌控权。
• 经过生产验证。 通过直接使用以及 shadcn/ui，Radix 基础组件已经支撑了数千个生产应用。

适用场景： 你需要只提供行为、不带样式的可访问基础组件，并希望对样式有完全控制权。非常适合构建定制化设计系统的团队。

权衡点： 所有样式都需要自己实现。对于较简单的使用场景，组合模式的学习曲线可能略陡。

7. Ant Design Copy Chapter

Ant Design 是由蚂蚁集团（阿里巴巴）创建的综合性设计系统与组件库，在企业级应用以及中国开发者社区中尤为流行。

核心优势：

• 企业级组件。 Table（支持排序、过滤、分页）、Form（带校验）、Tree 等复杂组件都非常成熟、功能丰富。
• 附带完整的设计系统。 Ant Design 不仅是组件库，还是一套完整的设计系统，包括设计 tokens、模式与规范指南。
• 国际化支持出色。 一流的 i18n 支持，提供 60+ 个本地化包。
• 组件质量高。 每个组件都处理了大量边缘情况，你自己实现的话需要花费大量时间。

适用场景： 你正在构建复杂的企业级应用，尤其是需要复杂数据表格、表单与树形视图的场景。

权衡点： 设计风格非常鲜明的 "Ant Design 范"，要改造成不同的外观需要相当多的工作。包体积较大。可访问性虽然在不断改进，但仍落后于基于 Radix / React Aria 的库。

8. Headless UI Copy Chapter

Headless UI 是 Tailwind Labs 团队提供的一组无样式、可访问的 UI 组件，专注于常见的交互模式 —— 下拉菜单、对话框、Tabs、组合框等。

核心优势：

• 与 Tailwind CSS 深度集成。 出自 Tailwind 团队，与 Tailwind 的工具类与过渡工具配合得天衣无缝。
• 小巧而聚焦。 仅覆盖那些真正难以做到可访问的组件（菜单、列表框、对话框等）。
• 轻量。 由于聚焦的组件集合，对包体积的影响极小。
• 简洁的 API。 使用 render props 和复合组件，API 简单且可预测。

适用场景： 你正在使用 Tailwind CSS，需要少量可访问的交互组件，但不想引入一整套 UI 库。

权衡点： 组件集合非常小 —— 数据表格、表单输入、日期选择器等大多数模式都需要另寻他解。

9. React Aria (Primitives) Copy Chapter

React Aria 是 Adobe 出品的 React 可访问性原语库。它提供 hooks 与组件，帮助你从零构建可访问的 UI。

核心优势：

• 业界领先的可访问性。 React Aria 可以说是目前可用的最完善的可访问性原语库。它处理了国际化、从右到左布局、触摸交互，以及大多数库都会忽略的边缘情况。
• Hooks + 组件。 同时提供低层 hooks（最大灵活性）与高层组件（更便捷）。
• 平台感知。 根据设备类型、指针类型与平台惯例自动调整行为。
• 众多库的底层基础。 HeroUI、Adobe Spectrum 以及其他库都建立在 React Aria 之上，证明了它在大规模场景下的可靠性。

适用场景： 你正在从零构建设计系统，需要尽可能强大的可访问性基础。当你需要特定基础组件（例如颜色选择器或日历）而其他库无法提供时，它也很有用。

权衡点： 比带样式的库学习曲线更陡。你需要自行实现所有样式与组合模式。

10. Ark UI Copy Chapter

Ark UI 出自 Chakra UI 的作者团队，是一个 headless 组件库，底层基于状态机，行为高度可预测。

核心优势：

• 状态机架构。 底层使用 Zag.js 状态机，组件行为可预测、易于调试。
• 框架无关的内核。 同一套状态机驱动每个组件的 React、Vue 与 Solid 版本。
• 现代模式。 提供了签名板、Pin 输入框、分栏器等其他 headless 库中较少见的组件。
• 样式方案灵活。 可搭配任何样式方案 —— Tailwind、Panda CSS、原生 CSS、CSS Modules 都行。

适用场景： 你想要带可预测状态管理的 headless 组件，或者需要在 React、Vue 与 Solid 项目之间复用组件逻辑。

权衡点： 社区规模小于 Radix 或 React Aria。状态机抽象在简单组件上会带来额外的概念负担。

11. Tremor Copy Chapter

Tremor 专注于仪表盘与数据可视化。其当前文档显示 Tremor Raw 面向 React 18.2+ 与 Tailwind CSS 4.0+ 设计。

核心优势：

• 以仪表盘为中心。 针对数据分析、仪表盘 UI 与数据展示提供专门的资源。
• Tailwind 原生。 无需额外样式配置，即可与现有 Tailwind 项目无缝集成。
• 简洁的默认样式。 图表与指标卡开箱即用，外观精致、设计语言统一。
• 聚焦的范围。 只关注数据展示，可以按需取用，而不必引入整套 UI 框架。

适用场景： 你正在构建数据分析仪表盘或数据密集型界面，并已经在使用 Tailwind CSS。

权衡点： 仅限于仪表盘相关组件。对于表单、导航、对话框等通用 UI 模式，你需要另寻他库。

12. Park UI Copy Chapter

Park UI 是构建在 Ark UI 基础组件之上的带样式组件库，提供 Panda CSS 与 Tailwind CSS 两种版本。

核心优势：

• 预先样式化的 Ark UI。 在 Ark UI 的 headless 组件基础上叠加了精致、可定制的样式 —— 类似 shadcn/ui 对 Radix 的做法。
• 支持双样式方案。 提供 Panda CSS 与 Tailwind CSS 两种变体，按项目情况选择即可。
• 复制粘贴模式。 与 shadcn/ui 一样，组件以源码形式加入你的项目，你拥有它们并可自由定制。
• 设计 tokens。 自带 token 体系，可以方便地进行全局样式调整。

适用场景： 你喜欢 shadcn/ui 的复制粘贴模式，但更倾向于使用基于状态机的 Ark UI 而非 Radix，或者你正在使用 Panda CSS。

权衡点： 相比 shadcn/ui，社区与生态规模更小，第三方扩展和主题也较少。

如何选择 Copy Chapter

并不存在一个绝对"最好"的库 —— 正确的选择取决于你项目的约束条件：

• 使用 Tailwind v4 开始新项目？ HeroUI 提供了最现代的技术栈：React Aria 可访问性、复合组件以及 AI 工具支持。
• 想完全拥有组件代码？ shadcn/ui 或 Park UI 让你直接把组件复制进项目。
• 构建有复杂数据需求的企业级应用？ MUI 的数据网格或 Ant Design 的表格组件难以被超越。
• 需要最强的可访问性合规？ HeroUI 基于 React Aria 的底层提供了开箱即用的最强可访问性。
• 希望拥有一套高质量的通用 UI 工具箱？ HeroUI 覆盖了所有核心 UI 模式并具备深度的可访问性；对于富文本编辑器等特定需求，可以搭配专门的库一起使用。
• 跨多个框架工作？ Ark UI 的状态机可以同时在 React、Vue 与 Solid 中使用。

开始使用 HeroUI Copy Chapter

如果你正在启动一个新的 React 项目，希望使用可访问性良好、设计精美、基于 Tailwind CSS v4 的组件，那么不妨试试 HeroUI：

• 快速开始指南
• 组件文档
• GitHub 仓库
• Discord 社区

Apps Docs Content Blog Cn Styling And Theming In Heroui Native (`apps/docs/content/blog/cn/styling-and-theming-in-heroui-native.mdx`) Copy Section

title: "HeroUI Native 的样式与主题机制" date: "2026-07-31" author: "Volodymyr Serbulenko" authorHandle: "@v_serbulenko" authorUrl: "https://x.com/v_serbulenko" authorAvatar: "https://avatars.githubusercontent.com/u/115154506?v=4" tags: ["native", "react-native", "styling", "theming", "css", "design-system"] image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-native-styling.jpg" Copy Chapter

大多数 React Native 组件库都在 JavaScript 中定义外观。组件的样式可能写在 StyleSheet.create 调用中、styled-components 模板里，或是通过 React context 层层传递的主题对象中。这些方式都能奏效，但有两件事做起来并不顺手：在不 fork 组件库的情况下覆盖其内部样式，以及将一套截然不同的视觉主题打包成可安装的资源。

HeroUI Native 选择了另一条路。组件外观定义在随包发布的真正的 .css 文件中，而主题机制则从头到尾都基于 CSS 变量。本文将介绍这一选择背后的原则，以及它们如何实现一种不常见的能力：将完整的视觉风格 —— 甚至包括并非由你编写的组件内部细节 —— 打包成一份可安装的样式表。

React Native 组件库中的 CSS Copy Chapter

HeroUI Native 基于 Uniwind 构建，后者将 Tailwind CSS v4 带到了 React Native。Uniwind 接入 Metro 打包工具，读取 CSS 入口文件，并解析 React Native 视图上的 className。样式表不会在设备运行时解析 —— CSS 在应用打包时就已处理完毕。

这带来了真正的 CSS 编写能力。安装组件库只需安装依赖包，再在 CSS 入口文件中添加一条导入语句：

/* global.css */
@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

@source "./node_modules/heroui-native/lib";

这一条导入语句就会引入整个样式系统：设计 tokens、浅色和深色主题、自定义工具类，以及所有组件的 CSS。此后，className 就是主要的样式 API：

import {View, Text} from "react-native";

<View className="bg-background flex-1 px-4">
  <Text className="text-foreground text-lg">Your app content</Text>
</View>;

关键不只是 Tailwind 类名能在 React Native 中使用，而是组件库自身的样式也用同样的 CSS 编写，存放在你可以阅读和覆盖的文件里，而非编译成只能通过 props 访问的 JavaScript 对象。

三层设计 tokens Copy Chapter

主题系统分为三层，将它们分开是降低自定义成本的关键。

第一层是基础值。 这些值不会随主题变化：固定颜色、基础边框宽度、基础圆角，以及禁用状态的不透明度。

@theme {
  --white: oklch(100% 0 0);
  --radius: 0.5rem;
  --border-width: 1px;
  --opacity-disabled: 0.5;
}

第二层是各主题的语义变量。 这些变量描述的是用途，而非具体数值 —— 背景、表面、强调色、危险状态等，每个主题都会重新定义它们：

@layer theme {
  :root {
    @variant light {
      --background: oklch(0.9702 0 0);
      --surface: var(--white);
      --accent: oklch(0.6204 0.195 253.83);
    }

    @variant dark {
      --background: oklch(12% 0.005 285.823);
      --surface: oklch(0.2103 0.0059 285.89);
      --accent: oklch(0.6204 0.195 253.83);
    }
  }
}

第三层是派生层。 这一层最能体现系统的价值。语义变量会映射到 Tailwind 的颜色命名空间，让 bg-accent 这样的工具类能够生效；与此同时，每种颜色的各种状态也会据此计算出来：

@theme inline static {
  --color-accent: var(--accent);
  --color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
  --color-accent-soft: color-mix(in oklab, var(--accent) 15%, transparent);
  --color-accent-soft-hover: color-mix(in oklab, var(--accent) 20%, transparent);
}

原则很简单：只需定义一次颜色，就能自动获得它的整套衍生配色。 在应用中覆盖 --accent，按下状态、柔和背景、柔和前景以及柔和配色的按下状态都会随之变化。组件库无需预先知道你的品牌色。

同样的思路也适用于形状尺寸。圆角尺寸体系由一个基础值派生而来，因此修改一个变量，就能按比例调整整个系统中的所有圆角：

--radius-lg: calc(var(--radius) * 1);
--radius-xl: calc(var(--radius) * 1.5);
--radius-3xl: calc(var(--radius) * 3);

使用 OKLCH 定义颜色、使用 OKLab 混合颜色，是有意为之。基于感知的色彩空间能让派生出的悬停状态保持一致的视觉效果，无论基础色是浅黄色还是高饱和度的蓝色。当基础色由你从未见过的用户提供时，这正是所需的特性。

前景色配对规则 Copy Chapter

一个命名约定就能解决很多问题。不带后缀的变量表示背景色；同名变量加上 -foreground 后缀，则表示应当显示在该背景之上的前景色。

例如 --accent 与 --accent-foreground、--surface 与 --surface-foreground、--danger 与 --danger-foreground。

这样，对比度就成了每个主题在设计时只需做一次的决定，无需在每个组件中反复判断。编写自定义主题时，只要提供每组配对的两个值，所有使用该语义角色的组件就会自动获得清晰可读的文本。

组件样式写在 CSS 中 Copy Chapter

每个组件都有一份样式表，其中的类名描述了组件的结构与变体：

.button__root--variant-primary {
  background-color: var(--color-accent);
}

.button__root--size-sm {
  height: calc(var(--spacing) * 10);
  padding-inline: calc(var(--spacing) * 3.5);
  border-radius: var(--radius-3xl);
}

TypeScript 不负责生成这些样式，而是使用 tailwind-variants 选择要应用的样式：

const root = tv({
  base: "button__root",
  variants: {
    variant: {
      primary: "button__root--variant-primary",
      secondary: "button__root--variant-secondary",
    },
    size: {
      sm: "button__root--size-sm",
      md: "button__root--size-md",
    },
  },
});

因此，CSS 是外观的唯一依据，TypeScript 则负责将 props 映射到相应的样式。这带来了两个结果。

首先，重新设计样式可以直接从已有规则入手，无需不断叠加额外的样式机制。组件自身的类就是普通 CSS，调整某个变体只需为它编写 CSS —— 不必与内联样式对象对抗，也不必等待组件库新增某个 prop。

其次，变体映射是公开的。每个组件都会导出自己的 classNames 对象，因此你可以构建与组件库外观完全一致的基础组件：

import {buttonClassNames, cn} from "heroui-native";
import {Pressable, Text} from "react-native";

<Pressable className={cn(buttonClassNames.root({variant: "primary", size: "md"}))}>
  <Text className={buttonClassNames.label({variant: "primary", size: "md"})}>Continue</Text>
</Pressable>;

自定义链接、可按压的自定义列表行、第三方控件的封装 —— 都能直接采用完全相同的按钮样式，无需从组件库中复制具体的样式值。

并非所有样式都适合放在 CSS 中，组件库也没有强行这么做。React Native 有些属性没有对应的 CSS 写法，还有一些样式由 Reanimated 驱动。这些样式仍保留在 StyleSheet 和组件的动画层中，且优先级高于 className。这是刻意安排的顺序，确保动画和平台特有的行为不会被某个工具类悄然覆盖。

一个主题就是一个 `@variant` 块 Copy Chapter

浅色模式和深色模式并没有特殊待遇。它们各自都是一个重新定义语义变量的 @variant 块，你也可以按需添加任意数量的主题。在 Metro 配置中向 Uniwind 注册它们即可：

module.exports = withUniwindConfig(config, {
  cssEntryFile: "./global.css",
  dtsFile: "./src/uniwind.d.ts",
  extraThemes: ["ocean-light", "ocean-dark"],
});

切换主题只需一次调用：

import {Uniwind} from "uniwind";

Uniwind.setTheme("ocean-dark");

这个过程不经过 React 主题 Provider。变量由 Uniwind 解析，因此主题变化不会触发贯穿整棵组件树的 context 更新。虽然有 HeroUINativeProvider，但它负责的是安全区域边距、文本默认设置、Toast 挂载容器以及 RTL 布局 —— 它是应用的基础设施，并非主题引擎。

Pro 主题的实现模式 Copy Chapter

由于 tokens 是变量，组件样式是 CSS 类，一套完整的视觉风格就能打包成一份样式表。HeroUI Native Pro 正是这样提供主题的，整个过程分为两步。Brutalism（粗野主义）主题与默认外观差异极大，能清楚地展示这两个步骤。

第一步，重新调整 tokens。 Brutalism 的整个变量文件只有大约十五行：

@layer theme {
  :root {
    @variant light {
      --accent: var(--foreground);
      --accent-foreground: var(--background);

      --radius: 0px;
      --field-radius: 0px;

      --field-border-width: 1px;
      --field-border: var(--border);

      --surface-shadow: 0 0 0 0 transparent;
      --field-shadow: 0 0 0 0 transparent;
    }
  }
}

这就完成了颜色和形状尺寸的全部调整。由于圆角尺寸是派生的，--radius: 0px 能一次性将整个组件库的圆角变成直角。表单字段读取各自的 tokens，因此一行就能为所有输入框加上细边框，再通过阴影变量移除柔和的悬浮层次感。--accent: var(--foreground) 也值得仔细看一下 —— 主题的强调色相对于当前调色板采用单色设计，而非硬编码某个颜色，因此仍能适应底层的浅色、深色或自定义调色板。

第二步，调整组件内部样式。 有些风格特征无法用 token 表达。Brutalism 希望标签使用大写的展示字体，并为特定按钮变体添加细边框。由于组件样式就是普通的 CSS 类，主题只需为它们编写规则：

.button__label {
  font-family: var(--brutalism-font-display);
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

.button__root--variant-secondary,
.button__root--variant-tertiary,
.button__root--variant-outline {
  border-width: 1px;
  border-color: var(--color-border);
}

这就是该主题对按钮的全部样式覆盖。Switch 只需两行，Widget 只需三行。整个主题由大约三十个这样的小文件组成，同时覆盖基础组件与 Pro 组件，只需在基础样式之后添加一条导入语句即可引入：

@import "heroui-native/styles";
@import "heroui-native-pro/styles";
@import "heroui-native-pro/themes/brutalism";

这种模式的价值在于：主题能够改变并非由它定义的组件内部元素的样式 —— 按钮中的标签、开关中的滑块、Widget 图例中的圆点 —— 无需额外的 prop、主题对象字段，也无需 fork。在样式写在 JavaScript 中的组件库里，要像这样修改组件内部文本的样式，前提是组件库预先考虑到了这个需求，并为该元素提供了专门的自定义接口。而在这里，整棵组件树默认都可以被定位，因为样式使用 CSS 编写，类名也稳定地反映了组件结构。

主题还可以引入自己的变量。上面的 --brutalism-font-display 由主题自行定义，再由应用赋值。对于主题无法自行提供的资源，就可以通过这种方式交给应用配置：

@layer theme {
  :root {
    @variant light {
      --brutalism-font-display: "Anton-Regular";
    }
  }
}

这些操作不依赖任何特权。Pro 主题所做的事，你自己的 global.css 完全可以做到：调整一些变量，再覆盖需要修改的类。区别只在于打包方式，而非能力。

这套机制带来的价值 Copy Chapter

将这些原则结合起来，可以得到以下好处：

• 自定义不妨碍升级。 通过覆盖 tokens 和编写 CSS 来调整外观，无需 fork 组件内部实现，因此可以继续接收组件库更新。
• 一处修改，全局生效。 一个强调色或基础圆角的变化，会传递到系统中所有相关的派生状态和尺寸。
• 主题机制独立于 React。 主题定义在 CSS 中，通过 Uniwind 切换，不会触发贯穿组件树的 context 更新。
• 主题可以独立发布。 完整的视觉风格就是一份样式表，可以像其他依赖一样发布、管理版本和安装。
• 与 HeroUI 的其他部分保持相同概念。 语义角色、前景色配对、复合组件，都与你在 Web 端使用的理念一致。
• AI 智能体也能读懂。 用 CSS 变量表达设计 tokens、用 CSS 类表达组件样式，都是 AI 助手擅长处理的格式，因此 MCP 服务器 和 llms.txt 端点能够准确描述这套样式系统。

下一步 Copy Chapter

先阅读快速开始，完成 Uniwind 和样式表的配置；再阅读样式，了解 className 与样式优先级规则；通过主题查阅完整的变量参考和自定义主题指南。如果你打算编写自己的主题，颜色文档提供了完整的语义调色板。

Apps Docs Content Blog Cn Why Choose Heroui For Your Design System (`apps/docs/content/blog/cn/why-choose-heroui-for-your-design-system.mdx`) Copy Section

title: "为什么选择 HeroUI 作为你的设计系统" date: "2026-05-17" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["heroui", "design-system", "react", "ui-libraries"] image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og_2x.jpg" darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-og-black_2x.jpg" Copy Chapter

大多数 React 组件库都在解决同一个问题：不再重复造按钮。但设计系统往往会在另一个阶段出问题 —— 当你选用的库无法灵活贴合产品需求时；当可访问性是发布之后才匆忙补上的考量时；又或者当你的 AI 编码助手凭空臆造出根本不存在的 props 时。

HeroUI 将 React Aria 的可访问性、Tailwind CSS v4 的样式系统，以及一套复合组件 API 结合到一起 —— 让你拥有结构上的掌控权，又不必让 props 数量失控。本文将给出选择它作为设计系统基础的具体理由。

技术栈 Copy Chapter

真正达到企业级标准的可访问性 Copy Chapter

每个 HeroUI 组件都构建在 React Aria 之上 —— Adobe 的可访问性原语库。这不是营销话术：React 生态中没有比它更深入的可访问性基础，它甚至支撑着 Adobe 自己的生产级设计系统（Spectrum），覆盖 Photoshop Web、Acrobat 和 Lightroom 等产品。

React Aria 处理了大多数库都未顾及的部分：

• 感知平台的键盘导航。 Mac、Windows 与 Linux 在 Home/End、option/alt+方向键和焦点行为上有着不同的惯例。React Aria 会自动适配。
• 屏幕阅读器的播报。 实时区域、状态消息以及动态内容播报，在 JAWS、NVDA 和 VoiceOver 上都能正确工作。
• 触摸交互。 移动端的长按、拖放与手势处理 —— 不仅仅是点击事件。
• 国际化。 从右到左布局、按区域格式化日期/数字，以及对 30+ 种语言的字符串排序支持。
• 虚拟焦点。 对于包含成千上万项的集合，React Aria 在保持性能的同时仍能正确通知屏幕阅读器。

这些都很重要，因为在 2026 年，可访问性合规已经不再是可选项。政府、医疗、金融与教育行业都要求符合 WCAG。HeroUI 把这种合规作为默认能力提供，而不是需要额外升级才能获得的特性。

React Aria 与 Radix UI 的对比 Copy Section

许多流行的库（如 shadcn/ui、Park UI）都构建在 Radix UI 之上。Radix 本身很扎实，但原团队已将重心转向 Base UI，Radix 基础组件的长期维护仍是未定之数。React Aria 则由 Adobe 持续维护 —— 一家自身产品就严重依赖它的公司。

原生支持 Tailwind CSS v4 Copy Chapter

HeroUI 不是把 Tailwind 当作兼容层 —— 它从一开始就是为 Tailwind CSS v4 设计的。

这意味着：

• 零运行时 CSS 开销。 所有样式都是静态 CSS，在构建时就被解析完毕。没有 CSS-in-JS 的运行时计算，没有样式注入，也没有水合(hydration)成本。
• 通过 CSS 自定义属性定义设计 tokens。 主题以标准 CSS @theme 指令的形式存在，而不是 JavaScript 配置对象。改一个 token，所有组件随之更新。
• 基于工具类的自定义。 用 className 覆盖任意组件 —— 与你在项目其他地方使用 Tailwind 的方式完全一致。
• 更小的输出体积。 Tailwind v4 的新引擎生成的 CSS 更少，再加上 HeroUI 的模块化导入，能让你的生产环境包保持精简。

<Button variant="secondary" className="font-semibold tracking-wide">
  Get Started
</Button>

<Card className="max-w-md shadow-lg">
  <Card.Header className="pb-0">
    <Card.Title className="text-xl font-bold">Dashboard</Card.Title>
  </Card.Header>
  <Card.Content className="py-4">
    Your metrics here
  </Card.Content>
</Card>

如果你的团队已经在用 Tailwind，引入 HeroUI 不会带来第二套样式系统。如果你还没用 Tailwind，是否采用它是另一个独立的决定 —— 但这是 2026 年大多数 React 团队都已经做出的选择。

复合组件 API Copy Chapter

HeroUI 采用复合组件 —— 父组件通过点号语法暴露其子组件的模式。这与 Radix UI 的做法相同，并且在复杂 UI 上比基于 props 的 API 扩展性更好。

<Modal>
  <Button>Open</Button>
  <Modal.Backdrop>
    <Modal.Container>
      <Modal.Dialog>
        <Modal.Header>
          <Modal.Heading>Confirm</Modal.Heading>
        </Modal.Header>
        <Modal.Body>Are you sure?</Modal.Body>
        <Modal.Footer>
          <Button variant="ghost">Cancel</Button>
          <Button>Confirm</Button>
        </Modal.Footer>
      </Modal.Dialog>
    </Modal.Container>
  </Modal.Backdrop>
</Modal>

这种模式对设计系统的意义：

• 结构可控。 可以在组件的各个部分之间重新排列、省略或插入自定义元素，而不必与库的内部布局对抗。
• 细粒度的样式。 可以为任意子组件单独应用 className，让 Card.Header 与 Card.Footer 拥有不同样式，无需 CSS 覆盖。
• TypeScript 校验。 编译器会检查你的组件树结构 —— 错误嵌套在构建时就会被发现，而不是带到生产环境。
• JSX 可读性强。 组件的层级结构直接映射到 UI 的视觉层级。新成员阅读代码即可理解布局。

+ 个组件 Copy Chapter

HeroUI 提供 + 个组件，以及 + 个有文档的示例。库覆盖了产品 UI 的完整面：

• 数据输入 —— Input、Textarea、NumberField、Select、ComboBox、Autocomplete、DatePicker、DateRangePicker、ColorPicker、Slider、Switch、Checkbox、Radio
• 数据展示 —— Table（排序、选择、分页）、Avatar、Badge、Chip、Tag、Skeleton
• 布局 —— Card、Surface、Separator、Fieldset
• 导航 —— Tabs、Breadcrumbs、Pagination、Link
• 反馈 —— Toast、ProgressBar、ProgressCircle、Meter、Spinner
• 覆盖层 —— Modal、Drawer、Popover、Tooltip、Dropdown、AlertDialog
• 展开/折叠 —— Accordion、Disclosure
• 动作类 —— Button、ToggleButton、ToggleButtonGroup

像 Calendar、DatePicker、ColorPicker 和 Table 这样的复杂组件都是自包含的 —— 它们在内部处理日期运算、本地化格式、键盘导航以及屏幕阅读器播报。这些组件想做到真正可访问其实非常困难，而 HeroUI 把它们作为持续维护、经过测试的原语提供出来。

面向 AI 的原生工具 Copy Chapter

如今，绝大多数开发者每天都在使用 AI 编码助手。生成代码的质量取决于 AI 是否拥有你所用组件库的准确上下文 —— 否则就只能凭借陈旧的训练数据猜测。

HeroUI 提供了四项官方集成：

MCP 服务器 Copy Section

一个 Model Context Protocol 服务器，AI 代理可以通过它查询组件文档、API、源码与设计 tokens。可接入 Cursor、Claude Code、Windsurf，或任何兼容 MCP 的编辑器。

当 AI 助手能够访问 MCP 服务器时，它可以查到任意 HeroUI 组件的复合组件结构、可用 props 以及正确的 import —— 不再需要凭空臆造。

了解如何配置 MCP 服务器 →

llms.txt Copy Section

一个结构化参考文件，位于 heroui.com/llms.txt，为 LLM 提供整个库的精炼且准确的参考。这是一个标准化格式，AI 工具会读取它来避免生成已废弃的写法。

进一步了解 llms.txt →

Agent Skills Copy Section

为 Cursor、Claude Code 等 AI 工具预构建的 skill 文件，帮助 AI 代理掌握 HeroUI 的约定 —— 包括正确的 import、复合组件模式、样式方案以及项目脚手架。

了解如何安装 Agent Skills →

AGENTS.md Copy Section

一份 AGENTS.md 文件，为 AI 编码代理提供仓库级上下文。它描述了项目结构、编码约定与组件模式，让代理从第一次 prompt 起就理解你的代码库。

了解 AGENTS.md →

一旦 AI 编码助手成为生产工作流的一部分，也值得评估专用推理容量。像 Morph 这样的提供商，会为高并发代码生成、搜索与 apply 工作负载的团队提供预留容量，让 agent 功能在用量增长时仍能保持快速、可靠。

结果是： AI 助手能够生成正确的 HeroUI v3 代码，使用正确的复合组件模式、import 路径与 Tailwind 类名。这一点至关重要，因为错误的 AI 输出在调试上耗费的时间，远多于它生成代码本身节省的时间。

生态系统 Copy Chapter

HeroUI Pro Copy Section

HeroUI Pro 在基础库之上扩展了应用级组件与模板：

• AppLayout、Sidebar、Navbar —— 包含响应式行为的完整应用外壳
• DataGrid —— 支持类型化列、排序与过滤的高密度数据表格
• KPI、NumberValue、TrendChip —— 仪表盘指标组件
• LineChart、BarChart —— 数据可视化
• Sheet、CommandMenu —— 高级覆盖层模式
• 模板 —— 仪表盘、财务、聊天与邮件应用等起点模板

Pro 是付费产品 —— 当你需要的不仅是 UI 组件，更是应用级基础设施时再使用。

HeroUI Native Copy Section

HeroUI 是目前唯一在 Web 与移动端上都能提供同等组件质量的开源设计系统。HeroUI Native 把同一套设计 tokens、复合组件 API 以及可访问性标准带到 React Native —— 利用各平台的原生 API，而非简单地包装 WebView。

这意味着构建跨平台产品的团队可以在 React（Web）和 React Native（移动端）之间共享同一套设计系统，无需对任何一端妥协。统一的视觉语言、统一的组件模式、统一的主题 tokens —— 但在各端都使用原生渲染。

目前没有其他开源 React 组件库能够做到这一点。MUI、shadcn/ui、Chakra UI 与 Mantine 都仅限于 Web。如果你的产品需要同时支撑 Web 与移动端，HeroUI 是唯一一套能从同一基础覆盖两端的设计系统。

Figma Kit Copy Section

HeroUI Figma Kit (v3) 让设计与代码保持同步。Figma 中的组件与 React 实现一一对应，设计师与开发者基于同一份真实来源进行工作。

Storybook Copy Section

每个组件都有对应的 Storybook stories，展示所有变体、状态与组合方式。可用于可视化测试、设计评审与文档。

社区 Copy Section

HeroUI 并非新生事物 —— 我们已经构建了 5 年多，最早从 v1（最初的 NextUI）开始。社区规模稳步增长：GitHub 上有 29.3K+ stars，Discord 上有 9K+ 成员，每周还有数以千计的讨论、社区回答与 issue 被解决。

• GitHub —— 源码、issue 与讨论
• Discord —— 9K+ 成员，社区支持与公告
• X / Twitter —— 更新与版本发布

获得 Y Combinator 投资 Copy Section

HeroUI 获得了风险投资，包括 Y Combinator。这意味着我们有专职的全职团队、长期的维护承诺，以及持续交付所需的资源。在选用一个组件库时，你其实是在押注它的未来 —— HeroUI 的目标是长期存在。

开箱即用的设计品质 Copy Chapter

HeroUI 提供经过精心打磨的默认样式，不做任何主题定制看起来也很精致：

• 流畅的动画。 按钮带有细腻的按下反馈，弹窗以弹簧物理动效呈现，手风琴展开时使用自然的缓动曲线。
• 均衡的间距 tokens。 所有组件遵循统一的数学比例，padding、margin 与 gap 都保持一致。
• 阴影层级。 浅色与深色模式下都能良好工作的高度层级，无需手动调整。
• 主题变体。 内置 glass、brutalism 以及中性等多种视觉风格，通过设计 tokens 即可切换。

设计 token 体系基于 CSS 自定义属性，主题就是标准 CSS：

@theme {
  --color-primary: oklch(0.6 0.25 260);
  --radius-field: 0.5rem;
  --shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
}

修改 tokens，所有组件都会随之全局更新。不需要 JavaScript 主题对象，不需要 provider 包装，也没有运行时开销。

想要几次点击就把 HeroUI 变成你自己的样子？主题构建器允许你以可视化的方式自定义颜色、字体、圆角与间距 —— 然后导出一份可直接用于项目的 CSS 主题。

两步即可就绪 Copy Chapter

大多数组件库在渲染第一个组件之前，都需要配置文件、provider 包装、主题对象与插件设置。HeroUI 不需要。整个安装过程只有两步：

1. 安装：

npm i @heroui/styles @heroui/react

2. 在你的 CSS 中加一行：

@import "tailwindcss";
@import "@heroui/styles"; /* 就这些 */

接下来即可使用任意组件 —— 不需要 ThemeProvider、不需要 ChakraProvider、不需要 MantineProvider，也不需要任何配置对象：

import { Button, Card } from "@heroui/react";

export default function Page() {
  return (
    <Card>
      <Card.Content>
        <Button>Click me</Button>
      </Card.Content>
    </Card>
  );
}

整个配置就是这些。不需要用 provider 包裹整个应用，不需要主题配置文件，也不需要任何运行时初始化。安装、引入一行 CSS，然后就可以开始构建。查看快速开始指南，五分钟内即可上手。

服务端组件 Copy Chapter

HeroUI 的设计契合 React Server Components 的模型：

• 静态组件（Card、Badge、Text、Separator、Avatar）可以留在服务端组件树中，不带任何客户端 JavaScript。
• 交互式组件（Button、Modal、Table、Select）使用客户端边界 —— 每个组件都有清晰的文档说明。
• 不强制使用 provider —— 没有迫使整个组件树进入客户端边界的客户端 context。

这意味着你的页面默认会输出更少的 JavaScript。静态布局在服务端渲染，交互式部件仅在需要的位置进行水合(hydration)。

一些权衡 Copy Chapter

HeroUI 采用聚焦的策略：与其交付所有可能的组件，我们更优先保证团队最常使用组件的深度、可访问性与品质。对于富文本编辑、拖放或图表等专门需求，我们建议将 HeroUI 与擅长这些特定问题的专业库搭配使用 —— 这比依赖单一库覆盖所有场景效果更好。

HeroUI 是为 Tailwind CSS v4 构建的。如果你的团队已经在使用 Tailwind，引入它非常顺畅。如果你使用的是其他样式方案，迁移到 Tailwind 是一个独立但值得的投入 —— 那是面向现代 CSS 工具链的一笔投资。

谁适合使用 HeroUI Copy Chapter

如果你正在构建以下产品，HeroUI 会是个不错的选择：

• SaaS 应用 —— 表单、表格、覆盖层与导航，并具备 React Aria 的可访问性
• 仪表盘与管理后台 —— 借助 HeroUI Pro 组件构建的高密度数据布局
• 电商门店 —— 高性能、可访问、对 SEO 友好的组件渲染
• 营销官网与落地页 —— 精致的默认样式，没有运行时 CSS 开销
• 跨平台产品 —— 借助 HeroUI Native，在 Web（React）与移动端（React Native）上共享同一套设计系统
• 任何重视可访问性、Tailwind CSS 集成与 AI 辅助开发的 React / Next.js 项目

开始使用 Copy Chapter

npm install @heroui/styles @heroui/react

• 快速开始指南 —— 五分钟内即可完成配置
• 组件文档 —— 完整的 API 参考与在线示例
• 主题指南 —— 自定义设计系统
• MCP 服务器 —— 接入你的 AI 编码助手
• GitHub 仓库 —— 源码与 issue

Apps Docs Content Blog En Best React Dashboards (`apps/docs/content/blog/en/best-react-dashboards.mdx`) Copy Section

title: "14 Dashboard Templates and Frameworks for React Teams in 2026" date: "2026-05-10" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["react", "dashboards", "templates"] image: "/images/blog/best-react-dashboards.jpg" draft: true Copy Chapter

Building a React dashboard from scratch takes weeks — picking the right template, framework, or component stack can cut that down dramatically. The strongest options give you responsive layouts, data visualization patterns, accessible navigation, and a theme system you can actually maintain.

I pulled together 14 options worth checking in 2026. Pricing and feature gates change often, so use this as a shortlist and verify the current license before you buy or build on top of anything.

Quick Comparison Copy Chapter

1. HeroUI Pro Dashboard Template Copy Chapter

HeroUI Pro offers pre-built dashboard templates designed specifically for SaaS products, admin panels, and analytics dashboards. Built on HeroUI v3 components with Tailwind CSS v4.

What you get:

• Complete dashboard layouts with sidebar navigation, header, and content areas
• Analytics pages with charts, metrics cards, and data tables
• Settings, analytics, orders, tracker, help, finance, chat, and email-style app surfaces across the current templates
• App shell patterns using AppLayout, Sidebar, and Navbar
• Pro dashboard widgets using KPI, DataGrid, LineChart, NumberValue, and TrendChip
• Dark mode support with HeroUI's theming system
• Responsive design that works on mobile and desktop

Key strengths:

• Production-quality components. Every component is built on React Aria with full accessibility support and keyboard navigation.
• Tailwind CSS v4. Modern styling with CSS-based theming, no runtime overhead.
• Next.js App Router ready. Templates are built for the latest Next.js with server components and streaming.
• AI tooling. Use HeroUI's MCP server with Cursor or other AI tools to extend and customize dashboards with AI assistance.

Pricing: Premium license through HeroUI Pro; check the current pricing page for details.

Best for: Teams building SaaS products who want accessible, modern dashboard components they can customize with Tailwind CSS.

2. Tremor Copy Chapter

Tremor is focused on dashboard UI. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.

What you get:

• Dashboard-oriented UI resources
• Tremor Blocks for copy-paste dashboard sections
• Figma UI Kit for dashboard design work
• Tailwind CSS v4 setup guides

Key strengths:

• Dashboard-first design. The project is centered on analytics and dashboard interfaces.
• Tailwind native. Current docs target Tailwind CSS v4.
• Useful design resources. The docs link to Tremor Blocks and a Figma UI Kit.

Trade-offs: Limited to dashboard-specific components. You'll need another library for forms, navigation, and other general UI patterns.

Pricing: Check Tremor's current site and repository before choosing it for a commercial project.

Best for: Teams that already have a UI library and need dashboard-specific visualization components to complement it.

3. Refine Copy Chapter

Refine is a meta-framework for building data-intensive applications — admin panels, dashboards, and internal tools. It's not a template; it's a framework that generates CRUD interfaces from your data model.

What you get:

• Automatic CRUD operations from data provider configuration
• Authentication and authorization hooks
• Routing integration (Next.js, Remix, React Router)
• Connectors for REST, GraphQL, Supabase, Strapi, Appwrite, and more
• UI framework adapters for Ant Design, MUI, Mantine, and Chakra UI

Key strengths:

• Data-first architecture. Define your data providers and Refine generates the boilerplate — list pages, create/edit forms, show views, and filters.
• Framework-agnostic UI. Swap between Ant Design, MUI, Mantine, or Chakra UI without changing your business logic.
• Headless mode. Use your own components if none of the bundled UI adapters fit.
• Active community. Regular releases, good documentation, and a responsive maintainer team.

Trade-offs: The abstraction adds complexity for simple dashboards. If your data layer doesn't fit Refine's provider model, you'll fight the framework more than benefit from it.

Pricing: Check Refine's current open-source and commercial offering before choosing it.

Best for: Teams building admin panels or internal tools with standard CRUD patterns over existing APIs.

4. AdminJS Copy Chapter

AdminJS (formerly Admin Bro) auto-generates an admin panel from your database models. Point it at your ORM, and it creates a full CRUD interface.

What you get:

• Auto-generated admin panel from Sequelize, TypeORM, Mongoose, Prisma, or MikroORM models
• CRUD views, search, filtering, and bulk actions
• Dashboard page with customizable widgets
• Role-based access control
• Custom action hooks for business logic

Key strengths:

• Zero-config setup for common ORMs. If you use Prisma or TypeORM, AdminJS reads your schema and generates an admin panel automatically.
• Customizable. Override components, actions, and views when the defaults don't fit.
• Plugin system. Add features like file upload, import/export, and logging through plugins.

Trade-offs: The auto-generated UI looks functional but plain. Heavy customization can become painful because you're working against the generated output. The React version uses older patterns.

Pricing: Check AdminJS's current open-source and hosted offering before choosing it.

Best for: Backend teams that need a quick admin panel for database management without building frontend code.

5. React Admin Copy Chapter

React Admin is the most mature admin framework in the React ecosystem, maintained by Marmelab since 2016.

What you get:

• Complete admin panel framework with routing, layout, and state management
• List, Create, Edit, Show views with declarative configuration
• Many data provider adapters for common backend patterns
• Authentication hooks and access control
• Theming through MUI

Key strengths:

• Mature and battle-tested. Years of production use mean many admin edge cases are documented and handled.
• Declarative API. Define resources, list columns, form fields, and filters with JSX — React Admin generates the plumbing.
• Enormous data provider ecosystem. If your backend speaks a protocol, there's probably a React Admin data provider for it.
• Enterprise edition. Calendar, kanban, audit log, real-time updates, and multi-tenancy for teams that need them.

Trade-offs: Tightly coupled to MUI for styling. The declarative API is powerful but opaque — debugging what goes wrong inside the framework requires understanding its internals.

Pricing: Check React Admin's current licensing and Enterprise Edition details.

Best for: Teams building full-featured admin panels that need a mature, well-documented framework with extensive data provider support.

6. Ant Design Pro Copy Chapter

Ant Design Pro is the official dashboard template ecosystem for Ant Design. It is aimed at full-featured admin products built around Ant Design and ProComponents.

What you get:

• Complete admin layout with sidebar, header, and breadcrumbs
• Pre-built pages: dashboard, forms, tables, profiles, error pages
• Authentication and authorization patterns in the Ant Design Pro ecosystem
• ProComponents (ProTable, ProForm, ProLayout) for complex data patterns
• Internationalization with 10+ language packs

Key strengths:

• ProComponents. Advanced components like ProTable (configurable data table with search, filtering, and actions) save weeks of development time.
• Umi integration. Built on the Umi framework with conventions for routing, plugins, and data fetching.
• Comprehensive template. Nearly every page you'd need in an admin panel is included and customizable.

Trade-offs: Tightly coupled to the Ant Design ecosystem (Umi, Ant Design, AntV). The aesthetic is distinctly Ant Design — theming it to look different is difficult. Documentation is primarily in Chinese with English translations.

Pricing: Check Ant Design Pro's current license and repository before choosing it.

Best for: Teams already using Ant Design who need a comprehensive admin template with advanced data components.

7. CoreUI Copy Chapter

CoreUI is a cross-framework admin template available for React, Vue, Angular, and vanilla Bootstrap. The React version ships with a complete dashboard layout and component set.

What you get:

• Dashboard layout with sidebar navigation and header
• 30+ page templates (analytics, user management, settings, etc.)
• Custom UI components built on Bootstrap foundations
• Chart examples for data visualization
• Icon library with 1,500+ icons

Key strengths:

• Cross-framework consistency. If your organization uses multiple frontend frameworks, CoreUI provides a consistent design language across all of them.
• Extensive page templates. Pre-built pages for common admin patterns save time on layout and structure.
• Regular updates. Actively maintained with frequent releases.

Trade-offs: The Bootstrap foundation feels dated compared to Tailwind-based alternatives. The free version is limited — most useful features require the Pro license.

Pricing: Check CoreUI's current pricing and license before choosing it.

Best for: Organizations that need the same admin panel design across React, Vue, and Angular projects.

8. Tabler Copy Chapter

Tabler is a free, open-source dashboard template built on Bootstrap with a React adaptation. Known for its clean, minimal design and extensive component set.

What you get:

• 200+ responsive UI components
• Dashboard layout with multiple navigation patterns
• Apache ECharts integration for data visualization
• Form components with validation
• Email and e-commerce page templates

Key strengths:

• Beautiful design. Tabler has one of the cleanest default aesthetics of any free dashboard template.
• Component breadth. Over 200 components covering navigation, forms, data display, feedback, and layout.
• Open-source starting point. Check the current repository license and docs before adopting it.
• Active development. Regular releases with new components and improvements.

Trade-offs: The React version lags behind the HTML/Bootstrap version in features. TypeScript support is incomplete. Based on Bootstrap rather than a modern CSS approach.

Pricing: Check Tabler's current license and template docs before choosing it.

Best for: Developers who want a beautiful, free dashboard template and are comfortable with Bootstrap-based styling.

9. Argon Dashboard Copy Chapter

Argon Dashboard React by Creative Tim is a popular dashboard template with a distinctive visual style.

What you get:

• Dashboard layout with sidebar and navbar
• Pre-built pages (dashboard, maps, tables, user profile)
• Bootstrap-based styling with custom extensions
• Chart examples

Key strengths:

• Distinctive design. Argon has a recognizable gradient-heavy aesthetic that stands out from more neutral templates.
• Creative Tim ecosystem. Integrates with Creative Tim's other products (login pages, landing pages, design system).
• Good documentation. Clear setup instructions and component guides.

Trade-offs: The free version is bare-bones — most useful pages and components require the Pro license. The design is polarizing. Bootstrap foundation limits modern CSS usage.

Pricing: Check Creative Tim's current pricing and license before choosing it.

Best for: Teams that like Creative Tim's design aesthetic and want a quick starting point for a dashboard.

10. Material Dashboard Copy Chapter

Material Dashboard React is another Creative Tim template, built on MUI with a Material Design aesthetic.

What you get:

• MUI-based dashboard layout
• Pre-built pages with Material Design styling
• Chart examples for data visualization
• Dark mode support
• RTL layout support

Key strengths:

• Material Design compliance. If you need a dashboard that follows Google's Material Design guidelines, this delivers out of the box.
• MUI foundation. Access to MUI's full component ecosystem for extending beyond the template's defaults.
• Well-documented. Clear guides for customization, theming, and deployment.

Trade-offs: Same Creative Tim free-vs-Pro split — the free version is limited. Closely tied to MUI, making it hard to use with other styling approaches.

Pricing: Check Creative Tim's current pricing and license before choosing it.

Best for: Teams using MUI who want a Material Design dashboard template with ready-made pages.

11. Berry Copy Chapter

Berry is an MUI-based admin dashboard template known for its polished design and comprehensive feature set.

What you get:

• A large set of page templates and widgets
• Chart examples for data visualization
• Authentication page examples
• Multi-language support
• Light and dark themes with RTL support

Key strengths:

• Feature density. Berry focuses on a large set of pre-built pages and widgets.
• Chart-heavy pages. The template includes polished chart-oriented dashboard pages.
• Auth examples. Includes authentication-related page examples.

Trade-offs: The Pro version is expensive compared to alternatives. MUI dependency means the same theming constraints apply.

Pricing: Check the current Berry pricing and license before choosing it.

Best for: Teams that want a feature-rich MUI dashboard with multiple authentication patterns and extensive pre-built pages.

12. Mantis Copy Chapter

Mantis is a React admin dashboard built on MUI, focused on clean design and developer experience.

What you get:

• Clean, modern dashboard layout
• Chart examples for data visualization
• Authentication page examples
• Form components with validation
• Widget pages for common dashboard patterns

Key strengths:

• Clean aesthetic. Mantis has a more restrained, modern design compared to other MUI-based templates.
• Good code organization. The project structure follows best practices for scalable React applications.
• Regular updates. Actively maintained with consistent releases.

Trade-offs: Similar to Berry — MUI dependency, limited free version, Pro pricing.

Pricing: Check the current Mantis pricing and license before choosing it.

Best for: Teams who want a clean, well-organized MUI dashboard template.

13. Shadcn Dashboard Copy Chapter

The shadcn/ui Dashboard example demonstrates how to build a full dashboard using shadcn/ui components with Tailwind CSS.

What you get:

• Example dashboard layout with sidebar and header
• Data table with sorting, filtering, and pagination
• Charts using Recharts
• Account/authentication page examples
• Settings forms

Key strengths:

• Full code ownership. Since shadcn/ui components are copied into your project, you have complete control over the dashboard code.
• Tailwind CSS styling. Clean, utility-first styling that's easy to customize.
• Community extensions. Many developers have built expanded dashboard templates on top of the shadcn example.

Trade-offs: It's an example, not a production template. You'll need to build out most pages yourself. The components need manual updates when shadcn releases improvements.

Pricing: Check shadcn/ui's current license and docs before choosing it.

Best for: Developers who want a Tailwind-based dashboard starting point with full control over the source code.

14. HeroUI Pro + Custom Widgets Copy Chapter

If you want a HeroUI-native dashboard, start with HeroUI Pro rather than rebuilding the frame from base components. Use the Pro dashboard template for the app shell and add product-specific widgets only where your product needs something unique.

What you get:

• AppLayout, Sidebar, and Navbar for the dashboard frame
• KPI, DataGrid, LineChart, NumberValue, and TrendChip for dashboard UI
• Base HeroUI components for local UI around the Pro primitives
• Full control over your data fetching, permissions, and business logic

Why this works:

• No hand-rolled shell. The app frame, sidebar, navbar, metrics, tables, and charts already have Pro primitives.
• Modern stack. The current dashboard template is built with Next.js and HeroUI Pro components.
• AI-assisted development. Use HeroUI's MCP server and docs so agents can extend the dashboard with current APIs.

How to start:

1. Start from the HeroUI Pro dashboard template.
2. Keep AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components as the foundation.
3. Replace the mock data files with your API, database, or analytics source.
4. Add custom widgets only for product-specific workflows.

Pricing: Check HeroUI Pro's current pricing and license before choosing it.

Best for: Teams that want a HeroUI-native dashboard without rebuilding dashboard infrastructure from scratch.

How to Choose Copy Chapter

Your choice depends on what you value most:

• Speed to launch: HeroUI Pro Dashboard or Ant Design Pro give you the most complete starting points.
• Maximum flexibility: HeroUI Pro plus custom widgets or the shadcn Dashboard example let you build around your product's exact needs.
• CRUD-heavy admin panels: React Admin or Refine auto-generate interfaces from your data model.
• Enterprise needs: React Admin Enterprise, MUI X, or Berry Pro offer advanced features with support contracts.
• Budget-friendly: Tabler, Tremor, and the shadcn Dashboard example are worth checking when you want an open-source starting point.

Build Your Dashboard with HeroUI Copy Chapter

HeroUI provides the components you need to build modern, accessible dashboards:

• Component Documentation — Tables, Cards, Navigation, Forms, and more
• Quick Start Guide — Set up a new project in minutes
• HeroUI Pro — Pre-built dashboard templates and premium components
• Tutorial: Build a React Dashboard — Step-by-step guide

Apps Docs Content Blog En Best React Ui Component Libraries (`apps/docs/content/blog/en/best-react-ui-component-libraries.mdx`) Copy Section

title: "12 Best React UI Component Libraries in 2026" date: "2026-05-16" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["react", "ui-libraries", "comparison"] image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heroui-overview-light.png" darkImage: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/heorui-overview-dark.png" Copy Chapter

Choosing the right React UI component library can make or break your development workflow. The best React UI component libraries in 2026 ship accessible, production-ready components that let you focus on building features instead of re-implementing dropdowns for the hundredth time.

I compared 12 libraries across styling, accessibility foundation, breadth, AI workflow, and licensing. Exact component counts and pricing can change quickly, so treat this as a practical field guide and check each project's docs before you commit.

Quick Comparison

1. HeroUI Copy Chapter

HeroUI pairs React Aria accessibility with Tailwind CSS v4 styling and a compound component API (Card.Header, Table.Column, Modal.Body). Components work with React 19 and the Next.js App Router out of the box.

Key strengths:

• Accessibility-first architecture. Every component is built on React Aria, Adobe's battle-tested accessibility primitives. This means screen reader support, keyboard navigation, and ARIA attributes are handled correctly out of the box — not bolted on as an afterthought.
• Tailwind CSS v4 native. HeroUI's styling system uses CSS-based theming with @theme and design tokens, avoiding the runtime overhead of CSS-in-JS.
• Compound component API. Components use a composable pattern (Card.Header, Card.Content, Card.Footer) that gives you full control over markup and layout without sacrificing ergonomics.
• AI tooling. HeroUI ships an MCP server, llms.txt, and agent skills so AI coding assistants can look up current HeroUI APIs instead of relying only on training data.
• Server component friendly. Components are designed with React Server Components in mind — client boundaries are minimal and clearly documented.

When to use it: You want a modern, accessible component library with Tailwind CSS styling and first-class AI tooling support. Ideal for new projects using Next.js, React 19, and Tailwind v4.

2. shadcn/ui Copy Chapter

shadcn/ui isn't a traditional component library — it's a collection of copy-paste components built on Radix UI and Tailwind CSS. Instead of installing a package, you add component source code directly to your project.

Key strengths:

• Full ownership. Components live in your codebase, so you can modify them freely without fighting library abstractions or waiting for upstream changes.
• Radix UI foundation. The underlying primitives handle accessibility and complex interactions (popovers, comboboxes, dialogs) reliably.
• CLI tooling. The shadcn CLI scaffolds components into your project with the right dependencies and file structure.
• AI-ready docs. shadcn/ui publishes llms.txt, skills, and an MCP server for agents.
• Massive ecosystem. The community has built hundreds of extensions, themes, and integrations around shadcn's patterns.

When to use it: You want maximum control over component code and you're comfortable maintaining copied components. Works well for teams that need heavy customization.

Trade-offs: You own the code, which means you also own the bugs. Upstream fixes and improvements require manual re-integration. No central update mechanism. Additionally, shadcn/ui's foundation on Radix UI carries some uncertainty — the original Radix team has shifted focus to Base UI, and the long-term maintenance status of Radix primitives is an open question in the community.

3. Material UI (MUI) Copy Chapter

Material UI is the most established React component library, with a decade of production use. MUI's stable styling path still centers on Emotion and the sx prop; Pigment CSS exists as an experimental zero-runtime direction rather than the default.

Key strengths:

• Massive component count. Over 70 components covering nearly every UI pattern you can think of, from basic buttons to complex data grids.
• Material Design compliance. If your design system is built on Material Design, MUI gives you pixel-perfect implementations.
• Enterprise ecosystem. MUI X offers premium components (data grid, date pickers, charts) with enterprise support and SLAs.
• Mature and battle-tested. Thousands of production apps run on MUI. Edge cases have been found and fixed over years.

When to use it: You're building a large enterprise application that needs Material Design compliance, or you need MUI X's premium data grid and date picker components.

Trade-offs: The Material Design aesthetic is opinionated. Theming away from Material's look-and-feel is possible but requires significant effort. Bundle size is larger than most alternatives.

4. Chakra UI Copy Chapter

Chakra UI pioneered the "style props" pattern in React, letting you style components with props like bg="blue.500" and p={4}. Chakra's current theming docs describe a system built around the Panda CSS API with defineConfig, createSystem, recipes, slot recipes, tokens, and semantic tokens.

Key strengths:

• Intuitive styling API. Style props make it fast to prototype and iterate on designs without leaving your JSX.
• Design token system. The theme object gives you centralized control over colors, spacing, fonts, and breakpoints.
• Good accessibility defaults. Components follow WAI-ARIA patterns and include keyboard navigation.
• Recipe-driven styling. Chakra uses recipes, slot recipes, and a token-based system for component styling.
• AI support. Chakra documents an MCP server for AI-assisted workflows.

When to use it: You like styling through props rather than class names, and you want a cohesive design system with good defaults.

Trade-offs: The style props pattern can make JSX noisy for complex components. Migrating from v2 to v3 required significant changes because the component and theming APIs changed.

5. Mantine Copy Chapter

Mantine is a full-featured React component library with a very broad component catalog, a hooks package, and a rich extension ecosystem. Mantine's homepage currently describes the library as 120+ components and 70+ hooks.

Key strengths:

• Unmatched breadth. Mantine has components and extensions for many product needs — date pickers, notifications, spotlight search, charts, forms, and more.
• Large hooks package. Beyond components, Mantine ships hooks for local storage, media queries, clipboard, idle detection, and many other common patterns.
• CSS styling. Mantine components are built with CSS files and can be customized through the Styles API.
• AI tooling. Mantine publishes LLM docs, skills, and an MCP server.
• Form library. @mantine/form provides form state management with validation that integrates seamlessly with Mantine inputs.

When to use it: You want a batteries-included library where you can find a component for almost any use case without adding third-party packages.

Trade-offs: The huge surface area means the bundle can grow quickly if you're not tree-shaking carefully. The component design aesthetic, while clean, is fairly specific.

6. Radix UI (Primitives) Copy Chapter

Radix UI provides unstyled, accessible UI primitives that you style yourself. It's the foundation behind shadcn/ui and many other component libraries.

Key strengths:

• Accessibility gold standard. Every primitive is built to WAI-ARIA specification with exhaustive keyboard navigation, focus management, and screen reader support.
• Unstyled by default. Zero design opinions means zero fighting with the library's aesthetic. Bring your own styling system.
• Composable APIs. Primitives use a compound component pattern with slot-based composition that gives you control over every rendered element.
• Production-proven. Radix primitives power thousands of production applications through both direct usage and shadcn/ui.

When to use it: You need accessible, behavior-only primitives and want complete control over styling. Great for teams building custom design systems.

Trade-offs: You need to bring all your own styling. The learning curve for the composition patterns can be steep for simpler use cases.

7. Ant Design Copy Chapter

Ant Design is a comprehensive design system and component library created by Ant Group (Alibaba). It's especially popular in enterprise applications and the Chinese development community.

Key strengths:

• Enterprise-grade components. Complex components like Table (with sorting, filtering, pagination), Form (with validation), and Tree are mature and feature-rich.
• Design system included. Ant Design is a complete design system with design tokens, patterns, and guidelines — not just a component library.
• Internationalization. First-class i18n support with 60+ locale packages.
• Component quality. Each component handles dozens of edge cases that you'd otherwise need to build yourself.

When to use it: You're building a complex enterprise application, especially one that needs sophisticated data tables, forms, and tree views.

Trade-offs: The design aesthetic is distinctly "Ant Design" and theming it to look different requires substantial effort. Bundle size is significant. Accessibility support, while improving, still lags behind Radix/React Aria-based libraries.

8. Headless UI Copy Chapter

Headless UI is a set of unstyled, accessible UI components from the Tailwind Labs team. It focuses on common interactive patterns — dropdowns, dialogs, tabs, comboboxes.

Key strengths:

• Tailwind CSS integration. Built by the Tailwind team, it works perfectly with Tailwind's utility classes and transition utilities.
• Small, focused scope. Only includes components that are genuinely hard to build accessibly (menus, listboxes, dialogs, etc.).
• Lightweight. Minimal bundle impact because of the focused component set.
• Clean API. Uses render props and compound components with a simple, predictable API.

When to use it: You're using Tailwind CSS and need a few accessible interactive components without a full UI library.

Trade-offs: Very small component set — you'll need other solutions for data tables, form inputs, date pickers, and most other patterns.

9. React Aria (Primitives) Copy Chapter

React Aria is Adobe's library of accessibility primitives for React. It provides hooks and components for building accessible UI from scratch.

Key strengths:

• Industry-leading accessibility. React Aria is arguably the most thoroughly accessible UI primitive library available. It handles internationalization, right-to-left layouts, touch interactions, and edge cases that most libraries miss.
• Hooks + components. Offers both low-level hooks (for maximum flexibility) and higher-level components (for convenience).
• Platform-aware. Adapts behavior based on device type, pointer type, and platform conventions.
• Foundation for other libraries. HeroUI, Adobe Spectrum, and other libraries build on React Aria, proving its reliability at scale.

When to use it: You're building a design system from scratch and need the strongest possible accessibility foundation. Also useful when you need specific primitives (like a color picker or calendar) that other libraries don't offer.

Trade-offs: Steeper learning curve than styled libraries. You need to bring all your own styling and composition patterns.

10. Ark UI Copy Chapter

Ark UI is a headless component library from the creators of Chakra UI, built on top of state machines for predictable behavior.

Key strengths:

• State machine architecture. Uses Zag.js state machines under the hood, making component behavior predictable and debuggable.
• Framework-agnostic core. The same state machines power React, Vue, and Solid versions of every component.
• Modern patterns. Includes components like Signature Pad, Pin Input, and Splitter that aren't commonly found in other headless libraries.
• Styling flexibility. Works with any styling solution — Tailwind, Panda CSS, vanilla CSS, CSS modules.

When to use it: You want headless components with predictable state management, or you need to share component logic across React, Vue, and Solid projects.

Trade-offs: Smaller community than Radix or React Aria. The state machine abstraction adds conceptual overhead for simple components.

11. Tremor Copy Chapter

Tremor is focused on dashboards and data visualization. Its current docs describe Tremor Raw as designed for React 18.2+ and Tailwind CSS 4.0+.

Key strengths:

• Dashboard-first design. Purpose-built resources for analytics, dashboard UI, and data display.
• Tailwind native. Integrates seamlessly with existing Tailwind projects without additional styling configuration.
• Clean defaults. Charts and metrics look polished out of the box with a cohesive design language.
• Lightweight scope. Focused on data display, so you pick what you need without pulling in an entire UI framework.

When to use it: You're building analytics dashboards or data-heavy interfaces and already use Tailwind CSS.

Trade-offs: Limited to dashboard-specific components. You'll need another library for general UI patterns like forms, navigation, and dialogs.

12. Park UI Copy Chapter

Park UI is a styled component library built on Ark UI primitives, available in both Panda CSS and Tailwind CSS variants.

Key strengths:

• Pre-styled Ark UI. Takes Ark UI's headless components and adds polished, customizable styling — similar to what shadcn/ui does for Radix.
• Dual styling support. Available in both Panda CSS and Tailwind CSS variants, so you can pick the approach that fits your project.
• Copy-paste model. Like shadcn/ui, components are added to your project as source files you own and customize.
• Design tokens. Ships with a token system that makes global style changes straightforward.

When to use it: You like the shadcn/ui copy-paste model but prefer Ark UI's state-machine-based primitives over Radix, or you're using Panda CSS.

Trade-offs: Smaller community and ecosystem compared to shadcn/ui. Fewer third-party extensions and themes.

How to Choose Copy Chapter

There's no single "best" library — the right choice depends on your project's constraints:

• Starting a new project with Tailwind v4? HeroUI gives you the most modern stack with React Aria accessibility, compound components, and AI tooling.
• Want full ownership of component code? shadcn/ui or Park UI let you copy components into your project.
• Building enterprise apps with complex data needs? MUI's data grid or Ant Design's table component are hard to beat.
• Need maximum accessibility compliance? HeroUI's React Aria foundation provides the strongest accessibility out of the box.
• Want a broad UI toolkit with quality? HeroUI covers all core UI patterns with deep accessibility; pair with dedicated libraries for specialized needs like rich text editors.
• Working across multiple frameworks? Ark UI's state machines work in React, Vue, and Solid.

Get Started with HeroUI Copy Chapter

If you're starting a new React project and want accessible, beautifully designed components with Tailwind CSS v4, give HeroUI a try:

• Quick Start Guide
• Component Documentation
• GitHub Repository
• Discord Community

Apps Docs Content Blog En Build React Dashboard With Heroui (`apps/docs/content/blog/en/build-react-dashboard-with-heroui.mdx`) Copy Section

title: "How to Build a React Dashboard with HeroUI Pro" date: "2026-05-11" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["react", "dashboard", "tutorial", "heroui", "admin"] image: "/images/blog/build-react-dashboard-with-heroui.jpg" draft: true Copy Chapter

I've watched too many teams spend their first two sprints hand-rolling a sidebar, a responsive navbar, and a metrics card layout — only to rip it out later when the requirements get real. If you have HeroUI Pro, skip that phase entirely.

This post shows the Pro-first approach: start with AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components, then plug in your data. The dashboard template already handles the layout, responsive behavior, and mobile navigation.

Project Setup Copy Chapter

Install HeroUI and HeroUI Pro packages:

npm install @heroui/styles @heroui/react @heroui-pro/react

HeroUI Pro requires access to the Pro package registry. The dashboard template uses these style imports:

@import "@heroui/styles/css";
@import "@heroui-pro/react/css";

@source "../**/*.{ts,tsx}";

body {
  background-color: var(--background);
}

Use AppLayout for the Frame Copy Chapter

The app frame should come from HeroUI Pro AppLayout, not a custom flex layout.

"use client";

import type {ReactNode} from "react";

import {AppLayout} from "@heroui-pro/react";
import {usePathname, useRouter} from "next/navigation";
import {useCallback} from "react";

import {DashboardNavbar} from "./dashboard-navbar";
import {DashboardSidebar} from "./dashboard-sidebar";

export function AppShell({children}: {children: ReactNode}) {
  const router = useRouter();
  const pathname = usePathname();
  const navigate = useCallback((href: string) => router.push(href), [router]);

  return (
    <AppLayout
      navbar={<DashboardNavbar title="Dashboard" />}
      navigate={navigate}
      sidebar={<DashboardSidebar pathname={pathname} />}
      sidebarCollapsible="offcanvas"
    >
      {children}
    </AppLayout>
  );
}

AppLayout handles the relationship between the sidebar, navbar, mobile menu, and content region. Keep it as the app shell and customize inside the slots.

Use Pro Sidebar and Navbar Copy Chapter

HeroUI Pro ships a Sidebar compound component and a Navbar compound component. The dashboard template uses both.

"use client";

import {Bell, Magnifier} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
import {AppLayout, Navbar, Sidebar} from "@heroui-pro/react";

export function DashboardNavbar({title}: {title: string}) {
  return (
    <Navbar maxWidth="full">
      <Navbar.Header>
        <AppLayout.MenuToggle />
        <Sidebar.Trigger />
        <h1 className="text-foreground truncate text-xl font-semibold">{title}</h1>
        <Navbar.Spacer />
        <Button isIconOnly aria-label="Search" size="sm" variant="tertiary">
          <Magnifier className="size-4" />
        </Button>
        <Button isIconOnly aria-label="Notifications" size="sm" variant="tertiary">
          <Bell className="size-4" />
        </Button>
      </Navbar.Header>
    </Navbar>
  );
}

For navigation, render Sidebar.MenuItem items instead of building custom active-link styles:

/* Detailed source-code truncated for AI context efficiency. */

The full Pro template also includes a header profile area, footer items, badges, and mobile content reuse.

Use KPI for Metrics Copy Chapter

Do not rebuild metric cards with Card unless you need a one-off design. Use KPI from HeroUI Pro.

"use client";

import {KPI} from "@heroui-pro/react";

const chartData = [
  {x: 1, y: 12},
  {x: 2, y: 18},
  {x: 3, y: 16},
  {x: 4, y: 24},
];

export function KpiRow() {
  return (
    <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
      <KPI>
        <KPI.Header>
          <KPI.Title>Revenue</KPI.Title>
        </KPI.Header>
        <KPI.Content>
          <KPI.Value currency="USD" maximumFractionDigits={0} style="currency" value={45231} />
          <KPI.Trend trend="up">12.5%</KPI.Trend>
        </KPI.Content>
        <KPI.Chart color="var(--color-accent)" data={chartData} height={60} strokeWidth={1.5} />
      </KPI>
    </div>
  );
}

The dashboard template uses this same pattern for analytics KPIs and finance KPIs.

Use Pro Charts Copy Chapter

HeroUI Pro chart components keep chart styling aligned with the rest of the design system.

/* Detailed source-code truncated for AI context efficiency. */

Use the chart components from Pro for dashboard analytics, then swap the sample arrays for your real metrics.

Use DataGrid for Tables Copy Chapter

Dashboards usually need dense, sortable tables. Use Pro DataGrid instead of composing raw table markup.

/* Detailed source-code truncated for AI context efficiency. */

This matches the template's table direction: typed columns, a controlled sort descriptor, search outside the grid, and getRowId for stable row identity.

Compose the Dashboard Page Copy Chapter

The page should mostly assemble widgets. In the Pro template, the dashboard view looks like this:

"use client";

import {DashboardToolbar} from "../widgets/dashboard-toolbar";
import {EmployeesTable} from "../widgets/employees-table";
import {KpiRow} from "../widgets/kpi-row";
import {SalesPerformanceCard} from "../widgets/sales-performance-card";
import {TrafficSourceCard} from "../widgets/traffic-source-card";

export function DashboardPage() {
  return (
    <div className="mx-auto flex max-w-7xl flex-col gap-4 px-5 pb-10 pt-4">
      <DashboardToolbar />
      <KpiRow />
      <div className="grid grid-cols-1 gap-3 lg:grid-cols-2">
        <SalesPerformanceCard />
        <TrafficSourceCard />
      </div>
      <EmployeesTable />
    </div>
  );
}

That is the main architectural point: the page should read like product composition, not infrastructure.

Why HeroUI for Dashboards Copy Chapter

Dashboards are dense — data tables, form controls, navigation, and overlays on a single screen. HeroUI handles the accessibility and styling for all of those pieces so you can focus on your data layer.

• Data tables that handle accessibility for you. Sortable columns, row selection, keyboard navigation, and screen reader announcements come from React Aria. You don't reimplement them per table.
• Static CSS for data-heavy pages. Tailwind v4 generates all styles at build time. Dashboards with KPI cards, charts, and grids don't pay a runtime styling tax.
• Pro primitives instead of hand-rolled infrastructure. AppLayout, Sidebar, Navbar, KPI, DataGrid, and chart components from HeroUI Pro save weeks of dashboard scaffold work.
• AI assistants that know the Pro API. The MCP server and agent skills let AI tools scaffold dashboard views with correct component APIs instead of guessing.

Next Steps Copy Chapter

• Start from the HeroUI Pro dashboard template if you have Pro access.
• Replace the mock files in src/data/* with your API, database, or analytics source.
• Keep AppLayout, Sidebar, Navbar, KPI, DataGrid, and Pro charts as the foundation.
• Use base HeroUI components for local UI that does not need a Pro primitive.

Apps Docs Content Blog En Choosing React Native Ui Library (`apps/docs/content/blog/en/choosing-react-native-ui-library.mdx`) Copy Section

title: "Choosing a React Native UI Library" date: "2026-05-12" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["native", "react-native", "ui-libraries", "comparison"] image: "/images/blog/choosing-react-native-ui-library.jpg" draft: true Copy Chapter

Choosing a React Native UI library is not just a component-count decision. It is a maintenance decision, a design decision, and increasingly an AI workflow decision.

The library you choose becomes the vocabulary your team uses every day. It shapes how designers hand off screens, how engineers compose interfaces, how quickly you can fix accessibility issues, and how well AI agents generate code that actually compiles.

This guide explains how we think about that decision, and why HeroUI Native is built the way it is.

What to Evaluate Copy Chapter

Before comparing libraries, write down what your product needs:

• Are you building a consumer app, internal tool, SaaS companion app, marketplace, fintech app, or mobile-first product?
• Do you need bottom sheets, dialogs, menus, tabs, forms, toasts, skeletons, and list patterns?
• Is your design system already defined in Figma?
• Do you need AI assistants to generate UI reliably?
• Does your team want a package that updates over time, or copied source code you fully own?

Those questions matter more than a screenshot gallery.

Package vs. Copy-Paste Copy Chapter

Copy-paste UI can be useful when you need total code ownership. The trade-off is maintenance. Once the code is in your app, your team owns the updates, accessibility fixes, dependency changes, and design consistency.

HeroUI Native takes the package approach:

• Install heroui-native.
• Configure Uniwind and the provider once.
• Compose components through documented APIs.
• Update the package when fixes and improvements ship.
• Use MCP/LLM docs so AI tools can read current component documentation.

That does not mean a package is always better. If your team has a dedicated design system group and wants to own every line of component code, copied source may fit. But if your team wants to ship product screens without becoming a component-maintenance team, a maintained package is usually the healthier default.

Design Quality Is a Feature Copy Chapter

Mobile apps are judged in milliseconds. A button press, sheet transition, input focus state, disabled control, or empty state can make an app feel cared for or unfinished.

HeroUI Native is intentionally opinionated about the baseline:

• Semantic component variants create a clear visual hierarchy.
• Components are designed to look complete before customization.
• Theming happens through CSS variables and Uniwind.
• Animated components use React Native animation libraries instead of web-only assumptions.
• Component APIs follow compound composition so you can adjust structure without forking internals.

The goal is not to lock you into one visual identity. The goal is to start from a designed system rather than a pile of primitives.

Ecosystem Fit Copy Chapter

HeroUI Native is strongest when you want one ecosystem across product surfaces:

• Web product: HeroUI React
• Mobile product: HeroUI Native
• Premium app surfaces: HeroUI Pro
• Design handoff: HeroUI Figma Kit V3
• AI workflow: Native MCP Server, llms.txt, and Agent Skills

That ecosystem is the advantage. A component library by itself saves some time. A design system, docs, Figma kit, AI context, and maintained package save coordination cost.

Where HeroUI Native Is Different Copy Chapter

HeroUI Native is built specifically for React Native. It does not ask you to use web imports or CSS files that do not belong in mobile apps.

Use Native patterns:

import {Button} from "heroui-native";

<Button variant="primary" onPress={() => console.log("Pressed")}>
  <Button.Label>Continue</Button.Label>
</Button>;

Avoid web patterns:

Do not use the HeroUI web package or web-only event handlers in React Native screens.

HeroUI Native uses onPress, HeroUINativeProvider, GestureHandlerRootView, Uniwind, and native overlay/portal patterns because those are the right abstractions for mobile.

Recommendation Copy Chapter

Choose HeroUI Native when your team values design quality, maintainability, and ecosystem leverage. It is especially compelling if you already use HeroUI on the web, work from Figma, or build with AI coding assistants.

Start with the Quick Start, then read the Design Principles before building your first screen.

Apps Docs Content Blog En Design To Code With Heroui Native (`apps/docs/content/blog/en/design-to-code-with-heroui-native.mdx`) Copy Section

title: "Design to Code with HeroUI Native" date: "2026-05-13" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["native", "react-native", "design-system", "figma", "ai"] image: "/images/blog/design-to-code-with-heroui-native.jpg" draft: true Copy Chapter

The hardest part of a mobile design system is not drawing components. It is keeping design, code, documentation, and generated AI output aligned over time.

HeroUI Native is built for that workflow. The library gives developers a maintained React Native component system, gives designers a shared HeroUI visual language through Figma, and gives AI assistants structured documentation through MCP, llms.txt, and skills.

The Problem Copy Chapter

Most teams drift in predictable ways:

• Figma components use one naming system.
• React Native components use another.
• Design tokens get translated by hand.
• AI agents guess props from old examples.
• Engineers copy a component once, customize it, and rarely bring upstream fixes back in.

The result is subtle inconsistency. One screen has different spacing. Another uses the wrong disabled state. A generated component imports web HeroUI into a native app. The first version ships, but the system becomes harder to maintain.

HeroUI Native is designed to reduce that drift.

Shared Mental Model Copy Chapter

HeroUI Native uses the same product-level ideas as the rest of the HeroUI ecosystem:

• Semantic variants like primary, secondary, and tertiary.
• Compound components for flexible composition.
• Theme variables for semantic colors and surfaces.
• Component documentation with anatomy, props, examples, and usage patterns.
• AI-readable docs for agents.

The implementation is native, not web. HeroUI Native uses React Native, Uniwind, HeroUINativeProvider, and mobile interaction patterns. But the design language stays familiar.

import {Button, Card} from "heroui-native";

<Card>
  <Card.Header>
    <Card.Title>Workspace</Card.Title>
    <Card.Description>Invite your team and manage access.</Card.Description>
  </Card.Header>
  <Card.Body>{/* Screen content */}</Card.Body>
  <Card.Footer>
    <Button variant="primary">
      <Button.Label>Invite member</Button.Label>
    </Button>
  </Card.Footer>
</Card>;

Figma Kit V3 Copy Chapter

The HeroUI Figma Kit V3 is the design-side entry point for the ecosystem. It is linked from the Native docs so teams can work from the same visual system while building mobile screens.

Use it to:

• Start from HeroUI's visual language instead of blank frames.
• Keep component names and variants close to the code model.
• Align designers and developers on hierarchy, states, and spacing.
• Create mobile product screens that feel connected to the rest of the HeroUI ecosystem.

Figma does not replace implementation details like keyboard handling, safe areas, bottom sheets, or screen reader behavior. But a shared kit reduces the translation cost between design and code.

AI Context That Knows Native Copy Chapter

AI coding tools are useful only when they have current context. Without that, they often mix web and native APIs.

HeroUI Native provides dedicated AI entry points:

• /native/llms.txt for a quick Native documentation index.
• /native/llms-full.txt for complete Native documentation.
• /native/llms-components.txt for component docs only.
• /native/llms-patterns.txt for common patterns.
• HeroUI Native MCP Server, published as @heroui/native-mcp.
• HeroUI Native Agent Skills.

That matters because Native code has different rules:

• Import from heroui-native.
• Use React Native press handlers such as onPress.
• Configure HeroUINativeProvider.
• Wrap the app with GestureHandlerRootView.
• Use Uniwind and heroui-native/styles.
• Use Native component anatomy, not web component anatomy.

The MCP server and skills help agents follow those rules.

A Practical Workflow Copy Chapter

Here is the workflow we recommend:

1. Design from the Figma kit. Start from HeroUI's component language instead of one-off mobile components.
2. Install HeroUI Native correctly. Follow the Quick Start so Uniwind, peer dependencies, styles, and providers are configured.
3. Give agents the docs. Add the MCP server or reference /native/llms-full.txt.
4. Build screens with compound components. Compose components using dot notation and semantic variants.
5. Customize through theme variables. Keep brand-level changes in the theming layer, not scattered across every screen.
6. Update through the package. Treat HeroUI Native as a maintained dependency, not a copied snapshot.

Why This Helps Copy Chapter

Design-to-code is not about removing engineers or designers. It is about reducing translation loss.

HeroUI Native helps because:

• Designers start from the HeroUI visual system.
• Developers get a maintained React Native package.
• AI assistants get current component docs.
• Teams keep a consistent vocabulary across web and mobile.
• The library can evolve without every app owning every internal component detail.

That is the long-term value: not just faster first screens, but fewer inconsistencies as the app grows.

Next Step Copy Chapter

Install the HeroUI Native MCP Server in your editor, then ask your assistant to build a screen using the Quick Start and the components in All Components.

Apps Docs Content Blog En Heroui Vs Chakra Ui (`apps/docs/content/blog/en/heroui-vs-chakra-ui.mdx`) Copy Section

title: "HeroUI vs Chakra UI: Which React UI Library Should You Choose in 2026?" date: "2026-05-14" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["comparison", "heroui", "chakra-ui", "react"] draft: true Copy Chapter

If you're picking a React component library in 2026, HeroUI and Chakra UI are both strong contenders. HeroUI styles components with Tailwind CSS v4 utility classes and builds accessibility on React Aria, using a compound component API (Card.Header, Modal.Body) instead of style props. Chakra UI pioneered the style-props pattern and has rebuilt on Panda CSS and Ark UI. Both ship accessible components — but they take fundamentally different approaches to styling, component design, and developer tooling that matter more than you might think.

This guide walks through where each library shines, where it falls short, and how to decide which one fits your project.

The TL;DR Copy Chapter

Styling: Two Different Philosophies Copy Chapter

This is the biggest architectural difference between the two libraries, and it's worth understanding deeply because it affects everything downstream — from how you customize components to how your app performs in production.

Chakra UI: Style Props Copy Section

Chakra pioneered the "style props" pattern in React. Instead of writing CSS classes, you style components through JSX props:

import { Box, Button } from "@chakra-ui/react";

<Box bg="blue.500" p={4} borderRadius="lg">
  <Button colorPalette="blue" size="lg">
    Click me
  </Button>
</Box>

This is ergonomic for quick prototyping. You stay in JSX, your styles are co-located with your markup, and the design token system (blue.500, p={4}) keeps things consistent. Chakra's current theming docs describe the styling system as built around Panda CSS APIs like defineConfig, createSystem, recipes, slot recipes, tokens, and semantic tokens.

The trade-off is that style props can make JSX verbose for complex layouts. A card with a dozen styling tweaks ends up with more prop noise than markup, and the default styling model is still different from a static CSS/Tailwind setup.

HeroUI: Tailwind CSS v4 Copy Section

HeroUI takes the opposite approach — components are styled with Tailwind CSS utility classes, and you customize them the same way you'd customize any Tailwind element:

import { Card, Button } from "@heroui/react";

<Card className="bg-blue-500 p-4 rounded-lg">
  <Card.Header>
    <Card.Title>My Card</Card.Title>
  </Card.Header>
  <Card.Content>
    <Button size="lg">Click me</Button>
  </Card.Content>
</Card>

Because Tailwind v4 and HeroUI styles are CSS-first, there is no component-level CSS-in-JS runtime in the HeroUI styling path. HeroUI's theming system uses CSS custom properties and Tailwind's @theme directive, so you can swap visual systems by changing variables.

If you're already using Tailwind in your project, HeroUI slots in naturally. If you're not, adopting Tailwind is a separate decision that comes with its own learning curve.

Which styling approach is better? Copy Section

Neither is objectively superior — it depends on your team.

Style props are great when you want to move fast and keep everything in JSX. They're intuitive for developers who think in "component properties" rather than "CSS classes." But they create a tight coupling between your component library and your styling strategy.

Tailwind utilities are great when you want a universal styling language that works the same way on library components and custom components. The build-time approach means better performance, and the utility-first workflow is something most React developers already know in 2026.

Accessibility Foundations Copy Chapter

Both libraries take accessibility seriously, but they build on different foundations.

HeroUI: React Aria Copy Section

HeroUI is built on React Aria, Adobe's accessibility primitives. React Aria handles keyboard navigation, screen reader announcements, focus management, and ARIA attributes for every component. It's the same foundation that powers Adobe's own design system (Spectrum), and it's one of the most thoroughly tested accessibility layers in the React ecosystem.

What this means in practice: HeroUI components handle edge cases that many libraries miss. Focus trapping in modals works correctly with screen readers. Comboboxes announce option counts. Date pickers support keyboard navigation across months and years. These aren't features you'd notice in a demo, but they're critical for shipping accessible software.

Chakra UI: Ark UI / Zag.js Copy Section

Chakra v3 rebuilt its accessibility layer on Ark UI and Zag.js, both maintained by the Chakra team. Zag uses state machines to model component behavior, which makes the logic predictable and testable. Ark UI wraps Zag into framework-specific components.

This is a solid approach, and Chakra's accessibility is genuinely good. The main difference is maturity — React Aria has been in production at Adobe for years and has a larger surface area of accessibility testing. Zag.js is newer and still expanding its component coverage.

The practical difference Copy Section

For most applications, both libraries will produce accessible UIs. The gap shows up in complex components — date pickers, comboboxes, drag-and-drop — where React Aria's deeper investment in accessibility edge cases gives HeroUI an advantage.

Component API Design Copy Chapter

This is where the day-to-day developer experience diverges most noticeably.

HeroUI: Compound Components Copy Section

HeroUI uses a compound component pattern where a parent component exposes sub-components through dot notation:

import { Modal, Button } from "@heroui/react";

<Modal>
  <Button>Open Modal</Button>
  <Modal.Backdrop>
    <Modal.Container>
      <Modal.Dialog>
        <Modal.CloseTrigger />
        <Modal.Header>
          <Modal.Heading>Confirm Action</Modal.Heading>
        </Modal.Header>
        <Modal.Body>Are you sure?</Modal.Body>
        <Modal.Footer>
          <Button variant="ghost">Cancel</Button>
          <Button>Confirm</Button>
        </Modal.Footer>
      </Modal.Dialog>
    </Modal.Container>
  </Modal.Backdrop>
</Modal>

This is more verbose than a flat prop API, but it gives you complete control over the component's structure. You can reorder parts, add custom elements between them, or omit parts entirely. It's the same pattern used by Radix UI, and it scales well for complex UIs.

Chakra UI: Flat Components with Style Props Copy Section

Chakra components are flatter and rely on props for configuration:

import { DialogRoot, DialogContent, DialogHeader, DialogBody, DialogFooter } from "@chakra-ui/react";

<DialogRoot>
  <DialogContent>
    <DialogHeader>Confirm Action</DialogHeader>
    <DialogBody>Are you sure?</DialogBody>
    <DialogFooter>
      <Button variant="ghost">Cancel</Button>
      <Button>Confirm</Button>
    </DialogFooter>
  </DialogContent>
</DialogRoot>

Chakra v3 moved toward a more composable approach compared to v2, but the styling still happens through props rather than class names. This makes the JSX self-documenting in one sense (you can see all the styles) but noisy in another (the styles obscure the structure).

Performance Copy Chapter

Performance differences between modern component libraries are often overstated, but there are real architectural factors worth considering.

Build-time vs. runtime CSS Copy Section

HeroUI generates all CSS at build time through Tailwind v4. Your production bundle includes only the utility classes your components actually use, and there's zero JavaScript overhead for style computation at runtime.

Chakra's styling API is much more structured than the older Chakra v2 era and is built around the Panda CSS API. It is still a different authoring model from HeroUI's Tailwind/CSS-variable path, so teams should test the exact runtime and bundle impact in their own app.

Bundle size Copy Section

HeroUI components are thin wrappers around React Aria primitives plus CSS classes. Chakra components carry a richer style-props and theme system. The practical impact depends on which components you use and how aggressively your app splits routes.

Server components Copy Section

HeroUI's static pieces can stay in React Server Component trees, while interactive pieces need client boundaries. Chakra's behavior depends on which components and style props you use, so I would test the exact pages you care about before making performance promises.

AI Tooling Copy Chapter

This is an area where HeroUI has a clear, measurable advantage.

HeroUI's AI stack Copy Section

HeroUI ships three tools specifically designed for AI coding assistants:

• MCP server. A Model Context Protocol server that exposes component documentation, API references, and code examples to AI agents. When your AI assistant has access to this, it can look up the exact props, compound component structure, and usage patterns for any HeroUI component — instead of guessing.
• llms.txt. A structured text file at heroui.com/llms.txt that gives LLMs a condensed reference of the entire library. This is the equivalent of giving your AI assistant a cheat sheet.
• Agent skills. Pre-built skill files for AI coding tools like Cursor and Claude Code that teach agents how to scaffold components, use the correct import paths, and follow HeroUI conventions.

In practice, this gives AI assistants a better chance of generating current HeroUI v3 code. They can look up the compound component patterns, prop names, and import paths instead of guessing from mixed training data.

Chakra UI's AI support Copy Section

Chakra's docs now point developers to an MCP server, so it is not accurate to say Chakra has no AI support. The practical difference is that HeroUI's AI context is specific to HeroUI's v3 compound components, Tailwind v4 styling, and package API, while Chakra's context teaches Chakra's style-prop and system APIs.

Why this matters Copy Section

If you're using AI coding assistants daily (and in 2026, most developers are), the quality of AI-generated code directly affects your productivity. Getting correct code on the first generation saves you from debugging hallucinated props, wrong imports, and deprecated patterns.

Ecosystem and Community Copy Chapter

Both libraries have active communities, good TypeScript support, and work with Next.js. HeroUI's community is growing quickly with strong documentation, an active Discord, and HeroUI Pro for teams that need premium components.

HeroUI also invests heavily in AI developer tooling — MCP servers, llms.txt, and agent skills — which is increasingly important as AI-assisted development becomes the default workflow.

Design Quality Copy Chapter

Design quality is subjective, but there are measurable differences in how these libraries handle visual polish.

HeroUI ships with refined default animations, consistent spacing tokens, and a design system that looks polished out of the box. Components have subtle transitions, well-balanced proportions, and sensible defaults that work without customization. The theme system supports variants like "glass" and "brutalism" for distinct visual identities.

Chakra provides good-looking defaults as well, especially in v3. The design token system is well-organized and the components are clean. However, HeroUI's defaults tend to feel more opinionated and "designed" — there's more attention to micro-interactions, shadows, and spacing out of the box.

If you plan to heavily customize the visual design anyway, this matters less. If you want something that looks great with minimal theming effort, HeroUI has an edge.

When to Choose Each Copy Chapter

Choose HeroUI if: Copy Section

• You're already using Tailwind CSS (or want to)
• Accessibility is a hard requirement and you want React Aria's depth
• You use AI coding assistants and want first-class tooling support
• You prefer compound component APIs that give you structural control
• You want polished defaults with minimal custom theming
• You're building with React 19 and want good server component support
• Performance matters and you prefer a static CSS styling path

When Chakra UI might work Copy Section

Chakra UI can be a reasonable choice if your team doesn't use Tailwind CSS and prefers styling through component props, or if you're maintaining an existing Chakra codebase. However, Chakra's reliance on Panda CSS and runtime styling introduces trade-offs in performance and bundle size that HeroUI avoids entirely with static CSS.

Summary Copy Chapter

For new projects in 2026, HeroUI's modern stack — React Aria accessibility, Tailwind CSS v4 static styling, compound component architecture, and first-party AI tooling — provides a stronger foundation for building production applications. If you're starting fresh, HeroUI is the clear choice.

Get Started with HeroUI Copy Chapter

Ready to try HeroUI? Check out the quick start guide to set up your first project in under five minutes. If you want to see components in action, browse the component docs or install the MCP server to let your AI assistant handle the boilerplate.

Apps Docs Content Blog En Heroui Vs Mantine (`apps/docs/content/blog/en/heroui-vs-mantine.mdx`) Copy Section

title: "HeroUI vs Mantine: Which React Component Library is Right for You in 2026?" date: "2026-05-15" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["comparison", "heroui", "mantine", "react"] draft: true Copy Chapter

HeroUI and Mantine are both modern, well-maintained React component libraries with genuine strengths. But they're built on very different philosophies. Mantine is a batteries-included toolkit with a very broad component and hooks catalog; Mantine's homepage currently describes it as 120+ components and 70+ hooks. HeroUI pairs React Aria's deep accessibility layer with Tailwind CSS v4 and a compound component API, plus first-party AI tooling through MCP, llms.txt, and agent skills.

This comparison breaks down the real differences — not just feature checklists, but the trade-offs that actually affect your daily development workflow.

Quick Comparison Copy Chapter

Component Coverage Copy Chapter

Mantine ships a large number of components across several packages, including a carousel, rich text editor, spotlight search, and notification system:

• @mantine/core — Buttons, inputs, modals, navigation, layout, typography
• @mantine/dates — Date pickers, calendars, date range inputs
• @mantine/charts — Charts built on Recharts
• @mantine/notifications — Toast notifications system
• @mantine/tiptap — Rich text editor
• @mantine/spotlight — Command palette / spotlight search
• @mantine/dropzone — File upload with drag-and-drop
• @mantine/carousel — Carousel / slider component
• @mantine/nprogress — Page loading progress bar

Mantine ships a large number of components, though breadth comes with trade-offs — larger bundle sizes, more APIs to learn, and components that may not all receive the same level of polish and accessibility testing.

HeroUI takes a more focused approach. The core library covers the essential component set — buttons, forms, modals, tables, navigation, data display — with depth rather than breadth. Components like Table support sorting, selection, column resizing, and infinite scrolling out of the box:

import { Table } from "@heroui/react";

<Table>
  <Table.ScrollContainer>
    <Table.Content aria-label="Users">
      <Table.Header>
        <Table.Column allowsSorting>Name</Table.Column>
        <Table.Column allowsSorting>Role</Table.Column>
        <Table.Column>Status</Table.Column>
      </Table.Header>
      <Table.Body>
        <Table.Row>
          <Table.Cell>Kate Moore</Table.Cell>
          <Table.Cell>Engineer</Table.Cell>
          <Table.Cell>Active</Table.Cell>
        </Table.Row>
      </Table.Body>
    </Table.Content>
  </Table.ScrollContainer>
</Table>

For charts, notifications, rich text editing, and other specialized needs, you'll combine HeroUI with dedicated libraries. This is a trade-off: more integration work, but you pick the best tool for each job.

Styling Approaches Copy Chapter

This is where the libraries diverge most sharply.

Mantine: CSS Modules + PostCSS Copy Section

Mantine uses CSS Modules for component styling. Each component has its own scoped CSS, and you customize components by targeting specific class selectors or using Mantine's classNames prop:

import { Button } from "@mantine/core";
import classes from "./MyButton.module.css";

<Button classNames={{ root: classes.root, label: classes.label }}>
  Click me
</Button>

This approach is familiar to anyone who's used CSS Modules. Styles are scoped, there's no runtime overhead, and you have direct access to override any part of a component. Mantine also supports a styles prop for inline style overrides and a global theme object for system-wide customization.

The downside is that you need to understand Mantine's internal class structure to customize deeply. Each component has its own set of "style names" (like root, label, inner for Button), and you need to reference the docs to know which ones to target.

HeroUI: Tailwind CSS v4 Copy Section

HeroUI components are styled with Tailwind CSS v4 utilities. You customize components the same way you style everything else in a Tailwind project — with className:

import { Button } from "@heroui/react";

<Button className="bg-gradient-to-r from-purple-500 to-pink-500 text-white shadow-lg">
  Click me
</Button>

For component sub-parts, HeroUI's compound component pattern lets you apply classes to any section:

import { Card } from "@heroui/react";

<Card className="max-w-md">
  <Card.Header className="pb-0">
    <Card.Title className="text-xl font-bold">Title</Card.Title>
    <Card.Description>Subtitle here</Card.Description>
  </Card.Header>
  <Card.Content className="py-4">
    Content goes here
  </Card.Content>
  <Card.Footer className="justify-end gap-2">
    <Button variant="ghost">Cancel</Button>
    <Button>Save</Button>
  </Card.Footer>
</Card>

Because each sub-component accepts className, you don't need to learn a separate styling API or memorize internal class name structures. If you know Tailwind, you know how to customize HeroUI.

The practical trade-off Copy Section

If your project already uses Tailwind CSS, HeroUI fits like a glove — there's no second styling system to learn. If your project uses CSS Modules or plain CSS, Mantine aligns more naturally with your existing approach. Adopting HeroUI without Tailwind means adopting Tailwind, which is a separate (and significant) decision.

Both approaches produce zero runtime CSS overhead. Neither ships CSS-in-JS to the browser.

Accessibility Copy Chapter

This is where the difference in architectural foundations becomes most apparent.

HeroUI: React Aria (Enterprise-Grade) Copy Section

HeroUI is built on React Aria, Adobe's accessibility primitive library. React Aria handles screen reader support, keyboard navigation, focus management, ARIA attributes, internationalization, and interaction patterns for every component.

React Aria is one of the most thoroughly tested accessibility layers available for React. It powers Adobe's Spectrum design system and handles details like keyboard behavior, focus management, screen reader announcements, touch interactions, and internationalization. Components like date pickers, comboboxes, and tables benefit from that depth in places most teams do not want to reimplement themselves.

Mantine: Good Built-In Accessibility Copy Section

Mantine has solid accessibility built into its components. WAI-ARIA attributes, keyboard navigation, and focus management are handled for common patterns. For the vast majority of applications, Mantine's accessibility is perfectly adequate.

The gap appears in complex, interaction-heavy components. Mantine doesn't use an external accessibility layer like React Aria or Radix — it implements accessibility in-house. This means the depth of testing and edge case coverage is necessarily narrower than a dedicated accessibility library backed by a company the size of Adobe.

When does this matter? Copy Section

If you're building consumer software where basic keyboard navigation and screen reader support are sufficient, both libraries will serve you well. If you're building for government, healthcare, finance, or any domain with strict WCAG compliance requirements, HeroUI's React Aria foundation provides a higher assurance level.

The Hooks Library Copy Chapter

Mantine also includes a utility hooks package (@mantine/hooks). HeroUI focuses on component quality and leverages the broader React ecosystem for utility hooks. The hooks package covers common categories like:

• Browser APIs: useClipboard, useFullscreen, useMediaQuery, useLocalStorage, useGeolocation
• UI patterns: useDisclosure, usePagination, useScrollIntoView, useHover
• Utilities: useDebounce, useThrottle, useInterval, useCounter, usePrevious
• State management: useListState, useSetState, useMap, useQueue

For similar utility hooks, you'd use community packages like usehooks-ts, or React Aria's hooks (which cover accessibility-related patterns like useFocusRing, usePress, and useSearchField). HeroUI focuses on components and leaves general-purpose utilities to the broader ecosystem.

If your team values having a single, cohesive dependency for both components and utility hooks, Mantine's integrated approach is appealing. If you prefer picking best-in-class tools for each concern, HeroUI's focused approach works better.

AI Tooling Copy Chapter

This is an area where HeroUI has invested heavily and Mantine hasn't.

HeroUI's AI developer tools Copy Section

HeroUI ships three first-class integrations for AI coding assistants:

• MCP server. A Model Context Protocol server that AI agents can query for component documentation, APIs, and usage examples. When your AI assistant is connected to this server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component in real time.

• llms.txt. A structured reference file at heroui.com/llms.txt that gives large language models a condensed, accurate reference for the entire library. This is a standardized format that AI tools can consume to avoid hallucinating APIs.

• Agent skills. Pre-built skill files for tools like Cursor and Claude Code that teach AI agents HeroUI's patterns — correct imports, compound component structures, styling conventions, and project scaffolding.

The result is that AI assistants have a better chance of generating current HeroUI code. They can use the correct compound component patterns (Modal.Header, Card.Content, Table.Row), the right import paths, and actual v3 APIs instead of guessing from mixed training data.

Mantine's AI story Copy Section

Mantine has strong AI-facing documentation too: its homepage documents llms.txt, skills, and @mantine/mcp-server. The practical difference is not "HeroUI has AI and Mantine does not." It is that HeroUI's AI context is specific to HeroUI's compound components, Tailwind v4 styling, and package API, while Mantine's context teaches Mantine's component and hooks ecosystem.

Why this matters in 2026 Copy Section

Most developers use AI assistants daily. When your component library has first-class AI tooling, agents can verify current APIs before writing code. That matters for both libraries.

Design Quality and Polish Copy Chapter

Both libraries ship good-looking defaults, but the design sensibilities are different.

HeroUI's defaults are more opinionated and "designed." Components ship with refined animations, carefully balanced spacing, smooth transitions, and attention to micro-interactions. Buttons have subtle press states. Modals animate in with spring physics. Cards have balanced padding and shadow hierarchies. The library includes theme variants (like "glass" and "brutalism") for distinct visual identities without custom CSS.

Mantine's defaults are clean and professional but more utilitarian. Components are well-proportioned and consistent, but they're designed to be a neutral starting point rather than a finished look. If you're planning to apply significant custom styling, this is actually an advantage — there's less opinionated design to override.

The trade-off is straightforward: HeroUI looks more polished out of the box with less effort. Mantine gives you a more neutral canvas to build on.

TypeScript Support Copy Chapter

Both libraries have excellent TypeScript support. Components are fully typed, props interfaces are well-documented, and autocomplete works as expected in modern editors.

HeroUI's compound component pattern means TypeScript can verify the structure of your component trees:

import { Tabs } from "@heroui/react";

<Tabs>
  <Tabs.ListContainer>
    <Tabs.List aria-label="Sections">
      <Tabs.Tab id="profile">Profile</Tabs.Tab>
      <Tabs.Tab id="settings">Settings</Tabs.Tab>
      <Tabs.Indicator />
    </Tabs.List>
  </Tabs.ListContainer>
  <Tabs.Panel id="profile">Profile content</Tabs.Panel>
  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
</Tabs>

Mantine provides equally strong types with a different API surface:

import { Tabs } from "@mantine/core";

<Tabs defaultValue="profile">
  <Tabs.List>
    <Tabs.Tab value="profile">Profile</Tabs.Tab>
    <Tabs.Tab value="settings">Settings</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="profile">Profile content</Tabs.Panel>
  <Tabs.Panel value="settings">Settings content</Tabs.Panel>
</Tabs>

No meaningful advantage either way. Both libraries take TypeScript seriously.

When to Choose Each Copy Chapter

Choose HeroUI if: Copy Section

• You're using Tailwind CSS v4 (or want to adopt it)
• Accessibility compliance is a hard requirement (healthcare, government, finance)
• You use AI coding assistants and want first-class tooling support
• You prefer compound component APIs with structural flexibility
• You want polished, animated defaults without heavy custom theming
• Performance matters and you want a Tailwind/static CSS path
• You're building with React 19 and want good server component compatibility

When Mantine might work Copy Section

Mantine can make sense if your team uses CSS Modules and doesn't want to adopt Tailwind CSS, or if you need a very broad set of built-in components including carousels, rich text editors, and notification systems. However, that breadth means a larger dependency footprint and more API surface to maintain.

Summary Copy Chapter

For teams building modern React applications, HeroUI's approach — React Aria accessibility, Tailwind CSS v4, compound components, and first-party AI tooling — delivers a more maintainable and performant foundation. HeroUI's focused component set means every component is deeply tested, fully accessible, and designed to work together seamlessly. For specialized needs beyond core UI, pairing HeroUI with dedicated libraries gives you better results than relying on one library to do everything.

Get Started with HeroUI Copy Chapter

Want to see how HeroUI works in practice? The quick start guide gets you set up in under five minutes. Explore the component docs for interactive examples, or connect the MCP server to your AI assistant for the best development experience.

Apps Docs Content Blog En Heroui Vs Mui (`apps/docs/content/blog/en/heroui-vs-mui.mdx`) Copy Section

title: "HeroUI vs Material UI (MUI): A Comprehensive Comparison for 2026" date: "2026-05-06" author: "Junior Garcia" authorHandle: "@jrgarciadev" authorUrl: "https://x.com/jrgarciadev" authorAvatar: "https://avatars.githubusercontent.com/u/30373425?v=4" tags: ["comparison", "heroui", "mui", "react"] image: "/images/blog/heroui-vs-mui.jpg" draft: true Copy Chapter

HeroUI and Material UI (MUI) represent two different generations of React component library design. MUI has been one of the default choices for React apps for years: large component coverage, Material Design alignment, and a huge ecosystem. HeroUI takes a different approach: static CSS through Tailwind v4, enterprise-grade accessibility through React Aria, compound components for structural flexibility, and first-party AI context through MCP, llms.txt, and agent skills.

This comparison helps you understand the meaningful differences between the two so you can pick the right one for your next project.

Architecture Overview Copy Chapter

HeroUI Copy Section

• Styling: Tailwind CSS v4 with Tailwind Variants
• Accessibility: React Aria (Adobe)
• Components: + with compound component pattern
• Design language: Neutral, customizable
• React version: Check the current peer dependency range for your installed HeroUI version
• Server Components: Static pieces can stay server-rendered; interactive pieces use client boundaries
• Package: @heroui/react

Material UI (MUI) Copy Section

• Styling: Emotion by default; Pigment CSS exists as an experimental zero-runtime path
• Accessibility: Custom ARIA implementation
• Components: 70+ (core) + MUI X premium components
• Design language: Material Design (Google)
• React version: Check the current peer dependency range for your installed MUI version
• Server Components: Depends on styling setup and component usage
• Package: @mui/material

Styling: Tailwind CSS vs Emotion / Pigment CSS Copy Chapter

This is the most consequential difference between the two libraries.

HeroUI: Tailwind CSS v4 Copy Section

HeroUI uses Tailwind CSS v4 for styling. Components are styled with utility classes, and customization happens through:

• Passing Tailwind classes via className props
• Overriding CSS custom properties (design tokens)
• Using Tailwind Variants for structured variant customization

<Button
  variant="secondary"
  className="font-semibold tracking-wide"
>
  Get Started
</Button>

Benefits:

• Zero runtime CSS overhead — all styles are static
• Tailwind's utility-first approach is familiar to most React developers in 2026
• CSS custom properties enable theming without JavaScript
• Server component compatible by default
• Token customization through standard CSS @theme

Trade-offs:

• Class strings can be verbose
• You need to understand Tailwind's utility vocabulary

MUI: Emotion by default, Pigment CSS experimental Copy Section

MUI's Material UI migration docs describe Emotion as the default styling engine. Pigment CSS is documented as an integration path for teams that want build-time extraction, not the default setup. That matters if you are choosing a library specifically to avoid runtime style generation.

<Button
  variant="contained"
  sx={{ fontWeight: 600, letterSpacing: '0.025em' }}
>
  Get Started
</Button>

Benefits:

• Familiar sx prop for one-off style overrides
• Structured theming through createTheme()
• A mature ecosystem of examples and theme recipes
• Full JavaScript expression support in styles

Trade-offs:

• The sx prop uses a custom DSL that's distinct from standard CSS
• Theme customization requires JavaScript configuration
• Emotion adds runtime styling work in the stable setup
• Pigment CSS is not the default stable path, so adopting it requires extra due diligence

Verdict Copy Section

If you're already using Tailwind CSS, HeroUI integrates naturally. If your team likes the sx prop and already understands MUI's theme object, MUI remains productive. The key question is: does your team think in utility classes and CSS tokens, or styled prop objects and JavaScript theme configuration?

Accessibility Copy Chapter

HeroUI: React Aria Copy Section

HeroUI builds on React Aria, Adobe's accessibility primitive library. Every component inherits:

• Platform-aware keyboard navigation (Mac, Windows, Linux differences)
• Comprehensive screen reader support (JAWS, NVDA, VoiceOver)
• Touch interaction handling
• Right-to-left layout support
• Locale-aware formatting (dates, numbers)
• Virtual focus for large collections
• Proper focus management (trapping, restoration)

React Aria is used in Adobe's own products (Photoshop Web, Acrobat, Lightroom), which means it's tested at massive scale with real users.

MUI: Custom Implementation Copy Section

MUI implements its own accessibility layer. The quality is generally good and has improved significantly over the years:

• ARIA roles and attributes on all components
• Keyboard navigation following WAI-ARIA patterns
• Focus management in dialogs and menus
• Screen reader announcements for dynamic content

However, MUI's accessibility implementation is less comprehensive than React Aria in several areas:

• Platform-specific behavior. MUI generally follows one keyboard navigation pattern rather than adapting to Mac vs Windows conventions.
• Touch interactions. Less sophisticated than React Aria's touch handling.
• Internationalization. MUI's i18n is primarily about string translation. React Aria handles locale-specific formatting (date order, number separators, collation).
• Virtual focus. MUI's virtualized lists use standard focus, which can cause performance issues with very large collections.

Verdict Copy Section

HeroUI has a clear accessibility advantage through React Aria. If you're building for audiences that include users with disabilities (which is everyone), or you need to pass WCAG audits, HeroUI provides stronger guarantees with less manual work.

Component Ecosystem Copy Chapter

HeroUI Core: + Components Copy Section

HeroUI ships + components covering:

• Layout (Card, Surface, Separator)
• Data Display (Table, Avatar, Badge, Chip, Tag)
• Data Input (Input, Textarea, NumberField, Select, ComboBox, Autocomplete, DatePicker, DateRangePicker, ColorPicker, Slider, Switch, Checkbox, Radio)
• Navigation (Tabs, Breadcrumbs, Pagination, Link)
• Feedback (Toast, ProgressBar, ProgressCircle, Meter, Spinner, Skeleton)
• Overlay (Modal, Drawer, Popover, Tooltip, Dropdown)
• Disclosure (Accordion, Disclosure)
• Actions (Button, ToggleButton, ToggleButtonGroup)

MUI Core: 70+ Components Copy Section

MUI's core library has slightly more components. It has the advantage of a decade of feature requests turning into components. You'll find things like:

• Speed Dial
• Stepper
• Masonry
• Timeline
• Transfer List

MUI X: Premium Components Copy Section

MUI X is MUI's premium component offering:

• Data Grid — Sorting, filtering, column pinning, row grouping, cell editing, lazy loading, tree data. This is MUI's strongest selling point for enterprise applications.
• Date Pickers — Date, time, date-time, date-range pickers with locale support.
• Charts — Line, bar, pie, scatter, and more.
• Tree View — Expandable tree with lazy loading.

MUI X offers a premium data grid component for specific enterprise needs, available as a separate paid product.

Verdict Copy Section

For most applications, both libraries cover the component needs. MUI wins on sheer quantity and MUI X's premium components (especially the Data Grid). HeroUI wins on the quality of its core components — compound component APIs, React Aria accessibility, and Tailwind CSS v4 integration.

Performance Copy Chapter

Bundle and runtime shape Copy Section

Exact bundle size depends on your imports, bundler, and route structure, so I avoid treating one static number as universal. The architecture still matters:

HeroUI tends to stay lean because:

• Tailwind CSS styles are static (no styling runtime)
• React Aria packages are modular
• Components expose explicit compound parts

MUI can carry more styling and theme machinery because:

• The stable setup uses Emotion
• The theme system and sx prop are central to the API
• MUI X adds powerful but separate premium packages when you need advanced data components

Runtime Performance Copy Section

HeroUI: All styles are resolved at build time. No runtime style calculation, injection, or hydration. Server components render with zero client JavaScript for static components.

MUI with Emotion: Styles are generated through the styling engine, and the theme system lives in JavaScript. This is flexible, but it is not the same runtime profile as static CSS.

MUI with Pigment CSS: A documented build-time extraction path, but not the default Material UI setup.

Server Components Copy Section

HeroUI: Static pieces like Card, Badge, Text, and Separator can stay in server component trees. Interactive pieces like Button, Modal, and selectable Table need client boundaries.

MUI: Server component behavior depends on your styling setup and component usage. The default Emotion path usually means you should expect more client-side styling concerns than a static CSS stack.

Verdict Copy Section

HeroUI is the cleaner fit when you want Tailwind CSS and static CSS as the default. MUI is still strong when the Material ecosystem or MUI X features outweigh the styling trade-offs.

Developer Experience Copy Chapter

Getting Started Copy Section

HeroUI:

npm install @heroui/styles @heroui/react

Add one CSS import. Start using components. Tailwind CSS handles styling.

MUI:

npm install @mui/material @emotion/react @emotion/styled

(Pigment CSS setup is separate and experimental.)

Wrap your app with ThemeProvider when you need MUI theming. Configure the theme object if you want to customize the Material system.

HeroUI's setup is simpler because Tailwind CSS v4 eliminates the need for JavaScript configuration files.

Customization Copy Section

HeroUI: Customize with Tailwind classes and CSS custom properties. Override design tokens in CSS. Use Tailwind Variants for component-level variant customization. Everything stays in CSS/Tailwind.

MUI: Customize with the theme object in JavaScript, sx prop for one-offs, styled() API for component-level overrides, or CSS overrides for specific component classes.

Documentation Copy Section

Both libraries have comprehensive documentation.

AI Tooling Copy Section

HeroUI ships structured AI tooling:

• MCP server for programmatic API access
• llms.txt for AI model context
• Agent skills for AI assistant integration

This means AI coding tools can generate correct HeroUI code without hallucinating props or patterns.

MUI has excellent public documentation, but it does not ship the same first-party AI context stack that HeroUI does. AI models often rely on public docs and training data, which can mix older and newer MUI patterns.

Design Language Copy Chapter

HeroUI: Neutral by Default Copy Section