# Taro UI Guide

Guides installing, configuring and styling taro-ui components for mini programs and H5.

- Repository: https://github.com/jd-opensource/taro-ui (4733 stars)
- Category: Mobile
- License: MIT
- Last updated: 2026-09-25
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jd-opensource/taro-ui --skill taro-ui-guide -g -a claude-code -y`
Codex: `npx skills add jd-opensource/taro-ui --skill taro-ui-guide -g -a codex -y`
Cursor: `npx skills add jd-opensource/taro-ui --skill taro-ui-guide -g -a cursor -y`
Gemini CLI: `npx skills add jd-opensource/taro-ui --skill taro-ui-guide -g -a gemini-cli -y`

## Description

Guides installation, Taro config, styling, and usage of taro-ui (At* components) for WeChat/Alipay/H5/RN. Use when building Taro apps with taro-ui, picking components, theming, i18n, or modifying packages/taro-ui source.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Taro UI 使用指南

基于 Taro 3+ 的多端 React 组件库。组件均以 `At` 前缀导出（如 `AtButton`），样式与逻辑分离，需单独引入 SCSS。

官方文档：<https://jd-opensource.github.io/taro-ui/#/>  
源码：`packages/taro-ui/`（本 monorepo）

## 何时使用本 Skill

- 在 Taro 项目中集成、配置或排查 taro-ui
- 选择/组合组件、查 Props、写示例页面
- 自定义主题、国际化、按需加载
- 在本仓库内开发/修复 `packages/taro-ui` 组件

## 版本与安装

| Taro 版本 | taro-ui 版本 |
|-----------|--------------|
| < 3       | `taro-ui@2.3.4` |
| ≥ 3       | `taro-ui@latest`（当前 monorepo 为 3.x） |

```bash
pnpm add taro-ui
# 或 npm install taro-ui@latest
```

**Peer 依赖**：`@tarojs/taro`、`@tarojs/components`、`@tarojs/react`、`react`、`react-dom`（≥16.13）。RN 端另需 `react-native`、`react-native-modal`（可选）。

微信小程序需基础库 **≥ 2.2.3**（`globalClass` 与样式穿透）。

## Taro 项目必配项

在消费方项目的 `config/index.ts`（或 `config/index.js`）中：

**1. H5 编译 node_modules 中的 taro-ui**

```js
h5: {
  esnextModules: ['taro-ui']
}
```

**2. Taro 3.5+ 关闭对 taro-ui 的 prebundle**（否则 `@tarojs/components` 可能未打进 bundle，页面异常）

```js
compiler: {
  type: 'webpack5',
  prebundle: {
    exclude: ['taro-ui']
  }
}
```

## 样式引入

样式在 `taro-ui/dist/style/`，**不会**随 JS 自动注入，必须显式引入。

### 全量（开发/原型）

入口或 `app.scss`：

```js
import 'taro-ui/dist/style/index.scss'
```

```scss
@import 'taro-ui/dist/style/index.scss';
```

### 按需（推荐生产）

页面/全局 SCSS 按组件名引入（`AtButton` → `button.scss`）：

```scss
@import 'taro-ui/dist/style/components/button.scss';
```

或用 `babel-plugin-import`（见 `docs/docs/guide/quickstart.md`）：

```js
// babel.config.js plugins
['import', {
  libraryName: 'taro-ui',
  customName: name => `taro-ui/lib/components/${name.slice(3)}`,
  customStyleName: name => `taro-ui/dist/style/components/${name.slice(3)}.scss`
}, 'taro-ui']
```

`At` 前缀去掉后即为目录名：`AtActionSheet` → `action-sheet`。

## 组件使用模式

### 基础引入

```tsx
import { View } from '@tarojs/components'
import { AtButton } from 'taro-ui'

export default function Page() {
  return (
    <View>
      <AtButton type="primary" onClick={() => {}}>
        按钮
      </AtButton>
    </View>
  )
}
```

### 公共 Props（`AtComponent`）

多数组件支持：

The rest: https://github.com/jd-opensource/taro-ui/blob/HEAD/packages/taro-ui-guide/SKILL.md