OpenParable
Skip to content
← Back to skills

Hiui

Development
hiui

Hiui is an Agent Skill for development published in the XiaoMi/hiui repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/XiaoMi/hiui/blob/HEAD/skills/hiui/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hiui, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.

# Check available props
hiui info Button --format json

# Full docs with usage examples (TSX demos in markdown)
hiui doc Button --format json

# Get the canonical llms URL for citations
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:

// Full bundle
import { Button, Input } from '@hi-ui/hiui'

// Per-component (recommended for existing apps)
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:

# Preview changes (no writes)
hiui migrate 4 5 --dry-run --format json

# Apply to current directory
hiui migrate 4 5 --format json

# Monorepo sub-app
hiui migrate 4 5 --path ./apps/web --format json

# Only bump @hi-ui/* in package.json
hiui migrate 4 5 --deps-only

# Only replace .hi-v4 / hi-v4- class prefixes
hiui migrate 4 5 --class-only

What migrate 4 5 does:

  1. Sets @hi-ui/* in all package.json files to ^5.0.0 (excludes tooling like @hi-ui/hi-build)
  2. 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:

  1. Adds @hi-ui/patch-for-react to dependencies (^5.0.0 by default, override with --patch-version)
  2. Inserts import '@hi-ui/patch-for-react' at the top of the entry file (after 'use client' if present)
  3. 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
# or
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

FlagPurpose
--format jsonStructured 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, --versionPrint CLI version (hiui version also works)

migrate options

FlagPurpose
--path <dir>Project root (default: .)
--dry-runPreview without writing
--deps-onlyOnly update package.json
--class-onlyOnly replace class name prefixes

patch-for-react options

FlagPurpose
--path <dir>Project root
--entry <file>Explicit entry file
--dry-runPreview only
--skip-installSkip package manager install
--patch-version <range>Version for @hi-ui/patch-for-react (default: ^5.0.0)

Key Rules

  1. Always query before writing — Don't guess HiUI APIs from memory. Run hiui info or hiui doc first.
  2. Use --format json — Parse JSON output instead of regex-matching plain text.
  3. Prefer hiui doc for examples — Demos live inside markdown; there is no separate hiui demo command yet.
  4. Migrate with preview — Run hiui migrate 4 5 --dry-run before applying; then install deps and fix API changes manually.
  5. React 19 patch is entry-level — patch-for-react only adds the side-effect import; ensure it runs before other app imports.
  6. Component names are kebab-case in packages — CLI normalizes CheckSelect → check-select for URLs and docs.
  7. 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

CommandDescription
hiui versionCLI version
hiui listAll 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 5V4 → V5 dependency + class prefix upgrade
hiui patch-for-reactInstall and inject React 19 patch

Related Links