Quick Start

Getting Started

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

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

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

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

It's recommended to use the exact versions specified above to avoid compatibility issues. Version mismatches may cause unexpected bugs.

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

4. 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';

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

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

7. 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/[component-name] - Individual components
heroui-native/portal - Portal utilities
heroui-native/utils - Utility functions
heroui-native/hooks - Custom hooks

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.

What's Next?

Running on Web (Expo)

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

On this page