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 use any prior knowledge of HeroUI React (web) patterns.

What Changed in Native

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

WRONG (React web patterns)

tsx

// DO NOT DO THIS - React web pattern
import { Button } from "@heroui/react";
import "./styles.css"; // CSS files don't work in React Native

<Button className="bg-blue-500">Click me</Button>;

CORRECT (Native patterns)

tsx

// DO THIS - Native pattern (Uniwind, React Native components)
import { Button } from "heroui-native";

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

Always fetch Native docs before implementing. Do not assume React web patterns work.

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

bash

# 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

bash

npm i heroui-native

Required Peer Dependencies

bash

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

Framework Setup (Expo - Recommended)

Install dependencies:

bash

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
:

css

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

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

Wrap app with providers:

tsx

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:

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Body>{/* Content */}</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
```
)
Each subcomponent may have its own props
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

css

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

Get current theme variables:

bash

node scripts/get_theme.mjs

Access theme colors programmatically:

tsx

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

Theme switching (Light/Dark Mode):

tsx

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

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 use any prior knowledge of HeroUI React (web) patterns.

What Changed in Native

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

WRONG (React web patterns)

tsx

// DO NOT DO THIS - React web pattern
import { Button } from "@heroui/react";
import "./styles.css"; // CSS files don't work in React Native

<Button className="bg-blue-500">Click me</Button>;

CORRECT (Native patterns)

tsx

// DO THIS - Native pattern (Uniwind, React Native components)
import { Button } from "heroui-native";

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

Always fetch Native docs before implementing. Do not assume React web patterns work.

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

bash

# 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

bash

npm i heroui-native

Required Peer Dependencies

bash

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

Framework Setup (Expo - Recommended)

Install dependencies:

bash

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
:

css

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

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

Wrap app with providers:

tsx

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:

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Body>{/* Content */}</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
```
)
Each subcomponent may have its own props
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

css

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

Get current theme variables:

bash

node scripts/get_theme.mjs

Access theme colors programmatically:

tsx

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

Theme switching (Light/Dark Mode):

tsx

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

heroui-native

NPX Install

Tags

SKILL.md Content

HeroUI Native Development Guide

CRITICAL: Native Only - Do Not Use Web Patterns

What Changed in Native

WRONG (React web patterns)

CORRECT (Native patterns)

Core Principles

Accessing Documentation & Component Information

Using Scripts

Direct MDX URLs

Installation Essentials

Quick Install

Required Peer Dependencies

Framework Setup (Expo - Recommended)

Critical Setup Requirements

Component Patterns

Semantic Variants

Theming

heroui-native

NPX Install

Tags

SKILL.md Content

HeroUI Native Development Guide

CRITICAL: Native Only - Do Not Use Web Patterns

What Changed in Native

WRONG (React web patterns)

CORRECT (Native patterns)

Core Principles

Accessing Documentation & Component Information

Using Scripts

Direct MDX URLs

Installation Essentials

Quick Install

Required Peer Dependencies

Framework Setup (Expo - Recommended)

Critical Setup Requirements

Component Patterns

Semantic Variants

Theming