taro-ui-guide

Taro UI Usage Guide

A multi-platform React component library based on Taro 3+. Components are all exported with the At prefix (e.g. AtButton), with styles and logic separated, requiring SCSS to be imported separately.

Official documentation:https://jd-opensource.github.io/taro-ui/#/
Source code:packages/taro-ui/(this monorepo)

When to Use This Skill

• Integrating, configuring, or troubleshooting taro-ui in a Taro project
• Selecting/combining components, looking up Props, writing example pages
• Custom themes, internationalization, on-demand loading
• Developing/fixing packages/taro-ui components in this repository

Versions and Installation

Taro version	taro-ui version
< 3	taro-ui@2.3.4
≥ 3	taro-ui@latest(the current monorepo is 3.x)

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

Peer Dependencies：@tarojs/taro、@tarojs/components、@tarojs/react、react、react-dom(≥16.13). The RN side additionally requires react-native、react-native-modal(optional).

WeChat Mini Program requires base library ≥ 2.2.3（globalClass and style penetration).

Required Configuration for Taro Projects

In the consuming project's config/index.ts(or config/index.js):

1. H5 compiles taro-ui in node_modules

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

2. Taro 3.5+ disables prebundle for taro-ui(otherwise @tarojs/components may not be bundled, causing page anomalies)

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

Style Import

Styles in taro-ui/dist/style/，will notbe automatically injected with JS; they must be imported explicitly.

Full import (development/prototyping)

Entry or app.scss：

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

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

On-demand (recommended for production)

Import by component name in page/global SCSS (AtButton → button.scss）：

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

or use babel-plugin-import(see docs/docs/guide/quickstart.md）：

// 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 After removing the prefix, it is the directory name:AtActionSheet → action-sheet。

Component Usage Patterns

Basic Import

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

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

Common Props (AtComponent）

Most components support:

Prop	Description
className	Outer class name (in Mini Programs, globalClass can be used to override internal BEM classes)
customStyle	Inline style,string or CSSProperties
children	Child nodes

Type definitions:packages/taro-ui/types/base.d.ts。

Composite Components

Combine subcomponents according to the documentation, for example:

• AtModal + AtModalHeader / AtModalContent / AtModalAction
• AtList + AtListItem
• AtTabs + AtTabsPane
• AtActionSheet + AtActionSheetItem

Look up by component:references/README.md(e.g. references/button.md）。only when using that componentopen the corresponding file.

Controlled and Callbacks

• Toggle-type:open / isOpened + onClick / onClose(subject to each component's types/*.d.ts )
• Form-type:AtForm wraps AtInput、AtSwitch , etc.; note formType, validation messages
• Environment detection: components internally commonly use Taro.getEnv() to distinguish WEB / WEAPP / ALIPAY

When looking up Propsread first references/<slug>.md, then packages/taro-ui/types/<component>.d.ts and docs/docs/components/<name>.md。

Imperative API:AtMessage

The page needs to mount <AtMessage />, then call via Taro.atMessage :

import Taro from '@tarojs/taro'
import { AtMessage } from 'taro-ui'

// render 中: <AtMessage />
Taro.atMessage({ message: '提示', type: 'success', duration: 3000 })
// type: info | success | error | warning

AtToast is declarative:isOpened、text、status、onClose。

Internationalization ConfigProvider

import { ConfigProvider, AtLoadMore, enUS } from 'taro-ui'

export default function App({ children }) {
  return (
    <ConfigProvider locale={enUS}>
      {children}
    </ConfigProvider>
  )
}

• Built-in:zhCN(default),enUS
• locale is deeply merged with the default package, so only some keys can be overridden (e.g. LoadMore.moreText）
• Priority: component props > ConfigProvider.locale > default zhCN

Custom Theme

1. SCSS variables(recommended): before importing the default stylesbeforeoverride the variables, then @import the full styles.

$color-brand: #6190e8;
@import 'taro-ui/dist/style/index.scss';

Variable table:packages/taro-ui/src/style/variables/default.scss。

1. globalClass: In Page level SCSS override with .my-btn.at-button { } (does not work in custom components).

2. customStyle: Only some components support it; prefer the first two methods.

AtSlider、AtSwitch does not currently support overriding the theme with SCSS variables.

Developing taro-ui in this repository

pnpm install          # 根目录，仅允许 pnpm
pnpm build:ui         # 构建 packages/taro-ui → dist/
pnpm --filter demo dev:h5
pnpm --filter demo dev:weapp
pnpm --filter docs dev

Component implementation paths:

Content	Path
Component implementation	packages/taro-ui/src/components/<name>/
Types	packages/taro-ui/types/<name>.d.ts
Styles	packages/taro-ui/src/style/components/<name>.scss
Exports	packages/taro-ui/src/index.ts
RN implementation	packages/taro-ui/rn/components/
Unit tests	packages/taro-ui/test/components/

Adding/modifying components: synchronously update src/index.ts, type files, styles,test snapshots; commit message format feat(ComponentName): ...(see .github/CONTRIBUTING.md）。

Agent workflow

1. Confirm the scenario: consumer Taro project vs source code changes in this monorepo.
2. Check the API：references/<slug>.md → types/*.d.ts → docs/docs/components/*.md。
3. Write usage：import { AtX } from 'taro-ui' + the corresponding dist/style/components/x.scss。
4. Troubleshoot missing styles: whether SCSS is imported; whether H5 is configured with esnextModules; whether prebundle.exclude。
5. Troubleshoot mini program styles: base library version,globalClass, whether the BEM class names match the documentation.

Further reading

• references/README.md — Component index (progressive disclosure by dimension)
• docs/docs/guide/quickstart.md — Quick start and babel on-demand
• docs/docs/guide/customize-theme.md — Theme details