heroui-native

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HeroUI Native Development Guide

HeroUI Native 开发指南

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.

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

CRITICAL: Native Only - Do Not Use Web Patterns

重要提示：仅适用于原生端 - 请勿使用Web模式

This guide is for HeroUI Native ONLY. Do NOT use any prior knowledge of HeroUI React (web) patterns.

本指南仅适用于HeroUI Native。请勿使用任何HeroUI React（Web端）的既有经验和模式。

What Changed in Native

原生端的变更点

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

特性	React（Web端）	原生端（移动端）
样式方案	Tailwind CSS v4	Uniwind（适用于React Native的Tailwind）
颜色格式	oklch格式	HSL格式
包名称	`@heroui/react@beta`	`heroui-native`
支持平台	Web浏览器	iOS 和 Android

WRONG (React web patterns)

错误示例（React Web模式）

tsx

// DO NOT DO THIS - React web pattern
import { Button } from "@heroui/react";
import "./styles.css"; // CSS files don't work in React Native

<Button className="bg-blue-500">Click me</Button>;

tsx

// 请勿这样做 - React Web模式
import { Button } from "@heroui/react";
import "./styles.css"; // CSS文件在React Native中无法生效

<Button className="bg-blue-500">Click me</Button>;

CORRECT (Native patterns)

正确示例（原生端模式）

tsx

// DO THIS - Native pattern (Uniwind, React Native components)
import { Button } from "heroui-native";

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

Always fetch Native docs before implementing. Do not assume React web patterns work.

tsx

// 请这样做 - 原生端模式（Uniwind、React Native组件）
import { Button } from "heroui-native";

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

实现前务必查阅原生端文档。不要默认React Web模式可以直接复用。

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

使用语义化变体（
```
primary
```
、
```
secondary
```
、
```
tertiary
```
）而非视觉描述
优先组合而非配置（复合组件）
使用HSL颜色格式定义主题变量
结合Uniwind工具类与React Native StyleSheet模式

Accessing Documentation & Component Information

查阅文档与组件信息

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

如需了解组件详情、示例、属性和实现模式，请务必查阅文档：

Using Scripts

使用脚本

bash

undefined

bash

undefined

List all available components

列出所有可用组件

node scripts/list_components.mjs

Get component documentation (MDX)

获取组件文档（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

undefined

node scripts/get_docs.mjs /docs/native/getting-started/theming

undefined

Direct MDX URLs

直接访问MDX文档链接

Component docs:

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

Examples:

Button:

https://v3.heroui.com/docs/native/components/button.mdx

Dialog:

https://v3.heroui.com/docs/native/components/dialog.mdx

TextField:

https://v3.heroui.com/docs/native/components/text-field.mdx

Getting started guides:

https://v3.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.

组件文档：

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

示例：

Button:

https://v3.heroui.com/docs/native/components/button.mdx

Dialog:

https://v3.heroui.com/docs/native/components/dialog.mdx

TextField:

https://v3.heroui.com/docs/native/components/text-field.mdx

入门指南：

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

重要提示：实现前务必查阅组件文档。MDX文档包含完整示例、属性、组件结构和API参考。

Installation Essentials

安装要点

CRITICAL: HeroUI Native is currently in BETA.

重要提示：HeroUI Native 当前处于BETA测试阶段。

Quick Install

快速安装

bash

npm i heroui-native

bash

npm i heroui-native

Required Peer Dependencies

必需的对等依赖

bash

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

bash

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

Framework Setup (Expo - Recommended)

框架配置（Expo - 推荐）

Install dependencies:

bash

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

Create
global.css
:

css

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

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

Wrap app with providers:

tsx

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

安装依赖：

bash

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

创建
global.css
文件：

css

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

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

使用Provider包裹应用：

tsx

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

必须安装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差异

Component Patterns

组件模式

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

Example - Card:

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Body>{/* Content */}</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
```
)
Each subcomponent may have its own props
Fetch component docs for complete anatomy and examples

HeroUI Native 采用复合组件模式。每个组件通过点语法访问其子组件。

示例 - Card组件：

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Body>{/* 内容 */}</Card.Body>
	<Card.Footer>{/* 操作项 */}</Card.Footer>
</Card>

核心要点：

务必使用复合结构 - 不要扁平化为属性
子组件通过点语法访问（例如
```
Card.Header
```
）
每个子组件可能有自己的属性
请查阅组件文档获取完整的结构和示例

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
`ghost`	Low-emphasis actions	Minimal weight
`outline`	Secondary actions	Bordered style

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

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

变体类型	用途	使用场景
`primary`	推进流程的主要操作	每个场景仅使用1个
`secondary`	备选操作	可使用多个
`tertiary`	取消、跳过等关闭类操作	谨慎使用
`danger`	破坏性操作	必要时使用
`danger-soft`	轻量破坏性操作	低突出显示场景
`ghost`	低强调操作	极简样式场景
`outline`	备选操作	边框样式场景

请勿直接使用原始颜色 - 语义化变体可适配主题和无障碍需求。

Theming

主题定制

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

global.css

css

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

Get current theme variables:

bash

node scripts/get_theme.mjs

Access theme colors programmatically:

tsx

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

Theme switching (Light/Dark Mode):

tsx

import { Uniwind, useUniwind } from "uniwind";

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

For detailed theming, fetch:

https://v3.heroui.com/docs/native/getting-started/theming.mdx

HeroUI Native 通过Tailwind/Uniwind的CSS变量实现主题定制。主题颜色在

global.css

中定义：

css

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

获取当前主题变量：

bash

node scripts/get_theme.mjs

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

tsx

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

主题切换（亮色/暗色模式）：

tsx

import { Uniwind, useUniwind } from "uniwind";

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

如需详细的主题定制指南，请查阅：

https://v3.heroui.com/docs/native/getting-started/theming.mdx