Beautiful, fast and modern React Native UI library
v1.0.0-beta.6
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](https:…
Beautiful, fast and modern React Native UI library
v1.0.0-beta.6
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
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:
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 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
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-handleris 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
- Accordion
- Avatar
- Button
- Card
- Checkbox
- Chip
- Dialog
- Divider
- Error View
- Form Field
- Popover
- Pressable Feedback
- Radio Group
- Scroll Shadow
- Select
- Skeleton
- Skeleton Group
- Spinner
- Surface
- Switch
- Tabs
- Text Field
- Toast
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.