HeroUI Native 移动端组件库：基于 React Native 和 Uniwind 的 Tailwind CSS UI 框架

heroui-native by heroui-inc/heroui

2,700 周安装量

28,600 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/heroui-inc/heroui --skill heroui-native

开发

🇨🇳中文介绍

HeroUI Native 开发指南

HeroUI Native 是一个基于 Uniwind（适用于 React Native 的 Tailwind CSS） 和 React Native 构建的组件库，为移动应用提供可访问、可定制的 UI 组件。

安装

curl -fsSL https://heroui.com/install | bash -s heroui-native

重要提示：仅限原生平台 - 请勿使用 Web 模式

本指南仅适用于 HeroUI Native。 请勿应用 HeroUI React（Web）的模式 —— 包、样式引擎和颜色格式均不相同：

功能	React (Web)	Native (移动端)
样式	Tailwind CSS v4	Uniwind（适用于 React Native 的 Tailwind）
颜色	oklch 格式	HSL 格式
包	`@heroui/react`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

访问文档和组件信息

关于组件详情、示例、属性和实现模式，请务必获取文档：

# 列出所有可用组件
node scripts/list_components.mjs

# 获取组件文档（MDX）
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# 获取主题变量
node scripts/get_theme.mjs

# 获取非组件文档（指南、发布说明）
node scripts/get_docs.mjs /docs/native/getting-started/theming

组件文档：https://heroui.com/docs/native/components/{component-name}.mdx

Button：https://heroui.com/docs/native/components/button.mdx
Dialog：https://heroui.com/docs/native/components/dialog.mdx
TextField：https://heroui.com/docs/native/components/text-field.mdx

入门指南：https://heroui.com/docs/native/getting-started/{topic}.mdx

重要提示： 在实现之前，请务必获取组件文档。MDX 文档包含完整的示例、属性、结构剖析和 API 参考。

npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

框架设置（Expo - 推荐）

安装依赖项：

npx create-expo-app MyApp

cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

2. 创建 global.css：

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

@source "./node_modules/heroui-native/lib";

3. 使用 Provider 包装应用：

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { HeroUINativeProvider } from "heroui-native";
import "./global.css";

export default function Layout() {
	return (
		<GestureHandlerRootView style={{ flex: 1 }}>
			<HeroUINativeProvider>
				<App />
			</HeroUINativeProvider>
		</GestureHandlerRootView>
	);
}

必须使用 Uniwind - HeroUI Native 使用 Uniwind（适用于 React Native 的 Tailwind CSS）
必须使用 HeroUINativeProvider - 使用 HeroUINativeProvider 包装你的应用
必须使用 GestureHandlerRootView - 使用 react-native-gesture-handler 的 GestureHandlerRootView 进行包装
使用复合组件 - 组件采用复合结构（例如 Card.Header、Card.Body）
使用 onPress，而非 onClick - React Native 使用 onPress 事件处理器
平台特定代码 - 使用 Platform.OS 处理 iOS/Android 差异

HeroUI Native 使用 复合组件模式。每个组件都有通过点号访问的子组件。

示例 - Card：

<Card>
	<Card.Header>{/* 图标、徽章 */}</Card.Header>
	<Card.Body>
		<Card.Title>标题</Card.Title>
		<Card.Description>描述</Card.Description>
	</Card.Body>
	<Card.Footer>{/* 操作按钮 */}</Card.Footer>
</Card>

始终使用复合结构 - 不要扁平化为属性
子组件通过点号访问（例如 Card.Header）
Native 的 Card 使用 Card.Body（而非 Card.Content）；Title 和 Description 放在 Body 内部
请获取组件文档以了解完整的结构剖析和示例

HeroUI 使用语义化命名来传达功能意图：

变体	用途	使用建议
`primary`	向前推进的主要操作	每个上下文 1 个
`secondary`	替代操作	多个
`tertiary`	取消性操作（取消、跳过）	谨慎使用
`danger`	破坏性操作	需要时使用
`danger-soft`	温和的破坏性操作	较不突出
`ghost`	低强调度操作	最小权重
`outline`	次要操作	边框样式

请勿使用原始颜色 - 语义化变体可适应主题和可访问性。

HeroUI Native 通过 Tailwind/Uniwind 使用 CSS 变量进行主题设置。主题颜色在 global.css 中定义：

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

获取当前主题变量：

node scripts/get_theme.mjs

以编程方式访问主题颜色：

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

主题切换（浅色/深色模式）：

import { Uniwind, useUniwind } from "uniwind";

const { theme } = useUniwind();
Uniwind.setTheme(theme === "light" ? "dark" : "light");

关于详细主题设置，请获取：https://heroui.com/docs/native/getting-started/theming.mdx

