---
title: Quick Start
description: Get up and running with HeroUI Native
icon: rocket
---

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.

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npx create-heroui-native-app@latest
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create heroui-native-app@latest
    ```
  </Tab>
  <Tab value="yarn">
    ```bash
    yarn create heroui-native-app
    ```
  </Tab>
  <Tab value="bun">
    ```bash
    bun create heroui-native-app@latest
    ```
  </Tab>
</Tabs>

Follow the interactive prompts, then start the dev server:

```bash
cd my-app
npm run start
```

You're ready to build. Skip ahead to [Use Your First Component](#use-your-first-component) or [browse components](/docs/native/components).

<Callout type="info">
  The scaffold includes Expo with TypeScript, Uniwind + Tailwind CSS preconfigured, `global.css` with the required imports, and the app entry already wrapped in `GestureHandlerRootView` and `HeroUINativeProvider`.
</Callout>

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

<CopyPrompt
  prompt={`Set up HeroUI Native in this React Native project.

Use the HeroUI Native MCP server (@heroui/native-mcp) as the single source of truth for installation steps, peer dependencies, and component APIs. Start by retrieving the latest quick-start / installation guide from the MCP and follow it precisely — do not rely on memory for versions, package names, or setup steps.

Before making any changes:

1. Analyze the project. Detect the package manager (npm / pnpm / yarn / bun), framework (Expo or bare React Native), TypeScript usage, and the location of node_modules. This matters for global.css — the @source path must be written relative to global.css itself and must resolve to node_modules/heroui-native/lib.
2. Read package.json and only install what is missing. Pin to the exact versions listed in the MCP quick-start to avoid compatibility issues.
3. Inspect the app entry (App.tsx, app/_layout.tsx, index.tsx, etc.) and check whether GestureHandlerRootView already wraps the app. If it does, reuse it — do not nest a second GestureHandlerRootView.

Then apply the setup:

- Install heroui-native plus any missing mandatory+optional peer dependencies.
- Set up Uniwind + Tailwind CSS (follow the Uniwind quickstart) and add the HeroUI Native imports plus the correct @source line to global.css.
- Make sure GestureHandlerRootView wraps the entire app — it must be the outermost wrapper with style { flex: 1 }.
- Add HeroUINativeProvider as a direct child of GestureHandlerRootView, wrapping the rest of the app.

When done, summarize the changes you made and tell me how to run the app on iOS / Android.`}
>
  **Prefer to let your AI assistant do it?** Install the [HeroUI Native MCP Server](/docs/native/getting-started/mcp-server) in your editor, then paste the prompt into your AI assistant — it will analyze your project and handle the entire setup for you.
</CopyPrompt>

### 1. Install HeroUI Native

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm install heroui-native
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm add heroui-native
    ```
  </Tab>
  <Tab value="yarn">
    ```bash
    yarn add heroui-native
    ```
  </Tab>
  <Tab value="bun">
    ```bash
    bun add heroui-native
    ```
  </Tab>
</Tabs>

### 2. Install Mandatory Peer Dependencies

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    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
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    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
    ```
  </Tab>
  <Tab value="yarn">
    ```bash
    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
    ```
  </Tab>
  <Tab value="bun">
    ```bash
    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
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  It's recommended to use the exact versions specified above to avoid compatibility issues. Version mismatches may cause unexpected bugs.
</Callout>

### 3. Optional Dependencies

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

| Package | Version | Required for |
| --- | --- | --- |
| `react-native-screens` | `^4.16.0` | BottomSheet, Dialog, Menu, Popover, Select, Toast |
| `@gorhom/bottom-sheet` | `^5.2.9` | BottomSheet, Menu / Popover / Select when `presentation="bottom-sheet"` |

### 4. Set Up Uniwind

Follow the [Uniwind installation guide](https://docs.uniwind.dev/quickstart) to set up Tailwind CSS for React Native.

If you're migrating from NativeWind, see the [migration guide](https://docs.uniwind.dev/migration-from-nativewind).

### 5. Configure global.css

Inside your `global.css` file add the following imports:

```css
@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
 */
/* Not required starting from heroui-native 1.0.8 — the library registers its own source */
@source './node_modules/heroui-native/lib';
```

### 6. Wrap Your App with Provider

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

```tsx
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](/docs/native/getting-started/provider).

## Use Your First Component

```tsx
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:

```tsx
// 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

<Callout type="warning">
  **Important**: To keep the bundle size under control, you must follow the pattern with granular imports consistently. Even one general import from `heroui-native` will break this optimization strategy.
</Callout>

> **Tip**: For even more control over your bundle, consider using [`HeroUINativeProviderRaw`](/docs/native/getting-started/provider#raw-provider) — a lightweight provider that excludes `ToastProvider` and `PortalHost`.

## What's Next?

- [HeroUI Native Provider](/docs/native/getting-started/provider)
- [Styling Guide](/docs/native/getting-started/styling)
- [Theming Documentation](/docs/native/getting-started/theming)

## Running on Web (Expo)

<Callout type="warning">
  HeroUI Native is currently not recommended for web use. We are focusing on mobile platforms (iOS and Android) at this time. For web development, please use [HeroUI React](/docs/react/getting-started/quick-start) instead.
</Callout>
