Quick Start

Choose the path that fits your project:

• Option 1 — Scaffold a new, preconfigured project with our CLI. Zero setup.
• Option 2 — Add HeroUI Native to an existing React Native or Expo project.

Option 1: Create a New Project

The fastest way to start. The CLI scaffolds an Expo project with HeroUI Native, all required peer dependencies, Uniwind / Tailwind CSS, global styles, and the HeroUINativeProvider already wired up — so you can jump straight to building.

npx create-heroui-native-app@latest

pnpm create heroui-native-app@latest

yarn create heroui-native-app

bun create heroui-native-app@latest

Follow the interactive prompts, then start the dev server:

cd my-app
npm run start

You're ready to build. Skip ahead to Use Your First Component or browse components.

Option 2: Add to an Existing Project

If you already have a React Native or Expo app, follow these steps to install and configure HeroUI Native manually.

1. Install HeroUI Native

npm install heroui-native

pnpm add heroui-native

yarn add heroui-native

bun add heroui-native

2. Install Mandatory Peer Dependencies

npm install 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

pnpm add 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

yarn add 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

bun add 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

3. Optional Dependencies

These packages are only needed if you use specific components or features:

4. Set Up Uniwind

Follow the Uniwind installation guide to set up Tailwind CSS for React Native.

If you're migrating from NativeWind, see the migration guide.

5. Configure global.css

Inside your global.css file add the following imports:

@import 'tailwindcss';
@import 'uniwind';

@import 'heroui-native/styles';

/* Path to the heroui-native lib inside node_modules relative to global.css */
/* Examples:
 *   - If global.css is at project root: ./node_modules/heroui-native/lib
 *   - If global.css is in app/: ../node_modules/heroui-native/lib
 *   - If global.css is in src/styles/: ../../node_modules/heroui-native/lib
 */
@source './node_modules/heroui-native/lib';

6. Wrap Your App with Provider

Wrap your application with HeroUINativeProvider. You must wrap it with GestureHandlerRootView:

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

Note: For advanced configuration options including text props, animation settings, and toast configuration, see the Provider documentation.

Use Your First Component

import { Button } from 'heroui-native';
import { View } from 'react-native';

export default function MyComponent() {
  return (
    <View className="flex-1 justify-center items-center bg-background">
      <Button onPress={() => console.log('Pressed!')}>Get Started</Button>
    </View>
  );
}

Reduce Bundle Size with Granular Exports

If you want to reduce bundle size and import only the components you need, our library provides granular exports for each component:

// Granular imports - use when you need only a few components
import { HeroUINativeProvider } from "heroui-native/provider";
import { Button } from "heroui-native/button";
import { Card } from "heroui-native/card";

// General import - imports the whole library, use when you're using many components
import { Button, Card } from "heroui-native";

Granular imports are ideal when you only need a few components, as they help keep your bundle size smaller. General imports from heroui-native will include the entire library, which is convenient when you're using many components throughout your app.

Available granular exports:

• heroui-native/provider - Provider component
• heroui-native/provider-raw - Lightweight provider (keeps bare minimum to start)
• heroui-native/[component-name] - Individual components
• heroui-native/portal - Portal utilities
• heroui-native/toast - Toast provider and utilities
• heroui-native/utils - Utility functions
• heroui-native/hooks - Custom hooks

Tip: For even more control over your bundle, consider using HeroUINativeProviderRaw — a lightweight provider that excludes ToastProvider and PortalHost.

What's Next?

• HeroUI Native Provider
• Styling Guide
• Theming Documentation

Running on Web (Expo)