/heroui-native

name: heroui-native
description: "HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind, mobile components."
metadata:
  author: heroui
  version: "2.0.1"

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)

1. **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

2. **Create `global.css`:**

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

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

3. **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

1. **Uniwind is Required** - HeroUI Native uses Uniwind (Tailwind CSS for React Native) 2. **HeroUINativeProvider Required** - Wrap your app with `HeroUINativeProvider` 3. **GestureHandlerRootView Required** - Wrap with `GestureHandlerRootView` from react-native-gesture-handler 4. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Body`) 5. **Use onPress, not onClick** - React Native uses `onPress` event handlers 6. **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`