🇺🇸English

HeroUI Native Development Guide

HeroUI Native is a component library built on Uniwind (Tailwind CSS for React Native) and React Native , providing accessible, customizable UI components for mobile applications.

Installation

curl -fsSL https://heroui.com/install | bash -s heroui-native

CRITICAL: Native Only - Do Not Use Web Patterns

This guide is for HeroUI Native ONLY. Do NOT apply HeroUI React (web) patterns — the package, styling engine, and color format all differ:

Feature	React (Web)	Native (Mobile)
Styling	Tailwind CSS v4	Uniwind (Tailwind for React Native)
Colors	oklch format	HSL format
Package	`@heroui/react`	`heroui-native`
Platform	Web browsers	iOS & Android

// CORRECT — Native pattern
import { Button } from "heroui-native";

<Button variant="primary" onPress={() => console.log("Pressed!")}>
	Click me
</Button>;

Always fetch Native docs before implementing.

Core Principles

Semantic variants (primary, secondary, tertiary) over visual descriptions
Composition over configuration (compound components)
Theme variables with HSL color format
React Native StyleSheet patterns with Uniwind utilities

Accessing Documentation & Component Information

For component details, examples, props, and implementation patterns, always fetch documentation:

Using Scripts

# List all available components
node scripts/list_components.mjs

# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# Get theme variables
node scripts/get_theme.mjs

# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/native/getting-started/theming

Direct MDX URLs

Component docs: https://heroui.com/docs/native/components/{component-name}.mdx

Examples:

Button: https://heroui.com/docs/native/components/button.mdx
Dialog: https://heroui.com/docs/native/components/dialog.mdx
TextField: https://heroui.com/docs/native/components/text-field.mdx

Getting started guides: https://heroui.com/docs/native/getting-started/{topic}.mdx

Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.

Installation Essentials

Quick Install

npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

Framework Setup (Expo - Recommended)

Install dependencies:

npx create-expo-app MyApp

cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

2. Createglobal.css:

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

@source "./node_modules/heroui-native/lib";

3. Wrap app with providers:

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { HeroUINativeProvider } from "heroui-native";
import "./global.css";

export default function Layout() {
	return (
		<GestureHandlerRootView style={{ flex: 1 }}>
			<HeroUINativeProvider>
				<App />
			</HeroUINativeProvider>
		</GestureHandlerRootView>
	);
}

Critical Setup Requirements

Uniwind is Required - HeroUI Native uses Uniwind (Tailwind CSS for React Native)
HeroUINativeProvider Required - Wrap your app with HeroUINativeProvider
GestureHandlerRootView Required - Wrap with GestureHandlerRootView from react-native-gesture-handler
Use Compound Components - Components use compound structure (e.g., Card.Header, Card.Body)
Use onPress, not onClick - React Native uses onPress event handlers
Platform-Specific Code - Use Platform.OS for iOS/Android differences

Component Patterns

HeroUI Native uses compound component patterns. Each component has subcomponents accessed via dot notation.

Example - Card:

<Card>
	<Card.Header>{/* Icons, badges */}</Card.Header>
	<Card.Body>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Body>
	<Card.Footer>{/* Actions */}</Card.Footer>
</Card>

Key Points:

Always use compound structure - don't flatten to props
Subcomponents are accessed via dot notation (e.g., Card.Header)
Native Card uses Card.Body (not Card.Content); Title and Description go inside Body
Fetch component docs for complete anatomy and examples

Semantic Variants

HeroUI uses semantic naming to communicate functional intent:

Variant	Purpose	Usage
`primary`	Main action to move forward	1 per context
`secondary`	Alternative actions	Multiple
`tertiary`	Dismissive actions (cancel, skip)	Sparingly
`danger`	Destructive actions	When needed
`danger-soft`	Soft destructive actions	Less prominent

Don't use raw colors - semantic variants adapt to themes and accessibility.

Theming

HeroUI Native uses CSS variables via Tailwind/Uniwind for theming. Theme colors are defined in global.css:

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

Get current theme variables:

node scripts/get_theme.mjs

Access theme colors programmatically:

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

Theme switching (Light/Dark Mode):

import { Uniwind, useUniwind } from "uniwind";

const { theme } = useUniwind();
Uniwind.setTheme(theme === "light" ? "dark" : "light");

For detailed theming, fetch: https://heroui.com/docs/native/getting-started/theming.mdx

Weekly Installs

2.7K

Repository

heroui-inc/heroui

GitHub Stars

28.6K

First Seen

Jan 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

github-copilot2.1K

cursor2.0K

opencode2.0K

codex2.0K

gemini-cli1.8K

claude-code1.6K