HeroUI Technical Reference - AI-Optimized

Critical Context

• Rebrand Warning: NextUI became HeroUI in January 2025 (corporate rebrand, same library)
• Migration Reality: Find-and-replace operation taking 30-60 minutes
• Current Version: v2.8.4 (September 2025)
• Bundle Impact: 15-30kb gzipped + mandatory 30kb+ Framer Motion dependency

Configuration That Works in Production

Installation & Setup

npx heroui-cli@latest init  # Preferred over manual config

Tailwind Config (Working Example)

const { heroui } = require("@heroui/react");

module.exports = {
  plugins: [
    heroui({
      themes: {
        light: { colors: { primary: "#0072f5", secondary: "#7828c8" } },
        dark: { colors: { primary: "#0072f5", secondary: "#9353d3" } }
      }
    })
  ]
};

Framework Compatibility

• Next.js: App Router + Pages Router (documented, tested)
• Vite: Works without surprises
• Remix/Astro: Functional but underdocumented

Critical Warnings & Failure Modes

Production Breaking Issues

1. Next.js 14.2 Dark Mode Failure

   • Symptom: White text on white background (invisible components)
   • Cause: Provider wrapper changed during Next.js upgrade
   • Impact: Complete UI failure, weekend debugging session
   • Solution: Check framework guide for provider placement

2. Framer Motion Dependency Trap

   • Reality: 30kb+ mandatory even without animations
   • False Promise: Claims of "lazy-loading" still include full Motion bundle
   • Detection: Use webpack-bundle-analyzer to verify chunk sizes

3. Import Strategy Critical

   • Bundle Killer: Global imports bloat bundle significantly
   • Required: Individual component imports for tree-shaking
   • Verification: Monitor bundle size during development

Component Coverage & Limitations

Available Components (~50 total)

• Forms: Input, Select, validation (works without external form libraries)
• Navigation: Navbar, Breadcrumbs, Tabs
• Data: Tables (basic CRUD, not complex data operations)
• Layout: Divider, Spacer (minimal - expect to build custom layouts)

Missing Components

• Complex data grids (requires TanStack Table integration)
• Advanced date/time pickers
• Specialized enterprise components

Performance Specifications

Bundle Size Reality

Component Set	Size (gzipped)	vs Competitors
Basic HeroUI	15-25kb	MUI: 50-80kb+
+ Framer Motion	+30kb	Unavoidable
vs CSS-in-JS libs	No runtime overhead	Emotion: Runtime injection penalty

Accessibility Implementation

• React Aria Integration: Real WCAG compliance, not marketing
• Keyboard Navigation: Tab, Enter, Arrow keys function correctly
• Screen Reader Support: Proper ARIA attributes, meaningful announcements
• Focus Management: Works with nested modals (audit-tested)
• Learning Curve: Requires understanding React Aria patterns vs simple onClick handlers

Resource Requirements

Development Time Investment

• Migration from NextUI: 30-60 minutes (find-and-replace)
• Migration from Chakra UI: 3-4 days (TypeScript error resolution)
• Accessibility Audit Fix: 2 hours for component swaps (vs weeks of custom implementation)
• Dark Mode Setup: Works out-of-box (vs afternoon of manual configuration)

Expertise Requirements

• Mandatory: Tailwind CSS knowledge (library assumes proficiency)
• Recommended: React Aria pattern understanding for custom components
• Optional: Framer Motion (if using animations)

Decision Support Matrix

Choose HeroUI When:

• Bundle size is critical concern
• Accessibility compliance required without expertise investment
• Tailwind CSS already in stack
• Need reliable TypeScript support
• Prefer CSS classes over CSS-in-JS runtime

Avoid HeroUI When:

• Need 100+ components out-of-box
• Bundle size irrelevant (enterprise constraints)
• Team unfamiliar with Tailwind
• Require complex data grid functionality
• Cannot accept 30kb+ Motion dependency

Competitive Analysis

Factor	HeroUI	Material-UI	Chakra UI	Ant Design
Bundle Size	15-30kb + Motion	50-80kb+	~40kb	100kb+
Runtime Overhead	None (CSS)	CSS-in-JS injection	CSS-in-JS injection	CSS-in-JS injection
Accessibility	React Aria (excellent)	Inconsistent	Basic ARIA	Basic ARIA
Component Count	~50	100+	~40	200+
TypeScript Quality	Native support	Good	Good	Adequate
Learning Curve	Easy (if Tailwind known)	Steep	Easy	Medium

Community & Support Indicators

• GitHub Activity: 26k+ stars, maintainer responsive
• Release Frequency: Regular updates
• Community Health: Active Discord, responsive GitHub discussions
• Migration Support: NextUI community successfully migrated
• Sustainability: Open Collective funding, transparent development

Common Troubleshooting

Import Errors During Migration

# Change package references
@nextui-org/* → @heroui/*

Bundle Analysis Commands

npm install --save-dev webpack-bundle-analyzer
# Check for Motion chunks in analysis

Dark Mode Provider Issues

• Verify provider wrapper placement after Next.js upgrades
• Check framework-specific integration guides

Resource Links for Implementation

• Documentation - Actually functional examples
• GitHub - Active issue tracking
• Discord - Fast community support
• Migration Guide - NextUI transition
• Tailwind Variants - Theming system understanding
• React Aria Docs - Accessibility patterns

Breaking Points & Thresholds

• Component Count: ~50 available, insufficient for complex enterprise apps
• Bundle Tolerance: 30kb+ Motion overhead non-negotiable
• Framework Support: Next.js/Vite well-documented, others require configuration research
• Customization Limits: Constrained by Tailwind ecosystem, extensive custom styling may require alternative solutions