SKILL.md

HeroUI Native Development Guide

HeroUI Native is a component library built on Uniwind (Tailwind CSS for React Native) and React Native, providing accessible, customizable UI components for mobile applications.

Installation

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

CRITICAL: Native Only - Do Not Use Web Patterns

This guide is for HeroUI Native ONLY. Do NOT apply HeroUI React (web) patterns — the package, styling engine, and color format all differ:

Feature

React (Web)

Native (Mobile)

Styling

Tailwind CSS v4

Uniwind (Tailwind for React Native)

Colors

oklch format

HSL format

Package

@heroui/react

heroui-native

Platform

Web browsers

iOS & Android

// CORRECT — Native pattern

import { Button } from "heroui-native";

<Button variant="primary" onPress={() => console.log("Pressed!")}>

	Click me

</Button>;

Always fetch Native docs before implementing.

Core Principles

Semantic variants (primary, secondary, tertiary) over visual descriptions

Composition over configuration (compound components)

Theme variables with HSL color format

React Native StyleSheet patterns with Uniwind utilities

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 theme variables

node scripts/get_theme.mjs

# Get non-component docs (guides, releases)

node scripts/get_docs.mjs /docs/native/getting-started/theming

Direct MDX URLs

Component docs: https://heroui.com/docs/native/components/{component-name}.mdx

Examples:

Button: https://heroui.com/docs/native/components/button.mdx

Dialog: https://heroui.com/docs/native/components/dialog.mdx

TextField: https://heroui.com/docs/native/components/text-field.mdx

Getting started guides: https://heroui.com/docs/native/getting-started/{topic}.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-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

Framework Setup (Expo - Recommended)

Install dependencies:

npx create-expo-app MyApp

cd MyApp

npm i heroui-native uniwind tailwindcss

npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

**Create global.css:**

@import "tailwindcss";

@import "uniwind";

@import "heroui-native/styles";

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

Wrap app with providers:

import { GestureHandlerRootView } from "react-native-gesture-handler";

import { HeroUINativeProvider } from "heroui-native";

import "./global.css";

export default function Layout() {

	return (

		<GestureHandlerRootView style={{ flex: 1 }}>

			<HeroUINativeProvider>

				<App />

			</HeroUINativeProvider>

		</GestureHandlerRootView>

	);

}

Critical Setup Requirements

Uniwind is Required - HeroUI Native uses Uniwind (Tailwind CSS for React Native)

HeroUINativeProvider Required - Wrap your app with HeroUINativeProvider

GestureHandlerRootView Required - Wrap with GestureHandlerRootView from react-native-gesture-handler

Use Compound Components - Components use compound structure (e.g., Card.Header, Card.Body)

Use onPress, not onClick - React Native uses onPress event handlers

Platform-Specific Code - Use Platform.OS for iOS/Android differences

Component Patterns

HeroUI Native uses compound component patterns. Each component has subcomponents accessed via dot notation.

Example - Card:

<Card>

	<Card.Header>{/* Icons, badges */}</Card.Header>

	<Card.Body>

		<Card.Title>Title</Card.Title>

		<Card.Description>Description</Card.Description>

	</Card.Body>

	<Card.Footer>{/* Actions */}</Card.Footer>

</Card>

Key Points:

Always use compound structure - don't flatten to props

Subcomponents are accessed via dot notation (e.g., Card.Header)

Native Card uses Card.Body (not Card.Content); Title and Description go inside Body

Fetch component docs for complete anatomy and examples

Semantic Variants

HeroUI uses semantic naming to communicate functional intent:

Variant

Purpose

Usage

primary

Main action to move forward

1 per context

secondary

Alternative actions

Multiple

tertiary

Dismissive actions (cancel, skip)

Sparingly

danger

Destructive actions

When needed

danger-soft

Soft destructive actions

Less prominent

ghost

Low-emphasis actions

Minimal weight

outline

Secondary actions

Bordered style

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

Theming

HeroUI Native uses CSS variables via Tailwind/Uniwind for theming. Theme colors are defined in global.css:

@theme {

	--color-accent: hsl(260, 100%, 70%);

	--color-accent-foreground: hsl(0, 0%, 100%);

}

Get current theme variables:

node scripts/get_theme.mjs

Access theme colors programmatically:

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

Theme switching (Light/Dark Mode):

import { Uniwind, useUniwind } from "uniwind";

const { theme } = useUniwind();

Uniwind.setTheme(theme === "light" ? "dark" : "light");

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

heroui-native