agentskills.codes
HE

heroui-react

by heroui-incCodingSource

Develop accessible React interfaces using the HeroUI v3 component library built on Tailwind CSS v4.

FrontendUI designReactTailwind

Install

mkdir -p .claude/skills/heroui-react && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/6803" && unzip -o skill.zip -d .claude/skills/heroui-react && rm skill.zip

Installs to .claude/skills/heroui-react

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles.
313 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Install HeroUI v3 components
  • →Configure themes using oklch variables
  • →Implement compound components like Card.Header
  • →Fetch component documentation and source code
  • →Apply semantic variants for UI consistency

How it works

The skill provides scripts to fetch documentation and enforces v3-specific patterns like compound components and CSS variable-based theming.

Inputs & outputs

You give it
Component name or theme request
You get back
Code implementation or documentation

When to use heroui-react

  • →Install HeroUI v3
  • →Build UI components
  • →Configure themes with oklch
  • →Access component documentation

About this skill

HeroUI v3 React Development Guide

HeroUI v3 is a component library built on Tailwind CSS v4 and React Aria Components, providing accessible, customizable UI components for React applications.

Installation

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

CRITICAL: v3 Only - Ignore v2 Knowledge

This guide is for HeroUI v3 ONLY. Do NOT apply v2 patterns — the provider, styling, and component API all changed:

Featurev2 (DO NOT USE)v3 (USE THIS)
Provider<HeroUIProvider> requiredNo Provider needed
Animationsframer-motion packageCSS-based, no extra deps
Component APIFlat props: <Card title="x">Compound: <Card><Card.Header>
StylingTailwind v3 + @heroui/themeTailwind v4 + @heroui/styles
Packages@heroui/system, @heroui/theme@heroui/react, @heroui/styles
// DO NOT DO THIS - v2 pattern
import { HeroUIProvider } from "@heroui/react";
import { motion } from "framer-motion";

<HeroUIProvider>
	<Card title="Product" description="A great product" />
</HeroUIProvider>;

CORRECT (v3 patterns)

// DO THIS - v3 pattern (no provider, compound components)
import { Card } from "@heroui/react";

<Card>
	<Card.Header>
		<Card.Title>Product</Card.Title>
		<Card.Description>A great product</Card.Description>
	</Card.Header>
</Card>;

Always fetch v3 docs before implementing.

Core Principles

  • Semantic variants (primary, secondary, tertiary) over visual descriptions
  • Composition over configuration (compound components)
  • CSS variable-based theming with oklch color space
  • BEM naming convention for predictable styling

Accessing Documentation & Component Information

For component details, examples, props, and implementation patterns, always fetch documentation:

Using Scripts

# List all available components
node scripts/list_components.mjs

# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# Get component source code
node scripts/get_source.mjs Button

# Get component CSS styles (BEM classes)
node scripts/get_styles.mjs Button

# Get theme variables
node scripts/get_theme.mjs

# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/react/getting-started/theming

Direct MDX URLs

Component docs: fetch .mdx with a concrete kebab-case slug. Run node scripts/list_components.mjs when the slug is unknown, and never fetch a URL that still contains a placeholder.

Examples:

  • Button: https://heroui.com/docs/react/components/button.mdx
  • Modal: https://heroui.com/docs/react/components/modal.mdx
  • Form: https://heroui.com/docs/react/components/form.mdx

Getting started guides: use a concrete topic URL such as https://heroui.com/docs/react/getting-started/quick-start.mdx.

Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.

Installation Essentials

Quick Install

npm i @heroui/styles @heroui/react tailwind-variants

Framework Setup (Next.js App Router - Recommended)

  1. Install dependencies:
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
  1. Create/update app/globals.css:
/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";

/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";
  1. Import in app/layout.tsx:
import "./globals.css";

export default function RootLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<html lang="en" suppressHydrationWarning>
			<body>
				{/* No Provider needed in HeroUI v3! */}
				{children}
			</body>
		</html>
	);
}
  1. Configure PostCSS (postcss.config.mjs):
export default {
	plugins: {
		"@tailwindcss/postcss": {},
	},
};

Critical Setup Requirements

  1. Tailwind CSS v4 is MANDATORY - HeroUI v3 will NOT work with Tailwind CSS v3
  2. Use Compound Components - Components use compound structure (e.g., Card.Header, Card.Content)
  3. Use onPress, not onClick - For better accessibility, use onPress event handlers
  4. Import Order Matters - Always import Tailwind CSS before HeroUI styles

Component Patterns

All components use the compound pattern shown above (dot-notation subcomponents like Card.Header, Card.Content). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.

Semantic Variants

HeroUI uses semantic naming to communicate functional intent:

VariantPurposeUsage
primaryMain action to move forward1 per context
secondaryAlternative actionsMultiple
tertiaryDismissive actions (cancel, skip)Sparingly
dangerDestructive actionsWhen needed
ghostLow-emphasis actionsMinimal weight
outlineSecondary actionsBordered style

Don't use raw colors - semantic variants adapt to themes and accessibility.

Theming

HeroUI v3 uses CSS variables with oklch color space:

:root {
	--accent: oklch(0.6204 0.195 253.83);
	--accent-foreground: var(--snow);
	--background: oklch(0.9702 0 0);
	--foreground: var(--eclipse);
}

Get current theme variables:

node scripts/get_theme.mjs

Color naming:

  • Without suffix = background (e.g., --accent)
  • With -foreground = text color (e.g., --accent-foreground)

Theme switching:

<html class="dark" data-theme="dark"></html>

For detailed theming, fetch: https://heroui.com/docs/react/getting-started/theming.mdx

When not to use it

  • →When using Tailwind CSS v3
  • →When using v2 HeroUI patterns

Prerequisites

Tailwind CSS v4React environment

Limitations

  • →Requires Tailwind CSS v4
  • →Does not support v2 component APIs

How it compares

It strictly enforces v3 architecture, preventing the use of legacy v2 providers and flat prop structures.

Compared to similar skills

heroui-react side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
heroui-react (this skill)34moReviewIntermediate
screenshot-to-code2042moNo flagsBeginner
web-artifacts-builder493moReviewIntermediate
frontend-ui-dark-ts43moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

More by heroui-inc

View all by heroui-inc →

heroui-native

heroui-inc

HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when working with HeroUI Native components, installing HeroUI Native, customizing themes, or accessing component documentation. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind.

535

You might also like

screenshot-to-code

OneWave-AI

Convert UI screenshots into working HTML/CSS/React/Vue code. Detects design patterns, components, and generates responsive layouts. Use this when users provide screenshots of websites, apps, or UI designs and want code implementation.

204389

web-artifacts-builder

anthropics

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

49162

frontend-ui-dark-ts

microsoft

Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces with a refined dark aesthetic.

430

gaming-ui-state-management

TheOrcDev

Patterns for game-like interfaces - health bars, XP bars, mana bars. Apply when building RPG/retro gaming UI components with state-driven visuals.

218

designer-skills

llama-farm

Designer subsystem patterns for LlamaFarm. Covers React 18, TanStack Query, TailwindCSS, and Radix UI.

68

retro-css-architecture

TheOrcDev

Organize 8-bit CSS with custom properties, pixel fonts, and responsive pixel art. Apply when creating or modifying retro-styled components and their CSS.

13

Search skills

Search the agent skills registry