---

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: "1.0.0"

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.

---

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@beta | 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://v3.heroui.com/docs/native/components/{component-name}.mdx

Examples:

• Button: https://v3.heroui.com/docs/native/components/button.mdx
• Dialog: https://v3.heroui.com/docs/native/components/dialog.mdx
• TextField: https://v3.heroui.com/docs/native/components/text-field.mdx

Getting started guides: https://v3.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

CRITICAL: HeroUI Native is currently in BETA.

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

All components use the compound pattern with dot-notation subcomponents (e.g., Card.Header, Card.Body, Card.Footer). 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:

| 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://v3.heroui.com/docs/native/getting-started/theming.mdx