HeroUI Native Development Guide

CRITICAL: Native Only - Do Not Use Web Patterns

What Changed in Native

WRONG (React web patterns)

Copy
// 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)`
// DO THIS - Native pattern (Uniwind, React Native components)
import { Button } from "heroui-native";

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

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

Using Scripts

Copy
# 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

• 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

Installation Essentials

Quick Install

Required Peer Dependencies

Framework Setup (Expo - Recommended)

1. Install dependencies:

Copy
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

Copy
<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>

• 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

Theming

Copy
@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");