HeroUI Native: 一款美观、快速且现代的React Native UI库

Beautiful, fast and modern React Native UI library

v1.0.0-beta.8

Preview App

Experience HeroUI Native components in action with our preview app! You can explore all components and their variants directly on your device.

Prerequisites

Make sure you have the latest version of Expo Go installed on your mobile device

How to Access

Choose one of the following methods to access the preview app:

Option 1: Scan the QR Code

Use your device’s camera or Expo Go app to scan:

Note for Android users: If scanning the QR code with your device’s camera or other scanner apps redirects to a browser and shows a 404 error, open Expo Go first and use its built-in QR scanner instead.

Option 2: Click the Link

📱 Open Demo App in Expo Go

This will automatically open the app in Expo Go if it’s installed on your device.

Quick Start with Example App

Want to start building with HeroUI Native immediately? We provide a standalone example app that’s fully configured and ready to use:

🚀 HeroUI Native Example App

This repository contains a pre-configured React Native app with HeroUI Native already set up, including:

All necessary dependencies installed
Uniwind configuration ready
Example components showcasing best practices
Perfect for quickly prototyping or starting a new project

Simply clone, install, and start building!

Getting Started

1. Install HeroUI Native

npm install heroui-native

2. Install Mandatory Peer Dependencies

npm install react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 [email protected] react-native-safe-area-context@~5.6.0 [email protected] tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5

Important: 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 from the root of your project */
@source './node_modules/heroui-native/lib';

Note: If you need the color scheme from the alpha version of HeroUI Native, you can find it in example/themes/alpha.css.

Running on Web (Expo)

Note: We are currently focusing on the mobile version. Using HeroUI Native on web is not recommended at this time.

If you’re using Expo and want to run your app on web, follow these additional steps:

Install web dependencies:

npx expo install react-dom react-native-web @expo/metro-runtime

Update your app.json:

{
  "expo": {
    "web": {
      "bundler": "metro"
    }
  }
}

5. Wrap Your App with Provider

Wrap your application with HeroUINativeProvider. Since HeroUI Native uses react-native-gesture-handler under the hood, 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: react-native-gesture-handler is required because HeroUI Native uses it internally for gesture handling. Make sure to install it if you haven’t already: npm install react-native-gesture-handler

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

Documentation

Core

Provider Configuration - Complete setup and configuration guide
Theming - Theme customization, colors, fonts and dark mode

Components

Changelog

See CHANGELOG.md for a history of changes to this library.

Roadmap

See Roadmap to see what we’re working on.

Community

We’re excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it’s a feature request, bug report, or a project to showcase, please get involved!

Contributing

Contributions are always welcome! We appreciate your help in making HeroUI Native better.

How to Contribute

Bug Fixes: Check our GitHub Issues for bugs that need fixing
New Components: Only core team can add new components. Check our Roadmap to see what’s planned
Feature Proposals: Start a discussion in GitHub Discussions before implementing

Important: Please do not add new components or variants, change existing designs, or modify component behavior without prior discussion. We follow a strict design system based on our Figma designs and roadmap.

For detailed guidelines, see CONTRIBUTING.md.

Please adhere to this project’s CODE_OF_CONDUCT.

License

MIT