| name | hiui |
| description | Use when the user's task involves HiUI (@hi-ui/*) — writing HiUI components, debugging HiUI issues, querying HiUI props/docs, migrating from HiUI V4 to V5, or setting up React 19 compatibility with @hi-ui/patch-for-react. Triggers on imports from '@hi-ui/*', hi-ui/hiui mentions, or explicit HiUI questions.
|
| allowed-tools | ["Bash(hiui *)","Bash(npm install -g @hi-ui/hiui-cli*)","Bash(which hiui)"] |
HiUI CLI
You have access to @hi-ui/hiui-cli — a CLI for querying HiUI component documentation and automating common upgrade tasks. Component docs are fetched from official llms endpoints (network required for list / doc / info / url). Migration and React 19 patch setup run locally on the project filesystem.
Setup
Before first use, check if the CLI is installed. If not, install it:
which hiui || npm install -g @hi-ui/hiui-cli
hiui version
The hiui command comes from the globally installed @hi-ui/hiui-cli package.
Always use --format json for structured output you can parse programmatically.
Scenarios
1. Writing HiUI component code
Before writing any HiUI component code, look up its API first — don't rely on memory.
hiui info Button --format json
hiui doc Button --format json
hiui url Button --format json
Workflow: hiui info → understand props → hiui doc → read examples → write code.
HiUI packages use kebab-case names (@hi-ui/date-picker). Component CLI args accept Button, datePicker, or date-picker (auto-normalized to kebab-case).
Import patterns:
import { Button, Input } from '@hi-ui/hiui'
import Button from '@hi-ui/button'
import Input from '@hi-ui/input'
import { InfoCircleFilled } from '@hi-ui/icons'
2. Looking up full documentation
When you need comprehensive component docs (not just props):
hiui doc Table --format json
Markdown includes description, usage examples, and props tables. Source: https://xiaomi.github.io/hiui/llms/<component>.md.
3. Exploring available components
When choosing which component to use:
hiui list --format json
Index is derived from llms.txt. For offline context, you can also reference llms-full.txt.
4. Migrating HiUI V4 → V5
When upgrading a project from HiUI 4.x to 5.x:
hiui migrate 4 5 --dry-run --format json
hiui migrate 4 5 --format json
hiui migrate 4 5 --path ./apps/web --format json
hiui migrate 4 5 --deps-only
hiui migrate 4 5 --class-only
What migrate 4 5 does:
- Sets
@hi-ui/* in all package.json files to ^5.0.0 (excludes tooling like @hi-ui/hi-build)
- Replaces
.hi-v4 → .hi-v5 and hi-v4- → hi-v5- in project source/styles
What it does NOT do: API breaking changes, import path refactors, or business logic. After migrate, run npm install or yarn, then fix remaining issues manually. See project migration docs.
Workflow: hiui migrate 4 5 --dry-run → review → hiui migrate 4 5 → install deps → hiui doc / hiui info per changed component → fix API usage.
Currently only 4 → 5 is supported; other version pairs return UNSUPPORTED_MIGRATION.
5. React 19 compatibility
When the project uses React 19 and needs ReactDOM.render / legacy static APIs patched for HiUI:
hiui patch-for-react --dry-run --format json
hiui patch-for-react --path . --format json
hiui patch-for-react --entry src/index.tsx --skip-install
What it does:
- Adds
@hi-ui/patch-for-react to dependencies (^5.0.0 by default, override with --patch-version)
- Inserts
import '@hi-ui/patch-for-react' at the top of the entry file (after 'use client' if present)
- Runs
npm / yarn / pnpm install unless --skip-install
Entry auto-detection: src/index.tsx, src/main.tsx, etc., or script src from index.html.
6. Customizing docs source
When using a mirror or internal docs host:
hiui doc alert --base-url https://xiaomi.github.io/hiui --format json
HIUI_DOCS_BASE_URL=https://your-mirror.example hiui list --format json
7. Semantic classNames / styles
Many HiUI 5 components support classNames and styles for per-element styling. Check the Semantic example in component docs:
hiui doc Alert --format json
Look for classNames / styles usage in the markdown examples.
8. Alternative: LLMs.txt without CLI
If the CLI is unavailable, fetch docs directly:
Global Flags
| Flag | Purpose |
|---|
--format json | Structured JSON output (agents should prefer this) |
--base-url <url> | Docs root (default: https://xiaomi.github.io/hiui) |
--timeout <ms> | HTTP timeout for doc fetch (default: 30000) |
-V, --version | Print CLI version (hiui version also works) |
migrate options
| Flag | Purpose |
|---|
--path <dir> | Project root (default: .) |
--dry-run | Preview without writing |
--deps-only | Only update package.json |
--class-only | Only replace class name prefixes |
patch-for-react options
| Flag | Purpose |
|---|
--path <dir> | Project root |
--entry <file> | Explicit entry file |
--dry-run | Preview only |
--skip-install | Skip package manager install |
--patch-version <range> | Version for @hi-ui/patch-for-react (default: ^5.0.0) |
Key Rules
- Always query before writing — Don't guess HiUI APIs from memory. Run
hiui info or hiui doc first.
- Use
--format json — Parse JSON output instead of regex-matching plain text.
- Prefer
hiui doc for examples — Demos live inside markdown; there is no separate hiui demo command yet.
- Migrate with preview — Run
hiui migrate 4 5 --dry-run before applying; then install deps and fix API changes manually.
- React 19 patch is entry-level —
patch-for-react only adds the side-effect import; ensure it runs before other app imports.
- Component names are kebab-case in packages — CLI normalizes
CheckSelect → check-select for URLs and docs.
- Network for docs commands —
list, doc, info, url need HTTP access to the llms host; migrate and patch-for-react are offline filesystem operations.
Command Reference
| Command | Description |
|---|
hiui version | CLI version |
hiui list | All components from llms.txt |
hiui info <component> | Props API |
hiui doc <component> | Full markdown documentation |
hiui url <component> | llms.md URL for component |
hiui migrate 4 5 | V4 → V5 dependency + class prefix upgrade |
hiui patch-for-react | Install and inject React 19 patch |
Related Links
