SkillsAdd

heroui-inc/heroui

heroui-migration

HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI.

All-time #3869 Trending #4598 Hot #4672 First seen Mar 17, 2026
8-week activity · all time api

Installation

$ npx skills add heroui-inc/heroui --skill heroui-migration
View on skills.sh ↗ GitHub repository ↗

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

agent-browser Shared topics
vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, includ…

810.4K installs
vercel-react-best-practices Shared topics
vercel-labs/agent-skills 697.8K installs
web-design-guidelines Shared topics
vercel-labs/agent-skills

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "chec…

617.3K installs
microsoft-foundry Shared topics
microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and …

576.5K installs
azure-rbac Shared topics
microsoft/azure-skills 489K installs
azure-hosted-copilot-sdk Shared topics
microsoft/azure-skills 440.4K installs

Also in this package

Other skills from heroui-inc/heroui.

npx skills add heroui-inc/heroui
heroui-react 10.6K heroui-native 9.6K

Browse all from heroui-inc/heroui

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 30.6K
License LICENSE
Default branch v3
Open issues 26
Status Active

Skill metadata

Parsed from SKILL.md frontmatter.

Version2.0.0
More metadata
author
heroui
version
2.0.0
status
preview

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 4,603 B
  • docs SUMMARY.md 239 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 3,500 installs

SKILL.md

HeroUI v2 to v3 Migration Guide

This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.

Installation

curl -fsSL https://heroui.com/install | bash -s heroui-migration

CRITICAL: Always Fetch Migration Docs Before Applying

Do NOT assume v2 patterns work in v3. Always fetch migration guides before implementing changes.

Key v2 → v3 Changes

Feature v2 (Migrate From) v3 (Migrate To)
Provider <HeroUIProvider> required No Provider needed
Component API Flat props: <Card title="x"> Compound: <Card><Card.Header>
Event handlers onClick onPress
Styling classNames prop className prop
Hooks useSwitch, useDisclosure, etc. Compound components, useOverlayState
Packages @heroui/system, @heroui/theme @heroui/react, @heroui/styles

Accessing Migration Documentation

For migration details, examples, and step-by-step guides, always fetch documentation:

Using Scripts

# List all available component migration guides
node scripts/list_migration_guides.mjs

# Get main migration workflow (full or incremental)
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental

# Get component-specific migration guides
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal

# Get styling migration guide
node scripts/get_styling_migration_guide.mjs

# Get hooks migration guide
node scripts/get_hooks_migration_guide.mjs

Direct URLs

Migration docs (preview): use a concrete guide URL from the examples below, and never fetch a URL that still contains a placeholder.

Examples:

  • Full migration: .../agent-guide-full.mdx
  • Incremental: .../agent-guide-incremental.mdx
  • Button: .../button.mdx
  • Styling: .../styling.mdx
  • Hooks: .../hooks.mdx

Override base URL with HEROUIMIGRATIONDOCS_BASE when docs are merged to production.

MCP Alternative

When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:

{
  "mcpServers": {
    "heroui-migration": {
      "url": "https://migration-mcp.heroui.com"
    }
  }
}

Migration Strategies

Full Migration

  • Best for: Projects that can dedicate focused time; teams comfortable with temporarily broken code
  • Migrate all component code first (project broken during migration)
  • Switch dependencies to v3
  • Complete styling migration

Incremental Migration

  • Best for: Projects that must stay functional; large codebases migrating gradually
  • Set up coexistence (pnpm aliases or component packages)
  • Migrate components one-by-one
  • Both v2 and v3 coexist during migration

Always fetch the agent guide before starting: node scripts/getmigrationguide.mjs full or incremental

Core Principles

  1. Fetch first: Use scripts to get migration guides before applying changes
  2. Compound components: v3 uses Card.Header, Card.Title, Button with children—not flat props
  3. No Provider: Remove HeroUIProvider when migrating
  4. onPress not onClick: All interactive components use onPress
  5. Workflow: Analyze → Migrate components → Switch deps → Styling migration

Migration Workflow Summary

  1. Create migration branch
  2. Analyze project (HeroUI imports, component usage)
  3. Fetch main guide: node scripts/getmigrationguide.mjs full
  4. Migrate components in batches (fetch component guides per batch)
  5. Switch dependencies to v3
  6. Fetch styling guide: node scripts/getstylingmigration_guide.mjs
  7. Apply styling updates

Preview Mode

This skill targets the staging deployment of the docs/migration branch. Once docs are merged to main and live on heroui.com, set HEROUIMIGRATIONDOCS_BASE=https://heroui.com/docs/react/migration or update the default in scripts.