---
url: https://rickyshin93.github.io/tao-ui/guide/getting-started.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Getting Started
Requires React and React DOM 18.2 at minimum and also supports React 19. Both peer dependency ranges are `^18.2.0 || ^19.0.0`. The date pickers' `dayjs` dependency is installed automatically. Install tao-ui with your preferred package manager.
```sh [npm]
npm install @rockshin/tao-ui
```
```sh [yarn]
yarn add @rockshin/tao-ui
```
```sh [pnpm]
pnpm add @rockshin/tao-ui
```
```sh [bun]
bun add @rockshin/tao-ui
```
```sh [deno]
deno add npm:@rockshin/tao-ui
```
## Add the provider
Wrap your application once with `TaoProvider`. Components inherit settings such as size, disabled state, and theme mode.
```tsx
import { Button, TaoProvider } from '@rockshin/tao-ui';
export default function App() {
return (
Continue
);
}
```
## Component imports
Component entries load only their component dependencies and shared theme styles. No separate CSS import is needed. The root entry remains available and includes all component styles.
```tsx
import { Button, type ButtonProps } from '@rockshin/tao-ui/button';
import { TaoProvider } from '@rockshin/tao-ui/provider';
```
Entry names use kebab-case, such as `/input-number`, `/range-picker`, and `/form-layout`. Related exports share an entry: `CheckboxGroup` uses `/checkbox`, and `HeadlessInputNumber` uses `/number-input`.
## Control field values
For Input, Textarea, InputNumber, Select, DatePicker, and RangePicker, an explicit `value={undefined}` is a controlled empty value. Omit `value` and use `defaultValue` for an uncontrolled field. Form fields can be cleared with `form.setFieldsValue({ field: undefined })` without remounting the control.
## Use dark mode
Set the theme mode on the provider. Portaled components inherit the same theme.
```tsx
```
Continue with the [Button component](https://rickyshin93.github.io/tao-ui/components/button.md).
## Accessibility and ARIA
Use `FormField` or `Form.Item` to associate labels, help and validation messages with controls. Input, Textarea, InputNumber, Select, Checkbox, Radio, Switch, DatePicker and RangePicker forward field ARIA attributes to their interactive elements; CheckboxGroup and RadioGroup expose group labels and validation messages. Placeholders do not replace field labels.
```tsx
```
Radio maps `aria-required` to native `required`; an explicit `required` prop takes precedence. Group options retain their native disabled state, including explicit `disabled={false}` overrides.
Desktop date inputs expose `combobox` semantics. ArrowDown opens the calendar and moves focus into it; Escape closes it and returns focus to the input. RangePicker combines explicit ARIA labels and each endpoint placeholder to distinguish its inputs. Native labels can instead target `id` and `${id}-end`. Calendar, month, year and time choices expose selection state.
- Name Tabs with `aria-label` or `aria-labelledby`; text panels are reachable with Tab.
- Give Modal, Drawer and Popover a visible `title` or explicit ARIA name. Popconfirm associates its question and description automatically.
- Spinner accepts `aria-label`, defaults to `Loading` without a tip, and marks wrapped content `aria-busy` throughout loading, including its display delay.
- Applications must still supply meaningful names for icon-only buttons.
Automated checks cover DOM semantics and keyboard interaction in React 18/19; test composed screens with a browser and screen reader as well. See the [WAI-ARIA date combobox example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/) and [Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
---
url: https://rickyshin93.github.io/tao-ui/guide/agents.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Working with AI agents
tao-ui is an MIT React component library for React and React DOM 18.2 or 19. Components support provider defaults, semantic `classNames` and `styles`, and OKLCH seed themes. The same bilingual references serve people and coding agents.
## Read the right source
| Source | Use it for |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [agent-manifest.json](https://rickyshin93.github.io/tao-ui/agent-manifest.json) | Website package version, peer dependencies, exact component import paths, and English/Chinese HTML and Markdown URLs |
| [component-manifest.json](https://rickyshin93.github.io/tao-ui/component-manifest.json) | Component descriptions, usage guidance, semantic parts, related components and selected props |
| [llms.txt](https://rickyshin93.github.io/tao-ui/llms.txt) | A small navigation index; fetch only relevant pages |
| [llms-full.txt](https://rickyshin93.github.io/tao-ui/llms-full.txt) | All English documentation when bulk context is necessary |
| Installed `.d.ts` and generated component API tables | Exact prop types, callback signatures and supported overloads |
`agent-manifest.json` is this project's discovery format, with `schemaVersion: 1`; it is not an MCP server or a universal agent protocol. The website tracks the current release. Check its package version against your installed dependency before copying an API. The metadata's `props` list is curated and can be incomplete; use declarations for the full contract.
## Generate a component safely
1. Read the installed package version and peer requirements.
2. Find the component in the discovery index, then fetch its Markdown page for examples and the API table.
3. Follow the documented import path. `TaoProvider` uses `/provider`; `HeadlessInputNumber` and `useNumberInput` use `/number-input`.
4. Wrap the application with `TaoProvider`; use `classNames` / `styles` with documented semantic parts for customization.
5. Run the application's typecheck and exercise the relevant interaction. Check narrow viewports for responsive controls.
```tsx
import { Button } from '@rockshin/tao-ui/button';
import { TaoProvider } from '@rockshin/tao-ui/provider';
export default function App() {
return (
console.log('Saved')}>Save
);
}
```
Component entries include their CSS and shared theme styles. No separate CSS import is required. The package root is also supported and includes all component styles. React is a peer dependency; the date pickers' `dayjs` is installed automatically.
For Next.js App Router, place interactive usage in a client component (`'use client'`). Use tao-ui's API documentation and type declarations as the component contract. For example, form controls distinguish an omitted `value` from `value={undefined}`; follow the [getting started guide](https://rickyshin93.github.io/tao-ui/guide/getting-started.md#control-field-values).
## Read installed metadata
```ts
import { getComponentDoc } from '@rockshin/tao-ui/meta';
const button = getComponentDoc('button');
console.log(button?.semanticParts);
```
Node tools can resolve plain JSON without importing UI code:
```js
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const file = require.resolve('@rockshin/tao-ui/component-manifest.json');
const manifest = JSON.parse(readFileSync(file, 'utf8'));
console.log(manifest.components.find((item) => item.name === 'button'));
```
The installed package also includes `llms.txt`. Source/story/test paths inside component metadata refer to the repository; they are not HTTP routes or files promised inside the npm package.
## Browser tools
Rspress enables six documentation tools through experimental WebMCP: `rspress_get_site_info`, `rspress_list_pages`, `rspress_get_page`, `rspress_get_current_page`, `rspress_search_docs`, and `rspress_navigate`. They require a browser supporting `document.modelContext` on HTTPS or localhost. A browser without it can still read the JSON and Markdown URLs above. No API key or hosted MCP service is required.
These tools read and navigate documentation; they do not execute your application or establish that generated code passes its tests. See the [Rspress WebMCP documentation](https://www.rspress.rs/guide/basic/webmcp).
---
url: https://rickyshin93.github.io/tao-ui/guide/changelog.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Changelog
User-facing changes for `@rockshin/tao-ui`, listed by release. Dates use UTC+8.
## 0.0.57
2026-11-16
- [Form](https://rickyshin93.github.io/tao-ui/components/form.md) clears stale validation errors when values are written through `setFields` or the controlled `fields` prop; entries that carry `errors` or `warnings` still apply their own validation state.
- [Modal](https://rickyshin93.github.io/tao-ui/components/modal.md) focuses the configured button on every open cycle and restores focus to the trigger on close, including when content is retained between opens.
- [Select](https://rickyshin93.github.io/tao-ui/components/select.md) keeps rich node labels intact in multiple-mode tags while text and number labels are still truncated by `maxTagTextLength`.
- [Steps](https://rickyshin93.github.io/tao-ui/components/steps.md) adds `finishIconBackground` and `finishIconColor` to style the built-in finished-step circle and check mark.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.56...v0.0.57)
## 0.0.56
2026-11-13
- [Select](https://rickyshin93.github.io/tao-ui/components/select.md) prevents option text from being clipped vertically with consumer fonts.
## 0.0.55
2026-11-13
- [Select](https://rickyshin93.github.io/tao-ui/components/select.md) wraps long option labels on request and keeps selected tags within the control.
## 0.0.54
2026-11-10
- [Textarea](https://rickyshin93.github.io/tao-ui/components/textarea.md) aligns its character count beside the native resize handle at the bottom corner and reserves room for text.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.53...v0.0.54)
## 0.0.53
2026-11-10
- [Textarea](https://rickyshin93.github.io/tao-ui/components/textarea.md) places the character count inside the control without adding a separate row.
- [Upload](https://rickyshin93.github.io/tao-ui/components/upload.md) keeps picture-card action backgrounds transparent over the image mask.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.52...v0.0.53)
## 0.0.52
2026-11-10
- [Upload](https://rickyshin93.github.io/tao-ui/components/upload.md) aligns picture cards, circular tiles, thumbnails and file actions; card triggers follow the file list and can be hidden with `null` or `false`. Uploading files show progress, and download actions appear for completed files. Dragger height applies to the drop zone independently of the file list.
- [Input](https://rickyshin93.github.io/tao-ui/components/input.md) preserves the password placeholder font when toggling visibility. [Modal](https://rickyshin93.github.io/tao-ui/components/modal.md) reserves vertical space around its body content so control focus rings remain visible.
- Upload documentation adds expanded bilingual examples and API guidance, original demo artwork, and a responsive two-column layout.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.51...v0.0.52)
## 0.0.51
2026-11-08
- Button sizes nested SVG icons consistently while respecting explicit dimensions; Input centers suffix content; Select maintains its intended single-row multiple-selection height; Transfer aligns its selection chevron and disabled state.
- The documentation adds a bilingual Showcase and responsive commerce example. Clean builds now prepare the icon package used by the Showcase.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.49...v0.0.51)
## 0.0.50
2026-11-08
- [Button](https://rickyshin93.github.io/tao-ui/components/button.md) sizes nested SVG icons consistently while respecting explicit dimensions.
- [Input](https://rickyshin93.github.io/tao-ui/components/input.md) centers suffix content, and [Select](https://rickyshin93.github.io/tao-ui/components/select.md) maintains its intended height for a single row of multiple selections.
- [Transfer](https://rickyshin93.github.io/tao-ui/components/transfer.md) aligns the selection menu chevron with Select and clarifies its disabled state.
- The documentation adds a bilingual Showcase and a responsive commerce example, alongside refreshed component and home pages.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.49...v0.0.50)
## 0.0.49
2026-11-07
**Data entry and selection**
- [Form](https://rickyshin93.github.io/tao-ui/components/form.md) resets controlled field values and keeps validation feedback and native submission in sync.
- [Select](https://rickyshin93.github.io/tao-ui/components/select.md) keeps the search query when a controlled multiple selection is declined and matches option values that contain a token separator.
- [Upload](https://rickyshin93.github.io/tao-ui/components/upload.md) shows a request setup error on the affected file while the rest of the batch continues. Once a request succeeds or fails, later callbacks cannot change its result. A disabled upload also ignores pasted files.
- [RangePicker](https://rickyshin93.github.io/tao-ui/components/range-picker.md) discards unconfirmed text when the user clears the range. If a controlled DatePicker or RangePicker ignores a keyboard request to open and the user leaves the field, opening it later no longer moves focus back.
- [Cascader](https://rickyshin93.github.io/tao-ui/components/cascader.md) drops newly selected paths that are removed or become disabled before the user taps Done on mobile. Existing selections the user leaves in place are preserved.
- [Table](https://rickyshin93.github.io/tao-ui/components/table.md) applies Select All to eligible rows on the current page, using the latest disabled state. Responsive columns retain their configured default sort when they appear.
- [Input](https://rickyshin93.github.io/tao-ui/components/input.md) and [Textarea](https://rickyshin93.github.io/tao-ui/components/textarea.md) accept Enter again after an interrupted input method composition. Textarea autosizing accounts for custom padding and borders. Changes to the arrays passed to CheckboxGroup and Slider callbacks no longer alter component state.
**Overlays and display**
- [Image](https://rickyshin93.github.io/tao-ui/components/image.md) removes its open preview when preview is disabled. Re-enabling preview leaves it closed until the user opens it again, unless the application controls it as open.
- [Modal](https://rickyshin93.github.io/tao-ui/components/modal.md) closes the remaining dialogs when an `afterClose` callback throws during `Modal.destroyAll()`, then reports the error. Tour uses its top-level scroll options unless a step supplies its own, and FloatButton detects outside clicks inside its iframe.
- [Badge](https://rickyshin93.github.io/tao-ui/components/badge.md) positions a status dot over wrapped content, including in RTL. Card renders arrays of tab bar extras, and BorderBeam resumes animation when its host element is replaced.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.48...v0.0.49)
## 0.0.48
2026-11-06
**Fixed and improved**
- **Form** reserves 24px for single-line feedback (18px for the message, 2px above and 4px below) at 12–14px message font sizes. Messages keep their existing font size, single lines appear without shifting fields, and longer messages wrap.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.47...v0.0.48)
## 0.0.47
2026-11-06
**Fixed and improved**
- **Form** restores required and error styles when imported from the form subpath. Feedback takes less space, and fields without validation or messages leave no empty feedback row.
- **Cascader** uses a bottom drawer on mobile. Search works inside it, single selection applies immediately, and multiple selection applies on Done. The clear affordance and expand arrow align with the control layout.
**Documentation**
- The bilingual docs use consistent colors, navigation and side-by-side example layouts.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.46...v0.0.47)
## 0.0.46
2026-11-06
**Added**
- **TaoProvider** adds 17 locale packs, available from the package root and individual `@rockshin/tao-ui/locale/*` imports. Provider locale now translates component labels, empty states, modal actions and form validation, including content rendered in portals.
- **DatePicker, RangePicker, Calendar and TimePicker** use regional labels and calendar conventions. Localized date and time formats support parsing user input, and per-component locale overrides take precedence.
- **InputNumber and Statistic** display regional digits and separators. InputNumber continues to emit exact decimal strings, and date pickers retain their default output formats unless a localized format is selected.
**Documentation**
- Updated the bilingual site with a vector logo, dark-mode artwork and a favicon.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.45...v0.0.46)
## 0.0.45
2026-11-06
**Added**
- **TaoProvider** adds `direction`. Components and portals inherit direction, and individual components can override it or use native `dir="auto"`.
**Fixed and improved**
- **RTL** fixes horizontal scroll, Splitter dragging, Rate input, pagination icons, Table alignment and fixed columns, and keyboard interaction in selection controls. Desktop and mobile popups keep their source direction.
**Compatibility**
- **Segmented** no longer hits a React 18 maximum update depth error during keyboard navigation.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.44...v0.0.45)
## 0.0.44
2026-11-05
**Added**
- **Form** adds `FormInstance.scrollToField(name, options)` for mounted fields, including nested names, `Form.List` paths and `noStyle` items. Options control scrolling and can focus the field. `FormScrollOptions` is exported from the root and form subpath.
**Fixed and improved**
- The Chinese AI agent guide link resolves to the correct locale URL.
**Migration**
- Custom controls used as scroll targets should forward a DOM or `nativeElement` ref, or the field ID.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.43...v0.0.44)
## 0.0.43
2026-11-05
**Added**
- **Input** adds clear/count support, Password, Search, TextArea, OTP and underlined variants.
- **Collapse** supports item panels, accordion behavior and built-in styling.
**Fixed and improved**
- Improved Calendar and Carousel controls, RadioGroup selection, Form feedback spacing, Tree and TreeSelect checking, and responsive picker titles. Fixed isolated CSS and dark theme details across controls.
**Migration**
- Replace `Collapsible` and `/collapsible` imports with `Collapse` and `/collapse`.
**Documentation**
- Redesigned the bilingual site and added agent guides, `agent-manifest.json`, the package's `component-manifest.json` export, and searchable Markdown references.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.42...v0.0.43)
## 0.0.42
2026-11-05
**Added**
- Expanded the catalog to 73 visual entries. New entries include Cascader, Tree, TreeSelect, Upload, Transfer, Calendar, ColorPicker, Carousel, and application-scoped feedback via App.
- Added public `GetProps`, `GetProp` and `GetRef` utilities for deriving types from components.
**Fixed and improved**
- Improved responsive selection controls, provider localization and focus handling, and unified the default theme radius to 6px.
**Documentation**
- Added bilingual runnable examples with independent phone and desktop previews, synchronized dark mode and copyable snippets.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.41...v0.0.42)
## 0.0.41
2026-11-04
**Fixed and improved**
- **Select** restores vertical scrolling in height-limited option lists for single, searchable, multiple and tags modes.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.40...v0.0.41)
## 0.0.40
2026-10-30
**Fixed and improved**
- **Fields, pickers and overlays** improve native labels, required and disabled semantics, and focus restoration. RangePicker names each endpoint and announces committed selections. Mobile Select exposes its current selection and search label.
- **Tabs, Spinner and Tag** expose clearer keyboard or accessibility states. Popover and confirmation dialogs use their visible titles as accessible names.
**Compatibility**
- Moved tao-ui into a Bun workspace and upgraded its build to Rslib 1.x. The npm package remains `@rockshin/tao-ui`.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.39...v0.0.40)
## 0.0.39
2026-10-18
**Fixed and improved**
- **Theme, Table, Tag and Steps** mix colored and neutral tints in OKLab. Primary and status fills stay closer to their intended hue, and Table hover and row separators are easier to distinguish.
- **Select** enlarges the `allowClear` hit area so near-edge clicks clear the value without opening the popup.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.38...v0.0.39)
## 0.0.38
2026-10-15
**Added**
- **Table** adds sticky headers when `scroll.y` is set, expandable rows via `expandable`, and a `Table.Summary` footer that can be pinned and aligned with fixed columns.
**Fixed and improved**
- **Table** keeps pinned headers and fixed cells opaque, updates edge shadows on container resize, and covers the full table with the loading mask.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.37...v0.0.38)
## 0.0.37
2026-10-12
**Fixed and improved**
- **Popover** uses the normal popup stacking level so a nested Select, Menu or DatePicker can open above its parent Popover.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.36...v0.0.37)
## 0.0.36
2026-10-05
**Fixed and improved**
- **Table** keeps sort, filter and pagination callbacks aligned with the same data view and honors controlled state supplied by the parent.
- **Select** keeps change, select, deselect and clear notifications in a consistent order. Mobile confirmation emits the committed changes, and cancelling discards the draft.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.35...v0.0.36)
## 0.0.35
2026-09-13
**Fixed and improved**
- **Tabs** renders the animated active indicator with square ends, avoiding pointed caps as it scales to the selected tab's width.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.34...v0.0.35)
## 0.0.34
2026-09-13
**Added**
- Added **Steps** with numbered progress, per-step status, keyboard-activatable items and `maxCount` for collapsing long workflows.
**Fixed and improved**
- **Table** keeps row dividers visible over colored rows and clips cell backgrounds inside rounded table corners.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.33...v0.0.34)
## 0.0.33
2026-09-08
**Fixed and improved**
- **Select** in tags mode suppresses an empty popup when empty content is disabled. Free-text tag entry, suffix icons, explicit empty content and custom popups still work.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.32...v0.0.33)
## 0.0.32
2026-09-06
**Fixed and improved**
- **DatePicker and RangePicker** handle changed date bounds, rejected edits and explicit form clears, and keep visible months synchronized.
- **Select, Table, InputNumber and Splitter** fix updates to search, selection, pagination, numeric input and drag state.
- **Popover, Modal, Checkbox, Tabs and Form** improve focus handling, label associations, checked-state rendering and cleared boolean values.
**Compatibility**
- Added React 18.2 support alongside React 19, including ref compatibility, and component subpath exports for importing an individual component with its styles.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.31...v0.0.32)
## 0.0.31
2026-09-01
**Fixed and improved**
- **Table** fixed headers use the active variant's background. Fixed columns gain edge shadows when there is more content to scroll into view.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.30...v0.0.31)
## 0.0.30
2026-08-28
**Added**
- **Button** adds the `bare` variant for retaining interaction behavior with caller-defined visuals.
**Fixed and improved**
- **Button** defaults move to a low-specificity component layer so consumer classes can override color, spacing and shape.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.29...v0.0.30)
## 0.0.29
2026-08-27
**Fixed and improved**
- **Input** geometrically centers the native text line box so the caret and selection align with the control's height.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.28...v0.0.29)
## 0.0.28
2026-08-25
**Fixed and improved**
- **Textarea** uses low-specificity defaults in the component cascade layer, letting Semantic DOM classes override the inner textarea's styles.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.27...v0.0.28)
## 0.0.27
2026-08-19
**Fixed and improved**
- **DatePicker and RangePicker** restore the controlled value after rejected edits and cancel unfinished range selection when closing or receiving a new value.
- **Select** keeps the first option when resolving duplicate values. **Sonner** keeps a recreated toast visible when an earlier instance's exit timer completes and cleans up loading toasts when promises settle.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.26...v0.0.27)
## 0.0.26
2026-08-19
**Added**
- Added **Form** with field validation, lists and dependency tracking, plus **Alert**, **Popover**, **Popconfirm** and **Tooltip**.
- **Table** columns accept responsive breakpoints. Added public responsive helpers and theme token utilities.
**Fixed and improved**
- **Button** keeps a typographic line box while flex-centering content to improve alignment across consumer fonts.
**Documentation**
- Added bilingual Rspress references with runnable examples and API tables. [Documentation PR](https://github.com/rickyshin93/tao-ui/pull/2)
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.25...v0.0.26)
## 0.0.25
2026-08-04
**Fixed and improved**
- **Input** centers text and password dots independently so aligning the mask glyphs does not shift the password selection line box.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.24...v0.0.25)
## 0.0.24
2026-08-04
**Fixed and improved**
- **Input** uses size-aware vertical padding to center native text and password mask glyphs.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.23...v0.0.24)
## 0.0.23
2026-08-04
**Fixed and improved**
- **Input** clips browser autofill paint within rounded control edges and preserves the text's normal vertical metrics.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.22...v0.0.23)
## 0.0.22
2026-08-03
**Added**
- Added typed Semantic DOM contracts for visual components, with dedicated metadata and theme helper imports.
**Fixed and improved**
- **DatePicker** improves keyboard navigation, **FormField** associates labels and help with controls, and **Select** keeps selected option checkmarks within the popup width.
- **Button** aligns icon size and text spacing. **TaoProvider** respects disabled motion and resets inherited theme seeds when `inherit={false}`.
**Migration**
- Import metadata and token helpers from `@rockshin/tao-ui/meta` and `@rockshin/tao-ui/tokens` when moving from their former root exports.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.21...v0.0.22)
## 0.0.21
2026-07-26
**Added**
- **Input** supports React SVG prefixes with automatic positioning and space reserved for typed text.
**Fixed and improved**
- **Drawer and Modal** close on an actual mask click when enabled. Interacting with a nested portal keeps the dialog open.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.20...v0.0.21)
## 0.0.20
2026-07-25
**Fixed and improved**
- **Input** removes duplicate start padding when a prefix is present, so the text starts next to the prefix at the intended spacing.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.19...v0.0.20)
## 0.0.19
2026-07-25
**Compatibility**
- Refreshed the Rslib, Rstest and Storybook development toolchain and synchronized the Bun lockfile during releases. This patch contains no component changes.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.18...v0.0.19)
## 0.0.18
2026-07-25
**Added**
- **TaoProvider** adds dark mode via `theme.mode`. Nested providers inherit the mode and portaled components carry their source theme. [PR #1](https://github.com/rickyshin93/tao-ui/pull/1)
- **DatePicker and RangePicker** accept strictly formatted typed dates on desktop and retain the drawer on mobile. Searchable **Select** supports editable desktop single selection and inline search for multiple and tags modes.
**Fixed and improved**
- **Input and RangePicker** improve prefix and text alignment. Table, Tag, Modal and Drawer derive their surfaces and overlays from theme tokens.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.17...v0.0.18)
## 0.0.17
2026-07-12
**Added**
- **Button** adds `icon` and `loadingIcon`. The icon slot stays mounted while switching to loading, preventing layout flicker.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.16...v0.0.17)
## 0.0.16
2026-07-12
**Fixed and improved**
- **Sonner** measures toast heights for expanded stacking, preserves positions during removal, and improves enter/exit motion and the close button's hit area.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.15...v0.0.16)
## 0.0.15
2026-07-12
**Added**
- Added **Sonner** and the imperative `toast()` API, including rich colors, custom content, action buttons and promise-driven loading, success and error states.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.14...v0.0.15)
## 0.0.14
2026-07-10
**Added**
- **Select** adds search, multiple and tags modes, custom tag rendering, selection limits and a mobile drawer with confirmation for multiple selection.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.13...v0.0.14)
## 0.0.13
2026-07-09
**Fixed and improved**
- **Checkbox and Radio** keep their native inputs within the visual control box so they remain focusable and clickable without intercepting clicks outside the control.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.12...v0.0.13)
## 0.0.12
2026-07-05
**Fixed and improved**
- **Select, DatePicker, RangePicker, Dropdown and menus** apply portal theme tokens directly to popup elements, avoiding leftover wrapper nodes for closed popups.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.11...v0.0.12)
## 0.0.11
2026-07-05
**Added**
- Added a component metadata manifest and public component prop and Semantic DOM types.
**Fixed and improved**
- **Breadcrumb** renders action items as buttons. **DatePicker** uses focusable native buttons for dates, with accessible names and disabled states.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.10...v0.0.11)
## 0.0.10
2026-07-05
**Fixed and improved**
- **FormSection** removes extra spacing caused by native fieldset and legend layout. Portal theme scopes are layout-transparent in flex and grid.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.9...v0.0.10)
## 0.0.9
2026-07-04
**Added**
- Added **InputNumber**, a themed numeric field with grouping, caret preservation, and canonical string values for precision. Also exposes headless numeric input building blocks.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.8...v0.0.9)
## 0.0.8
2026-07-03
**Added**
- **Table** adds row and cell props via `onRow`, `onHeaderRow`, `onCell` and `onHeaderCell`, plus row styles and callback-based Semantic DOM customization.
**Fixed and improved**
- **Tag** adjusts spacing and line height so its text and icon align more consistently.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.7...v0.0.8)
## 0.0.7
2026-07-03
**Added**
- **Table** defaults to the new `modern` variant with a subtle frame and lighter header. Existing variants can still be selected explicitly.
**Fixed and improved**
- **Select** centers text and icons and allows keyboard clearing with Enter or Space. **Tag** refines semantic color fills and close button styling.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.6...v0.0.7)
## 0.0.6
2026-07-02
**Fixed and improved**
- **TaoProvider** recalculates derived tokens inside nested providers and keeps children in their parent flex or grid layout. Equivalent inline token values avoid unnecessary context updates.
- **Theme and Button** update the default radius from 6px to 10px, refine focus rings and borders, and adjust button text weight and shadows.
**Migration**
- **Input, Textarea, Select and date pickers** fill the available width by default. Set the width explicitly if a layout relied on the old 200px default.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.5...v0.0.6)
## 0.0.5
2026-07-01
**Fixed and improved**
- **Input** fills the available width in a flex row. Single-row **Textarea** matches the Input height for the same size.
**Compatibility**
- The package preserves entry-point CSS with strict tree shaking.
**Migration**
- Set `rows={3}` to keep the previous taller Textarea default.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.4...v0.0.5)
## 0.0.4
2026-06-08
**Compatibility**
- Replaced Tailwind and PostCSS-generated styles with native CSS and centralized theme and control style imports at the package entry point.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.3...v0.0.4)
## 0.0.3
2026-06-07
**Added**
- **Select** adds an Ant Design-style single-select API for controlled opening, popup placement and width, custom rendering, grouped options and semantic styling.
- Added **Spinner** with delay, custom indicator, content overlay and fullscreen modes.
**Fixed and improved**
- Portaled controls inherit theme tokens. Popup layers render above Modal and Drawer, and clearing Select keeps the popup closed.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.2...v0.0.3)
## 0.0.2
2026-06-07
**Added**
- Added **Breadcrumb, Collapsible, ContextMenu, Dropdown and Textarea**. Textarea supports shared control variants and `autoSize` with minimum and maximum rows.
- Added **Modal** with a controlled `open` prop, imperative confirmation and status methods, and `Modal.useModal()`.
**Fixed and improved**
- Form controls share focus and variant styles. Container and elevated surfaces use white with derived neutral colors.
[Compare changes](https://github.com/rickyshin93/tao-ui/compare/v0.0.1...v0.0.2)
## 0.0.1
2026-06-06
**Added**
- Initial release of **@rockshin/tao-ui** for React 19, with semantic DOM customization and OKLCH theme tokens.
---
url: https://rickyshin93.github.io/tao-ui/components/border-beam.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# BorderBeam
General`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Highlights an active surface with a moving border light.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Props follow the 6.7.0 beam API. The child must expose a native DOM ref or nativeElement handle. Motion uses transform and respects reduced-motion preferences.
## When to use
Use sparingly for a meaningful active or processing state. Keep an explicit text status alongside the effect.
## Examples
### Active card
```tsx preview
import { BorderBeam, Card } from "@rockshin/tao-ui";
export default function Example() {
return (
12 tasks are running.
);
}
```
### Count and duration
```tsx preview
import { BorderBeam, Card } from "@rockshin/tao-ui";
export default function Example() {
return (
Two highlights follow the same border with evenly spaced phases.
);
}
```
### Custom gradient and item overrides
```tsx preview
import { BorderBeam, Card } from "@rockshin/tao-ui";
export default function Example() {
return (
Each item controls its own color, size and line width.
);
}
```
### Inset and nonuniform corners
```tsx preview
import { BorderBeam, Card } from "@rockshin/tao-ui";
export default function Example() {
return (
The effect follows the top rounded corners and the square bottom
corners.
);
}
```
### Toggle a meaningful active state
```tsx preview
import { useState } from "react";
import { BorderBeam, Button, Card } from "@rockshin/tao-ui";
export default function Example() {
const [active, setActive] = useState(true);
return (
setActive(!active)} style={{ marginBottom: 16 }}>
{active ? "Pause" : "Resume"}
The border animation follows the current state.
);
}
```
## API
### [#](#borderbeam)BorderBeam
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/button.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Button
General`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Use `Button` for immediate actions such as submitting a form, saving changes, or opening a surface.
## Examples
### Variants
Use one primary action per view or decision area. Secondary, ghost, and destructive variants reduce or clarify emphasis. Bare preserves button behavior while leaving its visual treatment to consumer classes or styles.
```tsx preview
import { Button } from '@rockshin/tao-ui';
function ButtonVariants() {
return (
Primary
Secondary
Ghost
Bare
Delete
);
}
export default ButtonVariants;
```
### Sizes
Use `small` for dense toolbars, `medium` for most actions, and `large` for prominent calls to action.
```tsx preview
import { Button } from '@rockshin/tao-ui';
function ButtonSizes() {
return (
Small
Medium
Large
);
}
export default ButtonSizes;
```
### Loading and disabled
Loading buttons set `aria-busy` and prevent repeated interaction. Their icon slot stays mounted, so switching states does not shift the content.
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';
function ButtonStates() {
const [saving, setSaving] = useState(false);
function save() {
setSaving(true);
window.setTimeout(() => setSaving(false), 1200);
}
return (
Loading
Loading
Disabled
Save changes
);
}
export default ButtonStates;
```
### Icons and custom loading
Pass a decorative leading icon with `icon`. Explicit SVG dimensions are preserved; unspecified dimensions default to the button's font size. Use `loadingIcon` only when the built-in spinner does not match the surrounding visual language.
```tsx preview
import { Button } from '@rockshin/tao-ui';
function DownloadIcon() {
return (
);
}
function ProgressIcon() {
return (
);
}
function ButtonIcons() {
return (
}>Download
}>
Export
}>
Processing
);
}
export default ButtonIcons;
```
### Provider defaults
Buttons inherit `size` and `disabled` from `TaoProvider`. A local prop can override the inherited size.
```tsx preview
import { Button, TaoProvider } from '@rockshin/tao-ui';
function ButtonProviderDefaults() {
return (
Inherited small
Local large
Provider disabled
Also disabled
);
}
export default ButtonProviderDefaults;
```
### Semantic customization
Customize the stable `root` part without depending on private selectors.
```tsx preview
import { Button } from '@rockshin/tao-ui';
function CustomizedButton() {
return (
Checkout
);
}
export default CustomizedButton;
```
### Native form actions
Submit and reset use native form semantics; no network request is sent.
```tsx preview
import { useState } from 'react';
import { Button, Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [result, setResult] = useState('');
return (
);
}
```
### Icon-only buttons
Provide a name with aria-label and hide decorative icons from assistive technology.
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';
export default function Example() {
const [count, setCount] = useState(0);
return (
setCount(count + 1)}>
{count} items
);
}
```
### Provider defaults and overrides
Set shared size and disabled defaults, then override a single button.
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function Example() {
return (
Inherited disabled
Available
Large override
);
}
```
## API
### [#](#button)Button
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Prevents interaction. Inherits from TaoProvider. | `boolean | undefined` | `-` |
| children | Button label or inline content. | `ReactNode` | `-` |
| variant | Visual emphasis for the action. | `"primary" | "secondary" | "ghost" | "destructive" | "bare" | undefined` | `primary` |
| size | Control height and horizontal spacing. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| loading | Shows the loading icon, sets aria-busy, and prevents interaction. | `boolean | undefined` | `-` |
| icon | Left-leading decorative icon (non-loading state). | `ReactNode` | `-` |
| loadingIcon | Icon shown while loading. Defaults to a built-in spinner. | `ReactNode` | `-` |
| classNames | Semantic class overrides keyed by ButtonSemanticPart. | `Partial> | undefined` | `-` |
| styles | Semantic style overrides keyed by ButtonSemanticPart. | `Partial> | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/icons.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Icons
Explore rounded line icons for everyday interfaces and insurance workflows. Browse by category or search by name or keyword. Select an icon to copy its import.
## Installation
The icons support React 18.2 and later and are available under the [MIT License
](/tao-ui/tao-icons-LICENSE.txt).
```sh
npm install @rockshin/tao-icons
```
## Icon catalog
2060 / 2060 icons
### Navigation
147 icons
arrow-big-downarrow-big-down-dasharrow-big-leftarrow-big-left-dasharrow-big-rightarrow-big-right-dash
### Actions
23 icons
closecopydownloadfilterfunnellink
### Files & documents
105 icons
archivearchive-restorearchive-xbook-openbookmarkbookmark-minus
### Editing
88 icons
axis-3dblendbrushcomponentcropdecimals-arrow-left
### Layout & typography
263 icons
a-arrow-downa-arrow-upa-large-smallalign-bottomalign-centeralign-center-vertical
### People & security
114 icons
awardbadgebadge-alertbadge-checkbadge-infobell-check
### Communication
119 icons
at-signbadge-minusbadge-percentbadge-plusbadge-xballoon
### Media
100 icons
adairplayapertureaudio-linesaudio-lines-offaudio-lines-x
### Time & status
77 icons
alarm-clockalarm-clock-offalert-circlealert-trianglebell-minusbell-plus
### Devices
76 icons
alarm-clock-checkalarm-clock-minusalarm-clock-plusantennabattery-mediumbattery-plus
### Developer tools
92 icons
bitcoinblocksbook-copybook-dashedbook-downbook-key
### Commerce & places
99 icons
anvilbadge-centbadge-dollar-signbadge-eurobadge-indian-rupeebadge-japanese-yen
### Everyday utility
22 icons
axeboltbroombroom-sparkleschart-columnchart-line
### Lines & insured objects
12 icons
insurance-accidentinsurance-autoinsurance-commercialinsurance-cyberinsurance-engineeringinsurance-health
### Product & rating
11 icons
coveragecoverage-exclusioncoverage-limitinsurance-deductiblepolicy-wordingpremium-rating
### Distribution & sales
10 icons
broker-networkcommission-paymentcommission-planembedded-insuranceinsurance-agentinsurance-needs
### Quote & application
10 icons
applicantapplication-submitbeneficiarybenefit-illustrationelectronic-signatureinsurance-application
### Underwriting
10 icons
medical-underwritingrisk-accumulationrisk-scorerisk-surveyunderwriting-acceptunderwriting-conditions
### Policy lifecycle
13 icons
coverage-periodinsurance-certificateinsurance-policypolicy-bindpolicy-cancelpolicy-endorsement
### Billing & payments
44 icons
agency-billingarmenian-dramautomatic-paymentbangladeshi-takabanknote-arrow-downbanknote-arrow-up
### Claims
16 icons
claim-appealclaim-assignmentclaim-caseclaim-coverage-checkclaim-denialclaim-investigation
### Reinsurance & coinsurance
8 icons
coinsurance-sharereinsurance-assumedreinsurance-bordereaureinsurance-cessionreinsurance-facultativereinsurance-recovery
### Health & group
12 icons
benefit-accumulatorbenefit-planbenefit-statementcost-sharinggroup-policymedical-claim-pricing
### Life & annuities
9 icons
annuity-paymentfund-switchmaturity-benefitpartial-withdrawalpolicy-cash-valuepolicy-loan
### Compliance & operations
8 icons
complaint-casecustomer-verificationinsurance-ledgerregulatory-reportsanctions-screeningservice-network
### Actions & form controls
24 icons
check-checkcheckboxcheckbox-checkedcheckbox-indeterminatecircle-minuscircle-plus
### Data & charts
38 icons
activitycalculatorchart-areachart-barchart-bar-bigchart-bar-decreasing
### Connectivity
60 icons
batterybattery-chargingbattery-fullbattery-lowbattery-warningbluetooth-connected
### Accessibility
18 icons
accessibilitybabybadge-question-markcaptionsclosed-captioncontrast
### Development & AI
19 icons
botbracketsbrainchart-networkcloud-checkcloud-off
### Animals & nature
37 icons
birdbirdhousebonecannabiscannabis-offcat
### Food & drink
76 icons
amphoraappleavocadobaconbananabarrel
### Games & sports
49 icons
backpackbow-arrowchess-bishopchess-kingchess-knightchess-pawn
### Health & medicine
34 icons
ambulancebandagebone-fracturebrain-offbriefcase-medicalcross
### Home & living
39 icons
air-ventalarm-smokearmchairbedbed-doublebed-single
### Math & science
48 icons
angleatombeakerbiohazardbrain-circuitbrain-cog
### Shapes & symbols
33 icons
astroidboxboxescircle-dashed-checkcircle-offcircle-pile
### Transport & travel
63 icons
anchorbaggage-claimbathbikebridgebriefcase
### Weather & seasons
34 icons
bubblescloud-drizzlecloud-fogcloud-hailcloud-lightningcloud-moon
## React examples
### Basic usage
Import named icons from the package. Icons render at 24px by default.
```tsx preview
import { HomeIcon, SearchIcon, SettingsIcon } from '@rockshin/tao-icons';
export default function BasicIcons() {
return (
);
}
```
### Size and stroke
Set size to change the dimensions and strokeWidth to adjust line weight.
```tsx preview
import { StarIcon } from '@rockshin/tao-icons';
export default function IconSizing() {
return (
);
}
```
### Color
Icons inherit the text color. Set color to override an individual icon.
```tsx preview
import { HeartIcon, CircleCheckIcon, TriangleAlertIcon } from '@rockshin/tao-icons';
export default function IconColors() {
return (
);
}
```
### Buttons and accessibility
Icons in labeled buttons can stay decorative. Give icon-only buttons an accessible name.
```tsx preview
import { DownloadIcon, SettingsIcon } from '@rockshin/tao-icons';
import { Button } from '@rockshin/tao-ui';
export default function IconButtons() {
return (
}>Download
} />
);
}
```
### State changes
Use React state to switch icons. Try the button in the preview.
```tsx preview
import { useState } from 'react';
import { VolumeIcon, VolumeOffIcon } from '@rockshin/tao-icons';
import { Button } from '@rockshin/tao-ui';
export default function VolumeToggle() {
const [muted, setMuted] = useState(false);
return (
: }
onClick={() => setMuted((value) => !value)}
>
{muted ? 'Muted' : 'Sound on'}
);
}
```
### Per-icon import
Each icon has a dedicated import path. Use title to name a standalone icon.
```tsx preview
import { ArrowRightIcon } from '@rockshin/tao-icons/icons/arrow-right';
export default function DirectImport() {
return ;
}
```
---
url: https://rickyshin93.github.io/tao-ui/components/float-button.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# FloatButton
General`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Provides persistent floating actions and a return-to-top control.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Buttons, Group and BackTop follow 6.7.0. Tooltips and badges use tao-ui components; scroll animations respect reduced motion. Fixed controls are isolated in iframe previews.
## When to use
Use for a few actions that apply across the current screen. Provide accessible labels for icon-only buttons.
## Examples
### Basic action and tooltip
```tsx preview="iframe-follow"
import { useState } from "react";
import { FloatButton } from "@rockshin/tao-ui";
export default function Example() {
const [count, setCount] = useState(0);
return (
Action count: {count}
setCount(count + 1)}
/>
);
}
```
### Shape, content and badge
```tsx preview="iframe-follow"
import { FloatButton } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Click group and placement
```tsx preview="iframe-follow"
import { useState } from "react";
import { FloatButton } from "@rockshin/tao-ui";
export default function Example() {
const [selected, setSelected] = useState("None");
return (
Selected: {selected}
setSelected("Action A")} />
setSelected("Action B")} />
);
}
```
### Controlled group
```tsx preview="iframe-follow"
import { useState } from "react";
import { Button, FloatButton } from "@rockshin/tao-ui";
export default function Example() {
const [open, setOpen] = useState(false);
return (
setOpen(!open)}>
{open ? "Close actions" : "Open actions"}
);
}
```
### Hover and disabled actions
```tsx preview="iframe-follow"
import { FloatButton } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Return to a scroll container top
```tsx preview="iframe-follow"
import { useRef } from "react";
import { FloatButton } from "@rockshin/tao-ui";
export default function Example() {
const target = useRef(null);
return (
Scroll down to reveal BackTop.
target.current!}
visibilityHeight={120}
showProgress
duration={250}
/>
);
}
```
## API
### [#](#floatbutton)FloatButton
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/watermark.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Watermark
General`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Repeats text or an image across content and inherited dialogs.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Canvas drawing follows the 6.7.0 content/font/gap/offset API. Modal and Drawer inherit by default; inherit=false disables portal inheritance. Removed or changed overlays are restored.
## When to use
Use to mark an owner, workspace or document classification while keeping the content readable.
## Examples
### Text watermark
```tsx preview
import { Watermark } from "@rockshin/tao-ui";
export default function Example() {
return (
Workspace report
Content remains selectable and interactive.
);
}
```
### Multiple lines and fonts
```tsx preview
import { Watermark } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Rotation, gap and offset
```tsx preview
import { Watermark } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Image with text fallback
```tsx preview
import { Watermark } from "@rockshin/tao-ui";
const image = `data:image/svg+xml,${encodeURIComponent('TAO ')}`;
export default function Example() {
return (
);
}
```
### Inherited Modal and Drawer
```tsx preview="iframe-follow"
import { useState } from "react";
import { Button, Drawer, Modal, Watermark } from "@rockshin/tao-ui";
export default function Example() {
const [panel, setPanel] = useState("");
return (
setPanel("modal")}>Open modal {" "}
setPanel("drawer")}>Open drawer
setPanel("")}
title="Marked modal"
footer={null}
>
This portaled panel inherits the watermark.
setPanel("")}
title="Marked drawer"
>
The drawer inherits the same watermark.
);
}
```
### Disable portal inheritance
```tsx preview="iframe-follow"
import { useState } from "react";
import { Button, Modal, Watermark } from "@rockshin/tao-ui";
export default function Example() {
const [open, setOpen] = useState(false);
return (
setOpen(true)}>Open unmarked modal
setOpen(false)}
title="No inherited mark"
footer={null}
>
Only the containing page has a watermark.
);
}
```
## API
### [#](#watermark)Watermark
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/divider.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Divider
Layout`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Separates content into readable sections or inline groups.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Use titlePlacement for the title position and orientation for the axis. TaoProvider controls the default size.
## When to use
Use separators when nearby content has a meaningful boundary.
## Examples
### Sections and titles
```tsx preview
import { Divider } from "@rockshin/tao-ui";
export default function Example() {
return (
Workspace overview
Activity
Recent changes and updates.
End of report.
);
}
```
### Title placement
```tsx preview
import { Divider } from "@rockshin/tao-ui";
export default function Example() {
return (
Start
Center
End
Plain label
);
}
```
### Line styles and spacing
```tsx preview
import { Divider } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Inline separators and RTL
```tsx preview
import { Divider } from "@rockshin/tao-ui";
export default function Example() {
return (
Overview
Activity
Settings
);
}
```
### Semantic styling
```tsx preview
import { Divider } from "@rockshin/tao-ui";
export default function Example() {
return (
Custom section
);
}
```
## API
### [#](#divider)Divider
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| type | @deprecated Use orientation. | `"vertical" | "horizontal" | undefined` | `-` |
| orientationMargin | @deprecated Use styles.content margins. | `string | number | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/form-layout.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# FormLayout
Layout`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Arranges form content with consistent label and control alignment.
## When to use
Use FormLayout to keep dense forms aligned and predictable.
**Recommended**
- Use one layout strategy per form.
- Prefer vertical layout on narrow screens.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import {
Button,
FormActions,
FormField,
FormLayout,
FormSection,
Input,
} from '@rockshin/tao-ui';
function FormLayoutExample() {
return (
Cancel
Create account
);
}
export default FormLayoutExample;
```
### Multiple sections
```tsx preview
import {
Button,
FormActions,
FormField,
FormLayout,
FormSection,
Input,
} from '@rockshin/tao-ui';
function CompleteFormLayout() {
return (
Cancel
Save profile
);
}
export default CompleteFormLayout;
```
### Semantic customization
```tsx preview
import { Button, FormActions, FormLayout } from '@rockshin/tao-ui';
function CustomizedFormLayout() {
return (
Layout width is customized through the stable root part.
Continue
);
}
export default CustomizedFormLayout;
```
### Complete form composition
Compose layout, fields, and actions with native submission feedback.
```tsx preview
import { useState } from 'react';
import {
FormLayout,
FormSection,
FormField,
FormActions,
Input,
Textarea,
Button,
} from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState('');
return (
);
}
```
### Responsive form columns
Use CSS Grid on the semantic root to collapse to one column when space is limited.
```tsx preview="iframe-follow"
import { FormLayout, FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Grouped form sections
Use section titles for hierarchy and the outer layout for spacing.
```tsx preview
import {
FormLayout,
FormSection,
FormField,
Input,
Switch,
} from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#formlayout)FormLayout
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/splitter.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Splitter
Layout`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Creates resizable panes separated by draggable handles.
## When to use
Use Splitter for work surfaces where users need to allocate space between adjacent panes.
**Recommended**
- Set sensible min sizes.
- Persist sizes only when the layout is user-specific.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
function SplitterExample() {
return (
);
}
export default SplitterExample;
```
### Vertical and multiple panels
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
function SplitterLayouts() {
return (
);
}
export default SplitterLayouts;
```
### Collapsible panel
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
function CollapsibleSplitter() {
return (
Collapsible navigation
Main content
);
}
export default CollapsibleSplitter;
```
### Three panels
Multiple panels share the available space; drag the adjacent separators to change their proportions.
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
const Panel = Splitter.Panel;
const boxStyle = (bg: string): React.CSSProperties => ({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: '100%',
minHeight: 40,
background: bg,
borderRadius: 4,
color: 'var(--tao-color-text-secondary)',
fontSize: 14,
});
export default function SplitterThreePanels() {
return (
);
}
```
### Collapsible panels
Collapse and restore supporting panels while retaining the main work area.
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
const Panel = Splitter.Panel;
const boxStyle = (bg: string): React.CSSProperties => ({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: '100%',
minHeight: 40,
background: bg,
borderRadius: 4,
color: 'var(--tao-color-text-secondary)',
fontSize: 14,
});
export default function SplitterCollapsible() {
return (
);
}
```
### Panel size limits
Constrain resizing with `min` and `max` so content remains usable.
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
const Panel = Splitter.Panel;
const boxStyle = (bg: string): React.CSSProperties => ({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: '100%',
minHeight: 40,
background: bg,
borderRadius: 4,
color: 'var(--tao-color-text-secondary)',
fontSize: 14,
});
export default function SplitterMinMax() {
return (
);
}
```
### Controlled panel sizes
Observe size changes and keep the layout in application state so it can be reset.
```tsx preview
import { Splitter, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
const Panel = Splitter.Panel;
const boxStyle = (bg: string): React.CSSProperties => ({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: '100%',
minHeight: 40,
background: bg,
borderRadius: 4,
color: 'var(--tao-color-text-secondary)',
fontSize: 14,
});
export default function SplitterControlled() {
function Demo() {
const [sizes, setSizes] = useState([]);
return (
sizes: [{sizes.map((s) => Math.round(s)).join(', ')}]
);
}
return ;
}
```
### Nested splitters
Combine horizontal and vertical splitters into an editor layout with bounded container heights.
```tsx preview
import { Splitter } from '@rockshin/tao-ui';
const Panel = Splitter.Panel;
const boxStyle = (bg: string): React.CSSProperties => ({
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: '100%',
minHeight: 40,
background: bg,
borderRadius: 4,
color: 'var(--tao-color-text-secondary)',
fontSize: 14,
});
export default function SplitterNested() {
return (
);
}
```
## API
### [#](#panel)Panel
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| style | Additional style | `CSSProperties | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
### [#](#splitter)Splitter
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
### [#](#splitterpanel)Splitter.Panel
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| style | Additional style | `CSSProperties | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/stack.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Stack
Layout`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Composes children in a flex row or column with consistent spacing.
## When to use
Use Stack for simple one-dimensional layout and spacing.
**Recommended**
- Prefer Stack over one-off margin rules for repeated spacing.
- Use semantic containers when the layout has richer meaning.
- Pass breakpoint maps (for example, `direction={{ xs: 'vertical', md: 'horizontal' }}`) for responsive layouts.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
function StackExample() {
return (
Design
Engineering
Research
);
}
export default StackExample;
```
### Direction, spacing, and alignment
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
function StackVariants() {
return (
Small gap
Centered
Large gap
End aligned
);
}
export default StackVariants;
```
### Responsive direction
```tsx preview
import { Button, Stack } from '@rockshin/tao-ui';
function ResponsiveStack() {
return (
Save
Preview
Cancel
);
}
export default ResponsiveStack;
```
### Alignment
Use align and justifyContent on the root to position children.
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Start
Centered vertically
End
);
}
```
### Wrapping items
Enable flexWrap on the semantic root so a long toolbar can wrap.
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
{['Overview', 'Members', 'Permissions', 'Billing', 'Settings'].map(
(item) => (
{item}
),
)}
);
}
```
### Responsive direction and gap
Use a vertical arrangement in narrow viewports and horizontal at wider breakpoints. Compare the phone preview.
```tsx preview="iframe-follow"
import { Stack, Input, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Continue
);
}
```
### Nested layouts
Let the outer stack space sections and the inner stack group related actions.
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Workspace
Invite members and manage access.
Invite member
Manage roles
);
}
```
## API
### [#](#stack)Stack
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| direction | Flex direction. Accepts a breakpoint map, e.g.
`direction={{ xs: 'vertical', md: 'horizontal' }}` — the largest matching
breakpoint wins (SSR/first render falls back to the plain default). | `TaoResponsiveValue | undefined` | `vertical` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/affix.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Affix
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Pins content when it crosses a scroll container boundary.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Affix uses fixed positioning and a placeholder, not CSS sticky. target returns a Window or HTMLElement; offsets are measured from that target.
## When to use
Keep a small set of actions visible within a defined scroll target. The examples use a dedicated scroll container.
## Examples
### Top boundary
```tsx preview="iframe-follow"
import { useRef } from "react";
import { Affix, Button } from "@rockshin/tao-ui";
export default function Example() {
const target = useRef(null);
return (
Scroll down in this panel.
target.current} offsetTop={12}>
Pinned actions
More content
);
}
```
### Observe affixed state
```tsx preview="iframe-follow"
import { useRef, useState } from "react";
import { Affix, Button } from "@rockshin/tao-ui";
export default function Example() {
const target = useRef(null);
const [affixed, setAffixed] = useState(false);
return (
{affixed ? "Actions are pinned" : "Actions are in the document flow"}
target.current}
onChange={(value) => setAffixed(Boolean(value))}
>
Actions
);
}
```
### Bottom boundary
```tsx preview="iframe-follow"
import { useRef } from "react";
import { Affix, Button } from "@rockshin/tao-ui";
export default function Example() {
const target = useRef(null);
return (
Scroll to the end to return the action to its original position.
target.current} offsetBottom={12}>
Bottom actions
);
}
```
### Change the offset and update position
```tsx preview="iframe-follow"
import { useRef, useState } from "react";
import { Affix, Button, type AffixRef } from "@rockshin/tao-ui";
export default function Example() {
const target = useRef(null);
const affix = useRef(null);
const [offset, setOffset] = useState(8);
return (
setOffset(offset === 8 ? 32 : 8)}>
Offset: {offset}px
{" "}
affix.current?.updatePosition()}>
Recalculate
target.current} offsetTop={offset}>
Tools
);
}
```
## API
### [#](#affix)Affix
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/breadcrumb.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Breadcrumb
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Renders the user location in a hierarchy of pages or views.
## When to use
Use Breadcrumb near the top of a page when users need to understand or move through nested context.
**Recommended**
- Keep labels short and recognizable.
- Use links for ancestors and plain text for the current item.
**Avoid**
- Do not use Breadcrumb as primary navigation.
## Examples
### Basic usage
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';
function BreadcrumbExample() {
return (
);
}
export default BreadcrumbExample;
```
### Separators and collapsed paths
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
function BreadcrumbSeparators() {
const items = [
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Settings', href: '#breadcrumb-example-1' },
{ title: 'Profile' },
];
return (
);
}
export default BreadcrumbSeparators;
```
### Disabled items and sizes
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
function BreadcrumbStates() {
const items = [
{ title: 'Home', href: '#breadcrumb-example-1' },
{ title: 'Archived', href: '#breadcrumb-example-1', disabled: true },
{ title: 'Item' },
];
return (
);
}
export default BreadcrumbStates;
```
### Custom separators
Change `separator` without changing link or current-page semantics.
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function BreadcrumbCustomSeparator() {
return (
);
}
```
### Collapsed paths
`maxItems` collapses middle segments; open the overflow menu to reach hidden levels.
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbCollapsed() {
return (
);
}
```
### Disabled items
Mark unavailable destinations with `disabled` while retaining the current page title.
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbDisabled() {
return (
);
}
```
### Custom link rendering
Use `itemRender` to integrate an application link component while retaining accessible link behavior.
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';
export default function BreadcrumbCustomLink() {
return (
isLast ? (
item.title
) : (
// Any custom element works — e.g. a router . Slot merges the
// breadcrumb link styles onto it instead of adding another .
{item.title}
)
}
/>
);
}
```
### Breadcrumb sizes
Use TaoProvider `size` to match a compact toolbar or a spacious page header.
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function BreadcrumbSizes() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
## API
### [#](#breadcrumb)Breadcrumb
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| items | Breadcrumb path, root first. The last item renders as the current page. | `BreadcrumbItemType[]` **(Required)** | `-` |
| separator | Separator between items. Defaults to a chevron, like shadcn. | `ReactNode` | `-` |
| maxItems | Collapse the middle of long paths into an ellipsis once the number of
items exceeds this value. Shows the first item and the last
`maxItems - 1` items. | `number | undefined` | `-` |
| itemRender | Custom renderer for an item's content. Return a React element (e.g. a
router ` `) and its props are merged onto the breadcrumb link via
Radix Slot — no extra `` wrapper is added. | `((item: BreadcrumbItemType, info: { index: number; isLast: boolean; items: BreadcrumbItemType[]; }) => ReactNode) | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/context-menu.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# ContextMenu
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays contextual actions from a right click or long press interaction.
## When to use
Use ContextMenu for secondary actions attached to an object or region.
**Recommended**
- Keep items short and action-oriented.
- Provide another reachable path for critical actions.
**Avoid**
- Do not put primary workflows only inside a context menu.
## Examples
### Basic usage
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
function ContextMenuExample() {
return (
Right-click this area
);
}
export default ContextMenuExample;
```
### Groups, disabled items, and submenus
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
function ContextMenuGroups() {
return (
Right-click for grouped actions
);
}
export default ContextMenuGroups;
```
### Selectable menu items
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
import { useState } from 'react';
function SelectableContextMenu() {
const [selected, setSelected] = useState(['comfortable']);
return (
setSelected(selectedKeys),
items: [
{ key: 'compact', label: 'Compact' },
{ key: 'comfortable', label: 'Comfortable' },
{ key: 'spacious', label: 'Spacious' },
],
}}
>
Current density: {selected[0]}
);
}
export default SelectableContextMenu;
```
### Groups and submenus
Organize actions with groups and nested `children`; mark destructive actions with `danger`. Right-click the area.
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
function Area({ children = 'Right-click here' }: { children?: string }) {
return (
{children}
);
}
export default function ContextMenuGroupsAndSubmenu() {
return (
);
}
```
### Selectable menu items
Keep selection in `selectedKeys` and `onSelect`, for example for view preferences.
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
import { useState } from 'react';
function Area({ children = 'Right-click here' }: { children?: string }) {
return (
{children}
);
}
export default function ContextMenuSelectable() {
const [checked, setChecked] = useState(['grid']);
return (
setChecked(selectedKeys),
items: [
{ key: 'grid', label: 'Show grid' },
{ key: 'ruler', label: 'Show ruler' },
{ key: 'guides', label: 'Show guides' },
],
}}
>
{`Right-click — ${checked.length} shown`}
);
}
```
### Disabled context menu
`disabled` turns off the custom menu. Keep essential actions available outside a context menu.
```tsx preview
import { ContextMenu, type MenuItem } from '@rockshin/tao-ui';
function Area({ children = 'Right-click here' }: { children?: string }) {
return (
{children}
);
}
export default function ContextMenuDisabled() {
return (
);
}
```
## API
### [#](#contextmenu)ContextMenu
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Element whose right-click (long-press on touch) opens the menu. | `ReactNode` **(Required)** | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/dropdown.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Dropdown
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Opens a menu of actions or navigation choices from a trigger.
## When to use
Use Dropdown for compact action sets that do not need to stay visible.
**Recommended**
- Order frequent actions first.
- Use destructive styling only for destructive items.
**Avoid**
- Do not use Dropdown as a replacement for visible primary navigation.
## Examples
### Basic usage
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';
function DropdownExample() {
return (
Actions
);
}
export default DropdownExample;
```
### Groups and submenus
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';
function DropdownGroups() {
return (
Project actions
);
}
export default DropdownGroups;
```
### Trigger, arrow, and split button
```tsx preview
import { useState } from 'react';
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';
const items = [
{ key: 'edit', label: 'Edit' },
{ key: 'duplicate', label: 'Duplicate' },
];
function DropdownTriggers() {
const [feedback, setFeedback] = useState('');
return (
<>
Hover
Click with arrow
setFeedback('save')}>
Save
{feedback}
>
);
}
export default DropdownTriggers;
```
### Icons, shortcuts, and disabled items
Items support icons and extra content. Shortcut text is a hint and does not register a global keyboard shortcut.
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';
function FileIcon() {
return (
);
}
function CopyIcon() {
return (
);
}
function ClipboardIcon() {
return (
);
}
export default function DropdownWithIconsAndShortcuts() {
return (
, extra: '⌘N' },
{ key: 'copy', label: 'Copy', icon: , extra: '⌘C' },
{
key: 'paste',
label: 'Paste',
icon: ,
extra: '⌘V',
disabled: true,
},
],
}}
>
Actions
);
}
```
### Groups and dividers
Group related tasks and separate different categories with dividers.
```tsx preview
import { Button, Dropdown } from '@rockshin/tao-ui';
export default function DropdownDividerAndGroup() {
return (
Account
);
}
```
### Nested submenus
Nested `children` create submenus that remain navigable with arrow keys.
```tsx preview
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';
export default function DropdownSubmenu() {
return (
Right menu
);
}
```
### Controlled menu selection
Manage selected keys in application state for view modes or filtering choices.
```tsx preview
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DropdownSelectable() {
const [single, setSingle] = useState(['md']);
const [multi, setMulti] = useState(['bold']);
return (
setSingle(selectedKeys),
items: [
{ key: 'sm', label: 'Small' },
{ key: 'md', label: 'Medium' },
{ key: 'lg', label: 'Large' },
],
}}
>
Size: {single[0]}
setMulti(selectedKeys),
items: [
{ key: 'bold', label: 'Bold' },
{ key: 'italic', label: 'Italic' },
{ key: 'underline', label: 'Underline' },
],
}}
>
Format ({multi.length})
);
}
```
### Menu placement
Configure `placement`; the popup still avoids viewport edges.
```tsx preview
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';
const basicItems: MenuItem[] = [
{ key: 'profile', label: 'Profile' },
{ key: 'billing', label: 'Billing' },
{ key: 'settings', label: 'Settings' },
];
export default function DropdownPlacement() {
return (
{(
[
'topLeft',
'top',
'topRight',
'bottomLeft',
'bottom',
'bottomRight',
] as const
).map((p) => (
{p}
))}
);
}
```
### Trigger behavior
Try click and hover triggers; retain a click entry point for touch devices.
```tsx preview
import { Button, Dropdown, type MenuItem, Stack } from '@rockshin/tao-ui';
const basicItems: MenuItem[] = [
{ key: 'profile', label: 'Profile' },
{ key: 'billing', label: 'Billing' },
{ key: 'settings', label: 'Settings' },
];
export default function DropdownTrigger() {
return (
Hover me
Click (with arrow)
);
}
```
## API
### [#](#dropdown)Dropdown
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Trigger element (a single React element). | `ReactNode` **(Required)** | `-` |
| trigger | How the menu opens. Defaults to `['click']`. | `DropdownTrigger[] | undefined` | `-` |
| placement | Defaults to `'bottomLeft'`. Ignored for `contextMenu`. | `DropdownPlacement | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| arrow | Show a pointing arrow on the menu. Defaults to `false`. | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#dropdownbutton)Dropdown.Button
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| children | Main button content. | `ReactNode` | `-` |
| onClick | Main button click handler. | `(() => void) | undefined` | `-` |
| icon | Icon for the trigger button. Defaults to an ellipsis. | `ReactNode` | `-` |
| trigger | How the menu opens. Defaults to `['click']`. | `DropdownTrigger[] | undefined` | `-` |
| placement | Defaults to `'bottomLeft'`. Ignored for `contextMenu`. | `DropdownPlacement | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| arrow | Show a pointing arrow on the menu. Defaults to `false`. | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/pagination.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Pagination
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Moves through paged data with current page and page-size controls.
## When to use
Use Pagination when a collection is split into pages rather than infinitely loaded.
**Recommended**
- Keep the current page controlled when data is loaded remotely.
- Show total counts when they help users judge scope.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Pagination } from '@rockshin/tao-ui';
import { useState } from 'react';
function PaginationExample() {
const [page, setPage] = useState(1);
return (
range[0] + '-' + range[1] + ' of ' + total}
/>
);
}
export default PaginationExample;
```
### Sizes
```tsx preview
import { Pagination, Stack } from '@rockshin/tao-ui';
function PaginationSizes() {
return (
);
}
export default PaginationSizes;
```
### Page size and totals
```tsx preview
import { Pagination } from '@rockshin/tao-ui';
import { useState } from 'react';
function PaginationPageSize() {
const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(10);
return (
range[0] + '-' + range[1] + ' of ' + total}
onChange={(nextPage, nextPageSize) => {
setPage(nextPage);
setPageSize(nextPageSize);
}}
/>
);
}
export default PaginationPageSize;
```
### Display totals
`showTotal` can describe the current record range and total count.
```tsx preview
import { Pagination } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function PaginationWithTotal() {
function Demo() {
const [page, setPage] = useState(1);
return (
setPage(p)}
showTotal={(t, [s, e]) => `${s}-${e} of ${t}`}
/>
);
}
return ;
}
```
### Change page size
Maintain page and page size together and use both updated values in a data request.
```tsx preview
import { Pagination } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function PaginationSizeChanger() {
function Demo() {
const [page, setPage] = useState(1);
const [ps, setPs] = useState(10);
return (
{
setPage(p);
setPs(s);
}}
showSizeChanger
/>
);
}
return ;
}
```
### Pagination sizes
Size controls the density of pagination buttons and can match the surrounding list.
```tsx preview
import { Pagination } from '@rockshin/tao-ui';
export default function PaginationSizes() {
return (
);
}
```
## API
### [#](#pagination)Pagination
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/steps.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Steps
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Guides users through the ordered stages of a task.
## When to use
Use Steps when the work has a sequence — a checkout flow, an onboarding wizard, a deployment pipeline. Steps also doubles as a progress indicator for a process the user is watching rather than driving.
**Recommended**
- Keep titles to one or two words; move detail into `content`.
- Drive the whole bar from `current` and let the status be derived from position.
- Provide `onChange` when revisiting an already completed step is meaningful.
- Switch to `orientation="vertical"` for long flows or narrow layouts.
**Avoid**
- Do not use Steps for peer views at the same level; use Tabs.
- Do not use Steps for a single indeterminate operation; use Spinner.
- Do not set `status` per item unless a step genuinely failed or was skipped.
## Examples
### Basic usage
```tsx preview
import { Steps } from '@rockshin/tao-ui';
function StepsExample() {
return (
);
}
export default StepsExample;
```
### Vertical and clickable
`onChange` receives the absolute step index. Clicking the current step is a no-op, and `disabled` items never become interactive.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
const items = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
{ title: 'Locked', content: 'Unavailable.', disabled: true },
];
function ClickableSteps() {
const [current, setCurrent] = useState(0);
return (
);
}
export default ClickableSteps;
```
### Status, variants, and sizes
`status` sets the state of the current step; every other step derives its own state from position. `variant` picks a solid or outlined icon treatment and `size` switches density.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
const items = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
function StepsStatus() {
return (
);
}
export default StepsStatus;
```
### Types
`type` changes the whole shape of the bar: `dot` replaces numbered icons with small dots, `navigation` turns each step into a clickable tab with an underline, and `panel` renders steps as contiguous notched panels.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
const items = [
{ title: 'One', content: 'First step' },
{ title: 'Two', content: 'Second step' },
{ title: 'Three', content: 'Third step' },
];
function StepsTypes() {
const [current, setCurrent] = useState(1);
return (
);
}
export default StepsTypes;
```
### Inline
`type="inline"` renders a compact dot strip whose descriptions live in tooltips. `offset` shifts the strip along its axis and `titlePlacement` moves the label under the dot.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
const items = [
{ title: 'One', content: 'First step' },
{ title: 'Two', content: 'Second step' },
{ title: 'Three', content: 'Third step' },
];
function InlineSteps() {
const [current, setCurrent] = useState(1);
return (
);
}
export default InlineSteps;
```
### Progress and max count
`percent` draws a progress ring around the current icon. `maxCount` collapses long flows, folding the hidden range into a disabled ellipsis step while `onChange` keeps reporting the original indexes.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
const items = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
function StepsProgress() {
return (
({
title: `Step ${index + 1}`,
}))}
/>
);
}
export default StepsProgress;
```
### Custom icons
`items[].icon` replaces a single step's glyph. `iconRender` replaces every glyph and receives the step index, the active flag, and an `Icon` component that renders the semantic icon container.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
const items = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
function CustomIconSteps() {
return (
(
{index + 1}
)}
/>
);
}
export default CustomIconSteps;
```
### Semantic DOM styling
Every part of a step is addressable through `classNames` and `styles`, and each item can override its own parts.
Use `finishIconBackground` and `finishIconColor` to set the built-in finished circle background and check color independently for default, navigation, and panel steps. Dot steps and custom icons are unaffected.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
function StyledSteps() {
return (
);
}
export default StyledSteps;
```
### Clickable steps
Maintain `current` with `onChange` and update the displayed content after a step changes.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsClickable() {
function Demo() {
const [current, setCurrent] = useState(0);
return (
current: {current}
);
}
return ;
}
```
### Current step error
`status="error"` marks the current step as failed; explain the cause in adjacent content.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsErrorStatus() {
return ;
}
```
### Per-step status
Set status per item for workflows that combine completed, failed, and waiting steps.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
export default function StepsPerStepStatus() {
return (
);
}
```
### Title placement
Choose where titles sit relative to step indicators to suit the available space.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsTitlePlacement() {
return (
);
}
```
### Progress within a step
Use `percent` for progress within the current step and change it in this example.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsWithProgress() {
function Demo() {
const [percent, setPercent] = useState(40);
return (
setPercent((p) => (p >= 100 ? 10 : p + 30))}
/>
percent: {percent}
);
}
return ;
}
```
### Dot steps
`type="dot"` uses compact nodes for tracking status.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsDotStyle() {
return ;
}
```
### Custom step dots
Customize step dots with a render callback while retaining titles and status.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsDotWithCustomDot() {
return (
(
)}
/>
);
}
```
### Navigation steps
Navigation steps support switching between stages of a workflow.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function StepsNavigation() {
function Demo() {
const [current, setCurrent] = useState(0);
return (
);
}
return ;
}
```
### Panel steps
Panel steps provide a larger area for titles, descriptions, and interaction.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function StepsPanel() {
function Demo() {
const [current, setCurrent] = useState(1);
return (
);
}
return ;
}
```
### Limit visible steps
Use `maxCount` for a long workflow and observe how the visible range follows the current step.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
export default function StepsMaxCount() {
return (
({
title: `Step ${index + 1}`,
}))}
/>
);
}
```
### Disabled steps
Disable unavailable steps without disabling navigation to the others.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
export default function StepsDisabledStep() {
return (
{}}
items={[
{ title: 'First' },
{ title: 'Second' },
{ title: 'Locked', disabled: true },
]}
/>
);
}
```
### Long title ellipsis
Truncate long titles in constrained space and put detail in step content.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsEllipsis() {
return (
);
}
```
### Initial step number
Use `initial` to offset displayed numbers while keeping the component index contract for `current`.
```tsx preview
import { Steps } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsInitial() {
return ;
}
```
### Inherit provider settings
Inherit size and appearance settings and override them on an individual Steps instance.
```tsx preview
import { Steps, TaoProvider } from '@rockshin/tao-ui';
const basicItems = [
{ title: 'Finished', content: 'This step is done.' },
{ title: 'In Progress', content: 'Working on it now.' },
{ title: 'Waiting', content: 'Not started yet.' },
];
export default function StepsProviderInherit() {
return (
);
}
```
## API
### [#](#steps)Steps
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| items | Step data. | `StepItem[] | undefined` | `-` |
| current | Current step, counted from 0. Overridden per step by `items.status`. | `number | undefined` | `-` |
| initial | Numbering offset — the first step is numbered `initial + 1`. | `number | undefined` | `-` |
| status | Status of the `current` step; the others derive theirs from position. | `StepsStatus | undefined` | `process` |
| orientation | Layout axis. | `StepsOrientation | undefined` | `-` |
| titlePlacement | Where the title sits relative to the icon. | `StepsTitlePlacement | undefined` | `-` |
| responsive | Collapse to `vertical` below 576px. | `boolean | undefined` | `true` |
| size | Visual density. | `StepsSize | undefined` | `-` |
| variant | Style variant. | `StepsVariant | undefined` | `filled` |
| type | Steps flavour. | `StepsType | undefined` | `-` |
| percent | Progress ring on the `process` icon; ignored by `type="inline"`. | `number | undefined` | `-` |
| maxCount | Collapse to at most N steps (`>= 3`); hidden ranges become an ellipsis step. | `number | undefined` | `-` |
| offset | Leading flex offset for `type="inline"`. | `number | undefined` | `-` |
| ellipsis | Truncate overflowing titles, subtitles, and content. | `boolean | undefined` | `-` |
| iconRender | Replace the icon node of every step. | `StepsIconRender | undefined` | `-` |
| finishIconBackground | Background of the built-in finished-step circle. | `BackgroundColor | undefined` | `-` |
| finishIconColor | Color of the built-in finished-step check mark. | `Color | undefined` | `-` |
| onChange | Fires with the absolute step index when a non-current step is activated. | `((current: number) => void) | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tabs.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Tabs
Navigation`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Switches between peer panels within the same page context.
## When to use
Use Tabs to separate peer views without navigating away from the current task.
**Recommended**
- Use short tab labels.
- Keep tab panels at comparable hierarchy.
**Avoid**
- Do not use Tabs for sequential steps.
## Examples
### Basic usage
```tsx preview
import { Tabs } from '@rockshin/tao-ui';
function TabsExample() {
return (
);
}
export default TabsExample;
```
### Card variant and sizes
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';
const items = [
{ key: 'general', label: 'General', children: 'General settings.' },
{ key: 'security', label: 'Security', children: 'Security settings.' },
];
function TabVariants() {
return (
);
}
export default TabVariants;
```
### Controlled and disabled tabs
```tsx preview
import { Tabs } from '@rockshin/tao-ui';
import { useState } from 'react';
function ControlledTabs() {
const [activeKey, setActiveKey] = useState('general');
return (
);
}
export default ControlledTabs;
```
### Externally controlled tabs
Use `activeKey` and `onChange` to keep tab selection in application state.
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';
import { useState } from 'react';
const basicItems = [
{ key: 'general', label: 'General', children: 'General settings content.' },
{
key: 'security',
label: 'Security',
children: 'Security settings content.',
},
{
key: 'notifications',
label: 'Notifications',
children: 'Notification preferences.',
},
];
export default function TabsControlled() {
function Demo() {
const [key, setKey] = useState('security');
return (
activeKey: {key}
);
}
return ;
}
```
### Disabled tabs
Disable unavailable content while leaving other tabs interactive.
```tsx preview
import { Tabs } from '@rockshin/tao-ui';
export default function TabsDisabledTab() {
return (
);
}
```
### Card tab sizes
Compare card tabs at different sizes and densities.
```tsx preview
import { Stack, Tabs } from '@rockshin/tao-ui';
const basicItems = [
{ key: 'general', label: 'General', children: 'General settings content.' },
{
key: 'security',
label: 'Security',
children: 'Security settings content.',
},
{
key: 'notifications',
label: 'Notifications',
children: 'Notification preferences.',
},
];
export default function TabsCardSizes() {
return (
);
}
```
### Provider size and local overrides
Inherit the provider size and explicitly override an individual tab group when needed.
```tsx preview
import { Tabs, TaoProvider } from '@rockshin/tao-ui';
const basicItems = [
{ key: 'general', label: 'General', children: 'General settings content.' },
{
key: 'security',
label: 'Security',
children: 'Security settings content.',
},
{
key: 'notifications',
label: 'Notifications',
children: 'Notification preferences.',
},
];
export default function TabsProviderInherit() {
return (
);
}
```
### Unmount inactive panels
Compare preserved and unmounted panels by editing content before switching tabs.
```tsx preview
import { Tabs } from '@rockshin/tao-ui';
export default function TabsDestroyInactive() {
return (
);
}
```
## API
### [#](#tabs)Tabs
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/auto-complete.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# AutoComplete
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Editable text with suggestions, grouped options, keyboard completion and custom inputs.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
Sizes are `small`, `medium` and `large`; the compatible `middle` alias uses the same dimensions as `medium`.
## Examples
### Free text and suggestions
The value remains editable even when it is not in the options list. Control it with onChange.
```tsx preview
import { useState } from 'react';
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function BasicAutoComplete() {
const [value, setValue] = useState('');
return (
Value: {value || 'empty'}
);
}
```
### Filter by a label
Search can compare the typed text against the displayed label or the stored value.
```tsx preview
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function FilteredSuggestions() {
return (
String(option?.label).toLowerCase().includes(text.toLowerCase()),
}}
placeholder="Search Alice or Bob"
style={{ width: '100%' }}
/>
);
}
```
### Keyboard backfill
Arrow keys preview the active option in the input; Enter commits it.
```tsx preview
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function KeyboardCompletion() {
return (
);
}
```
### Reuse a custom Input
A single input child becomes the editable control. Its own prefix and appearance are retained.
```tsx preview
import { AutoComplete, Input } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function CustomInput() {
return (
);
}
```
### Grouped suggestions
Group related options under a label and customize the rendered option content.
```tsx preview
import { AutoComplete } from '@rockshin/tao-ui';
export default function GroupedSuggestions() {
return (
(
{option.label}
{String(option.value)}
)}
placeholder="People and teams"
style={{ width: '100%' }}
/>
);
}
```
### Delayed suggestions
This local example waits 400 ms after typing and cancels the previous request simulation.
```tsx preview
import { useEffect, useState } from 'react';
import { AutoComplete } from '@rockshin/tao-ui';
export default function DelayedSuggestions() {
const [value, setValue] = useState('');
const [options, setOptions] = useState<{ value: string }[]>([]);
useEffect(() => {
setOptions([]);
if (!value) return;
const timer = setTimeout(
() =>
setOptions(
['example.com', 'company.dev'].map((domain) => ({
value: `${value.split('@')[0]}@${domain}`,
})),
),
400,
);
return () => clearTimeout(timer);
}, [value]);
return (
);
}
```
### Appearance and states
Size, variant, status and disabled are local overrides of TaoProvider defaults.
```tsx preview
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function AutoCompleteAppearance() {
return (
);
}
```
### Suggestions in a narrow form
Use the phone preview to type, select, and clear. AutoComplete retains an editable input and popup on mobile.
```tsx preview="iframe-follow"
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function MobileAutoComplete() {
return (
);
}
```
## API
### [#](#autocomplete)AutoComplete
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/cascader.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Cascader
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Choose complete paths through hierarchical options with search, multiple selection and a standalone panel.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
Sizes are `small`, `medium` and `large`; the compatible `middle` alias uses the same dimensions as `medium`.
Below 576px, Cascader automatically uses a bottom drawer. Use `mobile` to override the surface and `mobileTitle` to name the drawer. Mobile single selection commits immediately; multiple selection commits on Done and cancels on dismissal. On desktop, the clear action replaces the arrow on hover; touch keeps clear visible.
## Examples
### Choose a complete path
The selected value contains each level in the chosen path.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function BasicCascader() {
return (
);
}
```
### Controlled path and display
displayRender can shorten the displayed path while preserving every value in state.
```tsx preview
import { useState } from 'react';
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function ControlledLocation() {
const [value, setValue] = useState(['asia', 'japan', 'tokyo']);
return (
labels.at(-1)}
style={{ width: '100%' }}
/>
{value.join(' / ')}
);
}
```
### Select multiple paths
Multiple mode adds linked checkboxes. SHOW\_CHILD keeps leaf paths in the visible selection.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function MultipleLocations() {
return (
);
}
```
### Search every level
The search filter checks every label in a path. Selecting a result returns the full path.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function SearchLocations() {
return (
path.some((option) =>
String(option.label).toLowerCase().includes(input.toLowerCase()),
),
}}
placeholder="Search country or city"
style={{ width: '100%' }}
/>
);
}
```
### Choose intermediate levels
changeOnSelect allows a parent path to be selected. This example expands columns on pointer hover.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function IntermediateLocation() {
return (
);
}
```
### Map custom fields
Field names let existing domain data remain unchanged.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
export default function RegionFields() {
return (
);
}
```
### Load columns on demand
The local delay stands in for a data request. Mark unresolved parents with isLeaf:false and update options after loading.
```tsx preview
import { useState } from 'react';
import { Cascader, type DefaultOptionType } from '@rockshin/tao-ui';
export default function AsyncLocations() {
const [options, setOptions] = useState([
{ value: 'china', label: 'China', isLeaf: false },
]);
return (
{
const target = selected.at(-1)!;
target.loading = true;
setOptions([...options]);
await new Promise((resolve) => setTimeout(resolve, 500));
target.loading = false;
target.children = [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
];
setOptions([...options]);
}}
placeholder="Load cities"
style={{ width: '100%' }}
/>
);
}
```
### Use the standalone panel
Cascader.Panel keeps the columns visible without a trigger input.
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function LocationPanel() {
return (
);
}
```
### Mobile bottom drawer
Choose a three-level path in a bottom drawer on phones. The columns scroll horizontally when the path exceeds the available width.
Single selection applies as soon as the user picks a path. With `multiple`, changes in the drawer apply when the user taps Done. Since [0.0.49](https://rickyshin93.github.io/tao-ui/guide/changelog.md), Cascader skips newly chosen paths that are removed or disabled before confirmation, while keeping previously committed paths that the user has left selected.
```tsx preview="iframe-follow"
import { Cascader } from '@rockshin/tao-ui';
const options = [
{
value: 'asia',
label: 'Asia',
children: [
{
value: 'china',
label: 'China',
children: [
{ value: 'shanghai', label: 'Shanghai' },
{ value: 'hangzhou', label: 'Hangzhou' },
],
},
{
value: 'japan',
label: 'Japan',
children: [{ value: 'tokyo', label: 'Tokyo' }],
},
],
},
{
value: 'europe',
label: 'Europe',
children: [
{
value: 'germany',
label: 'Germany',
children: [{ value: 'berlin', label: 'Berlin' }],
},
],
},
];
export default function MobileLocation() {
return (
Delivery location
);
}
```
## API
### [#](#cascaderpanel)CascaderPanel
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
### [#](#cascader)Cascader
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| mobile | Use a bottom drawer. Automatically enabled below 576px. | `boolean | undefined` | `-` |
| mobileTitle | Drawer title; defaults to the field label, then localized selection text. | `ReactNode` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/checkbox.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Checkbox
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Selects one or more independent boolean options.
## When to use
Use Checkbox for independent choices, or CheckboxGroup when users can select multiple options from a set.
**Recommended**
- Use clear labels that describe the checked state.
- Group related options with CheckboxGroup.
**Avoid**
- Do not use CheckboxGroup when only one option may be selected; use RadioGroup instead.
## Examples
### Basic usage
```tsx preview
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function CheckboxExample() {
const [updates, setUpdates] = useState(true);
const [channels, setChannels] = useState(['email', 'push']);
return (
setUpdates(event.target.checked)}
>
Send product updates
);
}
export default CheckboxExample;
```
### Standalone states
```tsx preview
import { Checkbox, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function CheckboxStates() {
const [unchecked, setUnchecked] = useState(false);
const [checked, setChecked] = useState(true);
const [mixed, setMixed] = useState(false);
return (
setUnchecked(event.target.checked)}
>
Unchecked
setChecked(event.target.checked)}
>
Checked
setMixed(event.target.checked)}
>
Indeterminate
Disabled
{}}>
Checked disabled
);
}
export default CheckboxStates;
```
### Vertical groups
```tsx preview
import { CheckboxGroup, FormField } from '@rockshin/tao-ui';
import { useState } from 'react';
function VerticalCheckboxGroup() {
const [value, setValue] = useState(['email']);
return (
);
}
export default VerticalCheckboxGroup;
```
### Controlled checkbox
onChange provides a native event; read the next value from target.checked.
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [checked, setChecked] = useState(false);
return (
setChecked(e.target.checked)}
>
Receive updates
{checked ? 'Subscribed' : 'Not subscribed'}
);
}
```
### Select all and indeterminate
Derive indeterminate state from the selected count instead of storing separate conflicting state.
```tsx preview
import { useState } from 'react';
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [values, setValues] = useState(['Read']);
return (
0 && values.length < 3}
onChange={(e) =>
setValues(e.target.checked ? ['Read', 'Write', 'Share'] : [])
}
>
Select all
{values.join(', ') || 'None selected'}
);
}
```
### Vertical options and disabled items
Object options allow individual disabled items; direction controls layout.
```tsx preview
import { CheckboxGroup } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Native form values
Write controlled selections into hidden inputs and read them with FormData.
```tsx preview
import { useState } from 'react';
import { CheckboxGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [values, setValues] = useState(['email']);
const [result, setResult] = useState('');
return (
{
e.preventDefault();
setResult(
new FormData(e.currentTarget).getAll('channel').join(', ') || 'None',
);
}}
>
{values.map((value) => (
))}
Read values
{result}
);
}
```
### Sizes and shared disabled state
A local Provider can set size or disable a group of controls.
```tsx preview
import { Checkbox, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
{size}
))}
Disabled by provider
);
}
```
## API
### [#](#checkboxgroup)CheckboxGroup
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
### [#](#checkbox)Checkbox
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| required | Require a checked value when submitting a native form. | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/color-picker.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# ColorPicker
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Choose solid or gradient colors with precise Color objects, presets and format conversion.
The added API follows Ant Design 6.7.0; appearance, theming and Semantic DOM use tao-ui. Existing component APIs remain unchanged.
## Examples
### Controlled color
Keep the Color object returned by onChange to retain precision while editing.
```tsx preview
import { ColorPicker, type Color } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [color, setColor] = useState('#008888');
return (
{typeof color === 'string' ? color : color.toCssString()}
);
}
```
### Three sizes
Sizes follow the compatible API: small, middle and large.
```tsx preview
import { ColorPicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
{(['small', 'middle', 'large'] as const).map((size) => (
))}
);
}
```
### Gradients and stops
Add, remove and move stops, or switch between solid and gradient modes.
```tsx preview
import { ColorPicker } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Grouped presets
Group colors by use; presets can also contain gradients.
```tsx preview
import { ColorPicker } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### HEX, RGB and HSB
Switch representations in the panel or lock the required format.
```tsx preview
import { ColorPicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Alpha and clear
disabledAlpha emits opaque colors; allowClear provides a transparent value.
```tsx preview
import { ColorPicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Commit after editing
Use onChangeComplete to commit a completed drag or edit.
```tsx preview
import { ColorPicker } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [saved, setSaved] = useState('#008888');
return (
setSaved(color.toCssString())}
/>
Committed: {saved}
);
}
```
### Custom panel
Compose Picker and Presets while retaining picker state and events.
```tsx preview
import { ColorPicker } from '@rockshin/tao-ui';
export default function Demo() {
return (
(
)}
/>
);
}
```
### Triggers and disabled state
Use a custom button, hover activation or a disabled picker.
```tsx preview
import { ColorPicker, Button, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
Hover for color
);
}
```
### Phone palette
The independent phone viewport constrains the panel and inherits the theme.
```tsx preview="iframe-follow"
import { ColorPicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
## API
### [#](#colorpicker)ColorPicker
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| disabled | Whether to disable | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/date-picker.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# DatePicker
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Lets users enter or choose a single date, with optional time selection.
## When to use
Use DatePicker when free text date input would be error-prone or when users benefit from calendar context.
**Recommended**
- Support keyboard entry for known dates.
- Use presets for common relative choices when helpful.
**Avoid**
- Do not force calendar navigation for dates far in the past without typed input.
## Examples
### Basic usage
```tsx preview
import { DatePicker, FormField } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';
function DatePickerExample() {
const [value, setValue] = useState(null);
return (
);
}
export default DatePickerExample;
```
### Picker modes
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';
function DatePickerModes() {
const [date, setDate] = useState(null);
const [month, setMonth] = useState(null);
const [year, setYear] = useState(null);
return (
);
}
export default DatePickerModes;
```
### Time, presets, and disabled dates
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';
function AdvancedDatePicker() {
const [dateTime, setDateTime] = useState(null);
const [preset, setPreset] = useState(null);
const [future, setFuture] = useState(null);
return (
current.isBefore(dayjs().startOf('day'))}
placeholder="Future dates only"
/>
);
}
export default AdvancedDatePicker;
```
### Date and time
`showTime` combines date and time selection; format the displayed parts accordingly.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerWithTime() {
function Demo() {
const [val, setVal] = useState(dayjs());
return (
setVal(d)} showTime />
Value: {val ? val.format('YYYY-MM-DD HH:mm:ss') : 'none'}
);
}
return ;
}
```
### Date presets
Offer common dates through `presets` to reduce repeated calendar navigation.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerWithPresets() {
function Demo() {
const [val, setVal] = useState(null);
return (
setVal(d)}
presets={[
{ label: 'Today', value: dayjs() },
{ label: 'Yesterday', value: dayjs().subtract(1, 'day') },
{ label: 'Last week', value: dayjs().subtract(7, 'day') },
{ label: 'Last month', value: dayjs().subtract(1, 'month') },
]}
/>
);
}
return ;
}
```
### Disable unavailable dates
Use `disabledDate` for business constraints. This example calculates dates locally.
```tsx preview
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerDisabledDates() {
function Demo() {
const [val, setVal] = useState(null);
return (
setVal(d)}
disabledDate={(d) => d.isBefore(dayjs(), 'day')}
/>
setVal(d)}
minDate={dayjs().subtract(7, 'day')}
maxDate={dayjs().add(30, 'day')}
/>
);
}
return ;
}
```
### Sizes and variants
Choose size and variant to match neighboring input controls.
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
### Status and disabled state
Use error and warning for validation feedback and disabled for unavailable input.
```tsx preview
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Locale switching
TaoProvider locale updates built-in actions, placeholders, and calendar labels.
```tsx preview
import { useState } from 'react';
import {
DatePicker,
TaoProvider,
zhCN,
enUS,
Button,
Stack,
} from '@rockshin/tao-ui';
export default function Example() {
const [chinese, setChinese] = useState(false);
return (
setChinese(!chinese)}>
{chinese ? 'Switch to English' : '切换到中文'}
);
}
```
### Date boundaries
minDate and maxDate constrain input and navigation; this example uses a fixed 2026 range.
```tsx preview
import dayjs from 'dayjs';
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Controlled value and clearing
Store changes in application state and represent a cleared picker with null.
```tsx preview
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { DatePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState(null);
return (
setValue(null)}>Clear value
{value?.format('YYYY-MM-DD') || 'No selection'}
);
}
```
### Display format
format changes display text while values remain Dayjs objects.
```tsx preview
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Mobile date drawer
Use `mobile` to try the drawer on desktop and confirm the selected date.
```tsx preview="iframe-follow"
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerMobileDatePicker() {
function Demo() {
const [val, setVal] = useState(null);
return (
Using mobile prop to force Drawer mode.
setVal(d)}
mobile
presets={[
{ label: 'Today', value: dayjs() },
{ label: 'Yesterday', value: dayjs().subtract(1, 'day') },
]}
/>
);
}
return ;
}
```
Mobile drawer titles use `mobileTitle`, then the nearest `Form.Item` / `FormField` label, then localized default text. Required marks and help text are excluded; placeholders only describe the input. For standalone controls or native HTML labels, pass `mobileTitle="Departure date"` explicitly.
### Mobile selection
Open the picker in phone mode to try selection, confirmation, and clearing inside a drawer.
```tsx preview="iframe-follow"
import { DatePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#datepicker)DatePicker
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | `ReactNode` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/form.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Form
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Collects and validates field values with an antd-aligned API (rules, dependencies, Form.List) on top of the rc-form engine.
## When to use
Use Form with Form.Item when fields need a value store, rule validation, or submit handling. Use the lighter FormField when you manage state yourself.
Direct Form.Item children have 4px bottom spacing when a feedback row is present (`--tao-size-unit`), or 20px otherwise (`--tao-padding-md`). `--tao-form-field-item-gap` overrides either default. Stack and FormSection manage spacing for items placed inside them. `noStyle` adds neither a shell nor spacing, and standalone FormField layout is unchanged.
At the default 12–14px message sizes, the reserved line is 18px high; with its 2px top margin and 4px trailing gap, feedback occupies 24px. Larger custom message text can increase the line height.
Form.Item reserves one feedback line when it has validation rules or an explicit `help`, `extra` or `validateStatus`. Single-line validation messages can appear or disappear without moving subsequent fields or buttons. Longer messages wrap and expand the space naturally to avoid overlapping content. Fields without validation or feedback do not reserve an empty row. Use `help=""` to keep the row when controlling messages manually.
**Recommended**
- Declare validation as rules on Form.Item; the required mark is inferred from rules.
- Use dependencies for cross-field rules such as password confirmation.
- Use Form.useForm() for imperative control (setFieldsValue, resetFields, submit).
- Values written through `setFields` — including the controlled `fields` prop —
clear stale validation errors for fields whose value changed; include
`errors`/`warnings` in the same entry to provide fresh validation state.
- Set size or disabled on Form to cascade them to every control inside.
**Avoid**
- Do not bind the same name in two mounted Form.Items.
- Do not mix manual value/onChange props with a bound Form.Item on the same control.
## Examples
### Basic usage
```tsx preview
import { useState } from 'react';
import { Button, Form, Input } from '@rockshin/tao-ui';
function FormExample() {
const [feedback, setFeedback] = useState('');
return (
<>
setFeedback(JSON.stringify(values))}
style={{ maxWidth: 400 }}
>
Create account
{feedback}
>
);
}
export default FormExample;
```
### Validation
```tsx preview
import { useState } from 'react';
import { Button, Form, Input } from '@rockshin/tao-ui';
function ValidatedForm() {
const [feedback, setFeedback] = useState('');
return (
<>
setFeedback(JSON.stringify(values))}
style={{ maxWidth: 420 }}
>
Submit
{feedback}
>
);
}
export default ValidatedForm;
```
### Horizontal layout
```tsx preview
import { Button, Form, Input } from '@rockshin/tao-ui';
function HorizontalForm() {
return (
Create project
);
}
export default HorizontalForm;
```
### Complete form
Combine fields, sections, and actions into an end-to-end entry and submission flow.
```tsx preview
import {
Button,
FormActions,
FormField,
FormLayout,
FormSection,
Input,
Select,
Stack,
} from '@rockshin/tao-ui';
export default function FormCompleteForm() {
return (
✉️} />
+86} />
Cancel
Save Changes
);
}
```
### Cross-field validation
Validate against another field and update feedback when the related value changes.
```tsx preview
import { Button, Form, FormActions, Input, Stack } from '@rockshin/tao-ui';
export default function FormFormCrossField() {
return (
({
validator: (_, value) =>
!value || getFieldValue('password') === value
? Promise.resolve()
: Promise.reject(new Error('Passwords do not match')),
}),
]}
>
Change password
);
}
```
### Dynamic field lists
Add and remove repeated fields with `Form.List`, keeping form values and field indexes aligned.
```tsx preview
import { useState } from 'react';
import { Button, Form, FormActions, Input, Stack } from '@rockshin/tao-ui';
export default function FormFormDynamicList() {
const [feedback, setFeedback] = useState('');
return (
<>
setFeedback(JSON.stringify(values, null, 2))}
>
{(fields, { add, remove }) => (
<>
{fields.map((field, index) => (
remove(field.name)}>
Remove
))}
add()}>
Add member
>
)}
Save
{feedback}
>
);
}
```
### Scroll to a claim field
Get the instance with `Form.useForm()`, a Form ref, or `Form.useFormInstance()`. Array paths and full `Form.List` paths such as `['claims', 0, 'email']` are supported.
```tsx preview
import { Button, Form, Input } from '@rockshin/tao-ui';
export default function ScrollToClaimField() {
const [form] = Form.useForm();
return (
form.scrollToField(['claimant', 'email'], {
behavior: 'smooth', block: 'center', focus: true,
})}
>
Reveal and focus email
Scroll down, or use the button to reveal the field.
);
}
```
Defaults to `scrollMode: 'if-needed'` and `block: 'nearest'`. Accepts `behavior`, `block`, `inline`, `boundary`, `scrollMode` and other scroll options; `focus: true` focuses the control after starting the scroll. Only mounted fields can be located; reveal conditional or unmounted tab content first. Custom controls must forward `ref` (a DOM node or an instance with `nativeElement`) or `id`.
```tsx
{
if (errorFields.length) {
form.scrollToField(errorFields[0].name, { focus: true });
}
}}
/>
```
## API
### [#](#form)Form
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| layout | Label/control arrangement inherited by Form.Item. Defaults to 'vertical'. | `"vertical" | "horizontal" | undefined` | `-` |
| size | Cascades a control size to everything inside the form. | `TaoSize | undefined` | `-` |
| disabled | Disables every tao-ui control inside the form (e.g. while submitting). | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/form-actions.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# FormActions
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Lays out submit, cancel, and secondary actions for forms.
## When to use
Use FormActions at the end of a form or section to align the final actions consistently.
**Recommended**
- Keep action order consistent across forms.
- Use a single submit action unless the workflow truly branches.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Button, FormActions } from '@rockshin/tao-ui';
function FormActionsExample() {
return (
Cancel
Save changes
);
}
export default FormActionsExample;
```
### Secondary and destructive actions
```tsx preview
import { Button, FormActions } from '@rockshin/tao-ui';
function FormActionVariants() {
return (
Delete
Cancel
Save
);
}
export default FormActionVariants;
```
### Semantic alignment
```tsx preview
import { Button, FormActions } from '@rockshin/tao-ui';
function CustomizedFormActions() {
return (
Back
Continue
);
}
export default CustomizedFormActions;
```
### Complete form composition
Compose layout, fields, and actions with native submission feedback.
```tsx preview
import { useState } from 'react';
import {
FormLayout,
FormSection,
FormField,
FormActions,
Input,
Textarea,
Button,
} from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState('');
return (
{
e.preventDefault();
setSaved(String(new FormData(e.currentTarget).get('name')));
}}
onReset={() => setSaved('')}
>
Reset
Save
{saved ? `Saved ${saved}` : 'No changes saved'}
);
}
```
### Alignment and wrapping
Set root alignment while retaining wrapping on narrow screens.
```tsx preview
import { FormActions, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Back
Continue
);
}
```
### Pending actions
Disable form actions while pending and show loading; a separate control finishes this local demo.
```tsx preview
import { useState } from 'react';
import { FormActions, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [pending, setPending] = useState(false);
return (
Cancel
setPending(true)}>
Save
{pending && (
setPending(false)}>
Finish simulated request
)}
);
}
```
## API
### [#](#formactions)FormActions
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/form-field.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# FormField
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Associates labels, help text, validation state, and controls.
## When to use
Use FormField to provide accessible labeling and status text around a single control.
**Recommended**
- Connect every input with a visible label.
- Keep validation copy specific and actionable.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { FormField, Input } from '@rockshin/tao-ui';
function FormFieldExample() {
return (
);
}
export default FormFieldExample;
```
### Description and error states
```tsx preview
import { FormField, Input, Stack } from '@rockshin/tao-ui';
function FormFieldStates() {
return (
);
}
export default FormFieldStates;
```
### Semantic parts
```tsx preview
import { FormField, Input } from '@rockshin/tao-ui';
function CustomizedFormField() {
return (
);
}
export default CustomizedFormField;
```
### Complete form composition
Compose layout, fields, and actions with native submission feedback.
```tsx preview
import { useState } from 'react';
import {
FormLayout,
FormSection,
FormField,
FormActions,
Input,
Textarea,
Button,
} from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState('');
return (
{
e.preventDefault();
setSaved(String(new FormData(e.currentTarget).get('name')));
}}
onReset={() => setSaved('')}
>
Reset
Save
{saved ? `Saved ${saved}` : 'No changes saved'}
);
}
```
### Error feedback and recovery
Update errors with input while the field label remains associated with its control.
```tsx preview
import { useState } from 'react';
import { FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState('');
return (
setValue(e.target.value)} />
);
}
```
### Explicit association
Use htmlFor and an input id when integrating existing form identifiers; useId avoids duplicates.
```tsx preview
import { useId } from 'react';
import { FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
const id = useId();
return (
);
}
```
## API
### [#](#formfield)FormField
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/form-section.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# FormSection
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Groups related form fields with a title and optional description.
## When to use
Use FormSection to break long forms into scannable groups.
**Recommended**
- Use headings that describe the group, not the control type.
- Keep each section focused on one user decision area.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { FormField, FormSection, Input } from '@rockshin/tao-ui';
function FormSectionExample() {
return (
);
}
export default FormSectionExample;
```
### Multiple field groups
```tsx preview
import { FormField, FormSection, Input, Stack } from '@rockshin/tao-ui';
function FormSectionGroups() {
return (
);
}
export default FormSectionGroups;
```
### Semantic parts
```tsx preview
import { FormSection } from '@rockshin/tao-ui';
function CustomizedFormSection() {
return (
Advanced configuration belongs here.
);
}
export default CustomizedFormSection;
```
### Complete form composition
Compose layout, fields, and actions with native submission feedback.
```tsx preview
import { useState } from 'react';
import {
FormLayout,
FormSection,
FormField,
FormActions,
Input,
Textarea,
Button,
} from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState('');
return (
{
e.preventDefault();
setSaved(String(new FormData(e.currentTarget).get('name')));
}}
onReset={() => setSaved('')}
>
Reset
Save
{saved ? `Saved ${saved}` : 'No changes saved'}
);
}
```
### Optional descriptions
A title can stand alone; add description when extra context helps.
```tsx preview
import { FormSection, FormLayout, Input } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Section styling
Use header and body semantic parts to style a section.
```tsx preview
import { FormSection, FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#formsection)FormSection
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/input.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Input
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Single-line text input for short freeform values.
## When to use
Use Input for short text values such as names, filters, search terms, and identifiers.
**Recommended**
- Pair with FormField for labels and validation.
- Use type, inputMode, and autoComplete when applicable.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
function InputExample() {
return (
⌕} placeholder="Search" />
);
}
export default InputExample;
```
### Variants
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
function InputVariants() {
return (
);
}
export default InputVariants;
```
### Sizes and affixes
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
function InputSizes() {
return (
⌕}
placeholder="Small search"
/>
USD}
placeholder="Medium amount"
/>
);
}
export default InputSizes;
```
### Three sizes
Choose a size for regular forms, compact toolbars, or spacious layouts.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
### Clear and count
Clearing calls onChange and onClear. Controlled values remain owned by your state.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState('tao-ui');
return
setValue(e.target.value)} allowClear showCount maxLength={24} />
{value || 'Empty'}
;
}
```
### Prefixes and suffixes
Affixes show units or context while the input value contains only user data.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Password input
The visibility button supports keyboard access, disabled state, and controlled visibilityToggle.
```tsx preview
import { useState } from 'react';
import { Input, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [visible, setVisible] = useState(false);
return
setVisible(!visible)}>{visible ? 'Hide' : 'Show'}
;
}
```
### Search input
Button clicks, Enter and clearing call onSearch with source input or clear. IME confirmation and loading do not submit a search.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [result, setResult] = useState('No search yet');
return
setResult(`${info?.source}: ${value || '(empty)'}`)} />
{result}
;
}
```
### Native constraints and read-only
Use native email, required, maxLength, and readOnly; application state decides error feedback.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Cursor placement
The ref remains the native input. InputRef also exposes input, nativeElement and extended focus options.
```tsx preview
import { useRef } from 'react';
import { Input, type InputRef, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const ref = useRef(null);
return
{(['start', 'end', 'all'] as const).map((cursor) => ref.current?.focus({ cursor, preventScroll: true })}>{cursor} )}
;
}
```
### Custom counting
count.max warns by default. strategy and exceedFormatter can count and clip Unicode code points. Native maxLength counts UTF-16 code units independently.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
return
Array.from(value).length, exceedFormatter: (value, { max }) => Array.from(value).slice(0, max).join('') }} />
;
}
```
### Text area
Input.TextArea is the same component as standalone Textarea, with auto sizing, clearing, counting and Enter events.
```tsx preview
import { Input } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### One-time code
Supports automatic advance, pasting, arrow keys, Backspace, formatting and masking. onInput returns an array including empty slots; onChange fires only when complete.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [complete, setComplete] = useState('');
return
value.toUpperCase()} separator={(index) => index === 2 ? '-' : null} onChange={setComplete} />
{complete || 'Enter all characters'}
;
}
```
### Attached content
addonBefore / addonAfter attach labels; prefix / suffix sit inside the input area.
```tsx preview
import { Input } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
## API
### Input / Input.TextArea
Other props pass through to the native input / textarea. Input.TextArea does not accept prefix, suffix or addons; standalone Textarea remains compatible.
| Prop | Type | Default |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| value / defaultValue | Native input value / textarea value | — |
| onChange | `(event) => void` | — |
| allowClear | `boolean` or `{ clearIcon?, disabled?, tabIndex? }` | `false` |
| onClear | `() => void` | — |
| showCount | `boolean` or `{ formatter: ({ value, count, maxLength }) => ReactNode }` | `false` |
| count | `{ max?, strategy?: (value) => number, show?: boolean or formatter, exceedFormatter?: (value, { max }) => string }` | — |
| onPressEnter | `(event: KeyboardEvent) => void` | — |
| size | `'small'`, `'medium'`, `'large'` | TaoProvider |
| variant | `'outlined'`, `'filled'`, `'borderless'`, `'underlined'` | TaoProvider |
| status / error | `'error'` or `'warning'` / `boolean` | — |
| disabled / readOnly | `boolean` | TaoProvider / `false` |
| prefix / suffix | `ReactNode` (Input only) | — |
| addonBefore / addonAfter | `ReactNode` (Input only) | — |
| autoSize | `boolean` or `{ minRows?, maxRows? }` (TextArea only) | `false` |
| classNames / styles | Semantic part map or `({ props }) => map` | — |
A count limit does not clip unless count.exceedFormatter is set. Clipping waits for IME composition to finish. count.show takes precedence over showCount. Input semantic parts: root / input / prefix / suffix / clear / count / addonBefore / addonAfter. TextArea: root / textarea / clear / count.
### Input.Password
Inherits Input props.
| Prop | Type | Default |
| ---------------- | -------------------------------------------------------- | -------- |
| visibilityToggle | `boolean` or `{ visible?, onVisibleChange?, tabIndex? }` | `true` |
| iconRender | `(visible: boolean) => ReactNode` | Eye icon |
### Input.Search
Inherits Input props. The search button does not submit a surrounding form; onSearch reports source input or clear.
| Prop | Type | Default |
| ------------------- | ---------------------------------------------------------------- | ----------- |
| enterButton | `ReactNode` (boolean, label, native button or Button) | `false` |
| searchIcon | `ReactNode` | Search icon |
| loading | `boolean` | `false` |
| onSearch | `(value, event?, info?: { source: 'input' or 'clear' }) => void` | — |
| classNames / styles | Input parts plus `button` | — |
### Input.OTP
| Prop | Type | Default |
| ------------------------------- | ------------------------------------------------------ | ----------------------------- |
| length | Positive integer | `6` |
| value / defaultValue | `string` | — |
| formatter | `(value: string) => string` | — |
| onInput | `(value: string[]) => void` | — |
| onChange | `(value: string) => void` (complete values) | — |
| mask | `boolean` or `string` | `false` |
| separator | `ReactNode` or `(index: number) => ReactNode` | — |
| type / inputMode / autoComplete | Native input attributes | `text` / — / — |
| autoFocus / disabled | `boolean` | `false` / TaoProvider |
| size / variant / status | Same as Input | TaoProvider / TaoProvider / — |
| classNames / styles | `root / input / separator` map or `({ props }) => map` | — |
### Ref
Input, Password and Search refs remain HTMLInputElement; TextArea remains HTMLTextAreaElement. Exported InputRef / TextAreaRef types add `focus({ preventScroll, cursor: 'start' | 'end' | 'all' })`, blur(), nativeElement and input / textArea. Native types without selection support only receive focus. OTPRef exposes focus(), blur() and nativeElement.
The API follows local Ant Design 6.7.0 while retaining tao-ui native refs, theming and semantic DOM contracts; it is not a drop-in antd replacement. Deprecated bordered, prefixCls and antd component-global configuration are not supported. Set underlined through the local Input-family variant prop.
---
url: https://rickyshin93.github.io/tao-ui/components/input-number.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# InputNumber
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
A styled numeric input built on tao-ui number formatting and validation behavior.
## When to use
Use InputNumber for numeric values that need min, max, step, precision, or formatted display.
**Recommended**
- Set min and max when the domain is bounded.
- Use the headless API when custom rendering is required.
**Avoid**
- Do not use a numeric input for identifiers such as account numbers.
## Examples
### Basic usage
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';
import { useState } from 'react';
function InputNumberExample() {
const [value, setValue] = useState('1500');
return (
);
}
export default InputNumberExample;
```
### Currency and percentage
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';
function InputNumberFormats() {
return (
);
}
export default InputNumberFormats;
```
### Sizes, variants, and bounds
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';
function InputNumberStates() {
return (
);
}
export default InputNumberStates;
```
### Currency formatting
Thousands separators, decimals, and a prefix format display while retaining a usable value.
```tsx preview
import { useState } from 'react';
import { InputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(props: React.ComponentProps) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function InputNumberCurrency() {
const args: React.ComponentProps = {
prefix: '€',
thousandsSeparator: ',',
decimalSeparator: '.',
decimalPlaces: 2,
value: '150000',
placeholder: 'Amount',
};
return ;
}
```
### Prefix and suffix
Use affixes for units instead of storing them in the numeric value.
```tsx preview
import { useState } from 'react';
import { InputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(props: React.ComponentProps) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function InputNumberWithSuffix() {
const args: React.ComponentProps = {
suffix: 'USD',
prefix: '$',
decimalPlaces: 2,
placeholder: 'Try 1234567',
};
return ;
}
```
### Three sizes
Compare three control sizes with the same numeric behavior.
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';
export default function InputNumberSizes() {
const args: React.ComponentProps = {
thousandsSeparator: ',',
};
return (
);
}
```
### Visual variants
Keep the same controlled input behavior across visual variants.
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';
export default function InputNumberVariants() {
const args: React.ComponentProps = {
thousandsSeparator: ',',
};
return (
);
}
```
### Percentages
Set decimal precision and a percent suffix; this example does not convert between percentages and fractions.
```tsx preview
import { useState } from 'react';
import { InputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(props: React.ComponentProps) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function InputNumberPercentage() {
const args: React.ComponentProps = {
isPercentage: true,
decimalPlaces: 2,
suffix: '%',
placeholder: 'Type 50 → actual is 0.5',
};
return ;
}
```
### Numeric bounds
Set the accepted range and observe the value during editing and on blur.
```tsx preview
import { useState } from 'react';
import { InputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(props: React.ComponentProps) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function InputNumberClampedRange() {
const args: React.ComponentProps = {
min: 0,
max: 100,
decimalPlaces: 0,
placeholder: 'Type 999, blur to clamp to 100',
};
return ;
}
```
## Regional formatting
Regional grouping, decimal symbols and digits inherit `TaoProvider.locale.numberLocale`; set `locale="fr-FR"` on this component to override it. Explicit separators take precedence. Numeric input keeps canonical ASCII strings and precision while displaying localized digits.
## API
### [#](#inputnumber)InputNumber
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/mentions.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Mentions
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Text areas with prefix-triggered suggestions, keyboard insertion, async options and automatic sizing.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
Sizes are `small`, `medium` and `large`; the compatible `middle` alias uses the same dimensions as `medium`.
## Examples
### Controlled mentions
Typing @ opens suggestions. getMentions extracts matching tokens from the resulting text.
```tsx preview
import { useState } from 'react';
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function BasicMentions() {
const [value, setValue] = useState('Hi @alice ');
return (
Mentions:{' '}
{Mentions.getMentions(value)
.map((item) => item.value)
.join(', ') || 'none'}
);
}
```
### Multiple prefixes
onSearch receives the active prefix, so each prefix can offer its own options.
```tsx preview
import { useState } from 'react';
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
const topics = [
{ value: 'design', label: 'Design' },
{ value: 'release', label: 'Release' },
];
export default function PrefixMentions() {
const [prefix, setPrefix] = useState('@');
return (
setPrefix(active)}
options={prefix === '@' ? people : topics}
placeholder="Use @ for people or # for topics"
rows={3}
/>
);
}
```
### Automatic height
autoSize grows from two to six rows. More content scrolls inside the textarea.
```tsx preview
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function GrowingMentions() {
return (
);
}
```
### Custom matching and disabled choices
The filter can match labels as well as values. Disabled options remain visible but cannot be inserted.
```tsx preview
import { Mentions } from '@rockshin/tao-ui';
const options = [
{ value: 'alice', label: 'Alice — Design' },
{ value: 'bob', label: 'Bob — Engineering' },
{ value: 'archived', label: 'Archived user', disabled: true },
];
export default function FilteredMentions() {
return (
`${option.value} ${options.find((item) => item.value === option.value)?.label}`
.toLowerCase()
.includes(search.toLowerCase())
}
placeholder="Try @design"
rows={3}
/>
);
}
```
### Asynchronous suggestions
This local example simulates a search delay and shows the loading state while waiting.
```tsx preview
import { useEffect, useState } from 'react';
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function AsyncMentions() {
const [search, setSearch] = useState('');
const [loading, setLoading] = useState(false);
const [options, setOptions] = useState(people);
useEffect(() => {
setLoading(true);
const timer = setTimeout(() => {
setOptions(
people.filter((item) => item.value.includes(search.toLowerCase())),
);
setLoading(false);
}, 400);
return () => clearTimeout(timer);
}, [search]);
return (
);
}
```
### Custom popup content
popupRender retains the option menu and adds contextual help.
```tsx preview
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function MentionHelp() {
return (
(
{menu}
↑ ↓ to navigate · Enter to insert
)}
placeholder="Mention @someone"
/>
);
}
```
### Variants and validation
Variants, sizes and validation status follow the shared control theme.
```tsx preview
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function MentionAppearance() {
return (
);
}
```
### Mention on a phone
The popup follows the caret. Try top placement and a growing textarea in the phone preview.
```tsx preview="iframe-follow"
import { Mentions } from '@rockshin/tao-ui';
const people = [
{ value: 'alice', label: 'Alice Chen' },
{ value: 'bob', label: 'Bob Li' },
{ value: 'carol', label: 'Carol Wu' },
];
export default function MobileMentions() {
return (
Team update
Type @ to include a teammate.
);
}
```
## API
### [#](#mentions)Mentions
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/radio.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Radio
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Selects exactly one option from a mutually exclusive set.
## When to use
Use RadioGroup when every option is visible and only one can be selected.
**Recommended**
- Use concise labels.
- Provide a default value when one option is recommended or required.
**Avoid**
- Do not use RadioGroup for very long option lists; use Select instead.
## Examples
### Basic usage
```tsx preview
import { RadioGroup } from '@rockshin/tao-ui';
import { useState } from 'react';
function RadioExample() {
const [value, setValue] = useState('pro');
return (
);
}
export default RadioExample;
```
### Standalone states
```tsx preview
import { Radio, RadioGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function RadioStates() {
const [value, setValue] = useState('selected');
return (
Selected
Unselected
Disabled
);
}
export default RadioStates;
```
### Vertical group
```tsx preview
import { FormField, RadioGroup } from '@rockshin/tao-ui';
import { useState } from 'react';
function VerticalRadioGroup() {
const [value, setValue] = useState('monthly');
return (
);
}
export default VerticalRadioGroup;
```
### Controlled radio group
Group onChange returns the selected value directly.
```tsx preview
import { useState } from 'react';
import { RadioGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState('Weekly');
return (
Frequency: {value}
);
}
```
### Vertical and disabled options
Use a vertical layout for longer labels and disable individual options.
```tsx preview
import { RadioGroup } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Native form submission
Set a group name to read its selected value from FormData.
```tsx preview
import { useState } from 'react';
import { RadioGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [result, setResult] = useState('');
return (
{
e.preventDefault();
setResult(String(new FormData(e.currentTarget).get('plan')));
}}
>
Read plan
{result}
);
}
```
### Radio group sizes
Group options inherit size for consistent alignment and targets.
```tsx preview
import { RadioGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
## API
### [#](#radiogroup)RadioGroup
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| name | Native group name; generated when omitted to isolate keyboard navigation. | `string | undefined` | `-` |
### [#](#radio)Radio
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/range-picker.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# RangePicker
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Lets users select a start and end date as one range value.
## When to use
Use RangePicker for reporting windows, booking windows, and filters with start/end dates.
**Recommended**
- Use presets for common ranges such as today, this week, or last 30 days.
- Make inclusive/exclusive range behavior clear when it matters.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { FormField, RangePicker } from '@rockshin/tao-ui';
function RangePickerExample() {
return (
);
}
export default RangePickerExample;
```
### Controlled range
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';
function ControlledRangePicker() {
const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>([
dayjs().startOf('week'),
dayjs().endOf('week'),
]);
return ;
}
export default ControlledRangePicker;
```
### Presets and time
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
function RangePickerPresets() {
return (
);
}
export default RangePickerPresets;
```
### Range selection and clearing
Choose the start and end dates in sequence, maintain the range value, and allow clearing.
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';
export default function DatePickerRangePickerBasic() {
function Demo() {
const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
return (
setVal(d)} />
Range: {val?.[0]?.format('YYYY-MM-DD') ?? '?'} ~{' '}
{val?.[1]?.format('YYYY-MM-DD') ?? '?'}
);
}
return ;
}
```
### Range presets
Offer common report ranges using the same value structure as manual selections.
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerRangePickerPresets() {
function Demo() {
const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
return (
setVal(d)}
presets={[
{
label: 'This week',
value: [dayjs().startOf('week'), dayjs().endOf('week')],
},
{
label: 'This month',
value: [dayjs().startOf('month'), dayjs().endOf('month')],
},
{
label: 'Last 7 days',
value: [dayjs().subtract(7, 'day'), dayjs()],
},
{
label: 'Last 30 days',
value: [dayjs().subtract(30, 'day'), dayjs()],
},
]}
/>
);
}
return ;
}
```
### Sizes and variants
Choose size and variant to match neighboring input controls.
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
### Status and disabled state
Use error and warning for validation feedback and disabled for unavailable input.
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Locale switching
TaoProvider locale updates built-in actions, placeholders, and calendar labels.
```tsx preview
import { useState } from 'react';
import {
RangePicker,
TaoProvider,
zhCN,
enUS,
Button,
Stack,
} from '@rockshin/tao-ui';
export default function Example() {
const [chinese, setChinese] = useState(false);
return (
setChinese(!chinese)}>
{chinese ? 'Switch to English' : '切换到中文'}
);
}
```
### Date boundaries
minDate and maxDate constrain input and navigation; this example uses a fixed 2026 range.
```tsx preview
import dayjs from 'dayjs';
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Controlled value and clearing
Pass `value` to control the range and save the value received by `onChange`. Set `value` to `null` to reset the range from your application.
With both endpoints enabled, the built-in clear control reports `onChange(null, ['', ''])`. Since [0.0.49](https://rickyshin93.github.io/tao-ui/guide/changelog.md), RangePicker also discards any text still being edited without first emitting it as a selected range.
```tsx preview
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { RangePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>(null);
return (
setValue(null)}>Clear value
{value?.map((date) => date?.format('YYYY-MM-DD') || '—').join(' → ') ||
'No selection'}
);
}
```
### Display format
format changes display text while values remain Dayjs objects.
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Date and time ranges
showTime adds time selection for both endpoints before confirmation.
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Month and year ranges
Use picker to select month or year granularity.
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Disable one endpoint
A disabled tuple can lock only the start or end input.
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
Mobile drawer titles use `mobileTitle`, then the nearest `Form.Item` / `FormField` label, then localized default text. Required marks and help text are excluded; placeholders only describe the input. For standalone controls or native HTML labels, pass `mobileTitle="Departure date"` explicitly.
### Mobile selection
Open the picker in phone mode to try selection, confirmation, and clearing inside a drawer.
```tsx preview="iframe-follow"
import { RangePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#rangepicker)RangePicker
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | [boolean, boolean] | undefined` | `-` |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | `ReactNode` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/rate.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Rate
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Lets people choose a rating with full or half steps.
## When to use
Use for a short ordered scale. Add a visible label and explain what the highest and lowest ratings mean.
## Examples
### Controlled half-star rating
Arrow keys move the rating. allowHalf enables half steps and tooltips explain each whole-star score.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Rate, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState(3.5);
return (
How was your experience?
{value} / 5
);
}
```
### Allow or prevent clearing
With allowClear enabled, clicking the selected score again resets it to zero.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
Click the selected star to clear
A value is always retained
);
}
```
### Read-only and disabled
readOnly presents an existing score; disabled communicates that the control is unavailable.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Custom characters and count
character can be a node or a function of the item index.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
(
{(index ?? 0) + 1}
)}
aria-label="Numeric rating"
/>
);
}
```
### Sizes and provider defaults
small, middle and large are accepted. The native medium spelling is also supported.
```tsx preview
import { Rate, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Focus and semantic customization
Use the ref when another action needs to move focus into the rating control.
```tsx preview
import { useRef } from 'react';
import { Button, Rate, Stack } from '@rockshin/tao-ui';
import type { RateRef } from '@rockshin/tao-ui';
export default function Example() {
const ref = useRef(null);
return (
ref.current?.focus()}>
Focus rating
);
}
```
## API
### [#](#rate)Rate
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/segmented.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Segmented
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Selects one view or mode from a compact set of choices.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
The 6.7.0 value/options API is rendered with native radios and tao-ui motion. Size inherits TaoProvider; reduced-motion preferences disable the moving highlight.
## When to use
Use for small, closely related choices. Native radio controls support form submission and keyboard selection.
## Examples
### Basic selection
```tsx preview
import { Segmented } from "@rockshin/tao-ui";
export default function Example() {
return ;
}
```
### Controlled selection
```tsx preview
import { useState } from "react";
import { Segmented } from "@rockshin/tao-ui";
export default function Example() {
const [view, setView] = useState("List");
return (
options={["List", "Board", "Calendar"]}
value={view}
onChange={setView}
/>
Current view: {view}
);
}
```
### Sizes and rounded shape
```tsx preview
import { Segmented } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Disabled choices and labels
```tsx preview="iframe-follow"
import { Segmented } from "@rockshin/tao-ui";
export default function Example() {
return (
○,
},
{ value: "closed", label: "Closed", disabled: true },
{
value: "all",
label: "All records",
tooltip: "Includes archived records",
},
]}
/>
);
}
```
### Vertical and RTL
```tsx preview
import { Segmented } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Submit a native form
```tsx preview
import { useState } from "react";
import { Button, Segmented } from "@rockshin/tao-ui";
export default function Example() {
const [submitted, setSubmitted] = useState("");
return (
{
event.preventDefault();
setSubmitted(String(new FormData(event.currentTarget).get("period")));
}}
>
Apply
Submitted: {submitted || "—"}
);
}
```
## API
### [#](#segmented)Segmented
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/select.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Select
Data Entry`@rockshin/tao-ui`
[API](#api)
Choose one or more values, search options, create tags, and customize their presentation. The examples below cover the currently supported capabilities and can each be copied and run independently.
Examples normally adapt to a mobile drawer. Those described as desktop examples explicitly set `mobile={false}` to demonstrate input, menu, or popup-specific behavior.
## Basics and appearance
### Basic usage
Define choices with `options` and an initial selection with `defaultValue`. `FormField` gives the control an accessible label.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function BasicSelect() {
return (
);
}
```
### Three sizes
Use `small`, `medium`, and `large` for compact toolbars, standard forms, and prominent controls. Desktop option text and row height follow the control size; mobile drawers retain touch-friendly list sizing.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
const options = [
{ label: 'Design', value: 'design' },
{ label: 'Engineering', value: 'engineering' },
];
export default function SelectSizes() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
))}
);
}
```
### Variants
Choose `outlined`, `filled`, or `borderless` for the surrounding surface. `TaoProvider` can set the shared variant.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
const options = [
{ label: 'Personal', value: 'personal' },
{ label: 'Team', value: 'team' },
];
export default function SelectVariants() {
return (
{(['outlined', 'filled', 'borderless'] as const).map((variant) => (
))}
);
}
```
### Disabled controls and options
An option-level `disabled` affects one choice. The control-level prop disables all interaction while keeping the current value visible.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
const options = [
{ label: 'Starter', value: 'starter' },
{ label: 'Team', value: 'team' },
{ label: 'Enterprise — unavailable', value: 'enterprise', disabled: true },
];
export default function DisabledSelect() {
return (
);
}
```
### Validation states
Use `error` or `warning` with an explanation. Error status also sets `aria-invalid` on the control.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
const options = [
{ label: 'Production', value: 'production' },
{ label: 'Staging', value: 'staging' },
];
export default function SelectStatus() {
return (
);
}
```
### Controlled selection
Keep external state in sync with `value` and `onChange`. Clearing a single selection emits an empty string; an external action can also update the value.
```tsx preview
import { Button, FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ControlledSelect() {
const [value, setValue] = useState('react');
return (
setValue(next as string)}
allowClear
options={[
{ label: 'React', value: 'react' },
{ label: 'Vue', value: 'vue' },
]}
placeholder="Choose a framework"
/>
Value: {value || '(empty)'}
setValue('vue')}>
Select Vue
);
}
```
## Multiple selection and tags
### Multiple selection
`mode="multiple"` uses an array of strings. Remove a tag or select an option again to deselect it; `allowClear` clears the entire selection.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function MultipleSelect() {
const [value, setValue] = useState(['design', 'engineering']);
return (
setValue(next as string[])}
options={[
{ label: 'Design', value: 'design' },
{ label: 'Engineering', value: 'engineering' },
{ label: 'Research', value: 'research' },
{ label: 'Operations', value: 'operations' },
]}
placeholder="Choose teams"
/>
Selected: {value.join(', ') || '(none)'}
);
}
```
### Maximum selection count
`maxCount` limits the number of selections. At the limit, unselected options are disabled until an item is removed. This example uses the desktop popup.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function MaximumSelection() {
const [value, setValue] = useState(['design']);
return (
setValue(next as string[])}
options={['Design', 'Engineering', 'Research', 'Operations'].map(
(label) => ({ label, value: label.toLowerCase() }),
)}
placeholder="Choose teams"
/>
{value.length} / 2 selected
);
}
```
### Tags
Combine `mode="tags"` with `showSearch` to create new values with Enter. `notFoundContent={null}` hides an empty suggestion popup. This example uses the desktop input.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function TagInput() {
const [value, setValue] = useState(['design']);
return (
setValue(next as string[])}
options={[
{ label: 'design', value: 'design' },
{ label: 'frontend', value: 'frontend' },
]}
notFoundContent={null}
placeholder="Type a label and press Enter"
/>
Labels: {value.join(', ') || '(none)'}
);
}
```
### Token separators
Paste `design,frontend;docs` and press Enter to split and deduplicate values. In `multiple` mode, tokens must match existing values or labels; `tags` can create new values.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function TokenizedTags() {
const [value, setValue] = useState([]);
return (
setValue(next as string[])}
placeholder="Separate labels with , or ;"
/>
Labels: {value.join(', ') || '(none)'}
);
}
```
### Tag count and length
`maxTagCount` controls visible tags, `maxTagTextLength` shortens labels, and `maxTagPlaceholder` customizes the overflow message. The selected values stay intact.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
const options = [
'Product design',
'Frontend engineering',
'User research',
'Operations',
].map((label) => ({ label, value: label }));
export default function TagOverflow() {
return (
option.value)}
options={options}
maxTagCount={2}
maxTagTextLength={8}
maxTagPlaceholder={(omitted) => `+${omitted.length} teams`}
/>
);
}
```
### Hide selected options
`hideSelected` removes selected entries from the suggestions. Removing a tag makes its option available again. This example uses the desktop popup.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function HideSelected() {
return (
({
label,
value: label.toLowerCase(),
}))}
placeholder="Choose reviewers"
notFoundContent="Everyone has been selected"
/>
);
}
```
### Selection and clear events
`onChange` provides the full value and matching existing options. `onSelect`, `onDeselect`, and `onClear` describe individual actions. Newly created tags have no existing option object.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function SelectionEvents() {
const [value, setValue] = useState(['design']);
const [event, setEvent] = useState('No action yet');
return (
setValue(next as string[])}
onSelect={(_, option) => setEvent(`Selected: ${option.label}`)}
onDeselect={(_, option) => setEvent(`Removed: ${option.label}`)}
onClear={() => setEvent('Cleared all selections')}
options={['Design', 'Engineering', 'Research'].map((label) => ({
label,
value: label.toLowerCase(),
}))}
placeholder="Choose teams"
/>
{event}
);
}
```
## Search and data
### Search and clear
`showSearch` matches option labels without case sensitivity. Try `sv`, select a result, then clear it to choose again.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function SearchSelect() {
return (
);
}
```
### Custom filtering
Use `filterOption` to match labels, values, and descriptions. Search by city, airport code, or country, such as `hnd` or `Japan`.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function CustomFilter() {
return (
`${option.label} ${option.value} ${option.description}`
.toLowerCase()
.includes(input.toLowerCase())
}
placeholder="City, airport code, or country"
/>
);
}
```
### Controlled search
Manage the query with `searchValue` and `onSearch`; the caller decides when to clear it. Uncontrolled multi-select can retain it with `autoClearSearchValue={false}`. This example uses desktop input.
```tsx preview
import { Button, FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ControlledSearch() {
const [search, setSearch] = useState('');
return (
({ label, value: label }),
)}
placeholder="Try Product"
/>
Query: {search || '(empty)'}
setSearch('')}>
Clear query
);
}
```
### Grouped options
Nest options to form groups. Searching keeps the matching entries under their group labels; group labels are not selectable values.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function GroupedSelect() {
return (
);
}
```
### Dependent selections
When the upstream selection changes, update both the dependent options and value. Here the region determines the available cities.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
const cities: Record = {
Asia: ['Tokyo', 'Singapore'],
Europe: ['London', 'Berlin'],
};
export default function DependentSelects() {
const [region, setRegion] = useState('Asia');
const [city, setCity] = useState('Tokyo');
return (
({
label: value,
value,
}))}
onChange={(next) => {
const region = next as string;
setRegion(region);
setCity(cities[region][0]);
}}
/>
setCity(next as string)}
options={cities[region].map((value) => ({ label: value, value }))}
/>
{region} / {city}
);
}
```
### Async search and loading
This example simulates a search request with local data and a 500ms delay. It cancels stale work and combines loading, controlled search, and an empty state. Replace the local lookup with your API in an application. It uses desktop input.
```tsx preview
import { FormField, Select, type SelectOption } from '@rockshin/tao-ui';
import { useEffect, useState } from 'react';
const people = [
{ label: 'Maya Chen', value: 'maya', description: 'Design' },
{ label: 'Noah Kim', value: 'noah', description: 'Engineering' },
{ label: 'Lin Wang', value: 'lin', description: 'Research' },
];
export default function AsyncSelect() {
const [search, setSearch] = useState('');
const [options, setOptions] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
setLoading(true);
setOptions([]);
const timer = window.setTimeout(() => {
setOptions(
people.filter((person) =>
person.label.toLowerCase().includes(search.toLowerCase()),
),
);
setLoading(false);
}, 500);
return () => window.clearTimeout(timer);
}, [search]);
return (
true}
notFoundContent={loading ? 'Searching…' : 'No matching people'}
placeholder="Try Maya or Noah"
/>
);
}
```
### Custom empty state
`notFoundContent` accepts text or a React node for an empty list or no matching results. An external action can populate the options.
```tsx preview
import { Button, FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function EmptySelect() {
const [ready, setReady] = useState(false);
return (
No workspaces yet. Add one below.}
/>
setReady(true)}
>
Add workspace
);
}
```
## Content and styles
### Option icons and descriptions
Add context with option-level `icon` and `description`. Keep `label` short and textual for searching and the selected value.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
function WorkspaceIcon() {
return (
);
}
export default function OptionDetails() {
return (
,
description: 'Components and visual systems',
},
{
label: 'Engineering',
value: 'engineering',
icon: ,
description: 'Application development',
},
]}
/>
);
}
```
### Custom option rendering
`optionRender` receives the option and its flattened index. Compose labels and supporting details while Select keeps the keyboard and selection behavior.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function CustomOptions() {
return (
(
{index + 1}. {option.label}
{option.description}
)}
placeholder="Compare plans"
/>
);
}
```
### Custom selected label
`labelRender` customizes the selected single-value label independently of the option list. Here it adds the airport code beside the city.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function CustomLabel() {
return (
(
{option.value} · {option.label}
)}
/>
);
}
```
### Custom tag rendering
Customize multi-select tags with `tagRender`. Preserve removal behavior using the supplied `closable`, `disabled`, and `onClose`. This example reuses tao-ui `Tag`.
```tsx preview
import { FormField, Select, Tag } from '@rockshin/tao-ui';
export default function CustomTags() {
return (
({
label,
value: label.toLowerCase(),
}))}
tagRender={({ label, value, closable, disabled, onClose }) => (
{label}
)}
/>
);
}
```
### Prefix, suffix, and action icons
Use `prefix`, `suffixIcon`, `allowClear.clearIcon`, `removeIcon`, and `loadingIcon` for the corresponding slots. Custom icons retain the built-in clear and remove behavior.
```tsx preview
import { FormField, Select, Spinner, Stack } from '@rockshin/tao-ui';
const options = [
{ label: 'Design', value: 'design' },
{ label: 'Engineering', value: 'engineering' },
];
function Icon({ close = false }: { close?: boolean }) {
return (
);
}
export default function CustomIcons() {
return (
Team}
suffixIcon={ }
allowClear={{ clearIcon: }}
/>
}
/>
}
options={[]}
placeholder="Loading teams…"
/>
);
}
```
### Semantic styles
Customize public semantic parts through `styles` and `classNames` without private selectors. The popup receives them even when rendered through a portal.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
export default function SemanticSelect() {
return (
<>
>
);
}
```
## Popup and interaction
### Extend the popup
Keep the original menu and add actions through `popupRender`. Here a footer creates a project by name; the Add button preserves input focus. This example uses the desktop popup.
```tsx preview
import { Button, FormField, Input, Select } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ExtendedPopup() {
const [projects, setProjects] = useState(['Website', 'Mobile app']);
const [name, setName] = useState('');
function addProject() {
const label = name.trim();
if (!label || projects.includes(label)) return;
setProjects([...projects, label]);
setName('');
}
return (
({ label, value: label }))}
placeholder="Choose or add a project"
popupRender={(menu) => (
<>
{menu}
setName(event.target.value)}
placeholder="New project"
/>
event.preventDefault()}
onClick={addProject}
>
Add
>
)}
/>
);
}
```
### Popup placement
`placement` sets the preferred side and alignment. The popup still avoids viewport collisions. This example uses desktop popups.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
export default function PopupPlacement() {
return (
{(['bottomLeft', 'bottomRight', 'topLeft', 'topRight'] as const).map(
(placement) => (
),
)}
);
}
```
### Popup width and list height
`popupMatchSelectWidth` matches the trigger by default, or accepts `false` or a pixel width. Numeric widths currently retain the trigger's minimum width; this example pairs a 200px control with a 240px popup. `listHeight` limits the scrollable option area. This is a regular list, not a virtualized list.
```tsx preview
import { FormField, Select, Stack } from '@rockshin/tao-ui';
const options = Array.from({ length: 60 }, (_, index) => ({
label: `Workspace ${index + 1}`,
value: String(index + 1),
}));
export default function PopupDimensions() {
return (
);
}
```
### Long filenames
Enable `optionLabelWrap` to show built-in option labels in full, including filenames without spaces. Labels wrap without a line limit, and the checkmark keeps its own column aligned with the first line. Desktop popup widths stay within the available viewport; use `popupMatchSelectWidth` for a wider menu. Mobile drawers also wrap. Selected tags stay compact; custom `optionRender` content controls its own wrapping.
```tsx preview
import { Select } from '@rockshin/tao-ui';
export default function LongFilenameSelect() {
const files = [
'case2_03_estimated_cost_list.pdf',
'case2_02_cardiology_investigation_report.pdf',
'case2_01_admission_medical_report.pdf',
];
return (
({ label, value: label }))}
style={{ width: '100%', maxWidth: 320 }}
/>
);
}
```
### Controlled open and focus
Control popup visibility with `open` and `onOpenChange`. Use the ref methods `focus()` and `blur()` to coordinate external actions.
```tsx preview
import {
Button,
FormField,
Select,
type SelectRef,
Stack,
} from '@rockshin/tao-ui';
import { useRef, useState } from 'react';
export default function OpenAndFocus() {
const ref = useRef(null);
const [open, setOpen] = useState(false);
return (
{
ref.current?.focus();
setOpen(true);
}}
>
Open choices
{
setOpen(false);
ref.current?.blur();
}}
>
Close and blur
Popup: {open ? 'open' : 'closed'}
);
}
```
### Popup container
`getPopupContainer` chooses the popup DOM container. Leave room for it and avoid ancestor clipping. This example mounts the popup inside its local panel.
```tsx preview
import { FormField, Select } from '@rockshin/tao-ui';
import { useRef } from 'react';
export default function PopupContainer() {
const container = useRef(null);
return (
container.current!}
options={[
{ label: 'Local workspace', value: 'local' },
{ label: 'Shared workspace', value: 'shared' },
]}
placeholder="Open inside this panel"
/>
);
}
```
## Forms and mobile
### Provider defaults
Use `TaoProvider` to share `size`, `variant`, and `disabled`. Local props take precedence; the second control overrides the inherited size and disabled state.
```tsx preview
import { FormField, Select, Stack, TaoProvider } from '@rockshin/tao-ui';
const options = [
{ label: 'Personal', value: 'personal' },
{ label: 'Team', value: 'team' },
];
export default function ProviderSelect() {
return (
);
}
```
### Form submission
Desktop single-select can use `name` with native `FormData`; `id` associates the field label. Serialize controlled values explicitly for multiple selection and mobile drawers. This demo displays the result without sending a request.
```tsx preview
import { Button, FormField, Select, Stack } from '@rockshin/tao-ui';
import { useId, useState } from 'react';
export default function SelectForm() {
const id = useId();
const [result, setResult] = useState('Not submitted');
return (
{
event.preventDefault();
const data = new FormData(event.currentTarget);
setResult(`Submitted team: ${data.get('team')}`);
}}
>
Submit example
{result}
);
}
```
Mobile drawer titles use `mobileTitle`, then the nearest `Form.Item` / `FormField` label, then localized default text. Required marks and help text are excluded; placeholders only describe the input. For standalone controls or native HTML labels, pass `mobileTitle="Departure date"` explicitly.
### Mobile single and multiple selection
Select follows the viewport by default; `mobile` forces the bottom drawer. Single selection commits immediately. Multiple selection commits with Done; closing discards the draft. Try the mobile interaction on desktop here.
```tsx preview="iframe-follow"
import { FormField, Select, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
const options = ['Design', 'Engineering', 'Research', 'Operations'].map(
(label) => ({ label, value: label.toLowerCase() }),
);
export default function MobileSelect() {
const [value, setValue] = useState(['design']);
return (
setValue(next as string[])}
placeholder="Choose several teams"
/>
Committed: {value.join(', ') || '(none)'}
);
}
```
## Usage notes
- For a few mutually exclusive choices that should be compared directly, prefer [Radio](https://rickyshin93.github.io/tao-ui/components/radio.md).
- Single selection uses a string; multiple selection and tags use arrays. The second `onChange` argument contains matching existing options. A newly created tag may not have a matching option object.
- The tag overflow example uses a numeric `maxTagCount` to demonstrate a fixed number of visible tags.
- Mobile drawers support search, groups, custom options, and single/multiple confirmation. Examples marked as desktop use `mobile={false}` to demonstrate input and popup interactions. Placement, popup width, and portal containers configure desktop popups.
- Desktop single-select supports native form submission through `name`. Serialize controlled values in application submission logic for mobile and multiple selection.
## API
### [#](#select)Select
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| options | Available options; nested options form groups. | `SelectOption[]` **(Required)** | `-` |
| value | Controlled selection. Use an array for multiple or tags mode. | `string | string[] | undefined` | `-` |
| defaultValue | Initial selection for an uncontrolled Select. | `string | string[] | undefined` | `-` |
| onChange | Called with the new selection and its matching option or options. | `((value: string | string[], option?: SelectOption | SelectOption[] | undefined) => void) | undefined` | `-` |
| onSelect | Called when an option is selected. | `((value: string, option: SelectOption) => void) | undefined` | `-` |
| onDeselect | Called when a selected option is removed. | `((value: string, option: SelectOption) => void) | undefined` | `-` |
| onClear | Called when the selection is cleared. | `(() => void) | undefined` | `-` |
| mode | Multiple selection or free-form tags. Omit for single selection. | `"multiple" | "tags" | undefined` | `-` |
| placeholder | Hint displayed when no value is selected. | `string | undefined` | `-` |
| size | Control and desktop popup size; inherits from TaoProvider when omitted. | `TaoSize | undefined` | `-` |
| variant | Control appearance; inherits from TaoProvider when omitted. | `TaoVariant | undefined` | `-` |
| disabled | Disable interaction; inherits from TaoProvider when omitted. | `boolean | undefined` | `-` |
| status | Validation appearance: error or warning. | `TaoStatus | undefined` | `-` |
| showSearch | Enable searching the option list. | `boolean | undefined` | `-` |
| filterOption | Custom search predicate receiving the query and option. | `((input: string, option: SelectOption) => boolean) | undefined` | `-` |
| searchValue | Controlled search input text. | `string | undefined` | `-` |
| onSearch | Called when the search text changes. | `((value: string) => void) | undefined` | `-` |
| allowClear | Show a clear action, optionally with a custom icon. | `boolean | { clearIcon?: ReactNode; } | undefined` | `-` |
| loading | Show the loading indicator. | `boolean | undefined` | `-` |
| loadingIcon | Replace the default loading indicator. | `ReactNode` | `-` |
| notFoundContent | Content shown when there are no matching options. Defaults to No results. | `ReactNode` | `-` |
| prefix | Content before the selected value. | `ReactNode` | `-` |
| suffixIcon | Replace the dropdown indicator. | `ReactNode` | `-` |
| removeIcon | Replace the remove icon on selected tags. | `ReactNode` | `-` |
| autoFocus | Focus the control when it mounts. | `boolean | undefined` | `-` |
| id | Identifier for the control and its associated label. | `string | undefined` | `-` |
| name | Name used for form submission. | `string | undefined` | `-` |
| open | Controlled popup visibility. | `boolean | undefined` | `-` |
| defaultOpen | Initial popup visibility. | `boolean | undefined` | `-` |
| onOpenChange | Called when popup visibility changes. | `((open: boolean) => void) | undefined` | `-` |
| placement | Desktop popup position. Defaults to bottomLeft. | `SelectPlacement | undefined` | `-` |
| popupMatchSelectWidth | Desktop popup width: match the trigger, use intrinsic width, or specify pixels. Defaults to true. | `number | boolean | undefined` | `-` |
| listHeight | Desktop option-list height in pixels. Defaults to 256. | `number | undefined` | `-` |
| getPopupContainer | Choose the desktop popup portal container; mobile drawers portal to document.body. | `((trigger: HTMLElement) => HTMLElement) | undefined` | `-` |
| optionRender | Customize each option's content. | `((option: SelectOption, info: { index: number; }) => ReactNode) | undefined` | `-` |
| optionLabelWrap | Wrap built-in option labels without truncation on desktop and mobile. Defaults to false; custom optionRender controls its own content. | `boolean | undefined` | `-` |
| labelRender | Customize the selected option's label. | `((option: SelectOption) => ReactNode) | undefined` | `-` |
| popupRender | Wrap or extend the desktop menu or mobile drawer content. | `((menu: ReactNode) => ReactNode) | undefined` | `-` |
| tagRender | Customize a selected tag, including its remove action. | `((props: TagRenderProps) => ReactNode) | undefined` | `-` |
| maxTagCount | Maximum visible tags, or fit tags to the available width with 'responsive'. | `number | "responsive" | undefined` | `-` |
| maxTagPlaceholder | Content representing selected tags hidden by maxTagCount. | `ReactNode | ((omittedValues: SelectOption[]) => ReactNode)` | `-` |
| maxTagTextLength | Maximum displayed character count for each tag label. | `number | undefined` | `-` |
| maxCount | Maximum number of selected values in multiple or tags mode. | `number | undefined` | `-` |
| autoClearSearchValue | Clear the search after selecting an option. Defaults to true. | `boolean | undefined` | `-` |
| tokenSeparators | Characters that split entered text into selections in multiple or tags mode. | `string[] | undefined` | `-` |
| hideSelected | Hide already selected options from the list. | `boolean | undefined` | `-` |
| mobile | Force mobile or desktop. Otherwise use viewport <576px; an open popup keeps its presentation until closed. | `boolean | undefined` | `-` |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | `ReactNode` | `-` |
| className | CSS class on the root element. | `string | undefined` | `-` |
| style | Inline styles on the root element. | `CSSProperties | undefined` | `-` |
| classNames | CSS classes keyed by typed semantic parts. | `Partial> | undefined` | `-` |
| styles | Inline styles keyed by typed semantic parts. | `Partial> | undefined` | `-` |
### SelectOption
| Property | Type | Description |
| ------------- | ---------------- | ----------------------------------------------------------------------- |
| `label` | `ReactNode` | Option text; prefer a string for default filtering and trigger display. |
| `value` | `string` | Unique value; groups also need a stable value. |
| `disabled` | `boolean` | Prevent selecting or removing this option. |
| `icon` | `ReactNode` | Option icon. |
| `description` | `ReactNode` | Supporting text. |
| `options` | `SelectOption[]` | Nested options; makes the entry a group. |
### TagRenderProps
`tagRender` receives `{ label, value, closable, disabled, onClose }`. Use `closable` to decide whether to offer removal, and call `onClose` to perform it.
### SelectRef
The ref exposes `focus()`, `blur()`, and `nativeElement`. Avoid depending on private DOM structure.
---
url: https://rickyshin93.github.io/tao-ui/components/slider.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Slider
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Selects a numeric value or range using pointer and keyboard input.
## When to use
Use when approximate adjustment is more useful than typing. Show the current value and units next to the slider.
## Examples
### Controlled value and completion
onChange follows each movement; onChangeComplete reports the final pointer or keyboard interaction.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState(35);
const [committed, setCommitted] = useState(35);
return (
Volume: {value}%
Last completed value: {committed}%
);
}
```
### Range and draggable track
Drag either handle to resize the range or drag the selected track to move both endpoints.
```tsx preview
import { useState } from 'react';
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [range, setRange] = useState([20, 60]);
return (
Budget: {range[0]}–{range[1]}
);
}
```
### Marks and discrete values
step={null} restricts selection to marks. dots shows all valid step positions.
```tsx preview
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Tooltip formatting
Set formatter to null to suppress the tooltip, or open to keep it visible.
```tsx preview
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
`${value} °C`, open: true }}
ariaLabelForHandle="Temperature"
/>
);
}
```
### Vertical, reversed and RTL
A vertical slider needs an explicit container height. direction controls keyboard and horizontal value direction.
```tsx preview
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Editable ranges
Click the rail to add a handle. Drag a handle away from the rail to remove it, within minCount and maxCount.
```tsx preview
import { useState } from 'react';
import { Slider, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [values, setValues] = useState([20, 50, 80]);
return (
Stops: {values.join(', ')}
);
}
```
### Disabled state and focus
The ref exposes focus and blur. Semantic styles customize the track and handles.
```tsx preview
import { useRef } from 'react';
import { Button, Slider, Stack } from '@rockshin/tao-ui';
import type { SliderRef } from '@rockshin/tao-ui';
export default function Example() {
const ref = useRef(null);
return (
ref.current?.focus()}>
Focus slider
);
}
```
## API
### [#](#slider)Slider
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/switch.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Switch
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Toggles a setting on or off with immediate effect.
## When to use
Use Switch for settings that take effect immediately.
**Recommended**
- Use labels that describe the enabled state.
- Use Checkbox when the value is submitted with a form.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
function SwitchExample() {
const [enabled, setEnabled] = useState(true);
return (
);
}
export default SwitchExample;
```
### Labels and sizes
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';
function SwitchLabels() {
return (
}
unCheckedChildren={
}
/>
);
}
export default SwitchLabels;
```
### Loading and disabled states
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';
function SwitchStates() {
return (
);
}
export default SwitchStates;
```
### Controlled switch
onChange returns a boolean that can directly update setting state.
```tsx preview
import { useState } from 'react';
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [enabled, setEnabled] = useState(true);
return (
{enabled ? 'Notifications enabled' : 'Notifications disabled'}
);
}
```
### Loading prevents repeated toggles
Use a separate button to toggle loading and inspect the waiting state.
```tsx preview
import { useState } from 'react';
import { Switch, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [loading, setLoading] = useState(false);
return (
setLoading(!loading)}>
{loading ? 'Finish loading' : 'Start loading'}
);
}
```
### State labels and sizes
Keep state labels concise and readable at both sizes.
```tsx preview
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Shared size and disabled state
Multiple switches inherit configuration; a local disabled prop can override it.
```tsx preview
import { Switch, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#switch)Switch
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/textarea.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Textarea
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Multi-line text input with optional auto sizing.
## When to use
Use Textarea for longer freeform content such as descriptions, notes, and comments.
**Recommended**
- Set rows or autoSize based on expected content length.
- Use maxLength when limits are strict.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';
function TextareaExample() {
return (
);
}
export default TextareaExample;
```
### Variants
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';
function TextareaVariants() {
return (
);
}
export default TextareaVariants;
```
### Sizes and autosize
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';
function TextareaSizes() {
return (
);
}
export default TextareaSizes;
```
### Controlled text and character count
Native maxLength limits input; controlled state displays the character count.
```tsx preview
import { useState } from 'react';
import { Textarea, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [text, setText] = useState('');
return (
setText(e.target.value)}
/>
{text.length} / 120
);
}
```
### Bounded automatic height
Enter multiple lines to grow between minRows and maxRows.
```tsx preview
import { Textarea } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Read-only, disabled, and error
Distinguish readable content, unavailable input, and an error requiring correction.
```tsx preview
import { Textarea, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Submit and reset
Read content by name and use reset to restore the default value.
```tsx preview
import { useState } from 'react';
import { Textarea, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState('');
return (
{
e.preventDefault();
setSaved(String(new FormData(e.currentTarget).get('notes')));
}}
onReset={() => setSaved('')}
>
Save notes
Reset
{saved}
);
}
```
### Semantic styling
Style the textarea semantic part while retaining component states and focus behavior.
```tsx preview
import { Textarea } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## Clear and count
`Textarea` and `Input.TextArea` are the same component, supporting `allowClear`, `onClear`, `showCount`, `count`, `onPressEnter`, and `variant="underlined"`. [See the Input family examples and API](https://rickyshin93.github.io/tao-ui/components/input.md).
## API
### [#](#textarea)Textarea
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| autoSize | Auto-grow height to fit content. `true` grows freely; pass min/max rows to clamp. | `boolean | AutoSizeOptions | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/time-picker.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# TimePicker
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Select a time or time range with steps, disabled intervals, formatting and confirmation.
The added API follows Ant Design 6.7.0; appearance, theming and Semantic DOM use tao-ui. Existing component APIs remain unchanged.
## Examples
### Controlled time and clear
Values use Dayjs; clearing returns null.
```tsx preview
import { TimePicker } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';
export default function Demo() {
const [value, setValue] = useState(
dayjs('2026-11-04T09:30:00'),
);
return (
{value?.format('HH:mm:ss') ?? 'No time selected'}
);
}
```
### Formats and 12-hour clock
The format controls the visible columns. use12Hours adds AM/PM.
```tsx preview
import { TimePicker, Stack } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
export default function Demo() {
return (
);
}
```
### Time steps
Offer values in two-hour, fifteen-minute and ten-second steps.
```tsx preview
import { TimePicker } from '@rockshin/tao-ui';
export default function Demo() {
return ;
}
```
### Working hours
Limit choices to 09:00–18:00 and hide unavailable options.
```tsx preview
import { TimePicker } from '@rockshin/tao-ui';
export default function Demo() {
return (
({
disabledHours: () =>
Array.from({ length: 24 }, (_, i) => i).filter(
(i) => i < 9 || i > 18,
),
disabledMinutes: (hour) =>
hour === 18 ? Array.from({ length: 59 }, (_, i) => i + 1) : [],
})}
/>
);
}
```
### Three sizes
This compatible API uses small, middle and large; omitted sizes inherit TaoProvider.
```tsx preview
import { TimePicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
{(['small', 'middle', 'large'] as const).map((size) => (
))}
);
}
```
### Variants and states
Combine variants with error, warning or disabled states.
```tsx preview
import { TimePicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Time range
RangePicker submits the start and end values together.
```tsx preview
import { TimePicker } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [label, setLabel] = useState('Choose a range');
return (
setLabel(strings ? strings.join(' → ') : 'Cleared')
}
/>
{label}
);
}
```
### Confirmation behavior
needConfirm controls whether selecting a value requires confirmation.
```tsx preview
import { TimePicker, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Panel footer
Use renderExtraFooter for information relevant to the choice.
```tsx preview
import { TimePicker } from '@rockshin/tao-ui';
export default function Demo() {
return (
(
All appointments use your local time.
)}
styles={{ popup: { root: { maxWidth: 320 } } }}
/>
);
}
```
### Phone viewport and Chinese text
The example runs in an independent iframe. Switch viewport sizes to inspect the popup.
```tsx preview="iframe-follow"
import { TimePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
## API
### [#](#timepickerrangepicker)TimePicker.RangePicker
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| bordered | @deprecated Use variant. | `boolean | undefined` | `-` |
| popupClassName | @deprecated Use classNames.popup.root. | `string | undefined` | `-` |
| dropdownClassName | @deprecated Use classNames.popup.root. | `string | undefined` | `-` |
| popupStyle | @deprecated Use styles.popup.root. | `CSSProperties | undefined` | `-` |
### [#](#timepicker)TimePicker
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| onSelect | @deprecated Use onCalendarChange. | `((time: Dayjs) => void) | undefined` | `-` |
| addon | @deprecated Use renderExtraFooter. | `(() => ReactNode) | undefined` | `-` |
| bordered | @deprecated Use variant. | `boolean | undefined` | `-` |
| popupClassName | @deprecated Use classNames.popup.root. | `string | undefined` | `-` |
| dropdownClassName | @deprecated Use classNames.popup.root. | `string | undefined` | `-` |
| popupStyle | @deprecated Use styles.popup.root. | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/transfer.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Transfer
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Moves records between available and selected collections.
## When to use
Use for selecting several records while keeping both collections visible. Keep targetKeys in application state and use stable item keys.
## Examples
### Controlled target records
Select records, then use the middle action to move them. Disabled records cannot be selected.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState(['1', '4']);
return (
item.title}
/>
);
}
```
### Controlled selection and events
selectedKeys controls checkbox state independently from targetKeys. onChange also reports the direction and moved keys.
```tsx preview
import { useState } from 'react';
import { Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState([]);
const [selected, setSelected] = useState(['0']);
const [event, setEvent] = useState('No records moved');
return (
setSelected([...source, ...target])}
onChange={(next, direction, moved) => {
setKeys(next);
setEvent(`${moved.length} record(s) moved ${direction}`);
}}
render={(item) => item.title}
/>
{event}
);
}
```
### Search by multiple fields
filterOption receives the search text, item and list direction. The rendered label can differ from the searchable value.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState([]);
return (
`${item.title} ${item.description}`
.toLowerCase()
.includes(query.toLowerCase())
}
render={(item) => ({
label: (
{item.title} · {item.description}
),
value: `${item.title} ${item.description}`,
})}
/>
);
}
```
### One-way transfer and pagination
oneWay moves records right and removes them from the target list individually. Pagination applies to each list.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState(['1', '3']);
return (
item.title}
/>
);
}
```
### Footers and selection labels
Provide a footer for each direction and show selected counts with selectAllLabels.
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState([]);
return (
item.title}
selectAllLabels={[
({ selectedCount, totalCount }) =>
`${selectedCount} / ${totalCount} available`,
({ selectedCount, totalCount }) =>
`${selectedCount} / ${totalCount} selected`,
]}
footer={(_, info) => (
{info?.direction === 'left'
? 'Choose team members'
: 'Members added to this project'}
)}
/>
);
}
```
### Custom list body
The render function receives filteredItems, selectedKeys and selection callbacks. Preserve disabled behavior in your custom controls.
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
key: String(index),
title: `Member ${index + 1}`,
description: index % 2 ? 'Design' : 'Engineering',
disabled: index === 2,
}));
export default function Example() {
const [keys, setKeys] = useState([]);
return (
item.title}
>
{({ filteredItems, selectedKeys, onItemSelect, disabled }) => (
{filteredItems.map((item) => (
onItemSelect(item.key, event.currentTarget.checked)
}
>
{item.title} ({item.description})
))}
)}
);
}
```
### Custom keys, status and disabled state
rowKey supports records whose identifier is not named key. Source and target semantic styles can be configured separately.
```tsx preview
import { useState } from 'react';
import { Button, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = [
{ id: 1, title: 'Design' },
{ id: 2, title: 'Engineering' },
{ id: 3, title: 'Operations' },
];
export default function Example() {
const [keys, setKeys] = useState([]);
const [disabled, setDisabled] = useState(false);
return (
setDisabled((value) => !value)}
>
{disabled ? 'Enable' : 'Disable'}
item.id}
targetKeys={keys}
onChange={setKeys}
disabled={disabled}
status={keys.length ? undefined : 'warning'}
render={(item) => item.title}
styles={{
target: { header: { background: 'var(--tao-color-bg-container)' } },
}}
/>
Select at least one team.
);
}
```
## API
### [#](#transfer)Transfer
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| render | Item content; defaults to the title, or the key when the title is omitted. | `((item: T) => RenderResult) | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tree-select.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# TreeSelect
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Select values from hierarchical options with search, multiple selection and linked checkboxes.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
Sizes are `small`, `medium` and `large`; the compatible `middle` alias uses the same dimensions as `medium`.
## Examples
### Searchable single selection
Use treeNodeFilterProp="title" when the title is the searchable label.
```tsx preview
import { TreeSelect } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function BasicTreeSelect() {
return (
);
}
```
### Controlled multiple values
Use a value array and responsive tag overflow for a compact input.
```tsx preview
import { useState } from 'react';
import { TreeSelect } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function MultipleTeams() {
const [value, setValue] = useState(['design', 'web']);
return (
aria-label="Teams"
multiple
value={value}
onChange={setValue}
treeData={treeData}
treeDefaultExpandAll
maxTagCount="responsive"
style={{ width: '100%' }}
/>
);
}
```
### Parent and child checks
SHOW\_PARENT displays the parent when all enabled descendants are selected.
```tsx preview
import { TreeSelect } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function CheckedTeams() {
return (
);
}
```
### Keep the selected label
labelInValue returns an object containing the value and its rendered label.
```tsx preview
import { useState } from 'react';
import { TreeSelect, type TreeSelectLabeledValue } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function LabeledTeam() {
const [value, setValue] = useState({
value: 'design',
label: 'Design',
});
return (
labelInValue
value={value}
onChange={setValue}
treeData={treeData}
treeDefaultExpandAll
style={{ width: '100%' }}
/>
Value: {value.value}
);
}
```
### Flat data with parent IDs
treeDataSimpleMode converts id/pId records into a tree without changing your API response shape.
```tsx preview
import { TreeSelect } from '@rockshin/tao-ui';
export default function FlatTeams() {
return (
);
}
```
### Map field names
Map label, value and children when server data uses different names.
```tsx preview
import { TreeSelect } from '@rockshin/tao-ui';
export default function CustomFields() {
return (
);
}
```
### Sizes, variants and status
Local appearance props override the provider defaults.
```tsx preview
import { TreeSelect } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function TreeSelectAppearance() {
return (
);
}
```
### Narrow-screen selection
The popup stays within the phone viewport. TreeSelect uses its tree popup on both desktop and mobile.
```tsx preview="iframe-follow"
import { TreeSelect } from '@rockshin/tao-ui';
const treeData = [
{
value: 'product',
title: 'Product',
children: [
{ value: 'design', title: 'Design' },
{ value: 'research', title: 'Research' },
],
},
{
value: 'engineering',
title: 'Engineering',
children: [
{ value: 'web', title: 'Web' },
{ value: 'platform', title: 'Platform' },
],
},
];
export default function MobileTreeSelect() {
return (
Choose project teams
);
}
```
## API
### [#](#treeselect)TreeSelect
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/upload.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Upload
Data Entry`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Select, drop and manage files with real requests, custom uploads and controlled lists.
Choose from text, picture, picture-card and picture-circle lists. The examples below demonstrate local selection and explicitly simulated requests; connect `action` or `customRequest` to your own service for real uploads.
## Examples
### Click to select
Start with completed and failed files. New selections stay local because beforeUpload returns false.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}
defaultFileList={[
{ uid: '1', name: 'project-brief.pdf', status: 'done' },
{ uid: '2', name: 'requirements.docx', status: 'done' },
{
uid: '3',
name: 'budget.xlsx',
status: 'error',
error: new Error('Example: the server rejected this file'),
},
]}
>
Select files
);
}
```
### Controlled file list
Own fileList through onChange; the clear button updates the same state.
```tsx preview
import { Upload, Button, Stack, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [files, setFiles] = useState([]);
return (
false}
onChange={(info) => setFiles(info.fileList)}
>
Select files
setFiles([])}>
Clear list
);
}
```
### Validate and ignore files
LIST\_IGNORE excludes rejected files from the list. Browser accept is only a selection hint.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [error, setError] = useState('');
return (
{
if (!file.type.startsWith('image/')) {
setError('Choose an image file.');
return Upload.LIST_IGNORE;
}
setError('');
return false;
}}
>
Select image
{error}
);
}
```
### Multiple files and limits
maxCount caps the list length; one replaces the current file.
```tsx preview
import { Upload, Button, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}>
Select up to three files
false}>
Replace single file
);
}
```
### Drag and drop
Click anywhere in the drop zone or drop multiple files. Files stay local; no request is sent.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}
height={200}
hasControlInside={false}
>
Click or drag files to this area
Select a single file or multiple documents.
);
}
```
### Picture list
A compact list with thumbnails, filenames and actions. Click a thumbnail to preview; new images stay local.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}
defaultFileList={[
{
uid: '1',
name: 'image-01.png',
status: 'done',
url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
},
{
uid: '2',
name: 'image-02.png',
status: 'error',
url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
error: new Error('Example upload error'),
},
]}
>
Select images
);
}
```
### Picture wall with preview
Controlled picture-card list with completed, uploading and failed examples. Preview and remove images; the trigger hides at six files. Uploading progress is an initial display state, not a running request.
```tsx preview
import { Upload, Modal, type UploadFile } from '@rockshin/tao-ui';
import { useState } from 'react';
const imageUrl =
'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png';
export default function Demo() {
const [files, setFiles] = useState([
{ uid: '1', name: 'image-01.png', status: 'done', url: imageUrl },
{ uid: '2', name: 'image-02.png', status: 'done', url: imageUrl },
{ uid: '3', name: 'image-03.png', status: 'uploading', percent: 48 },
{
uid: '4',
name: 'image-04.png',
status: 'error',
error: new Error('Example upload error'),
},
]);
const [preview, setPreview] = useState({ name: '', url: '' });
const [error, setError] = useState('');
const showPreview = (file: UploadFile) => {
setError('');
if (file.url || file.thumbUrl) {
setPreview({ name: file.name, url: file.url || file.thumbUrl! });
} else if (file.originFileObj) {
const reader = new FileReader();
reader.onload = () =>
setPreview({ name: file.name, url: String(reader.result) });
reader.onerror = () => setError('Could not read this image.');
reader.readAsDataURL(file.originFileObj);
}
};
return (
<>
false}
onChange={({ fileList }) => setFiles(fileList)}
onPreview={showPreview}
showUploadList={{
showPreviewIcon: (file) =>
!!(file.url || file.thumbUrl || file.originFileObj),
}}
>
{files.length >= 6 ? null : (
<>
Add image
>
)}
{error && {error}
}
setPreview({ name: '', url: '' })}
>
>
);
}
```
### Circular picture list
The complete tile and its upload trigger are circular. Keyboard focus reveals the same actions as hover.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}
defaultFileList={[
{
uid: '1',
name: 'profile.png',
status: 'done',
url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
},
]}
hasControlInside={false}
>
Add image
);
}
```
### Avatar selection
Replace a single image without a file list. Validate image type and a 2 MB size limit before reading the local preview. This does not save an avatar to a server.
```tsx preview
import { Upload } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [avatar, setAvatar] = useState('');
const [error, setError] = useState('');
return (
<>
{
if (!file.type.startsWith('image/') || file.size > 2 * 1024 * 1024) {
setError('Choose an image smaller than 2 MB.');
return Upload.LIST_IGNORE;
}
setError('');
const reader = new FileReader();
reader.onload = () => setAvatar(String(reader.result));
reader.onerror = () => setError('Could not read this image.');
reader.readAsDataURL(file);
return false;
}}
>
{avatar ? (
) : (
Select avatar
)}
{error && {error}
}
>
);
}
```
### Custom request and progress
An explicit simulation with no network traffic: choose files to see progress, completion and cancellation. Enable the switch to simulate a failed request. Replace this customRequest with your transport in production.
```tsx preview
import { Upload, Button, Switch, type UploadProps } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [fail, setFail] = useState(false);
const customRequest: UploadProps['customRequest'] = ({
onProgress,
onSuccess,
onError,
}) => {
let percent = 0;
const timer = window.setInterval(() => {
percent += 20;
onProgress?.({ percent });
if (percent === 100) {
window.clearInterval(timer);
if (fail) onError?.(new Error('Simulated upload failure'));
else onSuccess?.({ simulated: true });
}
}, 300);
return { abort: () => window.clearInterval(timer) };
};
return (
Simulate failure
Start simulated upload
);
}
```
### Disabled upload
Disable selection and removal while keeping completed files available for preview.
```tsx preview
import { Upload, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [disabled, setDisabled] = useState(true);
return (
Disabled
false}
defaultFileList={[
{
uid: '1',
name: 'image.png',
status: 'done',
url: 'https://rickyshin93.github.io/tao-ui/demos/upload/mountain-lake.png',
},
]}
hasControlInside={false}
>
Add image
);
}
```
### Confirm removal
onRemove can reject removal synchronously or asynchronously. This example protects files with a switch.
```tsx preview
import { Upload, Button, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [locked, setLocked] = useState(true);
return (
Protect files
false}
onRemove={() => !locked}
defaultFileList={[
{ uid: '1', name: 'protected-report.pdf', status: 'done' },
]}
>
Select file
);
}
```
### Extra list information
Render per-file information and choose which list actions appear.
```tsx preview
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
return (
false}
defaultFileList={[
{ uid: '1', name: 'design-notes.pdf', size: 245760, status: 'done' },
]}
showUploadList={{
extra: (file) => (
{Math.ceil((file.size ?? 0) / 1024)} KB · local file
),
showDownloadIcon: false,
}}
>
Select document
);
}
```
### Phone selection and paste
pastable accepts clipboard files. The browser and device control available file sources.
```tsx preview="iframe-follow"
import { Upload, Button } from '@rockshin/tao-ui';
export default function Demo() {
return (
false} listType="picture">
Select or paste images
);
}
```
## API
| Property | Type | Default | Description |
| ----------------------------------- | -------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
| `fileList / defaultFileList` | `UploadFile[]` | — | Controlled list / initial uncontrolled list. |
| `onChange` | `({ file, fileList, event? }) => void` | — | Called for selection, progress, completion, failure and removal. |
| `action` | `string or (file) => string / PromiseLike` | — | Upload URL; required for the default transport. |
| `customRequest` | `(options, { defaultRequest }) => void / { abort() }` | — | Supply your transport; report progress, success or error through options. |
| `beforeUpload` | `(file, files) => boolean / File / Blob / Promise` | — | false stops the request but keeps the file; Upload.LIST\_IGNORE excludes it; return File/Blob to transform. |
| `listType` | `'text' / 'picture' / 'picture-card' / 'picture-circle'` | 'text' | List appearance; card and circle triggers follow the file tiles. |
| `showUploadList` | `boolean or ShowUploadListInterface` | true | Configure extra content and preview, download and remove actions per file. |
| `maxCount` | `number` | — | Limit list length; 1 replaces the previous file. Hide the trigger yourself with children={null}. |
| `multiple / directory / pastable` | `boolean` | false | Multiple selection / directory selection / clipboard file upload. |
| `accept` | `string or AcceptConfig` | — | Selection hint, such as image/\*. Validate files in beforeUpload. |
| `capture` | `boolean / 'user' / 'environment'` | — | Pass the capture hint to the native file input. |
| `name / method` | `string` | 'file' / 'post' | Multipart field name and HTTP method (POST, PUT or PATCH). |
| `data` | `object or (file) => object / Promise` | — | Additional multipart fields. |
| `headers / withCredentials` | `object / boolean` | — / false | Request headers and credential handling. |
| `onPreview / onDownload` | `(file) => void` | — | Override preview/download. Downloads appear only for done files; local images have a built-in preview. |
| `onRemove` | `(file) => void / boolean / Promise` | — | Return false (or resolve false) to prevent removal. Accepted removal aborts the active request. |
| `previewFile` | `(file: File or Blob) => PromiseLike` | — | Generate a local thumbnail URL. |
| `isImageUrl / iconRender` | `(file) => boolean / (file, listType) => ReactNode` | — | Customize image detection and the file/loading icon. |
| `itemRender` | `(node, file, fileList, actions) => ReactNode` | — | Customize each row with preview, download and remove actions. |
| `progress` | `UploadListProgressProps` | — | Customize the line progress indicator. |
| `disabled` | `boolean` | TaoProvider | Disable selection and removal; preview remains available. |
| `openFileDialogOnClick` | `boolean` | true | Open the file picker when the trigger is activated. |
| `hasControlInside` | `boolean` | Automatic / 自动 | Set false for plain-text/custom non-interactive children so the wrapper is keyboard accessible. |
| `onDrop / onFocus` | `event handler` | — | Receive drop and focus events. |
| `locale` | `UploadLocale` | TaoProvider | Override uploading, preview, download, remove and error labels. |
| `classNames / styles` | `object or ({ props }) => object` | — | Semantic parts: root, trigger, list, item. |
| `className / rootClassName / style` | `string / string / CSSProperties` | — | Root styling. Dragger style configures the drop zone. |
| `id / children` | `string / ReactNode` | — | Input identifier and trigger content. null or false hides the trigger. |
### Upload.Dragger
Inherits Upload props and adds `height?: number` for the drop zone, excluding the file list.
### UploadFile
Requires `uid` and `name`. Common fields are `status` (uploading / done / error / removed), `percent`, `url`, `thumbUrl`, `originFileObj`, `response`, `error`, `size` and `type`. Files stopped by beforeUpload have no status.
### ShowUploadListInterface
`showPreviewIcon`, `showDownloadIcon` and `showRemoveIcon` accept booleans or `(file) => boolean`. `previewIcon`, `downloadIcon`, `removeIcon` and `extra` accept ReactNode or `(file) => ReactNode`. Cards show preview and remove by default; download is opt-in.
## Connect an upload service
The live examples use local selection or simulated requests. To send files to a server, set `action` to the upload endpoint and `name` to the multipart field the server expects.
```tsx
import { Upload, Button } from '@rockshin/tao-ui';
// The application must implement this endpoint.
export function ServerUpload() {
return (
Upload to server
);
}
```
If you supply `customRequest`, report progress with `onProgress` and finish each request once with `onSuccess` or `onError`. Return an object with an `abort()` method if your transport supports cancellation. With a controlled `fileList`, store the list from `onChange` to show the latest status for each file.
Since [0.0.49](https://rickyshin93.github.io/tao-ui/guide/changelog.md), Upload also handles failures while resolving `action` or `data`, and synchronous exceptions from `customRequest`. The affected file shows an error and the other files in the batch continue.
---
url: https://rickyshin93.github.io/tao-ui/components/avatar.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Avatar
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Identifies people or entities using images, initials or icons.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Sizes inherit TaoProvider. Square avatars use the native tao-ui radius; group overflow uses the tao-ui Popover.
## When to use
Use short initials and meaningful alternative text. Groups show team membership.
## Examples
### Sizes and shapes
```tsx preview
import { Avatar } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Images and icons
```tsx preview
import { Avatar } from "@rockshin/tao-ui";
const image = `data:image/svg+xml,${encodeURIComponent(' ')}`;
export default function Example() {
return (
◎} aria-label="Guest" />
RS
);
}
```
### Automatic text fitting
```tsx preview
import { useState } from "react";
import { Avatar, Button } from "@rockshin/tao-ui";
const labels = ["A", "Ada", "Lovelace"];
export default function Example() {
const [index, setIndex] = useState(0);
return (
{labels[index]}
setIndex((index + 1) % labels.length)}>
Change name
);
}
```
### Groups and overflow
```tsx preview="iframe-follow"
import { Avatar } from "@rockshin/tao-ui";
export default function Example() {
return (
{["AL", "BT", "CW", "DX", "EY"].map((name) => (
{name}
))}
);
}
```
### Responsive sizes
```tsx preview="iframe-follow"
import { Avatar } from "@rockshin/tao-ui";
export default function Example() {
return (
AL
Resize the preview to change the avatar size.
);
}
```
### Local theme and semantic parts
```tsx preview
import { Avatar, TaoProvider } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
## API
### [#](#avatar)Avatar
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/badge.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Badge
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Shows counts, compact status indicators and ribbons.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Badge follows the 6.7.0 count/status API; colors and Ribbon surfaces use tao-ui tokens. Count changes update directly.
## When to use
Attach counts to a relevant control; include text when communicating status.
## Examples
### Counts, zero and overflow
```tsx preview
import { Avatar, Badge } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Change a count
```tsx preview
import { useState } from "react";
import { Badge, Button } from "@rockshin/tao-ui";
export default function Example() {
const [count, setCount] = useState(5);
return (
setCount(Math.max(0, count - 1))}>−
setCount(count + 1)}>+
);
}
```
### Dot and small indicators
```tsx preview
import { Badge, Button } from "@rockshin/tao-ui";
export default function Example() {
return (
Updates
Messages
Read
);
}
```
### Status labels
```tsx preview
import { Badge } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Custom color and offset
```tsx preview
import { Avatar, Badge } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Ribbon placement
```tsx preview
import { Badge, Card } from "@rockshin/tao-ui";
export default function Example() {
return (
Shared workspace and collaboration.
Try the updated workflow.
);
}
```
## API
### [#](#badge)Badge
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/calendar.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Calendar
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Display months or years with event cells, custom headers and selectable ranges.
The added API follows Ant Design 6.7.0; appearance, theming and Semantic DOM use tao-ui. Existing component APIs remain unchanged.
## Examples
### Full month calendar
A full calendar provides space for events inside each day.
```tsx preview
import { Calendar } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
export default function Demo() {
return ;
}
```
### Compact calendar
fullscreen=false uses a compact layout for sidebars and cards.
```tsx preview
import { Calendar } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
export default function Demo() {
return (
);
}
```
### Controlled selection and source
onSelect distinguishes day clicks from header changes; onChange updates the value.
```tsx preview
import { Calendar } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function Demo() {
const [value, setValue] = useState(dayjs('2026-11-04'));
const [source, setSource] = useState('initial');
return (
setSource(info.source)}
/>
{value.format('YYYY-MM-DD')} · {source}
);
}
```
### Event cells
cellRender adds events inside the default cell while keeping date interaction.
```tsx preview
import { Calendar, Badge } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
export default function Demo() {
return (
info.type === 'date' && [4, 12, 20].includes(date.date()) ? (
) : null
}
/>
);
}
```
### Valid range
The range constrains both header navigation and day selection.
```tsx preview
import { Calendar } from '@rockshin/tao-ui';
import dayjs from 'dayjs';
export default function Demo() {
return (
);
}
```
### Disable weekends
disabledDate receives Dayjs; dates returning true cannot be selected.
```tsx preview
import { Calendar } from '@rockshin/tao-ui';
export default function Demo() {
return (
date.day() === 0 || date.day() === 6}
/>
);
}
```
### Year view and week numbers
Switch between month and year views, or display week numbers.
```tsx preview
import { Calendar, Button } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [mode, setMode] = useState<'month' | 'year'>('year');
return (
setMode(mode === 'year' ? 'month' : 'year')}>
Switch view
setMode(next)}
/>
);
}
```
### Custom header
The header receives value and mode setters for a custom toolbar.
```tsx preview
import { Calendar, Button, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
(
onChange(value.subtract(1, 'month'))}
>
Previous
{value.format('YYYY-MM')}
onChange(value.add(1, 'month'))}
>
Next
)}
/>
);
}
```
### Phone and locale
The compact calendar inherits Chinese text from the provider.
```tsx preview="iframe-follow"
import { Calendar, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
## API
### [#](#calendar)Calendar
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/card.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Card
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Groups related content, actions and tabbed views in a surface.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
The public Card API follows 6.7.0; styling uses tao-ui tokens and Semantic DOM. Tabs use the low-level rc tabs engine with native tao-ui styles.
## When to use
Use cards for self-contained records. Use explicit links or buttons for actions.
## Examples
### Title and extra action
```tsx preview
import { useState } from "react";
import { Button, Card } from "@rockshin/tao-ui";
export default function Example() {
const [saved, setSaved] = useState(false);
return (
setSaved(!saved)}>
{saved ? "Saved" : "Save"}
}
>
Keep related project information together.
);
}
```
### Sizes and variants
```tsx preview
import { Card } from "@rockshin/tao-ui";
export default function Example() {
return (
Compact details.
Default surface.
A surface inside a shaded region.
);
}
```
### Cover, metadata and actions
```tsx preview
import { useState } from "react";
import { Avatar, Button, Card } from "@rockshin/tao-ui";
export default function Example() {
const [saved, setSaved] = useState(false);
const [message, setMessage] = useState("");
return (
}
actions={[
setSaved(!saved)}>
{saved ? "Saved" : "Save"}
,
setMessage("Read-only access for all team members")}
>
Details
,
]}
>
AL}
title="Design notes"
description={message || "Updated today by Ada"}
/>
);
}
```
### Controlled tabs
```tsx preview
import { useState } from "react";
import { Card } from "@rockshin/tao-ui";
export default function Example() {
const [tab, setTab] = useState("overview");
return (
{tab === "overview"
? "Project summary and owners."
: "The latest project activity."}
);
}
```
### Loading content
```tsx preview
import { useState } from "react";
import { Button, Card } from "@rockshin/tao-ui";
export default function Example() {
const [loading, setLoading] = useState(true);
return (
setLoading(!loading)} style={{ marginBottom: 16 }}>
Toggle loading
);
}
```
### Grid and inner cards
```tsx preview="iframe-follow"
import { Card } from "@rockshin/tao-ui";
export default function Example() {
return (
{["Asia", "Europe", "Americas"].map((region) => (
{region}
))}
Monthly subscription.
);
}
```
### Semantic styles and theme
```tsx preview
import { Card, TaoProvider } from "@rockshin/tao-ui";
export default function Example() {
return (
This card inherits its local tokens and dark surface.
);
}
```
## API
### [#](#card)Card
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| bordered | @deprecated Use variant. | `boolean | undefined` | `-` |
| headStyle | @deprecated Use styles.header. | `CSSProperties | undefined` | `-` |
| bodyStyle | @deprecated Use styles.body. | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/carousel.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Carousel
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Slides with native arrows and dots, automatic playback, fade transitions, responsive layouts and ref controls.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
## Examples
### Arrows and dots
Dots navigate directly to a slide. arrows enables previous/next controls.
```tsx preview
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function BasicCarousel() {
return {slides} ;
}
```
### Imperative navigation
The ref exposes goTo, next and prev while afterChange reports the settled slide index.
```tsx preview
import { useRef, useState } from 'react';
import { Button, Carousel, type CarouselRef } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function CarouselControls() {
const ref = useRef(null);
const [current, setCurrent] = useState(0);
return (
{slides}
ref.current?.prev()}>Previous
ref.current?.goTo(2, true)}>Go to third
ref.current?.next()}>Next
Slide {current + 1}
);
}
```
### Automatic playback
autoplaySpeed controls the interval. dotDuration shows elapsed time on the active indicator.
```tsx preview
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function AutoplayCarousel() {
return (
{slides}
);
}
```
### Fade transition
effect="fade" changes the transition while keeping the same navigation API.
```tsx preview
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function FadingCarousel() {
return (
{slides}
);
}
```
### Vertical slides
Placing dots at start or end enables vertical slides unless vertical is explicitly overridden.
```tsx preview
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function VerticalCarousel() {
return (
{slides}
);
}
```
### Multiple visible slides
Responsive settings show two slides on wider screens and one below 480 px.
```tsx preview="iframe-follow"
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function ResponsiveCarousel() {
return (
{slides}
);
}
```
### Custom pagination
customPaging changes each dot button; semantic styles position the dots as a group.
```tsx preview
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function NumberedCarousel() {
return (
(
{index + 1}
)}
>
{slides}
);
}
```
### Swipe on a phone
Touch swiping is enabled by default. draggable also enables mouse dragging for desktop previews.
```tsx preview="iframe-follow"
import { Carousel } from '@rockshin/tao-ui';
const slides = ['Explore', 'Review', 'Publish'].map((label, index) => (
));
export default function MobileCarousel() {
return (
Discover the workflow
{slides}
Swipe left or right to switch slides.
);
}
```
## API
### [#](#carousel)Carousel
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/collapse.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Collapse
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Item-based panels with built-in headers, expand icons and content regions; supports independent panels and accordions.
## When to use
Group settings, explanations and secondary details. Use `accordion` to keep one panel open at a time. Make required information easy to discover.
## Examples
### Basic panels
Pass `items` for complete panels. Multiple panels can be expanded by default.
```tsx preview
import { Collapse } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Accordion
Open one panel at a time. Clicking the active panel again closes it.
```tsx preview
import { Collapse } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Controlled expansion
Coordinate expansion through `activeKey` and `onChange`. Callbacks always receive an array of string keys.
```tsx preview
import { Button, Collapse, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
const items = [
{ key: '1', label: 'Project overview', children: 'Keep project goals, progress and recent changes together.' },
{ key: '2', label: 'Team members', children: 'Manage collaborators and their access to this project.' },
{ key: '3', label: 'Billing details', children: 'Review your next invoice and payment method.' },
];
export default function Example() {
const [activeKey, setActiveKey] = useState(['1']);
return
setActiveKey(['1', '2', '3'])}>Expand all
setActiveKey([])}>Collapse all
Expanded: {activeKey.join(', ') || '—'}
;
}
```
### Three sizes
Choose small, medium or large; size also inherits from TaoProvider.
```tsx preview
import { Collapse, Stack } from '@rockshin/tao-ui';
export default function Example() {
return
{(['small', 'medium', 'large'] as const).map((size) => )}
;
}
```
### Borderless and ghost
`bordered={false}` removes the outer border; `ghost` also removes the background and separators.
```tsx preview
import { Collapse, Stack } from '@rockshin/tao-ui';
const items = [
{ key: '1', label: 'Project overview', children: 'Keep project goals, progress and recent changes together.' },
{ key: '2', label: 'Team members', children: 'Manage collaborators and their access to this project.' },
{ key: '3', label: 'Billing details', children: 'Review your next invoice and payment method.' },
];
export default function Example() {
return
;
}
```
### Trigger modes and disabled panels
Toggle with the whole header, only the icon, or disable a panel. Arrow-free headers remain clickable.
```tsx preview
import { Collapse } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
### Extra actions and end icon
Put independent actions in `extra`. Clicking them does not toggle the panel.
```tsx preview
import { Button, Collapse, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Example() {
const [count, setCount] = useState(0);
return
setCount((value) => value + 1)}>Edit,
}]} />
Edit count: {count}
;
}
```
### Nested panels and custom icons
Nested groups keep independent state. Custom icons receive isActive.
```tsx preview
import { Collapse } from '@rockshin/tao-ui';
export default function Example() {
return (
)} items={[{
key: 'outer', label: 'Workspace settings', children: ,
}]} />;
}
```
### Retain or destroy content
Bodies mount on first expansion and retain inputs when closed. `destroyOnHidden` unmounts closed bodies; an item with `forceRender` stays mounted.
```tsx preview
import { Button, Collapse, Input, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Example() {
const [destroy, setDestroy] = useState(false);
return
setDestroy((value) => !value)}>{destroy ? 'Destroy on close' : 'Keep input'}
}]} />
;
}
```
### Panels on a phone
Long titles wrap while icons and extra actions stay usable. Phone and desktop selection follows the shared preview state.
```tsx preview="iframe-follow"
import { Collapse } from '@rockshin/tao-ui';
export default function Example() {
return ;
}
```
## Migration and composition
Rename `Collapsible` / `@rockshin/tao-ui/collapsible` to `Collapse` / `@rockshin/tao-ui/collapse`. Prefer `items` over hand-built headers and bodies. `Collapse.Trigger` / `Collapse.Content` remain available for custom single disclosures with `open` / `onOpenChange`; item panels use `activeKey` / `onChange`. Do not mix the two state APIs.
## API
### [#](#collapse)Collapse
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| items | Complete panels with built-in headers, icons and content styling. | `CollapseItem[] | undefined` | `-` |
| onChange | Called with normalized string keys, including in accordion mode. | `((activeKeys: string[]) => void) | undefined` | `-` |
| accordion | Allow at most one active panel; clicking it again closes it. | `boolean | undefined` | `-` |
| destroyOnHidden | Unmount closed bodies unless the item has forceRender. | `boolean | undefined` | `-` |
| open | Controlled open state. | `boolean | undefined` | `-` |
| defaultOpen | Uncontrolled initial open state. Defaults to `false`. | `boolean | undefined` | `-` |
| disabled | Disable the trigger. Falls back to TaoProvider's `disabled`. | `boolean | undefined` | `-` |
| className | Merged into the root element. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#collapsetrigger)Collapse.Trigger
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| asChild | Render the child element as the trigger instead of a default button. | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#collapsecontent)Collapse.Content
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### CollapseItem
| Property | Description |
| --------------------- | ------------------------------------------------------------------ |
| `key` | Unique string / number key; callbacks normalize it to a string |
| `label / children` | Header label and panel body |
| `extra` | Independent header actions |
| `collapsible` | header / icon / disabled |
| `showArrow` | Defaults to true; false cannot be combined with collapsible="icon" |
| `forceRender` | Defaults to false; mount early and keep the body mounted |
| `className / style` | Item container styling |
| `classNames / styles` | Semantic header/body styles; item styles override group values |
---
url: https://rickyshin93.github.io/tao-ui/components/descriptions.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Descriptions
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays labelled fields in a structured record view.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Items, responsive columns and spans follow 6.7.0. The default columns adapt from one on phones to three on desktop, using tao-ui breakpoints.
## When to use
Use for read-only account, order or configuration details.
## Examples
### Basic record
```tsx preview
import { Descriptions } from "@rockshin/tao-ui";
const items = [
{ key: "name", label: "Name", children: "Ada Lovelace" },
{ key: "plan", label: "Plan", children: "Team" },
{ key: "region", label: "Region", children: "London" },
{ key: "status", label: "Status", children: "Active" },
];
export default function Example() {
return ;
}
```
### Bordered and compact
```tsx preview
import { Descriptions } from "@rockshin/tao-ui";
const items = [
{ key: "name", label: "Name", children: "Ada Lovelace" },
{ key: "plan", label: "Plan", children: "Team" },
{ key: "region", label: "Region", children: "London" },
{ key: "status", label: "Status", children: "Active" },
];
export default function Example() {
return (
);
}
```
### Vertical fields
```tsx preview
import { Descriptions } from "@rockshin/tao-ui";
const items = [
{ key: "name", label: "Name", children: "Ada Lovelace" },
{ key: "plan", label: "Plan", children: "Team" },
{ key: "region", label: "Region", children: "London" },
{ key: "status", label: "Status", children: "Active" },
];
export default function Example() {
return (
);
}
```
### Spans and remaining space
```tsx preview="iframe-follow"
import { Descriptions } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Responsive columns
```tsx preview="iframe-follow"
import { Descriptions } from "@rockshin/tao-ui";
const items = [
{ key: "name", label: "Name", children: "Ada Lovelace" },
{ key: "plan", label: "Plan", children: "Team" },
{ key: "region", label: "Region", children: "London" },
{ key: "status", label: "Status", children: "Active" },
];
export default function Example() {
return (
);
}
```
### Actions and semantic styling
```tsx preview
import { useState } from "react";
import { Button, Descriptions } from "@rockshin/tao-ui";
const items = [
{ key: "name", label: "Name", children: "Ada Lovelace" },
{ key: "plan", label: "Plan", children: "Team" },
{ key: "region", label: "Region", children: "London" },
{ key: "status", label: "Status", children: "Active" },
];
export default function Example() {
const [editing, setEditing] = useState(false);
return (
setEditing(!editing)}>
{editing ? "Show less" : "Show all"}
}
items={editing ? items : items.slice(0, 2)}
styles={{
label: { color: "var(--tao-color-text-secondary)" },
content: { fontWeight: 600 },
}}
/>
);
}
```
## API
### [#](#descriptions)Descriptions
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/empty.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Empty
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Explains why a collection has no content and provides a useful next action.
## When to use
Use inside lists, search results and compact panels when no records are available. Keep the explanation specific to the current view.
## Examples
### Default and simple illustrations
Use the simple illustration in compact content areas.
```tsx preview="iframe-follow"
import { Empty, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Create the first item
The footer can contain an action. This example creates an item only in local React state.
```tsx preview
import { useState } from 'react';
import { Button, Empty } from '@rockshin/tao-ui';
export default function Example() {
const [created, setCreated] = useState(false);
return created ? (
Project Atlas is ready.
setCreated(false)}>
Reset
) : (
setCreated(true)}>Create project
);
}
```
### Custom illustration
Pass a React node to image and adjust its container through styles.image.
```tsx preview
import { Empty } from '@rockshin/tao-ui';
export default function Example() {
return (
}
description="The archive is empty"
styles={{ image: { height: 72, color: 'var(--tao-primary)' } }}
/>
);
}
```
### Provider language
Omitting description uses TaoProvider locale.emptyDescription. An explicit description takes priority.
```tsx preview
import { Empty, Stack, TaoProvider, enUS, zhCN } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Compact and image-only states
Set description to false to hide it. Keep a visible explanation elsewhere in the surrounding interface.
```tsx preview
import { Empty } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#empty)Empty
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| imageStyle | @deprecated Use styles.image. | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/image.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Image
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Images with full-screen preview, grouped navigation, zoom and rotation, fallbacks and progress placeholders.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
## Examples
### Preview an image
Click the image or focus it and press Enter. Escape closes the preview and restores focus.
```tsx preview="iframe-follow"
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function BasicImage() {
return (
);
}
```
### Browse an image group
PreviewGroup registers its children and supports previous/next navigation with buttons or arrow keys.
```tsx preview="iframe-follow"
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ImageGallery() {
return (
);
}
```
### Open a controlled preview
Control open and onOpenChange to launch the preview from another action.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ControlledPreview() {
const [open, setOpen] = useState(false);
return (
setOpen(true)}>Open original
);
}
```
### Fallback and thumbnail-only mode
fallback is shown after the source fails. preview:false keeps the image non-interactive.
```tsx preview
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ImageFallback() {
return (
);
}
```
### Progress placeholder
The progress value belongs to the application. This example controls it with a range input and shows the image at 100%.
```tsx preview
import { useState } from 'react';
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ImageProgress() {
const [percent, setPercent] = useState(45);
return (
Progress{' '}
setPercent(Number(event.target.value))}
/>
);
}
```
### Custom cover and styles
Customize the hover cover and image slot without changing the preview behavior.
```tsx preview="iframe-follow"
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ImageCover() {
return (
);
}
```
### Custom preview actions
actionsRender receives the existing toolbar and transform actions. This example adds Reset.
```tsx preview="iframe-follow"
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function ImageActions() {
return (
(
<>
{actions}
Reset
>
),
}}
/>
);
}
```
### Preview on a phone
The full-screen preview reserves space for actions and safe-area padding. Use the phone shell to check fit and navigation.
```tsx preview="iframe-follow"
import { Image } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function MobileGallery() {
return (
);
}
```
## API
### [#](#imagepreviewgroup)ImagePreviewGroup
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
### [#](#image)Image
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/list.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# List
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays repeated records with metadata, actions, pagination or a responsive grid.
## When to use
Use for content that needs more structure than plain text but fewer aligned columns than a table. Use Listy when you need explicit virtual scrolling.
## Examples
### Metadata and avatars
List.Item.Meta composes an avatar, title and description.
```tsx preview="iframe-follow"
import { Avatar, List } from '@rockshin/tao-ui';
const people = [
{ id: 'a', name: 'Alex Chen', role: 'Design lead' },
{ id: 'b', name: 'Morgan Lee', role: 'Frontend engineer' },
{ id: 'c', name: 'Sam Rivera', role: 'Product manager' },
];
export default function Example() {
return (
(
{person.name[0]}}
title={person.name}
description={person.role}
/>
)}
/>
);
}
```
### Vertical content and actions
Use itemLayout="vertical" for article-like content. extra is a separate supporting region.
```tsx preview
import { useState } from 'react';
import { Button, List, Tag } from '@rockshin/tao-ui';
export default function Example() {
const [saved, setSaved] = useState(false);
return (
Guide}
actions={[
setSaved((value) => !value)}
>
{saved ? 'Saved' : 'Save article'}
,
]}
>
Keep actions close to the information they affect, and use a
consistent visual hierarchy.
);
}
```
### Pagination and page size
List slices dataSource for the current page. For server paging, pass the page records and total explicitly.
```tsx preview
import { List } from '@rockshin/tao-ui';
const records = Array.from({ length: 24 }, (_, index) => ({
id: index,
title: `Release note ${index + 1}`,
}));
export default function Example() {
return (
`${total} notes`,
}}
renderItem={(item) => {item.title} }
/>
);
}
```
### Responsive grid
The grid changes from one column on a phone to three columns on larger viewports.
```tsx preview="iframe-follow"
import { Card, List } from '@rockshin/tao-ui';
const records = [
'Research',
'Design',
'Engineering',
'Content',
'Operations',
'Support',
];
export default function Example() {
return (
(
Workspace team
)}
/>
);
}
```
### Loading, empty and load more
This demo appends local records. Use loading for real requests and locale.emptyText for an application-specific empty state.
```tsx preview
import { useState } from 'react';
import { Button, Empty, List, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [count, setCount] = useState(0);
const [loading, setLoading] = useState(false);
return (
setLoading((value) => !value)}>
{loading ? 'Hide loading' : 'Show loading'}
`Activity ${index + 1}`,
)}
locale={{
emptyText: (
),
}}
loadMore={
setCount((value) => value + 3)}
>
Add three records
}
renderItem={(item) => {item} }
/>
);
}
```
### Compact rows and semantic styles
Disable split to remove row separators and customize header/footer regions independently.
```tsx preview
import { List } from '@rockshin/tao-ui';
export default function Example() {
return (
{item} }
/>
);
}
```
## API
### [#](#list)List
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/listy.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Listy
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Renders scrollable item collections with grouping and optional virtualization.
## When to use
Use for long scrollable collections. The data prop is items, each item needs a stable rowKey, and itemRender defines the row. Selection belongs to your row controls.
## Examples
### Basic items
Virtualization is off by default. Set height to create a bounded scrolling region.
```tsx preview="iframe-follow"
import { Listy } from '@rockshin/tao-ui';
const items = Array.from({ length: 60 }, (_, index) => ({
id: `item-${index}`,
name: `Record ${index + 1}`,
team: index < 20 ? 'Design' : index < 40 ? 'Engineering' : 'Operations',
}));
export default function Example() {
return (
(
{item.name} · {item.team}
)}
/>
);
}
```
### One thousand virtual rows
virtual renders the visible window instead of mounting every row at once.
```tsx preview
import { Listy } from '@rockshin/tao-ui';
const items = Array.from({ length: 1000 }, (_, index) => ({
id: index,
label: `Activity ${index + 1}`,
}));
export default function Example() {
return (
(
{item.label} · row {index + 1}
)}
/>
);
}
```
### Grouped rows and sticky headings
group.key chooses a group; group.title renders its header. sticky keeps the current heading visible inside this list.
```tsx preview
import { Listy } from '@rockshin/tao-ui';
const items = Array.from({ length: 60 }, (_, index) => ({
id: `item-${index}`,
name: `Record ${index + 1}`,
team: index < 20 ? 'Design' : index < 40 ? 'Engineering' : 'Operations',
}));
export default function Example() {
return (
item.team,
title: (team, records) => `${team} (${records.length})`,
}}
itemRender={(item) => item.name}
/>
);
}
```
### Scroll to a record or group
The ref accepts an item key, group key, numeric offset or a coordinate object.
```tsx preview
import { useRef } from 'react';
import { Button, Listy, Stack } from '@rockshin/tao-ui';
import type { ListyRef } from '@rockshin/tao-ui';
const items = Array.from({ length: 60 }, (_, index) => ({
id: `item-${index}`,
name: `Record ${index + 1}`,
team: index < 20 ? 'Design' : index < 40 ? 'Engineering' : 'Operations',
}));
export default function Example() {
const ref = useRef(null);
return (
ref.current?.scrollTo({ key: 'item-45', align: 'top' })
}
>
Record 46
ref.current?.scrollTo({ groupKey: 'Engineering', align: 'top' })
}
>
Engineering
ref.current?.scrollTo(0)}>
Top
item.team, title: (team) => team }}
itemRender={(item) => item.name}
/>
);
}
```
### Wide content and RTL
scrollWidth enables horizontal scrolling for rows wider than the viewport. Toggle direction to inspect RTL behavior.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Listy, Stack } from '@rockshin/tao-ui';
const items = Array.from({ length: 60 }, (_, index) => ({
id: `item-${index}`,
name: `Record ${index + 1}`,
team: index < 20 ? 'Design' : index < 40 ? 'Engineering' : 'Operations',
}));
export default function Example() {
const [rtl, setRtl] = useState(false);
return (
setRtl((value) => !value)}>
{rtl ? 'Use LTR' : 'Use RTL'}
(
{item.name}
{item.team}
Updated today
)}
/>
);
}
```
### Scroll events and semantic styles
onScroll exposes the scrolling element. rowHoverable controls row highlighting.
```tsx preview
import { useState } from 'react';
import { Listy, Stack } from '@rockshin/tao-ui';
const items = Array.from({ length: 60 }, (_, index) => ({
id: `item-${index}`,
name: `Record ${index + 1}`,
team: index < 20 ? 'Design' : index < 40 ? 'Engineering' : 'Operations',
}));
export default function Example() {
const [offset, setOffset] = useState(0);
return (
Scroll offset: {Math.round(offset)} px
setOffset(event.currentTarget.scrollTop)}
styles={{ root: { borderRadius: 12 }, item: { paddingInline: 20 } }}
itemRender={(item) => item.name}
/>
);
}
```
## API
### [#](#listy)Listy
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/masonry.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Masonry
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Arranges cards of different heights into balanced columns.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
The 6.7.0 items/itemRender contract supports responsive columns and fresh resize tracking. Layout uses native positioning; DOM order remains the input order.
## When to use
Use for galleries or varied content cards where row alignment is unnecessary.
## Examples
### Balanced columns
```tsx preview
import { Masonry } from "@rockshin/tao-ui";
const items = [100, 160, 80, 130, 90, 150].map((height, key) => ({
key,
height,
data: { title: `Tile ${key + 1}` },
}));
export default function Example() {
return (
(
{data.title}
)}
/>
);
}
```
### Responsive columns and gutters
```tsx preview="iframe-follow"
import { Masonry } from "@rockshin/tao-ui";
const items = [100, 160, 80, 130, 90, 150].map((height, key) => ({
key,
height,
data: { title: `Tile ${key + 1}` },
}));
export default function Example() {
return (
(
{data.title}
)}
/>
);
}
```
### Assign a column
```tsx preview
import { Masonry } from "@rockshin/tao-ui";
const items = [100, 160, 80, 130, 90, 150].map((height, key) => ({
key,
height,
data: { title: `Tile ${key + 1}` },
}));
export default function Example() {
return (
({
...item,
column: index === 0 ? 2 : undefined,
}))}
itemRender={({ data }) => (
{data.title}
)}
/>
);
}
```
### Track changing content heights
```tsx preview="iframe-follow"
import { useState } from "react";
import { Button, Masonry } from "@rockshin/tao-ui";
export default function Example() {
const [expanded, setExpanded] = useState(false);
return (
setExpanded(!expanded)}
style={{ marginBottom: 16 }}
>
Toggle details
Details
{expanded ? (
A longer description changes the card height and the
following cards are positioned again.
) : (
Short summary.
)}
),
},
...[2, 3, 4].map((key) => ({
key,
data: key,
height: 80 + key * 12,
children: (
Card {key}
),
})),
]}
/>
);
}
```
### Reorder and inspect layout
```tsx preview
import { useState } from "react";
import { Button, Masonry } from "@rockshin/tao-ui";
const items = [100, 160, 80, 130, 90, 150].map((height, key) => ({
key,
height,
data: { title: `Tile ${key + 1}` },
}));
export default function Example() {
const [reversed, setReversed] = useState(false);
const [columns, setColumns] = useState("");
return (
setReversed(!reversed)}
style={{ marginBottom: 16 }}
>
Reverse items
setColumns(
order.map((item) => `${item.key} → ${item.column + 1}`).join(", "),
)
}
itemRender={({ data }) => (
{data.title}
)}
/>
Item → column: {columns}
);
}
```
## API
### [#](#masonry)Masonry
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/popover.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Popover
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays a floating card with rich content anchored to a trigger element, opened by click or hover.
## When to use
Use Popover for rich, non-blocking contextual content behind a click or hover. Use Tooltip for short text-only hints and Modal for blocking interactions.
**Recommended**
- Keep the title to one short line; put detail in the content.
- Use the default hover trigger for read-only previews and trigger="click" for interactive content.
- Keep popup content compact; link out for long-form detail.
**Avoid**
- Do not nest essential workflows inside a hover-only popover.
- Do not chain popovers from inside another popover.
## Examples
### Basic usage
```tsx preview
import { Button, Popover } from '@rockshin/tao-ui';
function PopoverExample() {
return (
View status
);
}
export default PopoverExample;
```
### Hover, focus, and click
```tsx preview
import { Button, Popover, Stack } from '@rockshin/tao-ui';
function PopoverTriggers() {
return (
Hover
Focus
Click
);
}
export default PopoverTriggers;
```
### Placement and arrow
```tsx preview
import { Button, Popover, Stack } from '@rockshin/tao-ui';
function PopoverPlacements() {
return (
Top left
Bottom
Right
);
}
export default PopoverPlacements;
```
### Controlled popup and internal dismissal
An action inside the popup can update open and dismiss it after completion.
```tsx preview
import { useState } from 'react';
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
return (
setOpen(false)}>Done}
>
Open actions
);
}
```
### Focus trigger
Use trigger=focus for keyboard hints and keep essential instructions visible on the page.
```tsx preview
import { Popover, Input } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Arrow and delay
Hover delays use seconds, and arrow controls the pointer.
```tsx preview
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Hover for details
);
}
```
### Form content
A popup can contain input and actions; submit, report the result, and close it.
```tsx preview
import { useState } from 'react';
import { Popover, Input, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
const [name, setName] = useState('Workspace');
return (
{
e.preventDefault();
setName(String(new FormData(e.currentTarget).get('name')));
setOpen(false);
}}
>
Save name
}
>
Rename project
{name}
);
}
```
## API
### [#](#popover)Popover
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| title | Header content of the popup. | `PopoverRender` | `-` |
| content | Body content of the popup. | `PopoverRender` | `-` |
| trigger | How the popup opens. Defaults to `'hover'`. | `PopoverTrigger | PopoverTrigger[] | undefined` | `hover` |
| placement | Popup position relative to the trigger. Defaults to `'top'`. | `PopoverPlacement | undefined` | `top` |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to `0.1`. | `number | undefined` | `0.1` |
| mouseLeaveDelay | Hover delay in seconds before closing. Defaults to `0.1`. | `number | undefined` | `0.1` |
| arrow | Show a pointing arrow on the popup. Defaults to `true`. | `boolean | { pointAtCenter?: boolean | undefined; } | undefined` | `true` |
| destroyOnHidden | Unmount the popup content while closed. Defaults to `false`. | `boolean | undefined` | `-` |
| destroyTooltipOnHide | @deprecated Use `destroyOnHidden` instead. | `boolean | undefined` | `-` |
| className | Merged onto the popup root. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(Required)** | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/qr-code.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# QRCode
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Generate scannable Canvas or SVG QR codes with icons, status and refresh controls.
The added API follows Ant Design 6.7.0; appearance, theming and Semantic DOM use tao-ui. Existing component APIs remain unchanged.
## Examples
### Canvas and SVG
Canvas supports bitmap export; SVG scales without losing detail.
```tsx preview
import { QRCode, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Dynamic value
The code re-encodes when the value changes. Empty strings render no code.
```tsx preview
import { QRCode, Input, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [value, setValue] = useState('tao-ui');
return (
setValue(event.target.value)}
aria-label="QR content"
/>
);
}
```
### Error correction
L, M, Q and H provide different recovery levels. Center icons usually need a higher level.
```tsx preview
import { QRCode, Stack } from '@rockshin/tao-ui';
export default function Demo() {
return (
{(['L', 'M', 'Q', 'H'] as const).map((level) => (
))}
);
}
```
### Status and refresh
Expired codes show a refresh action. Loading and scanned states also cover the code.
```tsx preview
import { QRCode, Stack, Button, type QRStatus } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [status, setStatus] = useState('expired');
return (
setStatus('active')}
/>
{(['active', 'expired', 'loading', 'scanned'] as const).map((next) => (
setStatus(next)}
>
{next}
))}
);
}
```
### Colors and quiet zone
Keep high contrast. marginSize reserves the quiet zone in QR modules.
```tsx preview
import { QRCode } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
### Center icon
iconSize accepts one size or separate dimensions. A data URL avoids an external request.
```tsx preview
import { QRCode } from '@rockshin/tao-ui';
const icon =
'data:image/svg+xml,' +
encodeURIComponent(
' ',
);
export default function Demo() {
return (
);
}
```
### Download PNG
Use the public ref to export the canvas. Cross-origin icons require a suitable CORS response.
```tsx preview
import { QRCode, Button, Stack, type QRCodeRef } from '@rockshin/tao-ui';
import { useRef } from 'react';
export default function Demo() {
const ref = useRef(null);
return (
{
const canvas = ref.current!.nativeElement.querySelector('canvas')!;
const link = document.createElement('a');
link.download = 'tao-ui-qr.png';
link.href = canvas.toDataURL('image/png');
link.click();
}}
>
Download PNG
);
}
```
### Custom status
statusRender receives status, translated text and the refresh callback.
```tsx preview
import { QRCode, Button } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function Demo() {
const [expired, setExpired] = useState(true);
return (
setExpired(false)}
statusRender={({ onRefresh }) => (
Generate again
)}
/>
);
}
```
### Phone and locale
size controls dimensions; status text follows the provider locale.
```tsx preview="iframe-follow"
import { QRCode, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Demo() {
return (
);
}
```
## API
### [#](#qrcode)QRCode
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/scroll-area.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# ScrollArea
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Provides a styled scroll container for overflow content.
## When to use
Use ScrollArea when a fixed region needs overflow behavior without changing page scroll.
**Recommended**
- Constrain height explicitly.
- Avoid hiding important actions below a small scroll region.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';
function ScrollAreaExample() {
return (
{Array.from({ length: 12 }, (_, index) => (
Activity item {index + 1}
))}
);
}
export default ScrollAreaExample;
```
### Horizontal and two-axis scrolling
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';
function ScrollDirections() {
return (
A long horizontal timeline that remains inside its own scroll area.
Content that can scroll on both axes.
);
}
export default ScrollDirections;
```
### Persistent scrollbars and custom size
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';
function ScrollbarStyles() {
const content = Array.from({ length: 10 }, (_, index) => (
Scrollable row {index + 1}
));
return (
{content}
{content}
);
}
export default ScrollbarStyles;
```
### Horizontal scrolling
Constrain the available width and use the appropriate scrollbar orientation for horizontal content.
```tsx preview
import { ScrollArea, Tag } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaHorizontal() {
return (
{items.slice(0, 20).map((item) => (
{item}
))}
);
}
```
### Both axes
Scroll each axis when content exceeds both dimensions without widening the page.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaBoth() {
return (
{items.map((item) => (
{item} — This is a long line that overflows the container
horizontally to demonstrate both scrollbars.
))}
);
}
```
### Persistent scrollbars
`type="always"` retains the scrollbar track when scrollability should be more visible.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaAlwaysVisible() {
return (
{items.map((item) => (
{item}
))}
);
}
```
### Scroll edge shadows
Edge shadows indicate hidden content and disappear when that edge is reached.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaWithShadow() {
return (
{items.map((item) => (
{item}
))}
);
}
```
### Scrollbar size
Adjust scrollbar thickness while keeping the content area bounded.
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaCustomSize() {
return (
Thin (4px)
{items.slice(0, 30).map((item) => (
{item}
))}
Thick (10px)
{items.slice(0, 30).map((item) => (
{item}
))}
);
}
```
### Horizontal edge shadows
Use side shadows to indicate additional content while scrolling horizontally.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';
const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
export default function ScrollAreaHorizontalShadow() {
return (
{items.slice(0, 30).map((item) => (
{item}
))}
);
}
```
## API
### [#](#scrollarea)ScrollArea
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| type | Scrollbar visibility behavior | `ScrollAreaType | undefined` | `hover` |
| direction | Scroll direction | `"vertical" | "horizontal" | "both" | undefined` | `vertical` |
| maxHeight | Max height — enables vertical scroll | `string | number | undefined` | `-` |
| maxWidth | Max width — enables horizontal scroll | `string | number | undefined` | `-` |
| scrollbarSize | Scrollbar size in px | `number | undefined` | `6` |
| scrollbarOffset | Offset from edges in px | `number | undefined` | `2` |
| scrollShadow | Show scroll shadows at edges | `boolean | undefined` | `-` |
| onScroll | Callback on scroll | `((e: UIEvent) => void) | undefined` | `-` |
| onScrollEnd | Callback when scrolled to bottom (threshold in px) | `(() => void) | undefined` | `-` |
| scrollEndThreshold | Threshold in px for onScrollEnd | `number | undefined` | `10` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/statistic.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Statistic
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Highlights numeric values, formatted metrics and elapsed time.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
Numeric strings preserve large values; precision truncates decimal digits. Timer supports countdown/countup and the legacy Countdown alias.
## When to use
Use a clear title and unit so the value can be understood without surrounding context.
## Examples
### Values and units
```tsx preview
import { Statistic } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Precision and separators
```tsx preview
import { Statistic } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
### Custom formatting and value render
```tsx preview
import { Statistic } from "@rockshin/tao-ui";
export default function Example() {
return (
`${(Number(value) / 1024).toFixed(1)} GB`}
valueRender={(node) => {node} }
styles={{ value: { color: "var(--tao-color-success)" } }}
/>
);
}
```
### Loading state
```tsx preview
import { useState } from "react";
import { Button, Statistic } from "@rockshin/tao-ui";
export default function Example() {
const [loading, setLoading] = useState(true);
return (
setLoading(!loading)} style={{ marginTop: 16 }}>
Toggle loading
);
}
```
### Countdown with completion
```tsx preview
import { useState } from "react";
import { Button, Statistic } from "@rockshin/tao-ui";
export default function Example() {
const [deadline, setDeadline] = useState(() => Date.now() + 10000);
const [finished, setFinished] = useState(false);
return (
setFinished(true)}
/>
{finished ? "Finished" : "Running"}
{
setDeadline(Date.now() + 10000);
setFinished(false);
}}
>
Restart 10 seconds
);
}
```
### Elapsed time
```tsx preview
import { useState } from "react";
import { Statistic } from "@rockshin/tao-ui";
export default function Example() {
const [startedAt] = useState(() => Date.now() - 65000);
return (
);
}
```
## Regional formatting
Regional grouping, decimal symbols and digits inherit `TaoProvider.locale.numberLocale`; set `locale="fr-FR"` on this component to override it. Explicit separators and custom formatters take precedence. Numeric input keeps canonical ASCII strings and precision while displaying localized digits.
## API
### [#](#statistic)Statistic
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/table.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Table
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays structured row and column data with selection, sorting, filtering, and pagination hooks.
## When to use
Use Table for dense, comparable records that benefit from aligned columns.
**Recommended**
- Keep columns focused on the task.
- Use stable row keys.
- Control sorting and pagination when data is remote.
- Gate secondary columns with column.responsive (e.g. \['lg']) instead of hand-rolled media queries.
**Avoid**
- Do not use Table for card-like content where comparison is not important.
## Examples
### Basic usage
```tsx preview
import { Table } from '@rockshin/tao-ui';
const columns = [
{ key: 'name', dataIndex: 'name' as const, title: 'Name' },
{ key: 'role', dataIndex: 'role' as const, title: 'Role' },
];
const users = [
{ id: 1, name: 'Ada Lovelace', role: 'Engineer' },
{ id: 2, name: 'Grace Hopper', role: 'Scientist' },
];
function TableExample() {
return (
);
}
export default TableExample;
```
### Variants
```tsx preview
import { Stack, Table } from '@rockshin/tao-ui';
const columns = [
{ key: 'name', dataIndex: 'name' as const, title: 'Name' },
{ key: 'role', dataIndex: 'role' as const, title: 'Role' },
];
const data = [
{ id: 1, name: 'Ada', role: 'Engineer' },
{ id: 2, name: 'Grace', role: 'Scientist' },
];
function TableVariants() {
return (
);
}
export default TableVariants;
```
### Sizes and borders
```tsx preview
import { Stack, Table } from '@rockshin/tao-ui';
const columns = [
{ key: 'name', dataIndex: 'name' as const, title: 'Name' },
{ key: 'status', dataIndex: 'status' as const, title: 'Status' },
];
const data = [{ id: 1, name: 'Build', status: 'Passing' }];
function TableSizes() {
return (
);
}
export default TableSizes;
```
### Loading, empty, and pagination
```tsx preview
import { Stack, Table } from '@rockshin/tao-ui';
const columns = [{ key: 'name', dataIndex: 'name' as const, title: 'Name' }];
function TableStates() {
return (
({
id: index,
name: 'User ' + (index + 1),
}))}
rowKey="id"
pagination={{ pageSize: 5 }}
/>
);
}
export default TableStates;
```
### Fixed header, expandable rows, and summary
`scroll.y` caps the body height and pins the header; `expandable` renders details under a row (the expand column sits before the selection column); `summary` returns `Table.Summary.Row` / `Table.Summary.Cell` footer rows — `Cell.index` counts from the expand/selection columns to sync fixed columns, and \`\` pins the footer while the body scrolls.
```tsx preview
import { Table } from '@rockshin/tao-ui';
const data = Array.from({ length: 30 }, (_, index) => ({
id: index + 1,
name: 'User ' + (index + 1),
team: ['Design', 'Engineering', 'Sales'][index % 3],
score: 60 + ((index * 7) % 40),
}));
const columns = [
{
key: 'name',
dataIndex: 'name' as const,
title: 'Name',
width: 160,
fixed: 'left' as const,
},
{ key: 'team', dataIndex: 'team' as const, title: 'Team', width: 240 },
{
key: 'score',
dataIndex: 'score' as const,
title: 'Score',
width: 120,
align: 'right' as const,
},
];
function TableAdvanced() {
return (
record.name + ' works in ' + record.team + '.',
rowExpandable: (record) => record.team !== 'Sales',
}}
summary={(pageData) => (
Total
{pageData.reduce((sum, record) => sum + record.score, 0)}
)}
/>
);
}
export default TableAdvanced;
```
### Sorting
Configure sorting on columns and click a header to switch the sort direction.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableSorting() {
const columns: TableColumn[] = [
{
key: 'name',
dataIndex: 'name',
title: 'Name',
sorter: (a, b) => a.name.localeCompare(b.name),
},
{
key: 'age',
dataIndex: 'age',
title: 'Age',
sorter: (a, b) => a.age - b.age,
defaultSortOrder: 'ascend',
},
{ key: 'role', dataIndex: 'role', title: 'Role' },
];
return ;
}
```
### Column filtering
Provide filter choices and a predicate, then select items in the column menu.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableFiltering() {
const columns: TableColumn[] = [
{ key: 'name', dataIndex: 'name', title: 'Name' },
{ key: 'age', dataIndex: 'age', title: 'Age' },
{
key: 'role',
dataIndex: 'role',
title: 'Role',
filters: [
{ text: 'Admin', value: 'admin' },
{ text: 'Editor', value: 'editor' },
{ text: 'Viewer', value: 'viewer' },
],
onFilter: (value, record) => record.role === value,
},
{
key: 'department',
dataIndex: 'department',
title: 'Department',
filters: [
{ text: 'Engineering', value: 'Engineering' },
{ text: 'Design', value: 'Design' },
{ text: 'Marketing', value: 'Marketing' },
{ text: 'Sales', value: 'Sales' },
],
onFilter: (value, record) => record.department === value,
},
];
return ;
}
```
### Controlled row selection
Use a stable record ID for `rowKey`, such as a database ID. Keep selected keys in `rowSelection.selectedRowKeys` and update them from `rowSelection.onChange`.
Return `{ disabled: true }` from `rowSelection.getCheckboxProps(record)` for rows that cannot be selected. The header checkbox applies to eligible rows on the current page and preserves selection on other pages. Since [0.0.49](https://rickyshin93.github.io/tao-ui/guide/changelog.md), Table also uses the current disabled state when rows change and the callback stays the same.
```tsx preview
import { Stack, Table, type TableColumn } from '@rockshin/tao-ui';
import { useState } from 'react';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
const baseColumns: TableColumn[] = [
{ key: 'id', dataIndex: 'id', title: 'ID', width: 60, align: 'center' },
{ key: 'name', dataIndex: 'name', title: 'Name' },
{ key: 'age', dataIndex: 'age', title: 'Age', width: 80 },
{ key: 'email', dataIndex: 'email', title: 'Email' },
{ key: 'role', dataIndex: 'role', title: 'Role' },
];
export default function TableRowSelection() {
function Demo() {
const [selectedKeys, setSelectedKeys] = useState([]);
return (
Selected:{' '}
{selectedKeys.length === 0 ? 'none' : selectedKeys.join(', ')}
setSelectedKeys(keys),
getCheckboxProps: (record) => ({
disabled: record.role === 'viewer',
}),
}}
/>
);
}
return ;
}
```
### Horizontal scrolling and fixed columns
Combine column widths with `scroll.x`; fixed columns preserve context while scrolling.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableHorizontalScroll() {
const columns: TableColumn[] = [
{ key: 'id', dataIndex: 'id', title: 'ID', width: 80, fixed: 'left' },
{
key: 'name',
dataIndex: 'name',
title: 'Name',
width: 150,
fixed: 'left',
},
{ key: 'age', dataIndex: 'age', title: 'Age', width: 100 },
{ key: 'email', dataIndex: 'email', title: 'Email', width: 250 },
{ key: 'role', dataIndex: 'role', title: 'Role', width: 120 },
{
key: 'department',
dataIndex: 'department',
title: 'Department',
width: 150,
},
{
key: 'actions',
title: 'Actions',
width: 120,
fixed: 'right',
render: () => (
Edit
),
},
];
return (
);
}
```
### Fixed header
`scroll.y` creates a bounded scrolling body while retaining the table header.
```tsx preview
import { Stack, Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableFixedHeader() {
const columns: TableColumn[] = [
{ key: 'id', dataIndex: 'id', title: 'ID', width: 80, fixed: 'left' },
{ key: 'name', dataIndex: 'name', title: 'Name', width: 150 },
{ key: 'age', dataIndex: 'age', title: 'Age', width: 100 },
{ key: 'email', dataIndex: 'email', title: 'Email', width: 250 },
{ key: 'role', dataIndex: 'role', title: 'Role', width: 120 },
{
key: 'department',
dataIndex: 'department',
title: 'Department',
width: 150,
fixed: 'right',
},
];
return (
{(['modern', 'outlined', 'borderless'] as const).map((variant) => (
))}
);
}
```
### Expandable rows
Expand a record for additional details instead of placing everything in columns.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
const baseColumns: TableColumn[] = [
{ key: 'id', dataIndex: 'id', title: 'ID', width: 60, align: 'center' },
{ key: 'name', dataIndex: 'name', title: 'Name' },
{ key: 'age', dataIndex: 'age', title: 'Age', width: 80 },
{ key: 'email', dataIndex: 'email', title: 'Email' },
{ key: 'role', dataIndex: 'role', title: 'Role' },
];
export default function TableExpandable() {
return (
`${record.name} works in ${record.department} as ${record.role}.`,
rowExpandable: (record) => record.role !== 'viewer',
defaultExpandedRowKeys: [1],
}}
/>
);
}
```
### Expansion with scrolling
Combine expandable detail with a fixed body height and inspect scrolling and alignment.
```tsx preview
import { Table } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableExpandableWithScroll() {
return (
`${record.name} works in ${record.department} as ${record.role}; this text stays inside the visible area while the table scrolls sideways.`,
defaultExpandedRowKeys: [2],
}}
/>
);
}
```
### Summary rows
Render totals with `Table.Summary` and align summary cells with table columns.
```tsx preview
import { Table } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableSummary() {
return (
(
Total
{pageData.length} people
{pageData.reduce((sum, user) => sum + user.age, 0)}
)}
/>
);
}
```
### Custom pagination
Control pagination in application state when working with server totals and page data.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
const baseColumns: TableColumn[] = [
{ key: 'id', dataIndex: 'id', title: 'ID', width: 60, align: 'center' },
{ key: 'name', dataIndex: 'name', title: 'Name' },
{ key: 'age', dataIndex: 'age', title: 'Age', width: 80 },
{ key: 'email', dataIndex: 'email', title: 'Email' },
{ key: 'role', dataIndex: 'role', title: 'Role' },
];
export default function TableCustomPagination() {
return (
`${s}-${e} of ${total} users`,
}}
/>
);
}
```
### Combined features
Combine sorting, filtering, and selection and observe how they affect the current data.
```tsx preview
import { Table, type TableColumn } from '@rockshin/tao-ui';
import { useState } from 'react';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableFullFeature() {
function Demo() {
const [selectedKeys, setSelectedKeys] = useState([]);
const columns: TableColumn[] = [
{
key: 'id',
dataIndex: 'id',
title: 'ID',
width: 60,
align: 'center',
fixed: 'left',
},
{
key: 'name',
dataIndex: 'name',
title: 'Name',
width: 120,
fixed: 'left',
sorter: (a, b) => a.name.localeCompare(b.name),
},
{
key: 'age',
dataIndex: 'age',
title: 'Age',
width: 80,
sorter: (a, b) => a.age - b.age,
},
{
key: 'email',
dataIndex: 'email',
title: 'Email',
width: 220,
ellipsis: true,
},
{
key: 'role',
dataIndex: 'role',
title: 'Role',
width: 120,
filters: [
{ text: 'Admin', value: 'admin' },
{ text: 'Editor', value: 'editor' },
{ text: 'Viewer', value: 'viewer' },
],
onFilter: (value, record) => record.role === value,
},
{
key: 'department',
dataIndex: 'department',
title: 'Dept',
width: 140,
filters: [
{ text: 'Engineering', value: 'Engineering' },
{ text: 'Design', value: 'Design' },
{ text: 'Marketing', value: 'Marketing' },
{ text: 'Sales', value: 'Sales' },
],
onFilter: (value, record) => record.department === value,
},
{
key: 'actions',
title: 'Actions',
width: 100,
fixed: 'right',
render: () => (
Edit
),
},
];
return (
setSelectedKeys(keys),
fixed: true,
}}
pagination={{
pageSize: 10,
showSizeChanger: true,
showTotal: (total) => `${total} users`,
}}
/>
);
}
return ;
}
```
### Responsive columns
Use responsive column settings on smaller screens while retaining identifying fields.
```tsx preview="iframe-follow"
import { Table } from '@rockshin/tao-ui';
interface User {
id: number;
name: string;
age: number;
email: string;
role: string;
department: string;
}
const users: User[] = Array.from({ length: 46 }, (_, i) => ({
id: i + 1,
name: ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank'][
i % 8
],
age: 22 + (i % 20),
email: `user${i + 1}@example.com`,
role: i % 3 === 0 ? 'admin' : i % 3 === 1 ? 'editor' : 'viewer',
department: ['Engineering', 'Design', 'Marketing', 'Sales'][i % 4],
}));
export default function TableResponsiveColumns() {
return (
);
}
```
## API
### [#](#table)Table
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| scroll | `y` caps the body height and keeps the header pinned while it scrolls. | `{ x?: string | number | undefined; y?: string | number | undefined; } | undefined` | `-` |
| summary | Footer rows built from `Table.Summary.Row` / `Table.Summary.Cell`. | `((pageData: T[]) => ReactNode) | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#tablesummary)Table.Summary
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| fixed | Pin the summary to the bottom while the body scrolls (needs `scroll.y`). | `boolean | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tag.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Tag
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays compact labels, statuses, categories, or checkable chips.
## When to use
Use Tag for lightweight metadata or status markers. Use CheckableTag for compact filter choices.
**Recommended**
- Use semantic colors consistently.
- Keep tag text short.
**Avoid**
- Do not encode critical state by color alone.
## Examples
### Basic usage
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
function TagExample() {
return (
Default
Primary
Success
Warning
Error
);
}
export default TagExample;
```
### Variants
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
function TagVariants() {
return (
Filled
Success
Warning
Solid
Success
Error
Outlined
Warning
);
}
export default TagVariants;
```
### Custom colors and closable tags
```tsx preview
import { useState } from 'react';
import { Stack, Tag } from '@rockshin/tao-ui';
function CustomTags() {
const [feedback, setFeedback] = useState('');
return (
<>
Custom teal
Custom ochre
{feedback !== 'closed' && (
setFeedback('closed')}>
Closable
)}
Disabled
{feedback}
>
);
}
export default CustomTags;
```
### Checkable tags
```tsx preview
import { CheckableTag, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function CheckableTags() {
const [selected, setSelected] = useState(['Design']);
return (
{['Design', 'Engineering', 'Research'].map((label) => (
setSelected((items) =>
checked
? [...items, label]
: items.filter((item) => item !== label),
)
}
>
{label}
))}
);
}
export default CheckableTags;
```
### Custom colors
Use custom colors for categories while keeping their meaning in readable text.
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
export default function TagCustomColor() {
return (
Indigo
Pink
Teal
Orange
Violet
Indigo
Pink
Teal
Orange
Violet
Indigo
Pink
Teal
Orange
Violet
);
}
```
### Tags with icons
Icons assist recognition while text retains the full meaning.
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';
export default function TagWithIcon() {
return (
🔥} color="error">
Hot
✅} color="success">
Done
⚡} color="warning">
Fast
🏷️}>Label
);
}
```
### Checkable tags
Use `checked` and its change callback for lightweight category filtering.
```tsx preview
import { CheckableTag, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function TagCheckable() {
function Demo() {
const [selected, setSelected] = useState(['react']);
const options = ['react', 'vue', 'angular', 'svelte', 'solid'];
return (
{options.map((opt) => (
setSelected((prev) =>
checked ? [...prev, opt] : prev.filter((x) => x !== opt),
)
}
>
{opt}
))}
);
}
return ;
}
```
### Disabled tags
Disable selection or removal while retaining the label for reading.
```tsx preview
import { CheckableTag, Stack, Tag } from '@rockshin/tao-ui';
export default function TagDisabled() {
return (
Disabled
Disabled Solid
{}}>
Can't Close
Can't Check
);
}
```
## API
### [#](#tag)Tag
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#tagcheckabletag)Tag.CheckableTag
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#checkabletag)CheckableTag
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/timeline.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Timeline
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Orders events and milestones along a vertical or horizontal rail.
This native tao-ui component follows the public API of Ant Design 6.7.0. Appearance, theme tokens and Semantic DOM customization belong to tao-ui; configure themes with `TaoProvider`.
The 6.7.0 title/content/placement API is supported alongside legacy label/children/position aliases. Numeric titleSpan uses a 24-column proportion.
## When to use
Use for activity history or a sequence of events, not for selecting a current step.
## Examples
### Event history
```tsx preview
import { Timeline } from "@rockshin/tao-ui";
const items = [
{ title: "09:00", content: "Workspace created", color: "green" },
{ title: "09:20", content: "Members invited" },
{ title: "09:45", content: "First task completed" },
];
export default function Example() {
return ;
}
```
### Placement and title width
```tsx preview="iframe-follow"
import { Timeline } from "@rockshin/tao-ui";
const items = [
{ title: "09:00", content: "Workspace created", color: "green" },
{ title: "09:20", content: "Members invited" },
{ title: "09:45", content: "First task completed" },
];
export default function Example() {
return ;
}
```
### Horizontal timeline
```tsx preview="iframe-follow"
import { Timeline } from "@rockshin/tao-ui";
const items = [
{ title: "09:00", content: "Workspace created", color: "green" },
{ title: "09:20", content: "Members invited" },
{ title: "09:45", content: "First task completed" },
];
export default function Example() {
return ;
}
```
### Pending and reverse order
```tsx preview
import { useState } from "react";
import { Button, Timeline } from "@rockshin/tao-ui";
const items = [
{ title: "09:00", content: "Workspace created", color: "green" },
{ title: "09:20", content: "Members invited" },
{ title: "09:45", content: "First task completed" },
];
export default function Example() {
const [reverse, setReverse] = useState(false);
return (
setReverse(!reverse)} style={{ marginBottom: 16 }}>
Reverse order
);
}
```
### Icons, colors and loading
```tsx preview
import { Timeline } from "@rockshin/tao-ui";
export default function Example() {
return (
✓,
},
{
title: "Review",
content: "Waiting for review",
color: "var(--tao-color-warning)",
},
{ title: "Sync", content: "Synchronizing", loading: true },
]}
/>
);
}
```
### Semantic customization
```tsx preview
import { Timeline } from "@rockshin/tao-ui";
export default function Example() {
return (
);
}
```
## API
### [#](#timeline)Timeline
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/tooltip.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Tooltip
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Shows a brief informational popup when hovering or focusing an element.
## When to use
Use Tooltip for short contextual hints on hover or focus. The popup is portaled and inherits the TaoProvider theme.
**Recommended**
- Keep tooltip text short and supplementary.
- Wrap exactly one focusable trigger element.
**Avoid**
- Do not put critical information or interactive content inside a Tooltip.
## Examples
### Basic usage
```tsx preview
import { Button, Tooltip } from '@rockshin/tao-ui';
function TooltipExample() {
return (
Hover or focus
);
}
export default TooltipExample;
```
### Placements
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
function TooltipPlacements() {
return (
Top
Bottom
Left
Right
);
}
export default TooltipPlacements;
```
### Arrow, color, and controlled visibility
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
function TooltipStyles() {
return (
No arrow
Custom color
Focus for a hint
);
}
export default TooltipStyles;
```
### Hide the arrow
Set arrow=false to remove the pointer.
```tsx preview
import { Button, Tooltip } from '@rockshin/tao-ui';
export default function TooltipNoArrow() {
return (
No arrow
);
}
```
### Controlled tooltip
Synchronize visibility through open and onOpenChange.
```tsx preview
import { useState } from 'react';
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
return (
setOpen(!open)}>
{open ? 'Hide hint' : 'Show hint'}
Hint target
);
}
```
### Custom color
color customizes the background; retain readable contrast.
```tsx preview
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
export default function TooltipCustomColor() {
return (
#1677ff
#f76b15
);
}
```
### Hover delays
Delays use seconds; keyboard focus does not wait for a hover delay.
```tsx preview
import { Tooltip, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Hover or focus
);
}
```
### Conditional content
An empty title disables the tooltip so hints only appear when useful.
```tsx preview
import { useState } from 'react';
import { Tooltip, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [enabled, setEnabled] = useState(true);
return (
setEnabled(!enabled)}>
{enabled ? 'Disable hint' : 'Enable hint'}
Hint target
);
}
```
## API
### [#](#tooltip)Tooltip
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| title | Tooltip content. Empty strings, booleans, null and undefined disable it. | `ReactNode` | `-` |
| placement | Popup side relative to the trigger. Defaults to 'top'. | `TooltipPlacement | undefined` | `-` |
| arrow | Show the arrow pointing at the trigger. Defaults to true. | `boolean | undefined` | `-` |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to 0.1. Focus opens immediately. | `number | undefined` | `-` |
| mouseLeaveDelay | Delay in seconds before a pointer-leave closes the tooltip. Defaults to
0.1 (antd parity) — re-entering the trigger or content before the
deadline cancels the close. Esc / focus-blur closes stay immediate. | `number | undefined` | `-` |
| color | Custom content background color. | `string | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(Required)** | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tree.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Tree
Data Display`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Hierarchical data with selection, checkboxes, async children, dragging and virtual scrolling.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
## Examples
### Expand and select
Use stable keys for nodes. Arrow keys navigate the tree; Enter selects the active node.
```tsx preview
import { Tree } from '@rockshin/tao-ui';
const nodes = [
{
key: 'workspace',
title: 'Workspace',
children: [
{
key: 'design',
title: 'Design',
children: [{ key: 'tokens', title: 'tokens.json', isLeaf: true }],
},
{
key: 'engineering',
title: 'Engineering',
children: [{ key: 'readme', title: 'README.md', isLeaf: true }],
},
],
},
];
export default function BasicTree() {
return (
);
}
```
### Controlled checks
Checking a parent includes its enabled descendants. Keep the returned keys in state.
```tsx preview
import { useState, type Key } from 'react';
import { Tree } from '@rockshin/tao-ui';
const nodes = [
{
key: 'workspace',
title: 'Workspace',
children: [
{
key: 'design',
title: 'Design',
children: [{ key: 'tokens', title: 'tokens.json', isLeaf: true }],
},
{
key: 'engineering',
title: 'Engineering',
children: [{ key: 'readme', title: 'README.md', isLeaf: true }],
},
],
},
];
export default function ControlledTree() {
const [checked, setChecked] = useState(['tokens']);
return (
setChecked(Array.isArray(keys) ? keys : keys.checked)
}
/>
Checked: {checked.join(', ') || 'none'}
);
}
```
### Independent and disabled checks
checkStrictly separates parent and child checks. disabled and disableCheckbox have different scopes.
```tsx preview
import { Tree } from '@rockshin/tao-ui';
export default function StrictChecks() {
return (
);
}
```
### Directory tree
DirectoryTree adds folder/file icons and familiar range or modifier-key selection when multiple is enabled.
```tsx preview
import { Tree } from '@rockshin/tao-ui';
const nodes = [
{
key: 'workspace',
title: 'Workspace',
children: [
{
key: 'design',
title: 'Design',
children: [{ key: 'tokens', title: 'tokens.json', isLeaf: true }],
},
{
key: 'engineering',
title: 'Engineering',
children: [{ key: 'readme', title: 'README.md', isLeaf: true }],
},
],
},
];
export default function FileBrowser() {
return (
);
}
```
### Custom titles and semantics
titleRender decorates content without changing node keys. Semantic styles target the real title slot.
```tsx preview
import { Tree, type DataNode } from '@rockshin/tao-ui';
const nodes: DataNode[] = [
{
key: 'workspace',
title: 'Workspace',
children: [
{
key: 'design',
title: 'Design',
children: [{ key: 'tokens', title: 'tokens.json', isLeaf: true }],
},
{
key: 'engineering',
title: 'Engineering',
children: [{ key: 'readme', title: 'README.md', isLeaf: true }],
},
],
},
];
export default function CustomTitles() {
return (
(
{node.title as string}
{node.isLeaf && (
file
)}
)}
styles={{ itemTitle: { fontWeight: 500 } }}
/>
);
}
```
### Load children on demand
This local example simulates a delayed result. Resolve loadData after updating the parent node.
```tsx preview
import { useState } from 'react';
import { Tree, type DataNode } from '@rockshin/tao-ui';
export default function AsyncTree() {
const [nodes, setNodes] = useState([
{ key: 'reports', title: 'Reports' },
]);
return (
{
if (node.children) return;
await new Promise((resolve) => setTimeout(resolve, 500));
setNodes([
{
key: 'reports',
title: 'Reports',
children: [
{ key: 'annual', title: 'Annual report', isLeaf: true },
{ key: 'monthly', title: 'Monthly report', isLeaf: true },
],
},
]);
}}
/>
);
}
```
### Virtual list and scrollTo
A bounded height enables virtual rendering. The ref scrolls to a key even when its row is outside the viewport.
```tsx preview
import { useRef } from 'react';
import { Button, Tree, type TreeRef } from '@rockshin/tao-ui';
const nodes = Array.from({ length: 500 }, (_, index) => ({
key: `row-${index}`,
title: `Document ${index + 1}`,
}));
export default function VirtualTree() {
const ref = useRef(null);
return (
ref.current?.scrollTo({ key: 'row-399', align: 'top' })}
>
Jump to document 400
);
}
```
### Reorder a flat tree
This example allows drops between rows and stores the new order. Nested moves can use the same onDrop contract.
```tsx preview
import { useState } from 'react';
import { Tree } from '@rockshin/tao-ui';
export default function ReorderTree() {
const [nodes, setNodes] = useState(
['Inbox', 'In review', 'Published'].map((title) => ({ key: title, title })),
);
return (
dropPosition !== 0}
onDrop={(info) => {
const moving = nodes.find((node) => node.key === info.dragNode.key)!;
const next = nodes.filter((node) => node.key !== moving.key);
const at = next.findIndex((node) => node.key === info.node.key);
const offset =
info.dropPosition - Number(info.node.pos.split('-').at(-1));
next.splice(at + (offset > 0 ? 1 : 0), 0, moving);
setNodes(next);
}}
/>
);
}
```
### Tree in a narrow pane
Use the phone preview to expand and check nodes within a bounded scroller.
```tsx preview="iframe-follow"
import { Tree } from '@rockshin/tao-ui';
const nodes = [
{
key: 'workspace',
title: 'Workspace',
children: [
{
key: 'design',
title: 'Design',
children: [{ key: 'tokens', title: 'tokens.json', isLeaf: true }],
},
{
key: 'engineering',
title: 'Engineering',
children: [{ key: 'readme', title: 'README.md', isLeaf: true }],
},
],
},
];
export default function MobileTree() {
return (
Project access
);
}
```
## API
### [#](#basicdatanode)BasicDataNode
**For fieldNames, we provides a abstract interface**
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
### [#](#directorytree)DirectoryTree
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| rootStyle | @deprecated Use styles.root. | `CSSProperties | undefined` | `-` |
| filterAntTreeNode | @deprecated Use filterTreeNode. | `((treeNode: EventDataNode) => boolean) | undefined` | `-` |
### [#](#tree)Tree
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| rootStyle | @deprecated Use styles.root. | `CSSProperties | undefined` | `-` |
| filterAntTreeNode | @deprecated Use filterTreeNode. | `((treeNode: EventDataNode) => boolean) | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/alert.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Alert
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays important contextual feedback messages with semantic status types.
## When to use
Use Alert for persistent, page-level feedback about a state or operation. Use Sonner toasts for transient notifications.
**Recommended**
- Pick the semantic type that matches the severity of the message.
- Keep the title short; put detail in the description.
- Enable showIcon when the alert needs to be scannable at a glance.
**Avoid**
- Do not stack many alerts in one view; prefer a single summary.
- Do not use Alert for transient feedback; use a toast instead.
## Examples
### Basic usage
```tsx preview
import { Alert, Stack } from '@rockshin/tao-ui';
function AlertExample() {
return (
);
}
export default AlertExample;
```
### Descriptions and icons
```tsx preview
import { Alert, Stack } from '@rockshin/tao-ui';
function DetailedAlerts() {
return (
);
}
export default DetailedAlerts;
```
### Closable alerts and actions
```tsx preview
import { Alert, Button, Stack } from '@rockshin/tao-ui';
function ActionAlerts() {
return (
Update
}
/>
Retry}
closable
showIcon
/>
);
}
export default ActionAlerts;
```
### Title and description
Use `description` for the cause and recovery while keeping the title concise.
```tsx preview
import { Alert, Stack } from '@rockshin/tao-ui';
export default function AlertWithDescription() {
return (
);
}
```
### Status icons
`showIcon` adds the matching success, information, warning, or error icon.
```tsx preview
import { Alert, Stack } from '@rockshin/tao-ui';
export default function AlertWithIcon() {
return (
🔥}
/>
);
}
```
### Inline actions
Use `action` for an operation related to the message and provide feedback when it completes.
```tsx preview
import { useState } from 'react';
import { Alert, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [updated, setUpdated] = useState(false);
const [retried, setRetried] = useState(false);
return (
setUpdated(true)}
>
Update
}
/>
setRetried(true)}
>
Retry
}
/>
);
}
```
## API
### [#](#alert)Alert
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/drawer.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Drawer
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Opens a side panel for related tasks without leaving the current page.
## When to use
Use Drawer for inspection, editing, or supporting workflows that should stay connected to the current page.
**Recommended**
- Use a clear title and predictable close affordance.
- Keep destructive confirmations in a dedicated confirmation step.
**Avoid**
- Do not stack multiple drawers for a single workflow.
## Examples
### Basic usage
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';
function DrawerExample() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open drawer
setOpen(false)}
title="Project settings"
>
Update settings without leaving the current page.
>
);
}
export default DrawerExample;
```
### Placement and size
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function DrawerPlacement() {
const [placement, setPlacement] = useState<'right' | 'bottom' | null>(null);
return (
<>
setPlacement('right')}>
Right
setPlacement('bottom')}>
Bottom
setPlacement(null)}
>
Drawer content follows the selected edge.
>
);
}
export default DrawerPlacement;
```
### Footer and extra actions
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function DrawerFooter() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Edit settings
Help
}
footer={
setOpen(false)}>
Cancel
setOpen(false)}>Save
}
onClose={() => setOpen(false)}
>
Drawer footer actions stay attached to the workflow.
>
);
}
export default DrawerFooter;
```
### Resizable drawer
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';
function ResizableDrawer() {
const [open, setOpen] = useState(false);
const [width, setWidth] = useState(null);
return (
<>
setOpen(true)}>
Open resizable drawer
setWidth(Math.round(size)) }}
onClose={() => setOpen(false)}
>
Current width: {width === null ? 'default' : width + 'px'}
>
);
}
export default ResizableDrawer;
```
### Header actions and footer
Put actions in `extra` and `footer` so they remain visible while content scrolls.
```tsx preview
import { Button, Drawer, FormField, Input, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DrawerWithFooterAndExtra() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open
setOpen(false)}
title="Edit Profile"
extra={
setOpen(false)}>
Reset
}
footer={
<>
setOpen(false)}>
Cancel
setOpen(false)}>
Save
>
}
>
>
);
}
return ;
}
```
### Preset and custom sizes
Use a size preset or set the required `width` or `height`.
```tsx preview
import { Button, Drawer, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DrawerSizes() {
function Demo() {
const [size, setSize] = useState<'default' | 'large' | null>(null);
return (
setSize('default')}>
default (378)
setSize('large')}>
large (736)
setSize(null)}
title={`Size: ${size}`}
size={size ?? 'default'}
>
Preset width via the `size` prop.
);
}
return ;
}
```
### Mask and close controls
Configure the mask, mask dismissal, and close button while keeping an explicit exit path.
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DrawerNoMaskClosableConfig() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open (mask click won't close)
setOpen(false)}
title="Locked"
maskClosable={false}
keyboard={false}
footer={
setOpen(false)}>
Done
}
>
Mask click and Esc are disabled — close via the × or the footer
button.
>
);
}
return ;
}
```
### Resizable drawer
`resizable` lets users drag the edge when a detail panel needs more workspace.
```tsx preview
import { Button, Drawer } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DrawerResizable() {
function Demo() {
const [open, setOpen] = useState(false);
const [size, setSize] = useState(null);
return (
<>
setOpen(true)}>
Open resizable
setOpen(false)}
title="Drag the left edge"
resizable={{ onResize: (s) => setSize(Math.round(s)) }}
>
Grab the inner edge and drag to resize. Current width:{' '}
{size != null ? `${size}px` : 'default'}
>
);
}
return ;
}
```
## API
### [#](#drawer)Drawer
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| extra | Extra content rendered on the trailing side of the header. | `ReactNode` | `-` |
| footer | Footer content; renders a bordered footer area when provided. | `ReactNode` | `-` |
| size | Preset drawer size: `default` (378) / `large` (736). `width`/`height` override it. | `DrawerSize | undefined` | `-` |
| closable | Show the close (×) button. Defaults to true. | `boolean | undefined` | `true` |
| closeIcon | Custom close icon. | `ReactNode` | `-` |
| maskClosable | Close when clicking the mask. Defaults to true. | `boolean | undefined` | `true` |
| mask | Render the mask/overlay. Defaults to true. | `boolean | undefined` | `true` |
| keyboard | Close on Esc key. Defaults to true. | `boolean | undefined` | `true` |
| resizable | Allow resizing by dragging the inner edge. Pass an object for resize callbacks. | `boolean | DrawerResizableConfig | undefined` | `-` |
| afterOpenChange | Called after open transitions in either direction. | `((open: boolean) => void) | undefined` | `-` |
| afterClose | Called after the drawer has fully closed. | `(() => void) | undefined` | `-` |
| destroyOnHidden | Unmount children when closed. Defaults to `true`.
Set `false` to keep children mounted while releasing modal interaction locks when hidden. | `boolean | undefined` | `true` |
---
url: https://rickyshin93.github.io/tao-ui/components/modal.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Modal
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays a focused dialog for decisions, forms, and interruptive information.
## When to use
Use Modal for focused tasks or decisions. Static helpers such as Modal.confirm mirror common confirmation flows.
**Recommended**
- Prefer Modal.useModal inside React trees so dialogs inherit TaoProvider context.
- Keep modal content short and task-oriented.
**Avoid**
- Do not use nested modals for multi-step workflows.
## Examples
### Basic usage
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
function ModalExample() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open modal
setOpen(false)}
onOk={() => setOpen(false)}
>
You can restore the project later.
>
);
}
export default ModalExample;
```
### Confirmation loading
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
function LoadingModal() {
const [open, setOpen] = useState(false);
const [loading, setLoading] = useState(false);
function confirm() {
setLoading(true);
window.setTimeout(() => {
setLoading(false);
setOpen(false);
}, 1200);
}
return (
<>
setOpen(true)}>
Publish
setOpen(false)}
>
The production site will update immediately.
>
);
}
export default LoadingModal;
```
### Custom and absent footers
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function ModalFooters() {
const [mode, setMode] = useState<'custom' | 'none' | null>(null);
return (
<>
setMode('custom')}>
Custom footer
setMode('none')}>
No footer
setMode(null)}>Done
) : null
}
onClose={() => setMode(null)}
>
Footer content is optional and can be replaced.
>
);
}
export default ModalFooters;
```
### Imperative dialogs
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';
function ImperativeModals() {
return (
Modal.info({ title: 'Information', content: 'Your export is ready.' })
}
>
Info
Modal.success({ title: 'Saved', content: 'Changes were saved.' })
}
>
Success
Modal.confirm({
title: 'Delete project?',
content: 'This cannot be undone.',
})
}
>
Confirm
);
}
export default ImperativeModals;
```
### Async confirmation
A local delay simulates submission; `confirmLoading` communicates progress and prevents duplicate confirmation.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalConfirmLoading() {
function Demo() {
const [open, setOpen] = useState(false);
const [loading, setLoading] = useState(false);
return (
<>
setOpen(true)}>
Open Confirm
setOpen(false)}
onOk={() => {
setLoading(true);
setTimeout(() => {
setLoading(false);
setOpen(false);
}, 1500);
}}
>
This action cannot be undone.
>
);
}
return ;
}
```
### Custom footer
Replace the default actions with `footer` for a multi-step or specialized flow.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalCustomFooter() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open
setOpen(false)}
footer={
setOpen(false)}>
Got it
}
>
Single-action footer.
>
);
}
return ;
}
```
### Extend the default footer
Use the footer render function to preserve the built-in buttons while adding actions.
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalFooterRenderFn() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open
setOpen(false)}
onOk={() => setOpen(false)}
footer={(origin, { CancelBtn }) => (
setOpen(false)}>
Read later
{origin}
)}
>
The render-prop footer receives the default node plus{' '}
OkBtn / CancelBtn so you can keep defaults
and add your own.
>
);
}
return ;
}
```
### Confirm and cancel button props
Configure the confirm and cancel buttons separately for destructive or unavailable actions.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalButtonProps() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open
setOpen(false)}
onOk={() => setOpen(false)}
>
OK is a destructive button via okButtonProps.
>
);
}
return ;
}
```
### Preserve content between openings
Preserving children allows editing to continue after reopening. Enter text, close, and reopen.
```tsx preview
import { Button, FormField, Input, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalKeepAlive() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open (state preserved across reopen)
setOpen(false)}
onOk={() => setOpen(false)}
>
>
);
}
return ;
}
```
### Imperative confirmation
`Modal.confirm` creates a one-off confirmation. This example uses a local delay for async behavior.
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';
export default function ModalImperativeConfirm() {
return (
Modal.confirm({
title: 'Delete item?',
content: 'This action cannot be undone.',
okText: 'Delete',
okButtonProps: { variant: 'destructive' },
onOk: () => new Promise((res) => setTimeout(res, 1200)),
})
}
>
confirm (async OK)
Modal.info({ title: 'Info', content: 'FYI.' })}
>
info
Modal.success({ title: 'Saved!' })}
>
success
Modal.error({ title: 'Something broke' })}
>
error
Modal.warning({ title: 'Heads up', content: 'Check your input.' })
}
>
warning
);
}
```
### Context-aware confirmation
`Modal.useModal` returns an instance and context holder; render the holder within application providers.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
export default function ModalUseModalHook() {
function Demo() {
const [modal, contextHolder] = Modal.useModal();
return (
<>
modal.confirm({
title: 'Context-aware confirm',
content: 'Inherits TaoProvider config & theme.',
})
}
>
useModal confirm
{contextHolder}
>
);
}
return ;
}
```
### Responsive modal width
Set widths by breakpoint so the dialog adapts to the screen and content wraps naturally.
```tsx preview="iframe-follow"
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function ModalResponsiveWidth() {
function Demo() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>
Open Responsive Modal
setOpen(false)}
onOk={() => setOpen(false)}
>
Resize the viewport: full-width on phones, 640px from md up, 800px
from xl up.
>
);
}
return ;
}
```
## API
### [#](#modal)Modal
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| footer | Footer content.
- `undefined` renders default OK/Cancel buttons
- `null` renders no footer
- a function receives `(originNode, { OkBtn, CancelBtn })` to compose around the defaults | `ReactNode | ModalFooterRender` | `-` |
| okButtonProps | Extra props forwarded to the default OK button. | `ButtonProps | undefined` | `-` |
| cancelButtonProps | Extra props forwarded to the default Cancel button. | `ButtonProps | undefined` | `-` |
| width | Dialog width. Accepts a breakpoint map, e.g.
`width={{ xs: '100%', md: 640 }}` — the largest matching breakpoint wins,
falling back to the 520px default when no entry matches. | `string | number | Partial> | undefined` | `520` |
| centered | Vertically center the dialog. Defaults to true. | `boolean | undefined` | `true` |
| closable | Show the close (×) button. Defaults to true. | `boolean | (AriaAttributes & { disabled?: boolean | undefined; closeIcon?: ReactNode; onClose?: (() => void) | undefined; afterClose?: (() => void) | undefined; }) | undefined` | `true` |
| maskClosable | Close when clicking the mask/overlay. Defaults to true. | `boolean | undefined` | `true` |
| keyboard | Close on Esc key. Defaults to true. | `boolean | undefined` | `true` |
| getContainer | Portal destination. `false` renders the dialog in place. | `string | false | HTMLElement | (() => HTMLElement) | undefined` | `-` |
| afterClose | Called after the modal has fully closed (open transitions true → false). | `(() => void) | undefined` | `-` |
| destroyOnHidden | Unmount children when closed. Defaults to `true`.
Set `false` to keep children mounted while releasing modal interaction locks when hidden. | `boolean | undefined` | `true` |
---
url: https://rickyshin93.github.io/tao-ui/components/popconfirm.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Popconfirm
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Shows a compact confirmation popup anchored to a trigger element, with OK and Cancel actions.
## When to use
Use Popconfirm for lightweight inline confirmations such as delete actions, where a full Modal would be too heavy. Use Modal.confirm for critical or complex confirmations.
**Recommended**
- Keep the title to one short question; put detail in the description.
- Use Popconfirm for reversible, low-risk actions anchored to the control that triggers them.
**Avoid**
- Do not use Popconfirm for irreversible high-risk operations; use Modal.confirm instead.
- Do not put forms or rich interactions inside a Popconfirm.
## Examples
### Basic usage
```tsx preview
import { useState } from 'react';
import { Button, Popconfirm } from '@rockshin/tao-ui';
function PopconfirmExample() {
const [feedback, setFeedback] = useState('');
return (
<>
setFeedback('confirmed')}
>
Delete
{feedback}
>
);
}
export default PopconfirmExample;
```
### Description and custom labels
```tsx preview
import { useState } from 'react';
import { Button, Popconfirm, Stack } from '@rockshin/tao-ui';
function PopconfirmVariants() {
const [feedback, setFeedback] = useState('');
return (
<>
setFeedback('delete')}
>
Delete
setFeedback('leave')}
>
Leave page
{feedback}
>
);
}
export default PopconfirmVariants;
```
### Button props and disabled state
```tsx preview
import { Button, Popconfirm, Stack } from '@rockshin/tao-ui';
function PopconfirmStates() {
return (
Loading confirm
Disabled
);
}
export default PopconfirmStates;
```
### Confirm and cancel outcomes
Handle both callbacks and show the chosen outcome inline.
```tsx preview
import { useState } from 'react';
import { Popconfirm, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [result, setResult] = useState('No decision yet');
return (
setResult('Archived')}
onCancel={() => setResult('Kept')}
>
Archive
{result}
);
}
```
### Conditional availability
disabled prevents opening; a separate switch demonstrates availability.
```tsx preview
import { useState } from 'react';
import { Popconfirm, Button, Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [enabled, setEnabled] = useState(false);
return (
Archive item
);
}
```
### Placement and icon
placement sets the preferred direction, and icon=null hides the default warning icon.
```tsx preview
import { Popconfirm, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
Apply changes
);
}
```
## API
### [#](#popconfirm)Popconfirm
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| title | Main question text of the confirm popup (required, antd parity). | `ReactNode` **(Required)** | `-` |
| description | Secondary text shown under the title. | `ReactNode` | `-` |
| onConfirm | Called when OK is clicked; the popup also closes. | `((e?: MouseEvent | undefined) => void) | undefined` | `-` |
| onCancel | Called when Cancel is clicked; the popup also closes. | `((e?: MouseEvent | undefined) => void) | undefined` | `-` |
| okText | Text of the OK button. Defaults to `'OK'`. | `ReactNode` | `-` |
| cancelText | Text of the Cancel button. Defaults to `'Cancel'`. | `ReactNode` | `-` |
| okButtonProps | Extra props forwarded to the OK button. | `ButtonProps | undefined` | `-` |
| cancelButtonProps | Extra props forwarded to the Cancel button. | `ButtonProps | undefined` | `-` |
| icon | Icon shown before the title. Defaults to a warning triangle; pass `null` to hide it. | `ReactNode` | `-` |
| disabled | When true, the trigger still renders but the popup never opens. | `boolean | undefined` | `-` |
| placement | Popup side relative to the trigger. Defaults to `'top'`. | `PopoverPlacement | undefined` | `top` |
| className | Merged onto the confirm content wrapper. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(Required)** | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/progress.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Progress
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays measurable completion with lines, circles or dashboard arcs.
## When to use
Use percent for measured progress. Give each progress indicator an accessible label that identifies the operation.
## Examples
### Controlled progress
This local demo changes percent in increments of ten.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [percent, setPercent] = useState(40);
return (
setPercent((value) => Math.max(0, value - 10))}
>
Decrease
setPercent((value) => Math.min(100, value + 10))}
>
Increase
);
}
```
### Statuses
Active indicates ongoing work; exception identifies a failed operation.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Circle and dashboard
Dashboard gapDegree and gapPlacement control the opening of the arc.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Gradients and success segments
success.percent identifies the completed part of the overall percent.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Discrete steps
Use steps for a fixed number of units; circle steps also accept an explicit gap.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Label placement and formatting
Place text inside the track or replace the percentage with task units.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
`${Math.round((value ?? 0) / 10)} / 10 files`}
aria-label="Processed files"
/>
);
}
```
### Size and semantic styles
Numeric sizes set line height or circle diameter; a tuple sets line width and height.
```tsx preview
import { Progress, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#progress)Progress
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| trailColor | @deprecated Use railColor. | `string | undefined` | `-` |
| width | @deprecated Use size. | `number | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| gapPosition | @deprecated Use gapPlacement. | `GapPosition | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/result.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Result
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Shows the outcome of a completed operation, including recovery actions.
## When to use
Use after a meaningful operation or for a full-page error. For transient updates use a message or notification.
## Examples
### Success with a next step
Actions should explain what happens next. The example action updates only its local status.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Result } from '@rockshin/tao-ui';
export default function Example() {
const [opened, setOpened] = useState(false);
return (
setOpened(true)}>Open workspace}
/>
);
}
```
### Information, warning and error
Choose a status based on the outcome; changing the icon alone does not explain the issue.
```tsx preview
import { useState } from 'react';
import { Button, Result, Stack } from '@rockshin/tao-ui';
import type { ResultStatusType } from '@rockshin/tao-ui';
export default function Example() {
const [status, setStatus] = useState('info');
return (
<>
{(['info', 'warning', 'error'] as const).map((value) => (
setStatus(value)}
>
{value}
))}
>
);
}
```
### HTTP error pages
403, 404 and 500 provide dedicated illustrations. Supply application-specific titles and recovery guidance.
```tsx preview
import { useState } from 'react';
import { Button, Result, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [status, setStatus] = useState<403 | 404 | 500>(404);
const titles = {
403: 'Access required',
404: 'Page not found',
500: 'Unable to load this page',
};
return (
<>
{([403, 404, 500] as const).map((value) => (
setStatus(value)}
>
{value}
))}
>
);
}
```
### Failure details
Use children for actionable details, and keep the main title brief.
```tsx preview
import { Result } from '@rockshin/tao-ui';
export default function Example() {
return (
Row 12: enter a valid email address.
Row 28: choose a workspace owner.
);
}
```
### Custom icon and semantic styles
Customize the icon, title and body independently through Semantic DOM.
```tsx preview
import { Result } from '@rockshin/tao-ui';
export default function Example() {
return (
}
title="Invitation prepared"
subTitle="Review the recipient before sending."
styles={{
icon: { color: 'var(--tao-primary)' },
title: { fontSize: 20 },
root: { padding: 20 },
}}
/>
);
}
```
## API
### [#](#result)Result
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/skeleton.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Skeleton
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Preserves content structure while data is loading.
## When to use
Use for the initial loading of known content. Match the final layout and replace the placeholder when real content becomes available.
## Examples
### Loading replacement
Skeleton renders its children when loading is false.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Skeleton, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [loading, setLoading] = useState(true);
return (
setLoading((value) => !value)}>
{loading ? 'Show content' : 'Show skeleton'}
Workspace overview
Your team has completed the first milestone.
);
}
```
### Match the final layout
Control avatar shape, title width and each paragraph line width.
```tsx preview
import { Skeleton } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Form and action placeholders
Compound placeholders can be composed without the full article layout.
```tsx preview
import { Skeleton, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Images and custom nodes
Skeleton.Image provides an image placeholder. Skeleton.Node can hold a custom silhouette.
```tsx preview
import { Skeleton, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
### Rounded shapes and provider size
Compound placeholders inherit TaoProvider size. Use semantic styles to adjust spacing without changing the loading structure.
```tsx preview
import { Skeleton, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function Example() {
return (
);
}
```
## API
### [#](#skeleton)Skeleton
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/sonner.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Sonner
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Displays temporary toast notifications with optional actions and provider-aware theming.
## When to use
Mount one Sonner near app root, then call toast() imperatively from event handlers. Supports toast.loading(), toast.promise(), and toast.custom() for richer async and custom notification flows.
**Recommended**
- Prefer short, status-oriented messages with one primary action at most.
- Enable richColors when semantic status color should be visible.
**Avoid**
- Do not use toast notifications for blocking confirmations.
## Examples
Each example runs independently, and notifications stay inside its preview. Applications normally mount one `Sonner` host.
### Basic usage
```tsx preview="iframe-follow"
import { Button, Sonner, toast } from '@rockshin/tao-ui';
function SonnerExample() {
return (
<>
toast.success({
title: 'Saved',
description: 'Your profile has been updated.',
})
}
>
Show toast
>
);
}
export default SonnerExample;
```
### Semantic and rich-color toasts
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
function SemanticToasts() {
return (
<>
toast.info({
title: 'Info',
description: 'A new version is ready.',
})
}
>
Info
toast.success({ title: 'Saved' })}
>
Success
toast.warning({ title: 'Almost full' })}
>
Warning
toast.error({ title: 'Build failed' })}
>
Error
>
);
}
export default SemanticToasts;
```
### Loading and promise lifecycle
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
const wait = (duration: number) =>
new Promise((resolve) => window.setTimeout(resolve, duration));
function AsyncToasts() {
return (
<>
{
const id = toast.loading({ title: 'Syncing workspace' });
window.setTimeout(() => {
toast.dismiss(id);
toast.success({ title: 'Workspace synced' });
}, 1200);
}}
>
Loading
toast.promise(wait(1200), {
loading: { title: 'Publishing' },
success: { title: 'Published' },
error: { title: 'Publish failed' },
})
}
>
Promise
>
);
}
export default AsyncToasts;
```
### Actions, positions, and stack limits
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
function ActionToasts() {
return (
<>
toast({
title: 'Message sent',
action: {
label: 'Undo',
onClick: () => toast.success({ title: 'Send reverted' }),
},
})
}
>
With action
toast.info({ title: 'Top right' })}
>
Positioned
toast.dismiss()}>
Dismiss all
>
);
}
export default ActionToasts;
```
### Semantic colors
richColors distinguishes status notifications.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
export default function SonnerRichColors() {
return (
<>
toast.info({
title: 'Deploy started',
description: 'We will notify you when it finishes.',
action: { label: 'View' },
})
}
>
Info
toast.error({
title: 'Build failed',
description: 'Check logs and retry.',
cancel: { label: 'Dismiss' },
})
}
>
Error
>
);
}
```
### Notification actions
action and cancel provide related actions.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
export default function SonnerActions() {
return (
<>
toast({
title: 'Message sent',
description: 'Your message has been delivered.',
action: {
label: 'Undo',
onClick: () =>
toast.warning({
title: 'Send reverted',
description: 'Draft restored to composer.',
}),
},
cancel: { label: 'Dismiss' },
})
}
>
Undo toast
toast.warning({
title: 'Storage almost full',
description: 'Delete unused files or upgrade your plan.',
action: { label: 'Manage storage' },
})
}
>
Warning action
>
);
}
```
### Toast positions
Choose the toast position; notifications remain inside the preview window.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
export default function SonnerPositions() {
return (
<>
toast({
title: 'Top left',
description: 'Positioned in the top-left corner.',
})
}
>
Trigger
>
);
}
```
### Stacking and visible limits
visibleToasts limits the number of simultaneously visible notifications.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
export default function SonnerStackAndLimit() {
return (
<>
{
for (let index = 1; index <= 5; index += 1) {
toast({
title: `Queued task #${index}`,
description: `Background job ${index} is now running.`,
});
}
}}
>
Push 5 toasts
toast.dismiss()}>
Clear all
>
);
}
```
### Toast duration
Override duration per toast and provide dismissal for persistent messages.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
export default function SonnerCustomDuration() {
return (
<>
toast({
title: 'Autosaves enabled',
description: 'This one disappears quickly.',
duration: 1200,
})
}
>
Short
toast({
title: 'Manual review needed',
description: 'This one stays longer for attention.',
duration: 8000,
})
}
>
Long
>
);
}
```
### Submission feedback
A local delay simulates submission feedback for pending, success, and error states.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';
function wait(ms: number) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export default function SonnerFormSubmit() {
return (
<>
{
await toast.promise(wait(1200), {
loading: {
title: 'Submitting form',
description: 'Validating fields and saving changes.',
},
success: {
title: 'Profile updated',
description: 'Name, email, and preferences are saved.',
},
error: {
title: 'Submit failed',
},
});
}}
>
Submit profile
toast
.promise(
wait(1200).then(() => {
throw new Error('Card declined');
}),
{
loading: {
title: 'Submitting payment',
description: 'Contacting payment gateway.',
},
success: { title: 'Paid' },
error: (error) => ({
title: 'Payment failed',
description: (error as Error).message,
}),
},
)
.catch(() => undefined)
}
>
Submit payment
>
);
}
```
## API
### [#](#sonner)Sonner
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
### [#](#toast)toast
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/spinner.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Spinner
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Indicates indeterminate loading activity.
## When to use
Use Spinner for short indeterminate waits when progress cannot be measured.
**Recommended**
- Prefer inline placement near the content that is loading.
- Use aria labels for standalone spinners.
**Avoid**
- Do not use Spinner for determinate progress.
## Examples
### Basic usage
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';
function SpinnerExample() {
return (
);
}
export default SpinnerExample;
```
### Tips and custom indicators
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';
function SpinnerIndicators() {
return (
◌}
tip="Custom"
/>
);
}
export default SpinnerIndicators;
```
### Content overlay and delay
```tsx preview
import { Button, Spinner, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function SpinnerOverlay() {
const [spinning, setSpinning] = useState(true);
return (
setSpinning((value) => !value)}
>
{spinning ? 'Stop' : 'Start'} loading
Content remains mounted below the overlay.
);
}
export default SpinnerOverlay;
```
### Loading over content
spinning controls loading over a content area.
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function SpinnerWrapContent() {
function Demo() {
const [spinning, setSpinning] = useState(true);
return (
setSpinning((s) => !s)}>
{spinning ? 'Stop' : 'Start'} loading
Card title
Content stays in place and dims while the spinner overlays it.
);
}
return ;
}
```
### Delayed loading
A short request can finish before delay to avoid flicker.
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function SpinnerDelay() {
function Demo() {
const [spinning, setSpinning] = useState(false);
return (
500ms delay — quick toggles won't flash the spinner.
setSpinning((s) => !s)}>
Toggle spinning ({String(spinning)})
Toggle quickly to see the delay in action.
);
}
return ;
}
```
### Custom indicator
indicator replaces the visual mark; retain clear status text.
```tsx preview
import { Spinner } from '@rockshin/tao-ui';
export default function SpinnerCustomIndicator() {
return (
⏳}
tip="Please wait"
/>
);
}
```
### Controlled loading
Control spinning externally while keeping content in place.
```tsx preview
import { useState } from 'react';
import { Spinner, Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [loading, setLoading] = useState(false);
return (
Your workspace content stays here.
);
}
```
## API
### [#](#spinner)Spinner
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| spinning | Whether the spinner is visible. Defaults to true. | `boolean | undefined` | `true` |
| size | Size of the indicator. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| tip | Description text rendered under the indicator. | `ReactNode` | `-` |
| delay | Delay (ms) before showing the spinner — prevents flicker on fast loads. | `number | undefined` | `-` |
| indicator | Custom indicator node, replaces the default spinner. | `ReactNode` | `-` |
| children | Wrap content: the spinner overlays `children` while spinning. | `ReactNode` | `-` |
| fullscreen | Render a full-screen backdrop with a centered spinner. | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tour.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Tour
Feedback`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Guided steps with target positioning, spotlight masks, custom actions and keyboard navigation.
Each example can be copied and run independently. Use the device control on framed previews to switch between desktop and phone widths.
Masked centered steps and steps with `disabledInteraction` contain keyboard focus. Steps that allow target interaction are nonmodal and keep the target focusable. Closing restores focus to the launch control.
## Examples
### Guide users between targets
Targets are read from refs when the tour opens. Next moves to the following target.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function BasicTour() {
const [open, setOpen] = useState(false);
const upload = useRef(null);
const save = useRef(null);
return (
Upload
Save
setOpen(true)}>Start tour
setOpen(false)}
steps={[
{
title: 'Upload a file',
description: 'Choose a document to begin.',
target: () => upload.current!,
},
{
title: 'Save changes',
description: 'Review your work, then save.',
target: () => save.current!,
},
]}
/>
);
}
```
### Controlled current step
Keep current and open in state. Reset the step before starting the tour again.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function ControlledTour() {
const [open, setOpen] = useState(false);
const [current, setCurrent] = useState(0);
const upload = useRef(null);
const save = useRef(null);
return (
Upload
Save
{
setCurrent(0);
setOpen(true);
}}
>
Start again
Current step: {current + 1}
setOpen(false)}
steps={[
{
title: 'Upload a file',
description: 'Choose a document to begin.',
target: () => upload.current!,
},
{
title: 'Save changes',
description: 'Review your work, then save.',
target: () => save.current!,
},
]}
/>
);
}
```
### A centered introduction
Omit target for an introduction centered in the viewport.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function CenteredTour() {
const [open, setOpen] = useState(false);
return (
setOpen(true)}>Welcome tour
setOpen(false)}
steps={[
{
title: 'Welcome to your workspace',
description:
'Organize documents, review changes and share results from one place.',
},
{
title: 'Ready to begin',
description: 'Choose Done to close this introduction.',
},
]}
/>
);
}
```
### Primary emphasis and a cover
type="primary" changes the panel emphasis. A step can include a cover image or other React content.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
const photo = (color: string) =>
`data:image/svg+xml,${encodeURIComponent(` `)}`;
export default function PrimaryTour() {
const [open, setOpen] = useState(false);
return (
setOpen(true)}>Discover the workspace
setOpen(false)}
steps={[
{
title: 'A clear place to start',
description: 'Create your first project when you are ready.',
cover: ,
},
]}
/>
);
}
```
### Mask, gap and interaction
gap controls the highlighted rectangle. disabledInteraction prevents clicks on the highlighted target.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function SpotlightTour() {
const [open, setOpen] = useState(false);
const upload = useRef(null);
const save = useRef(null);
return (
Upload
Save
setOpen(true)}>Start tour
setOpen(false)}
gap={{ offset: 10, radius: 10 }}
mask={{ color: 'rgba(25,34,46,.65)' }}
disabledInteraction
steps={[
{
title: 'Upload a file',
description: 'Choose a document to begin.',
target: () => upload.current!,
},
{
title: 'Save changes',
description: 'Review your work, then save.',
target: () => save.current!,
},
]}
/>
);
}
```
### Custom indicators and actions
Keep the default actions and add a Skip action. Per-step button props customize labels and handlers.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function CustomTourActions() {
const [open, setOpen] = useState(false);
const upload = useRef(null);
const save = useRef(null);
return (
Upload
Save
setOpen(true)}>Start tour
setOpen(false)}
indicatorsRender={(current, total) => (
{current + 1} / {total}
)}
actionsRender={(actions) => (
<>
setOpen(false)}>
Skip
{actions}
>
)}
steps={[
{
title: 'Upload a file',
target: () => upload.current!,
nextButtonProps: { children: 'Continue' },
},
{
title: 'Save changes',
target: () => save.current!,
nextButtonProps: { children: 'Got it' },
},
]}
/>
);
}
```
### Non-modal guidance
mask:false leaves the page unobscured. keyboard:false disables step navigation and Escape handling; Done still closes this example.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function NonModalTour() {
const [open, setOpen] = useState(false);
const target = useRef(null);
return (
setOpen(true)}>
Show a hint
setOpen(false)}
mask={false}
keyboard={false}
closable={false}
steps={[
{
title: 'Save your work',
description: 'You can continue interacting with the page.',
target: () => target.current!,
},
]}
/>
);
}
```
### Guide a narrow layout
The panel flips and shifts around its target to stay inside the phone viewport.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { Button, Tour } from '@rockshin/tao-ui';
export default function MobileTour() {
const [open, setOpen] = useState(false);
const upload = useRef(null);
const save = useRef(null);
return (
Start your project
Follow two steps to upload and save.
Upload
Save
setOpen(true)}>Start tour
setOpen(false)}
steps={[
{
title: 'Upload a file',
description: 'Choose a document to begin.',
target: () => upload.current!,
},
{
title: 'Save changes',
description: 'Review your work, then save.',
target: () => save.current!,
},
]}
/>
);
}
```
## API
### [#](#tour)Tour
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
---
url: https://rickyshin93.github.io/tao-ui/components/headless-input-number.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# HeadlessInputNumber
Headless`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Headless numeric input primitives and hook for custom number entry experiences.
## When to use
Use the headless API when tao-ui styling is not appropriate but number formatting behavior should stay consistent.
**Recommended**
- Use useNumberInput for fully custom rendering.
- Reuse the validation helpers for parity with the styled InputNumber.
**Avoid**
- Do not use the component outside its intended interaction model.
## Examples
### Basic usage
```tsx preview
import { HeadlessInputNumber } from '@rockshin/tao-ui';
import { useState } from 'react';
function HeadlessInputNumberExample() {
const [value, setValue] = useState('');
return (
);
}
export default HeadlessInputNumberExample;
```
### Formatting and affixes
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';
function HeadlessNumberFormats() {
return (
);
}
export default HeadlessNumberFormats;
```
### Locale separators and bounds
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';
function HeadlessNumberConstraints() {
return (
);
}
export default HeadlessNumberConstraints;
```
### Thousands separators
Configure grouping and decimal separators and compare display with the emitted value.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberWithThousandSeparator() {
const args: React.ComponentProps = {
placeholder: 'Try 1234567',
decimalPlaces: 2,
thousandsSeparator: ',',
decimalSeparator: '.',
};
return ;
}
```
### Affix formatting
Configure unit or currency affixes while the headless input handles numeric values.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberWithPrefixSuffix() {
const args: React.ComponentProps = {
prefix: '$',
suffix: 'USD',
decimalPlaces: 2,
};
return ;
}
```
### Percentage values
Use a percent suffix and precision; define percentage conversion in application logic.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberPercentage() {
const args: React.ComponentProps = {
isPercentage: true,
decimalPlaces: 2,
suffix: '%',
placeholder: 'Type 50 → actual is 0.5',
};
return ;
}
```
### Negative values
Allow negative input and compare intermediate editing states with complete values.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberAllowNegative() {
const args: React.ComponentProps = {
allowNegative: true,
placeholder: 'Type -123.45',
};
return ;
}
```
### Range limits
Constrain accepted values with bounds and observe blur behavior.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberClampedRange() {
const args: React.ComponentProps = {
min: 0,
max: 100,
decimalPlaces: 0,
placeholder: 'Type 999, blur to clamp to 100',
};
return ;
}
```
### Pad decimals on blur
Pad decimal places to the configured precision when editing ends.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberPadOnBlurAlways() {
const args: React.ComponentProps = {
padDecimalsOnBlur: 'always',
decimalPlaces: 2,
placeholder: 'Type 5, blur to see 5.00',
};
return ;
}
```
### Localized separators
Use a dot for grouping and a comma for decimal separation.
```tsx preview
import { useState } from 'react';
import { HeadlessInputNumber } from '@rockshin/tao-ui';
function ControlledWrapper(
props: React.ComponentProps,
) {
const [value, setValue] = useState((props.value as string | undefined) ?? '');
return (
{
setValue(v);
props.onChange?.(v);
}}
/>
actual value: {JSON.stringify(value)}
);
}
export default function HeadlessInputNumberEuropeanLocale() {
const args: React.ComponentProps = {
decimalSeparator: ',',
thousandsSeparator: '.',
decimalPlaces: 2,
placeholder: '1.234,56',
};
return ;
}
```
## Regional formatting
Regional grouping, decimal symbols and digits inherit `TaoProvider.locale.numberLocale`; set `locale="fr-FR"` on this component to override it. Explicit separators take precedence. Numeric input keeps canonical ASCII strings and precision while displaying localized digits.
## API
### [#](#headlessinputnumber)HeadlessInputNumber
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |
### [#](#numberinput)NumberInput
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/app.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# App
Config`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Provides scoped message, notification and modal instances with application context.
## When to use
Wrap the consuming subtree with App, then call App.useApp() inside a descendant. Put TaoProvider and any custom context providers outside App so feedback content inherits them. Each example has an isolated preview.
## Examples
### Scoped messages
The hook must run below App. Each instance owns its messages and can destroy only its own notices.
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';
function Actions() {
const { message } = App.useApp();
return (
message.success('Changes saved')}>Success
message.info('A new version is ready')}
>
Info
message.warning('Storage is almost full')}
>
Warning
message.error('Unable to save changes')}
>
Error
message.destroy()}>
Clear messages
);
}
export default function Example() {
return (
);
}
```
### Keyed updates and close promises
A message result is both a close function and a thenable. Reusing key updates the existing message.
```tsx preview="iframe-follow"
import { useRef, useState } from 'react';
import { App, Button, Stack } from '@rockshin/tao-ui';
import type { AppMessageType } from '@rockshin/tao-ui';
function Actions() {
const { message } = App.useApp();
const close = useRef(null);
const [status, setStatus] = useState('Idle');
return (
{
setStatus('Running');
close.current = message.loading({
key: 'job',
content: 'Preparing local preview…',
duration: 0,
});
close.current.then(() => setStatus('Message closed'));
}}
>
Start
message.success({
key: 'job',
content: 'Preview ready',
duration: 0,
})
}
>
Update
close.current?.()}>
Close
{status}
);
}
export default function Example() {
return (
);
}
```
### Notifications with actions and progress
duration is measured in seconds. showProgress visualizes the auto-close timer; hovering pauses it by default.
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';
function Actions() {
const { notification } = App.useApp();
return (
notification.success({
key: 'export',
title: 'Export ready',
description: 'The sample report is ready to review.',
duration: 8,
showProgress: true,
actions: (
notification.destroy('export')}
>
Dismiss
),
})
}
>
Timed notification
notification.info({
title: 'Review needed',
description: 'This notification stays open until dismissed.',
duration: 0,
placement: 'bottomRight',
})
}
>
Persistent notification
);
}
export default function Example() {
return (
);
}
```
### Await a confirmation
The result resolves to true for confirmation and false for cancellation. This demo changes local state only.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { App, Button, Stack } from '@rockshin/tao-ui';
function Actions() {
const { modal } = App.useApp();
const [status, setStatus] = useState('Project is active');
return (
{
const accepted = await modal.confirm({
title: 'Archive this project?',
content: 'You can restore it from archived projects.',
okText: 'Archive',
cancelText: 'Keep project',
});
setStatus(
accepted ? 'Project archived in this demo' : 'Project is active',
);
}}
>
Archive project
{status}
);
}
export default function Example() {
return (
);
}
```
### Async confirmation and retry
Returning a promise keeps the action busy. Rejection keeps the modal open. This local simulation deliberately fails once, then succeeds.
```tsx preview="iframe-follow"
import { App, Button } from '@rockshin/tao-ui';
function Actions() {
const { modal } = App.useApp();
return (
{
let attempts = 0;
const dialog = modal.confirm({
title: 'Save sample changes?',
content:
'The first attempt demonstrates an error. Try again to finish.',
onOk: async () => {
await new Promise((resolve) => window.setTimeout(resolve, 700));
attempts += 1;
if (attempts === 1) {
dialog.update({
content: 'The simulated save failed. Choose OK to retry.',
});
throw new Error('Simulated save failure');
}
},
});
}}
>
Try async confirmation
);
}
export default function Example() {
return (
);
}
```
### Update and destroy a modal
The returned handle updates content or closes the dialog. A custom footer can retain the supplied OkBtn and CancelBtn.
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';
function Actions() {
const { modal } = App.useApp();
return (
{
const dialog = modal.info({
title: 'Preview version 1',
content: 'Review the current draft.',
footer: (_, { OkBtn }) => (
dialog.update({
title: 'Preview version 2',
content: 'The draft has been updated.',
})
}
>
Update
dialog.destroy()}>
Close
),
});
}}
>
Open editable preview
);
}
export default function Example() {
return (
);
}
```
### Theme, locale and custom context
Feedback portals retain provider tokens and React context. Locale supplies default confirmation and close labels.
```tsx preview="iframe-follow"
import { createContext, useContext } from 'react';
import { App, Button, Stack, TaoProvider, zhCN } from '@rockshin/tao-ui';
const Workspace = createContext('');
function Details() {
return Workspace: {useContext(Workspace)} ;
}
function Actions() {
const { notification, modal } = App.useApp();
return (
notification.info({
title: 'Workspace context',
description: ,
})
}
>
Show notification
modal.confirm({ title: 'Continue?', content: })
}
>
Show confirmation
);
}
export default function Example() {
return (
);
}
```
### Independent scopes and custom roots
Two App instances keep separate message stores. component changes the wrapper element; component={false} omits only that wrapper.
```tsx preview="iframe-follow"
import { App, Button, Stack } from '@rockshin/tao-ui';
function Actions({ name }: { name: string }) {
const { message } = App.useApp();
return (
message.info({
key: 'status',
content: `${name} workspace ready`,
duration: 0,
})
}
>
Show {name}
message.destroy()}>
Clear {name}
);
}
export default function Example() {
return (
);
}
```
## API
### [#](#app)App
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
---
url: https://rickyshin93.github.io/tao-ui/components/tao-provider.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# TaoProvider
Config`@rockshin/tao-ui`
[Examples](#examples)[API](#api)
Provides global component defaults, portal scoping, and theme seed token overrides.
## When to use
Wrap an app or subtree with TaoProvider to set size, disabled, variant, and theme defaults.
**Recommended**
- Prefer provider-level defaults for app-wide decisions.
- Use nested providers for scoped theme overrides.
**Avoid**
- Do not override derived CSS variables directly unless a theme token cannot express the change.
## Examples
### Basic usage
```tsx preview
import { Button, Input, Stack, TaoProvider } from '@rockshin/tao-ui';
function TaoProviderExample() {
return (
Inherited button
);
}
export default TaoProviderExample;
```
### Global sizes
```tsx preview
import { Button, Input, Stack, TaoProvider } from '@rockshin/tao-ui';
function ProviderSizes() {
return (
{(['small', 'medium', 'large'] as const).map((size) => (
{size} button
))}
);
}
export default ProviderSizes;
```
### Brand tokens and component tokens
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
function ProviderTokens() {
return (
Branded primary
Secondary
);
}
export default ProviderTokens;
```
### Dark mode, compact density, and isolation
```tsx preview
import { Button, Input, Stack, TaoProvider } from '@rockshin/tao-ui';
function ProviderModes() {
return (
Compact
Dark mode
);
}
export default ProviderModes;
```
### Global variants
Set a common appearance for form controls and override individual controls when needed.
```tsx preview
import { FormField, Input, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function ProviderGlobalVariant() {
return (
);
}
```
### Brand colors
Change brand colors across the same components while retaining status semantics.
```tsx preview
import {
Button,
Checkbox,
Input,
Select,
Stack,
Switch,
Tag,
TaoProvider,
} from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
function ControlRow({
label,
selectOptions = [
{ value: '1', label: 'Option 1' },
{ value: '2', label: 'Option 2' },
],
}: {
label: string;
selectOptions?: { value: string; label: string }[];
}) {
return (
{label}
Primary
Secondary
Check
Tag
);
}
const BRAND_PALETTES = [
{ name: 'Default (Anthropic-neutral)', color: 'oklch(0.205 0.01 70)' },
{ name: 'Vercel Black', color: 'oklch(0.145 0 0)' },
{ name: 'Linear Indigo', color: 'oklch(0.52 0.19 275)' },
{ name: 'Stripe Purple', color: 'oklch(0.55 0.22 300)' },
{ name: 'Supabase Green', color: 'oklch(0.62 0.17 155)' },
{ name: 'Notion Orange', color: 'oklch(0.68 0.17 45)' },
];
export default function ProviderBrandColors() {
return (
{BRAND_PALETTES.map((p) => (
{p.name}
))}
);
}
```
### Semantic colors
Configure success, warning, and error colors separately so states remain distinguishable.
```tsx preview
import {
Button,
FormField,
Input,
Stack,
Tag,
TaoProvider,
} from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
export default function ProviderSemanticColors() {
return (
success
Deployed
Passed
Ready
warning
Degraded
Preview
Draft
error
Failed
Blocked
Broken
Delete
);
}
```
### Radius scale
The base radius derives size-specific radii; compare the effect across controls.
```tsx preview
import {
Button,
Checkbox,
Input,
Select,
Stack,
Switch,
Tag,
TaoProvider,
} from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
function ControlRow({
label,
selectOptions = [
{ value: '1', label: 'Option 1' },
{ value: '2', label: 'Option 2' },
],
}: {
label: string;
selectOptions?: { value: string; label: string }[];
}) {
return (
{label}
Primary
Secondary
Check
Tag
);
}
const RADIUS_STEPS = [
{ name: 'sharp', value: 2 },
{ name: 'default (10)', value: 10 },
{ name: 'rounded', value: 16 },
{ name: 'pill-ish', value: 24 },
];
export default function ProviderRadiusScale() {
return (
{RADIUS_STEPS.map((r) => (
{r.name} · {r.value}px
))}
);
}
```
### Nesting and isolation
Nested providers can inherit or reset their theme without affecting the outer scope.
```tsx preview
import {
Button,
Checkbox,
Input,
Select,
Stack,
Switch,
Tag,
TaoProvider,
} from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
function ControlRow({
label,
selectOptions = [
{ value: '1', label: 'Option 1' },
{ value: '2', label: 'Option 2' },
],
}: {
label: string;
selectOptions?: { value: string; label: string }[];
}) {
return (
{label}
Primary
Secondary
Check
Tag
);
}
export default function ProviderNestedIsolation() {
return (
outer · purple / large
inner · orange, size inherited (large)
{/* only size, no token override: color stays purple, size collapses to small */}
inner · color inherited (purple), size=small
);
}
```
### Portal theme inheritance
Open the dropdown to see that portal content retains its provider theme.
```tsx preview
import { FormField, Select, Stack, TaoProvider } from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
export default function ProviderPortalTheming() {
return (
Select popup portals to body but still reads the closest TaoProvider —
both dropdowns below should match their parent primary.
);
}
```
### Dynamic theme switching
Change theme settings through state and observe the controls and popups update.
```tsx preview
import {
Button,
Checkbox,
Input,
Select,
Stack,
Switch,
Tag,
TaoProvider,
} from '@rockshin/tao-ui';
import { type CSSProperties, useState } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
function ControlRow({
label,
selectOptions = [
{ value: '1', label: 'Option 1' },
{ value: '2', label: 'Option 2' },
],
}: {
label: string;
selectOptions?: { value: string; label: string }[];
}) {
return (
{label}
Primary
Secondary
Check
Tag
);
}
const BRAND_PALETTES = [
{ name: 'Default (Anthropic-neutral)', color: 'oklch(0.205 0.01 70)' },
{ name: 'Vercel Black', color: 'oklch(0.145 0 0)' },
{ name: 'Linear Indigo', color: 'oklch(0.52 0.19 275)' },
{ name: 'Stripe Purple', color: 'oklch(0.55 0.22 300)' },
{ name: 'Supabase Green', color: 'oklch(0.62 0.17 155)' },
{ name: 'Notion Orange', color: 'oklch(0.68 0.17 45)' },
];
export default function ProviderDynamicSwitching() {
function Demo() {
const [idx, setIdx] = useState(0);
const current = BRAND_PALETTES[idx];
return (
{BRAND_PALETTES.map((p, i) => (
setIdx(i)}
>
{p.name.split(' ')[0]}
))}
active · {current.name}
);
}
return ;
}
```
### Layout transparency
The provider does not add a layout wrapper, so components retain their parent layout.
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
import { type CSSProperties } from 'react';
const swatchLabel: CSSProperties = {
fontSize: 12,
color: 'var(--tao-color-text-tertiary)',
minWidth: 72,
fontFamily: 'var(--tao-font-family-code)',
};
export default function ProviderLayoutTransparent() {
return (
Children of a single TaoProvider must land in separate grid columns. If
the wrapper collapsed layout, both cards would stack in column 1.
Main
col 2 · 1fr — buttons below should feel indigo
Primary
Secondary
);
}
```
### Component tokens
Override tokens for a target component while other components retain the global theme.
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function ProviderComponentTokens() {
return (
theme.components.Button — pill radius + custom padding/font weight
Pill Primary
Pill Secondary
);
}
```
### Compact density
Compact mode changes spacing and control density while retaining the theme font size.
```tsx preview
import { Button, Input, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function ProviderCompactDensity() {
return (
theme.compact: control height 32→28, paddings one notch tighter
Default
Button
Compact
Button
);
}
```
### Right-to-left layouts
Set `direction="rtl"` on TaoProvider or use HTML `dir="rtl"` on a surrounding element. Components inherit the local direction, and popups keep the direction of their trigger even when rendered into a portal. An explicit component `direction` prop or nested provider can override it; Carousel uses `rtl`. Locale and direction are independent. Explicit popup placements such as `bottomLeft` retain their physical meaning.
```tsx preview
import { Select, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function DirectionExample() {
return (
);
}
```
### 17 languages and regional formats
Switch the language to update component defaults, dates and numbers. Existing ISO date formats remain the default; this example explicitly requests a regional date with `format="L"`. Numeric input still emits canonical ASCII decimal strings. Caller-owned labels are independent of the component dictionary.
```tsx preview
import { useState } from 'react';
import dayjs from 'dayjs';
import {
DatePicker, Empty, InputNumber, Pagination, Select, Stack, Statistic, TaoProvider, Upload,
enUS, zhCN, zhTW, jaJP, koKR, frFR, deDE, esES, itIT, ptBR, ruRU, arEG, hiIN, trTR, idID, thTH, viVN,
} from '@rockshin/tao-ui';
const languages = [
{ value: 'enUS', label: 'English', locale: enUS },
{ value: 'zhCN', label: '简体中文', locale: zhCN },
{ value: 'zhTW', label: '繁體中文', locale: zhTW },
{ value: 'jaJP', label: '日本語', locale: jaJP },
{ value: 'koKR', label: '한국어', locale: koKR },
{ value: 'frFR', label: 'Français', locale: frFR },
{ value: 'deDE', label: 'Deutsch', locale: deDE },
{ value: 'esES', label: 'Español', locale: esES },
{ value: 'itIT', label: 'Italiano', locale: itIT },
{ value: 'ptBR', label: 'Português (Brasil)', locale: ptBR },
{ value: 'ruRU', label: 'Русский', locale: ruRU },
{ value: 'arEG', label: 'العربية', locale: arEG },
{ value: 'hiIN', label: 'हिन्दी', locale: hiIN },
{ value: 'trTR', label: 'Türkçe', locale: trTR },
{ value: 'idID', label: 'Bahasa Indonesia', locale: idID },
{ value: 'thTH', label: 'ไทย', locale: thTH },
{ value: 'viVN', label: 'Tiếng Việt', locale: viVN },
];
export default function LocaleExample() {
const [language, setLanguage] = useState('frFR');
const selected = languages.find((item) => item.value === language)!;
return (
setLanguage(String(value))} />
);
}
```
## API
### [#](#usetaointernalconfig)useTaoInternalConfig
**Internal component access for token propagation through third-party portals.**
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
### [#](#usetaodirection)useTaoDirection
**Resolve DOM inheritance at a component's source, before it creates portals.**
| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
### [#](#usetaotoken)useTaoToken
**antd `theme.useToken` counterpart, zero-runtime edition: returns every
design token as a `var(--tao-*)` reference string, so custom components can
stay visually consistent with tao-ui and still resolve in the browser
against the live theme (dark mode, seed overrides, compact density):
````
const { token } = useTaoToken();
```**
|Property|Description|Type|Default Value|
|:---:|:---:|:---:|:---:|
### TaoPortalScope
**Re-establishes the theme token scope inside a portal. Floating components
portal their popup to document.body, escaping the `[data-tao-provider]`
element that carries custom token overrides; wrapping the portal content in
this component re-applies those overrides so colors/sizes stay consistent.
With `asChild`, merges the tokens onto the immediate child (via Radix Slot)
instead of adding a wrapper div. Prefer `asChild` inside portals whose Radix
primitive does NOT Presence-gate its Portal (notably `@radix-ui/react-select`
— see `SelectPortal` in `node_modules/@radix-ui/react-select`): the wrapper
div would otherwise render even while the popup is closed, leaving a ghost
`` in the body for every mounted-but-closed Select.**
|Property|Description|Type|Default Value|
|:---:|:---:|:---:|:---:|
|style|Additional style|`CSSProperties \| undefined`|`-`|
### TaoProvider
|Property|Description|Type|Default Value|
|:---:|:---:|:---:|:---:|
|direction|Text and interaction direction. Defaults to the surrounding DOM direction.|`TaoDirection \| undefined`|`-`|
|locale|Component text and regional settings; omitted keys inherit from the parent.|`Partial \| undefined`|`-`|
|disabled|Whether to disable |`boolean \| undefined`|`-`|
### BuiltinTaoLocale
**Complete dictionaries shipped by tao-ui; custom TaoLocale values stay compatible.**
|Property|Description|Type|Default Value|
|:---:|:---:|:---:|:---:|
### TaoLocale
**Built-in Select and date-picker text. Arrays use calendar order (Monday first).**
|Property|Description|Type|Default Value|
|:---:|:---:|:---:|:---:|
````
---
url: https://rickyshin93.github.io/tao-ui/components/util.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Util
Config`@rockshin/tao-ui`
Infer TypeScript types from components and their public props without a runtime helper.
## GetProps
Read the props of a component, a Context value or an existing props object.
```tsx preview
import { Button, type GetProps } from '@rockshin/tao-ui';
const props: GetProps = {
variant: 'secondary',
children: 'Typed button',
};
export default function Demo() {
return ;
}
```
## GetProp
Read a non-nullable property type; the third argument Return extracts a function property’s return type.
```tsx preview
import { Select, type GetProp } from '@rockshin/tao-ui';
const options: GetProp = [
{ value: 'design', label: 'Design' },
{ value: 'engineering', label: 'Engineering' },
];
export default function Demo() {
return ;
}
```
```tsx
import type { GetProp } from '@rockshin/tao-ui';
type SearchProps = { onSearch?: (query: string) => Promise };
type SearchResult = GetProp; // Promise
```
## GetRef
Infer the public instance accepted by a component ref and use it with useRef.
```tsx preview
import { Input, Button, Stack, type GetRef } from '@rockshin/tao-ui';
import { useRef } from 'react';
export default function Demo() {
const input = useRef>(null);
return (
input.current?.focus()}>Focus input
);
}
```
## Subpath import
```tsx
import type { GetProps, GetProp, GetRef } from '@rockshin/tao-ui/util';
```
These exports exist only in the type system and add no browser runtime code.
---
url: https://rickyshin93.github.io/tao-ui/showcase/commerce.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
[← All showcases](/tao-ui/showcase)[中文](/tao-ui/zh/showcase/commerce)
Daybreak BlueVerdantMagentaVermilionTangerineInk
LightDark
Compact
Fieldnote Store
OverviewOrders8CustomersProductsFinanceReports
Organization
TeamSecuritySettings
Monthly order quota
72%
Upgrade plan
1. Workspace
1.
1. Overview
⌘K
M
2026.11.08 · Daily brief
## Good morning, Maya Chen
Here is today at a glance.
Holiday sale
-
Revenue · 30 days
$1,588,000
+12.4%vs last period
7 days30 days12 months
10/1010/1510/2010/2510/3011/411/8
Orders3,842+8.1%Avg. order$47.48-2.3%Refund rate1.8%-0.4%
Channels
- **Website$83,918**46%**
- **Mobile app$51,080**28%**
- **Retail stores$29,189**16%**
- **Partners$18,243**10%**
Monthly target
**80%**$1.28M of $1.6M
Announcements
**Payout schedule update**
Payouts move to weekly from December.
Learn more
**New product editor is live**
Step-by-step forms, scheduled publishing and @mentions.
Learn more
**Holiday campaign sign-ups open**
Sign up before Nov 20 for a homepage slot.
Learn more
**Payout schedule update**
Payouts move to weekly from December.
Learn more
**New product editor is live**
Step-by-step forms, scheduled publishing and @mentions.
Learn more
- 1
- 2
- 3
Schedule
2026
Nov
MonthYear
| Su | Mo | Tu | We | Th | Fr | Sa |
| --- | --- | --- | --- | --- | --- | --- |
| 01 | 02 | 03 | 04 | 05 | 06 | 07 |
| 08 | 09 | 10 | 11 | 12 | 13 | 14 |
| 15 | 16 | 17 | 18 | 19 | 20 | 21 |
| 22 | 23 | 24 | 25 | 26 | 27 | 28 |
| 29 | 30 | 01 | 02 | 03 | 04 | 05 |
| 06 | 07 | 08 | 09 | 10 | 11 | 12 |
Activity
1. 16:40
Maya Chen placed an order of $182
1. 15:53
Leo Park requested a refund
1. 15:06
Ava Brooks left a 5-star review
1. 14:19
Noah Kim joined as a member
1. 13:32
Iris Wong placed an order of $182
1. 12:45
Owen Hart requested a refund
1. 11:58
Zoe Adams left a 5-star review
1. 11:11
Eli Ross joined as a member
---
url: https://rickyshin93.github.io/tao-ui/showcase.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# Built with tao-ui
Explore interactive examples and see how components come together in real products.
**********
****
****
*¥ 1.28M**3,842**¥ 334**1.8%*
****
OPERATIONS
## Fieldnote Store
Explore a complete commerce workspace, from orders and products to team and security settings.
[Explore showcase ](/tao-ui/showcase/commerce)
## Components in the commerce showcase68
- [Affix](/tao-ui/components/affix)
- [Alert](/tao-ui/components/alert)
- [AutoComplete](/tao-ui/components/auto-complete)
- [Avatar](/tao-ui/components/avatar)
- [Badge](/tao-ui/components/badge)
- [BorderBeam](/tao-ui/components/border-beam)
- [Breadcrumb](/tao-ui/components/breadcrumb)
- [Button](/tao-ui/components/button)
- [Calendar](/tao-ui/components/calendar)
- [Card](/tao-ui/components/card)
- [Carousel](/tao-ui/components/carousel)
- [Cascader](/tao-ui/components/cascader)
- [Checkbox](/tao-ui/components/checkbox)
- [Collapse](/tao-ui/components/collapse)
- [ColorPicker](/tao-ui/components/color-picker)
- [ContextMenu](/tao-ui/components/context-menu)
- [DatePicker](/tao-ui/components/date-picker)
- [Descriptions](/tao-ui/components/descriptions)
- [Divider](/tao-ui/components/divider)
- [Drawer](/tao-ui/components/drawer)
- [Dropdown](/tao-ui/components/dropdown)
- [Empty](/tao-ui/components/empty)
- [FloatButton](/tao-ui/components/float-button)
- [Form](/tao-ui/components/form)
- [FormActions](/tao-ui/components/form-actions)
- [FormField](/tao-ui/components/form-field)
- [FormSection](/tao-ui/components/form-section)
- [Image](/tao-ui/components/image)
- [Input](/tao-ui/components/input)
- [InputNumber](/tao-ui/components/input-number)
- [List](/tao-ui/components/list)
- [Listy](/tao-ui/components/listy)
- [Masonry](/tao-ui/components/masonry)
- [Mentions](/tao-ui/components/mentions)
- [Modal](/tao-ui/components/modal)
- [Popconfirm](/tao-ui/components/popconfirm)
- [Popover](/tao-ui/components/popover)
- [Progress](/tao-ui/components/progress)
- [QRCode](/tao-ui/components/qr-code)
- [Radio](/tao-ui/components/radio)
- [RangePicker](/tao-ui/components/range-picker)
- [Rate](/tao-ui/components/rate)
- [Result](/tao-ui/components/result)
- [ScrollArea](/tao-ui/components/scroll-area)
- [Segmented](/tao-ui/components/segmented)
- [Select](/tao-ui/components/select)
- [Skeleton](/tao-ui/components/skeleton)
- [Slider](/tao-ui/components/slider)
- [Sonner](/tao-ui/components/sonner)
- [Spinner](/tao-ui/components/spinner)
- [Splitter](/tao-ui/components/splitter)
- [Statistic](/tao-ui/components/statistic)
- [Steps](/tao-ui/components/steps)
- [Switch](/tao-ui/components/switch)
- [Table](/tao-ui/components/table)
- [Tabs](/tao-ui/components/tabs)
- [Tag](/tao-ui/components/tag)
- [TaoProvider](/tao-ui/components/tao-provider)
- [Textarea](/tao-ui/components/textarea)
- [TimePicker](/tao-ui/components/time-picker)
- [Timeline](/tao-ui/components/timeline)
- [Tooltip](/tao-ui/components/tooltip)
- [Tour](/tao-ui/components/tour)
- [Transfer](/tao-ui/components/transfer)
- [Tree](/tao-ui/components/tree)
- [TreeSelect](/tao-ui/components/tree-select)
- [Upload](/tao-ui/components/upload)
- [Watermark](/tao-ui/components/watermark)
## Icons in the commerce showcase62
- Activity
- ArrowLeft
- ArrowRight
- Bell
- ChartColumn
- CheckCheck
- CheckCircle
- ChevronsUpDown
- Clock
- Coins
- Compass
- Copy
- CreditCard
- Download
- Edit
- Eye
- FileText
- FilterClear
- Gift
- Globe
- HelpCircle
- ImagePlus
- Laptop
- Layers
- LayoutDashboard
- LogOut
- Mail
- MapPin
- Megaphone
- MessageCircle
- MessageSquare
- Moon
- MoreHorizontal
- PackageCheck
- Package
- Phone
- Plus
- Printer
- Receipt
- RefreshCw
- Rocket
- RotateCcw
- Save
- Search
- Send
- Settings
- ShieldCheck
- Smartphone
- Sparkles
- Star
- Store
- Sun
- TrendingDown
- TrendingUp
- Trophy
- Truck
- Upload
- UserGroup
- User
- UserPlus
- Users
- Wallet
[Browse all 2,126 icons →](/tao-ui/components/icons)
---
url: https://rickyshin93.github.io/tao-ui/index.md
---
> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.
# tao-ui
Good ideas.
Great interfaces.
> Customizable React components for ideas that deserve a great interface. From your first button to your next big thing.
[Get started](https://rickyshin93.github.io/tao-ui/guide/getting-started) | [Components](https://rickyshin93.github.io/tao-ui/components/button)
## Package contract
- @rockshin/tao-ui 0.0.57 · MIT
- React: ^18.2.0 || ^19.0.0; React DOM: ^18.2.0 || ^19.0.0
- npm install @rockshin/tao-ui
- [AI agent guide](https://rickyshin93.github.io/tao-ui/guide/agents.md)
- [JSON discovery](https://rickyshin93.github.io/tao-ui/agent-manifest.json)