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) // DO NOT DO THIS - React web pattern import { Button } from "@heroui/react"; import "./styles.css"; // CSS files don't work in React Native

Click me;

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

console.log("Pressed!")}> Click me ;

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

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

Required Peer Dependencies 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: 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 ( ); }

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:

Title Description {/ Content /} {/ Actions /}

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:

@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