HeroUI Native

A component library built on Tailwind v4 via Uniwind for React Native/Expo. Components come with smooth animations, polished details, and built-in accessibility.

Quick Start

1. Install

npm install heroui-native

2. Install Peer Dependencies

npm install react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@0.5.1 react-native-safe-area-context@~5.6.0 react-native-svg@15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5

3. Setup Uniwind

Follow Uniwind installation guide for Tailwind CSS in React Native.

4. Configure global.css

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";
@source './node_modules/heroui-native/lib';

5. Wrap App with Provider

import { HeroUINativeProvider } from "heroui-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

For Expo Router, wrap in app/_layout.tsx:

import { HeroUINativeProvider } from "heroui-native";
import { Stack } from "expo-router";

export default function RootLayout() {
  return (
    <HeroUINativeProvider>
      <Stack />
    </HeroUINativeProvider>
  );
}

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

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

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

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

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

Core Patterns

Compound Components

Components use dot notation for sub-components that work together:

import { Button, Dialog, Card } from 'heroui-native';

// Button with explicit label
<Button>
  <Button.Label>Click me</Button.Label>
</Button>

// Dialog with compound parts
<Dialog>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

// Card with sections
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>
    <Card.Title>Title</Card.Title>
    <Card.Description>Description</Card.Description>
  </Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

The asChild Prop

Merge component functionality into a custom child element:

<Dialog.Trigger asChild>
  <Button variant="primary">Open Dialog</Button>
</Dialog.Trigger>

Styling

Use className with Tailwind classes (via Uniwind):

<Button className="bg-accent px-6 py-3 rounded-lg">
  <Button.Label>Custom Button</Button.Label>
</Button>

Use render props for state-based styling:

<RadioGroup.Item value="opt1">
  {({ isSelected }) => (
    <RadioGroup.Label
      className={cn(
        "text-foreground",
        isSelected && "text-accent font-semibold",
      )}
    >
      Option 1
    </RadioGroup.Label>
  )}
</RadioGroup.Item>

Colors

Semantic color variables with automatic dark mode:

• bg-background, bg-surface, bg-overlay - backgrounds
• bg-accent, text-accent-foreground - brand colors
• bg-success, bg-warning, bg-danger - status colors
• text-foreground, text-muted - text colors

Available Components

For detailed component documentation, patterns, and props, see references/components.md.

Buttons

• Button - Interactive button with variants: primary, secondary, tertiary, ghost, danger, danger-soft

Forms

• TextField - Text input with label, description, error handling
• Checkbox - Toggle between checked/unchecked states
• RadioGroup - Single selection from options
• Switch - Toggle on/off states
• Select - Dropdown selection
• InputOTP - One-time password input
• FormField - Wrapper for consistent form layout
• Label, Description, ErrorView - Form helpers

Navigation

• Tabs - Tabbed views with animated transitions
• Accordion - Collapsible content panels

Overlays

• Dialog - Modal overlay with gestures
• Bottom Sheet - Slides up from bottom
• Popover - Floating content anchored to trigger
• Toast - Temporary notifications via useToast()

Feedback

• Spinner - Loading indicator
• Skeleton / SkeletonGroup - Loading placeholders

Layout

• Card - Container with Header, Body, Footer
• Surface - Elevation and background styling
• Divider - Visual separator

Media

• Avatar - User avatar with image, initials, or fallback

Data Display

• Chip - Compact capsule element

Utilities

• PressableFeedback - Visual press feedback
• ScrollShadow - Gradient shadows on scroll
• cn - Class name utility (from heroui-native)
• useThemeColor - Access theme colors programmatically