---
title: "HeroUI Skills for Claude Code: React, Native and v3"
canonical: https://skillselion.com/guides/heroui-skills-claude-code
content_type: text/markdown
description: "The best HeroUI skill for Claude Code is the official heroui-react (12,973 installs), which stops the agent from writing HeroUI v2 code into a v3 project."
---

# HeroUI Skills for Claude Code: React, Native and v3 Migration

Title: HeroUI Skills for Claude Code: React, Native and v3

> The best HeroUI skill for Claude Code is the official heroui-react (12,973 installs), which stops the agent from writing HeroUI v2 code into a v3 project.

Canonical: https://skillselion.com/guides/heroui-skills-claude-code

The best HeroUI skill for Claude Code is the official heroui-react (12,973 installs), which stops the agent from writing HeroUI v2 code into a v3 project. heroui-native (11,496 installs) covers React Native through Uniwind, and heroui-migration (4,590 installs) moves a v2 app to v3.

## Key facts

- Last updated: November 10, 2026

## Article

HeroUI v3 changed almost everything an agent remembers about it: no provider, compound components, Tailwind CSS v4 and CSS animations instead of framer-motion. The official [heroui-react skill from HeroUI](/skills/heroui-inc/heroui/heroui-react) (12,973 installs, 31,278 GitHub stars) exists to stop Claude Code from writing v2 code into a v3 project.

## Key takeaways

- heroui-react (12,973 installs) opens with a v2-vs-v3 table and an explicit order to ignore v2 knowledge before the agent writes any component.
- [heroui-native](/skills/heroui-inc/heroui/heroui-native) (11,496 installs) covers the React Native library, which styles with Uniwind and HSL colors instead of Tailwind v4 and oklch.
- [heroui-migration](/skills/heroui-inc/heroui/heroui-migration) (4,590 installs) is still marked preview and walks a v2 app to v3 either in one pass or component by component.
- All three skills ship from the main heroui-inc/heroui repo (31,278 GitHub stars), so they move with the library itself.
- The skills tell the agent to fetch the component's MDX docs before writing code. The [frontend and design category](/category/frontend-design) lists other UI library skills.

## Why does Claude Code get HeroUI wrong without a skill?

It writes HeroUI v2. The v2 API wrapped the app in `<HeroUIProvider>`, used flat props such as `<Card title="x">`, imported `framer-motion` for animation and styled through `@heroui/theme` on Tailwind v3. HeroUI v3 drops the provider, moves to compound components like `<Card.Header>` and `<Card.Title>`, and ships styles as `@heroui/styles` on Tailwind CSS v4. A v3 project needs the v3 imports, props and styles throughout. The heroui-react skill (12,973 installs, skills.sh registry) puts that difference in a table at the top of its instructions, so the agent sees it before it writes a single import.

## What is the best HeroUI skill for Claude Code?

heroui-react is the one to install for web projects. It is maintained by the HeroUI team, has 12,973 installs and sits in a repo with 31,278 GitHub stars (skills.sh registry, GitHub). Install it with:

`npx skills add https://github.com/heroui-inc/heroui --skill heroui-react`

![HeroUI organization avatar on GitHub](https://github.com/heroui-inc.png?size=200)

The skill bundles small Node scripts that the agent runs instead of guessing: `list_components.mjs`, `get_component_docs.mjs Button Card TextField`, `get_source.mjs`, `get_styles.mjs` for the BEM classes and `get_theme.mjs` for theme variables. It also lists the direct MDX URLs for every component page on [the HeroUI docs](https://heroui.com/docs/react/getting-started). Its stated principles are semantic variants (`primary`, `secondary`, `tertiary`) over visual names, composition over configuration, oklch CSS variables for theming and BEM class names. The recommended setup is Next.js App Router with `@heroui/styles`, `@heroui/react` and `tailwind-variants`.

## How do you build a React Native app with HeroUI and Claude Code?

Use heroui-native, not heroui-react. heroui-native has 11,496 installs (skills.sh registry) and starts with its own warning table: web patterns do not apply, the package is `heroui-native`, styling runs through Uniwind and theme colors use HSL instead of oklch. Its Expo setup installs Reanimated, Gesture Handler, Safe Area Context, `@gorhom/bottom-sheet` and `react-native-svg`, then wraps the app in `HeroUINativeProvider`. That provider is correct on mobile even though the web library dropped its own. For the rest of a mobile stack, see the [Expo mobile UI guide](/guides/how-to-build-mobile-ui-expo-claude-code-2026).

## How do you migrate a HeroUI v2 app to v3 with an agent?

Install heroui-migration (4,590 installs) and pick a strategy before the agent touches a file. The skill offers two. A full migration converts all component code first, switches dependencies, then migrates styling, and accepts a broken build in between. An incremental migration keeps v2 and v3 side by side with pnpm aliases and moves one component at a time. Either way the agent fetches the migration guide first with `get_migration_guide.mjs full` or `incremental`. The skill lists the renames that break most often: `onClick` becomes `onPress`, the `classNames` prop becomes `className`, and hooks such as `useDisclosure` give way to compound components and `useOverlayState`.

## Should you choose HeroUI or shadcn/ui for an AI-built UI?

Choose by ownership model. HeroUI is a dependency you install and theme, while shadcn/ui copies component source into your repo. The official [shadcn skill](/skills/shadcn/ui/shadcn) has 271,099 installs against 12,973 for heroui-react (skills.sh registry), so shadcn has far more agent usage today. Both sit on accessible primitives: HeroUI v3 builds on React Aria Components, and Adobe publishes its own [react-aria skill](/skills/react-aria.adobe.com/react-aria) (3,024 installs) for teams that want unstyled parts. The [shadcn/ui design hub](/design/shadcn-ui) and the [best shadcn/ui skills guide](/guides/best-shadcn-ui-skills-for-claude-code) cover the other path.

## A complete starter stack

- heroui-react (12,973 installs): v3 components, theming and docs scripts for web apps.
- heroui-native (11,496 installs): the same library for iOS and Android through Expo.
- heroui-migration (4,590 installs): only while you still have v2 code to move.
- react-aria (3,024 installs): for custom components HeroUI does not ship.

## Common pitfalls

- Letting the agent add `<HeroUIProvider>` to a v3 web app. The heroui-react table marks it as the first v2 pattern to avoid.
- Installing heroui-react in a React Native project. The two skills use different packages and color formats (oklch on web, HSL on native), so the wrong skill points the agent at the wrong package and theme format.
- Running a v2 to v3 migration without choosing a strategy. heroui-migration is still a preview skill, and its full mode leaves the build broken until every component moves.

Install the skill that matches your platform, then browse the [best frontend and design skills](/best/skills-for-frontend-design) for the rest of the UI stack.

## Related

- [/best/skills-for-frontend-design](https://skillselion.com/best/skills-for-frontend-design)
- [/category/frontend-design](https://skillselion.com/category/frontend-design)
- [/design/shadcn-ui](https://skillselion.com/design/shadcn-ui)
- [/design/ui-design](https://skillselion.com/design/ui-design)
- [/design/css-tailwind](https://skillselion.com/design/css-tailwind)
- [/guides/best-shadcn-ui-skills-for-claude-code](https://skillselion.com/guides/best-shadcn-ui-skills-for-claude-code)

## FAQ

### Is there an official HeroUI skill for Claude Code?

Yes. HeroUI publishes heroui-react (12,973 installs), heroui-native and heroui-migration from its main repo (31,278 GitHub stars). See [heroui-react](/skills/heroui-inc/heroui/heroui-react).

### How do I install the HeroUI skill?

Run `npx skills add https://github.com/heroui-inc/heroui --skill heroui-react` in your project. heroui-react has 12,973 installs. Swap the skill name for heroui-native (11,496 installs) or heroui-migration (4,590 installs). More UI library skills are on the [best frontend and design skills](/best/skills-for-frontend-design) page.

### Does the HeroUI skill support HeroUI v3?

Yes. heroui-react (12,973 installs) is written for v3 only and tells the agent to ignore v2 patterns such as HeroUIProvider and flat props. See [heroui-react](/skills/heroui-inc/heroui/heroui-react).

### Is there a HeroUI skill for React Native?

Yes. heroui-native (11,496 installs) covers HeroUI Native with Uniwind, HSL theme colors and an Expo setup. See [heroui-native](/skills/heroui-inc/heroui/heroui-native).

### How do I migrate HeroUI v2 to v3 with Claude Code?

Install heroui-migration (4,590 installs) and choose a full or incremental migration. It renames onClick to onPress and classNames to className. See [heroui-migration](/skills/heroui-inc/heroui/heroui-migration).

## Machine access

- [Sitemap](https://skillselion.com/sitemap.xml)
- [llms.txt](https://skillselion.com/llms.txt)
- [llms-full.txt](https://skillselion.com/llms-full.txt)
- [Developer resources](https://skillselion.com/developers)
- [OpenAPI spec](https://skillselion.com/openapi.json)
- [MCP handshake](https://skillselion.com/.well-known/mcp)
- [API catalog](https://skillselion.com/.well-known/api-catalog)
- [AI catalog](https://skillselion.com/.well-known/ai-catalog.json)
- [Pricing](https://skillselion.com/pricing.md)
- [Auth](https://skillselion.com/auth.md)
- [AGENTS.md](https://skillselion.com/AGENTS.md)
- [Contact](https://skillselion.com/contact)
- [Home](https://skillselion.com/)
