# Kui Vue
> Kui Vue is a Vue 3 desktop component library with TypeScript support.
## Install
```bash
pnpm add kui-vue kui-icons
```
Import `kui-vue/style/index.css`, then import components from `kui-vue` or install the plugin globally.
## Machine-readable resources
- [Complete AI documentation](https://k-ui.cn/llms-full.txt)
- [Component metadata](https://k-ui.cn/kui-components.json)
- [Documentation](https://k-ui.cn/components)
- [GitHub](https://github.com/smallerqiu/kui-vue)
## Components
- [Affix](https://k-ui.cn/components/affix): tags `Affix`, `KAffix`, `k-affix`, `affix`
- [Popup](https://k-ui.cn/components/popup): tags `Popup`, `KPopup`, `k-popup`, `popup`
- [Alert](https://k-ui.cn/components/alert): tags `Alert`, `KAlert`, `k-alert`, `alert`
- [AutoComplete](https://k-ui.cn/components/auto-complete): tags `AutoComplete`, `KAutoComplete`, `k-auto-complete`, `auto-complete`
- [Anchor](https://k-ui.cn/components/anchor): tags `Anchor`, `KAnchor`, `k-anchor`, `anchor`
- [AnchorLink](https://k-ui.cn/components/anchor): tags `AnchorLink`, `KAnchorLink`, `k-anchor-link`, `anchor-link`
- [Avatar](https://k-ui.cn/components/avatar): tags `Avatar`, `KAvatar`, `k-avatar`, `avatar`
- [AvatarGroup](https://k-ui.cn/components/avatar): tags `AvatarGroup`, `KAvatarGroup`, `k-avatar-group`, `avatar-group`
- [Breadcrumb](https://k-ui.cn/components/breadcrumb): tags `Breadcrumb`, `KBreadcrumb`, `k-breadcrumb`, `breadcrumb`
- [BreadcrumbItem](https://k-ui.cn/components/breadcrumb): tags `BreadcrumbItem`, `KBreadcrumbItem`, `k-breadcrumb-item`, `breadcrumb-item`
- [BackTop](https://k-ui.cn/components/back-top): tags `BackTop`, `KBackTop`, `k-back-top`, `back-top`
- [Badge](https://k-ui.cn/components/badge): tags `Badge`, `KBadge`, `k-badge`, `badge`
- [Button](https://k-ui.cn/components/button): tags `Button`, `KButton`, `k-button`, `button`
- [ButtonGroup](https://k-ui.cn/components/button): tags `ButtonGroup`, `KButtonGroup`, `k-button-group`, `button-group`
- [Cascader](https://k-ui.cn/components/cascader): tags `Cascader`, `KCascader`, `k-cascader`, `cascader`
- [Card](https://k-ui.cn/components/card): tags `Card`, `KCard`, `k-card`, `card`
- [CardMeta](https://k-ui.cn/components/card): tags `CardMeta`, `KCardMeta`, `k-card-meta`, `card-meta`
- [Calendar](https://k-ui.cn/components/calendar): tags `Calendar`, `KCalendar`, `k-calendar`, `calendar`
- [FeatureCard](https://k-ui.cn/components/feature-card): tags `FeatureCard`, `KFeatureCard`, `k-feature-card`, `feature-card`
- [FlameWrap](https://k-ui.cn/components/flame-wrap): tags `FlameWrap`, `KFlameWrap`, `k-flame-wrap`, `flame-wrap`
- [ListPanel](https://k-ui.cn/components/list-panel): tags `ListPanel`, `KListPanel`, `k-list-panel`, `list-panel`
- [Carousel](https://k-ui.cn/components/carousel): tags `Carousel`, `KCarousel`, `k-carousel`, `carousel`
- [CarouselItem](https://k-ui.cn/components/carousel-item): tags `CarouselItem`, `KCarouselItem`, `k-carousel-item`, `carousel-item`
- [Checkbox](https://k-ui.cn/components/checkbox): tags `Checkbox`, `KCheckbox`, `k-checkbox`, `checkbox`
- [CheckboxGroup](https://k-ui.cn/components/checkbox): tags `CheckboxGroup`, `KCheckboxGroup`, `k-checkbox-group`, `checkbox-group`
- [CheckCard](https://k-ui.cn/components/check-card): tags `CheckCard`, `KCheckCard`, `k-check-card`, `check-card`
- [CheckCardGroup](https://k-ui.cn/components/check-card): tags `CheckCardGroup`, `KCheckCardGroup`, `k-check-card-group`, `check-card-group`
- [Collapse](https://k-ui.cn/components/collapse): tags `Collapse`, `KCollapse`, `k-collapse`, `collapse`
- [CollapsePanel](https://k-ui.cn/components/collapse): tags `CollapsePanel`, `KCollapsePanel`, `k-collapse-panel`, `collapse-panel`
- [ColorPickerPanel](https://k-ui.cn/components/color-picker-panel): tags `ColorPickerPanel`, `KColorPickerPanel`, `k-color-picker-panel`, `color-picker-panel`
- [ColorPicker](https://k-ui.cn/components/color-picker): tags `ColorPicker`, `KColorPicker`, `k-color-picker`, `color-picker`
- [DatePickerPanel](https://k-ui.cn/components/date-picker-panel): tags `DatePickerPanel`, `KDatePickerPanel`, `k-date-picker-panel`, `date-picker-panel`
- [DatePicker](https://k-ui.cn/components/date-picker): tags `DatePicker`, `KDatePicker`, `k-date-picker`, `date-picker`
- [Descriptions](https://k-ui.cn/components/descriptions): tags `Descriptions`, `KDescriptions`, `k-descriptions`, `descriptions`
- [DescriptionsItem](https://k-ui.cn/components/descriptions): tags `DescriptionsItem`, `KDescriptionsItem`, `k-descriptions-item`, `descriptions-item`
- [Drawer](https://k-ui.cn/components/drawer): tags `Drawer`, `KDrawer`, `k-drawer`, `drawer`
- [Dropdown](https://k-ui.cn/components/dropdown): tags `Dropdown`, `KDropdown`, `k-dropdown`, `dropdown`
- [DropdownButton](https://k-ui.cn/components/dropdown): tags `DropdownButton`, `KDropdownButton`, `k-dropdown-button`, `dropdown-button`
- [Divider](https://k-ui.cn/components/divider): tags `Divider`, `KDivider`, `k-divider`, `divider`
- [Empty](https://k-ui.cn/components/empty): tags `Empty`, `KEmpty`, `k-empty`, `empty`
- [Form](https://k-ui.cn/components/form): tags `Form`, `KForm`, `k-form`, `form`
- [FormItem](https://k-ui.cn/components/form): tags `FormItem`, `KFormItem`, `k-form-item`, `form-item`
- [Flex](https://k-ui.cn/components/flex): tags `Flex`, `KFlex`, `k-flex`, `flex`
- [Grid](https://k-ui.cn/components/grid): tags `Grid`, `KGrid`, `k-grid`, `grid`
- [GridItem](https://k-ui.cn/components/grid): tags `GridItem`, `KGridItem`, `k-grid-item`, `grid-item`
- [Image](https://k-ui.cn/components/image): tags `Image`, `KImage`, `k-image`
- [ImageGroup](https://k-ui.cn/components/image): tags `ImageGroup`, `KImageGroup`, `k-image-group`, `image-group`
- [Icon](https://k-ui.cn/components/icon): tags `Icon`, `KIcon`, `k-icon`, `icon`
- [Input](https://k-ui.cn/components/input): tags `Input`, `KInput`, `k-input`, `input`
- [InputGroup](https://k-ui.cn/components/input): tags `InputGroup`, `KInputGroup`, `k-input-group`, `input-group`
- [TextArea](https://k-ui.cn/components/input): tags `TextArea`, `KTextArea`, `k-text-area`, `text-area`
- [InputTag](https://k-ui.cn/components/input-tag): tags `InputTag`, `KInputTag`, `k-input-tag`, `input-tag`
- [InputOTP](https://k-ui.cn/components/input-otp): tags `InputOTP`, `KInputOTP`, `k-input-otp`, `input-otp`
- [InputNumber](https://k-ui.cn/components/input-number): tags `InputNumber`, `KInputNumber`, `k-input-number`, `input-number`
- [Content](https://k-ui.cn/components/content): tags `Content`, `KContent`, `k-content`, `content`
- [Footer](https://k-ui.cn/components/footer): tags `Footer`, `KFooter`, `k-footer`, `footer`
- [Header](https://k-ui.cn/components/header): tags `Header`, `KHeader`, `k-header`, `header`
- [Layout](https://k-ui.cn/components/layout): tags `Layout`, `KLayout`, `k-layout`, `layout`
- [Sider](https://k-ui.cn/components/layout): tags `Sider`, `KSider`, `k-sider`, `sider`
- [Menu](https://k-ui.cn/components/menu): tags `Menu`, `KMenu`, `k-menu`, `menu`
- [MenuDivider](https://k-ui.cn/components/menu-divider): tags `MenuDivider`, `KMenuDivider`, `k-menu-divider`, `menu-divider`
- [MenuGroup](https://k-ui.cn/components/menu): tags `MenuGroup`, `KMenuGroup`, `k-menu-group`, `menu-group`
- [MenuItem](https://k-ui.cn/components/menu): tags `MenuItem`, `KMenuItem`, `k-menu-item`, `menu-item`
- [SubMenu](https://k-ui.cn/components/menu): tags `SubMenu`, `KSubMenu`, `k-sub-menu`, `sub-menu`
- [Mentions](https://k-ui.cn/components/mentions): tags `Mentions`, `KMentions`, `k-mentions`, `mentions`
- [MessagePanel](https://k-ui.cn/components/message-panel): tags `MessagePanel`, `KMessagePanel`, `k-message-panel`, `message-panel`
- [NoticePanel](https://k-ui.cn/components/notice-panel): tags `NoticePanel`, `KNoticePanel`, `k-notice-panel`, `notice-panel`
- [ModalPanel](https://k-ui.cn/components/modal-panel): tags `ModalPanel`, `KModalPanel`, `k-modal-panel`, `modal-panel`
- [Modal](https://k-ui.cn/components/modal): tags `Modal`, `KModal`, `k-modal`, `modal`
- [Page](https://k-ui.cn/components/page): tags `Page`, `KPage`, `k-page`, `page`
- [PageHeader](https://k-ui.cn/components/page-header): tags `PageHeader`, `KPageHeader`, `k-page-header`, `page-header`
- [PoptipPanel](https://k-ui.cn/components/poptip-panel): tags `PoptipPanel`, `KPoptipPanel`, `k-poptip-panel`, `poptip-panel`
- [Poptip](https://k-ui.cn/components/poptip): tags `Poptip`, `KPoptip`, `k-poptip`, `poptip`
- [PopconfirmPanel](https://k-ui.cn/components/popconfirm-panel): tags `PopconfirmPanel`, `KPopconfirmPanel`, `k-popconfirm-panel`, `popconfirm-panel`
- [Popconfirm](https://k-ui.cn/components/popconfirm): tags `Popconfirm`, `KPopconfirm`, `k-popconfirm`, `popconfirm`
- [Progress](https://k-ui.cn/components/progress): tags `Progress`, `KProgress`, `k-progress`, `progress`
- [Ripple](https://k-ui.cn/components/ripple): tags `Ripple`, `KRipple`, `k-ripple`, `ripple`
- [QRCode](https://k-ui.cn/components/qrcode): tags `QRCode`, `KQRCode`, `k-qr-code`, `qr-code`
- [Radio](https://k-ui.cn/components/radio): tags `Radio`, `KRadio`, `k-radio`, `radio`
- [RadioButton](https://k-ui.cn/components/radio): tags `RadioButton`, `KRadioButton`, `k-radio-button`, `radio-button`
- [RadioGroup](https://k-ui.cn/components/radio): tags `RadioGroup`, `KRadioGroup`, `k-radio-group`, `radio-group`
- [Segmented](https://k-ui.cn/components/segmented): tags `Segmented`, `KSegmented`, `k-segmented`, `segmented`
- [Rate](https://k-ui.cn/components/rate): tags `Rate`, `KRate`, `k-rate`, `rate`
- [Result](https://k-ui.cn/components/result): tags `Result`, `KResult`, `k-result`, `result`
- [FeedbackPanel](https://k-ui.cn/components/feedback-panel): tags `FeedbackPanel`, `KFeedbackPanel`, `k-feedback-panel`, `feedback-panel`
- [Option](https://k-ui.cn/components/select): tags `Option`, `KOption`, `k-option`, `option`
- [Select](https://k-ui.cn/components/select): tags `Select`, `KSelect`, `k-select`, `select`
- [ConfigProvider](https://k-ui.cn/components/config): tags `ConfigProvider`, `KConfigProvider`, `k-config-provider`, `config-provider`
- [Skeleton](https://k-ui.cn/components/skeleton): tags `Skeleton`, `KSkeleton`, `k-skeleton`, `skeleton`
- [SkeletonAvatar](https://k-ui.cn/components/skeleton): tags `SkeletonAvatar`, `KSkeletonAvatar`, `k-skeleton-avatar`, `skeleton-avatar`
- [SkeletonButton](https://k-ui.cn/components/skeleton): tags `SkeletonButton`, `KSkeletonButton`, `k-skeleton-button`, `skeleton-button`
- [SkeletonImage](https://k-ui.cn/components/skeleton): tags `SkeletonImage`, `KSkeletonImage`, `k-skeleton-image`, `skeleton-image`
- [SkeletonText](https://k-ui.cn/components/skeleton): tags `SkeletonText`, `KSkeletonText`, `k-skeleton-text`, `skeleton-text`
- [StatCard](https://k-ui.cn/components/stat-card): tags `StatCard`, `KStatCard`, `k-stat-card`, `stat-card`
- [StatNumber](https://k-ui.cn/components/stat-number): tags `StatNumber`, `KStatNumber`, `k-stat-number`, `stat-number`
- [Slider](https://k-ui.cn/components/slider): tags `Slider`, `KSlider`, `k-slider`, `slider`
- [Space](https://k-ui.cn/components/space): tags `Space`, `KSpace`, `k-space`, `space`
- [Spin](https://k-ui.cn/components/spin): tags `Spin`, `KSpin`, `k-spin`, `spin`
- [Step](https://k-ui.cn/components/steps): tags `Step`, `KStep`, `k-step`, `step`
- [Steps](https://k-ui.cn/components/steps): tags `Steps`, `KSteps`, `k-steps`, `steps`
- [Switch](https://k-ui.cn/components/switch): tags `Switch`, `KSwitch`, `k-switch`
- [Splitter](https://k-ui.cn/components/splitter): tags `Splitter`, `KSplitter`, `k-splitter`, `splitter`
- [SplitterPanel](https://k-ui.cn/components/splitter): tags `SplitterPanel`, `KSplitterPanel`, `k-splitter-panel`, `splitter-panel`
- [Table](https://k-ui.cn/components/table): tags `Table`, `KTable`, `k-table`, `table`
- [TableColumnSetting](https://k-ui.cn/components/table): tags `TableColumnSetting`, `KTableColumnSetting`, `k-table-column-setting`, `table-column-setting`
- [Kanban](https://k-ui.cn/components/kanban): tags `Kanban`, `kanban`
- [TooltipPanel](https://k-ui.cn/components/tooltip-panel): tags `TooltipPanel`, `KTooltipPanel`, `k-tooltip-panel`, `tooltip-panel`
- [Tooltip](https://k-ui.cn/components/tooltip): tags `Tooltip`, `KTooltip`, `k-tooltip`, `tooltip`
- [Tour](https://k-ui.cn/components/tour): tags `Tour`, `KTour`, `k-tour`, `tour`
- [Transfer](https://k-ui.cn/components/transfer): tags `Transfer`, `KTransfer`, `k-transfer`, `transfer`
- [Typography](https://k-ui.cn/components/typography): tags `Typography`, `KTypography`, `k-typography`, `typography`
- [TypographyParagraph](https://k-ui.cn/components/typography-paragraph): tags `TypographyParagraph`, `KTypographyParagraph`, `k-typography-paragraph`, `typography-paragraph`
- [TypographyText](https://k-ui.cn/components/typography-text): tags `TypographyText`, `KTypographyText`, `k-typography-text`, `typography-text`
- [TypographyTitle](https://k-ui.cn/components/typography-title): tags `TypographyTitle`, `KTypographyTitle`, `k-typography-title`, `typography-title`
- [TabPanel](https://k-ui.cn/components/tabs): tags `TabPanel`, `KTabPanel`, `k-tab-panel`, `tab-panel`
- [Tabs](https://k-ui.cn/components/tabs): tags `Tabs`, `KTabs`, `k-tabs`, `tabs`
- [TimeLine](https://k-ui.cn/components/time-line): tags `TimeLine`, `KTimeLine`, `k-time-line`, `time-line`
- [TimeLineItem](https://k-ui.cn/components/time-line): tags `TimeLineItem`, `KTimeLineItem`, `k-time-line-item`, `time-line-item`
- [Tree](https://k-ui.cn/components/tree): tags `Tree`, `KTree`, `k-tree`, `tree`
- [TreeSelect](https://k-ui.cn/components/tree-select): tags `TreeSelect`, `KTreeSelect`, `k-tree-select`, `tree-select`
- [Tag](https://k-ui.cn/components/tag): tags `Tag`, `KTag`, `k-tag`, `tag`
- [Col](https://k-ui.cn/components/row-col): tags `Col`, `KCol`, `k-col`, `col`
- [Row](https://k-ui.cn/components/row-col): tags `Row`, `KRow`, `k-row`, `row`
- [Upload](https://k-ui.cn/components/upload): tags `Upload`, `KUpload`, `k-upload`, `upload`
- [Watermark](https://k-ui.cn/components/watermark): tags `Watermark`, `KWatermark`, `k-watermark`, `watermark`
- [VirtualList](https://k-ui.cn/components/virtual-list): tags `VirtualList`, `KVirtualList`, `k-virtual-list`, `virtual-list`
---
# Affix
Pin page elements within the visible range.
## When to Use
When the content area is long and requires scrolling, the corresponding operations or navigation for this part of the content need to remain visible within the scrolling range. Commonly used for side menus and button combinations.
Use this feature cautiously when the visible area of the page is small to avoid blocking page content.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage.
[Fixed State Change Callback](./demo/callbacks.vue)
- You can get whether it is fixed.
[Scroll Container](./demo/container.vue)
- Use `target` to set the element whose scroll event `Affix` listens to. Defaults to `window`.
[Affix to Bottom](./demo/bottom.vue)
- Use `offsetBottom` to pin an element to the bottom of the viewport.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| offsetTop | Affix after reaching the specified offset from the target top | `number` | 0 |
| offsetBottom | Affix after reaching the specified offset from the target bottom; takes priority over `offsetTop` | `number` | - |
| target | Scroll target observed by Affix | `() => Window \| HTMLElement \| null` | window |
| change | Emitted when the affixed state changes | `(affixed: boolean) => void` | - |
---
# Popup
A generic anchored popup. Dropdown adds menu semantics on top; Popup can display forms, pickers, or arbitrary content. It does not supply a menu role, selection logic, or a focus trap.
```vue
```
## When to use
Use Popup for anchored custom forms, filters, and compound panels. Use Dropdown for menus, Poptip for titled cards, and Tooltip for brief text hints. Popup handles positioning and visibility, not selection, form validation, or focus trapping. Use Modal or Drawer when a modal interaction is needed.
Use the default slot for the trigger and the scoped overlay slot for content; avoid h() in .vue examples. Bind v-model:open for controlled state.
## Examples
[Basic usage and custom content](./demo/basic.vue)
- Render inputs, buttons, or arbitrary content and call close from inside. Mounted content is retained by default; destroyOnClose unmounts it after the exit animation.
[Trigger modes](./demo/trigger.vue)
- Supports click, hover, focus, and contextmenu. Context menus use the pointer position. Hover supports opening/closing delays; see the controlled example for manual mode.
[Placement and arrows](./demo/placement.vue)
- Choose among 12 placements, toggle arrow, and set offset. Placement may adjust when space is limited.
[Controlled state and instance methods](./demo/controlled.vue)
- Interactions update internal visibility and emit changes for external synchronization. Instances expose open / close / updatePosition; this example displays the latest request reason.
[Custom container](./demo/container.vue)
- getPopupContainer selects the mount node, otherwise ConfigProvider or body is used. Establish a positioning context on custom containers. matchTriggerWidth matches the trigger's minimum width; ancestor overflow may clip the popup.
[Nested popups and selectors](./demo/nested.vue)
- Choosing a Select option keeps the outer popup open. Escape dismisses the topmost popup first; dismissing the parent also closes its nested popups.
## Popup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| open | Initial visibility; subsequent changes synchronize the state; Vue supports v-model:open | `boolean` | - |
| disabled | Prevents opening and cancels delayed opening; does not override open | `boolean` | false |
| placement | Popup placement; supports 12 positions | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "left-bottom" \| "left-top" \| "right" \| "right-top" \| "right-bottom"` | bottom-left |
| trigger | Trigger mode; manual uses open or instance methods | `"hover" \| "click" \| "focus" \| "contextmenu" \| "manual"` | click |
| arrow | Show arrow | `boolean` | false |
| offset | Position offset in pixels | `number` | 3 |
| openDelay | Hover opening delay in milliseconds | `number` | 0 |
| closeDelay | Hover / focus closing delay in milliseconds | `number` | 300 |
| closeOnOutsideClick | Close on outside click; nested Popup content counts as inside | `boolean` | true |
| closeOnEscape | Escape closes the top Popup and restores trigger focus | `boolean` | true |
| matchTriggerWidth | Use trigger width as the minimum popup width | `boolean` | false |
| getPopupContainer | Container; falls back to Config or body | `(() => HTMLElement \| null \| undefined)` | - |
| destroyOnClose | Destroy after exit; preserves form state by default | `boolean` | false |
| target | Optional external positioning anchor; no event binding, use with manual and open | `HTMLElement \| Ref` | - |
| overlay | Overlay content; prefer the overlay slot in Vue | `VNodeChild` | - |
| onOpenChange | Visibility change request with reason and native event | `((open: boolean, detail: PopupOpenChangeDetail) => void)` | - |
| onAfterOpen | Called after entering | `(() => void)` | - |
| onAfterClose | Called after leaving | `(() => void)` | - |
The default slot renders the trigger; the overlay slot renders popup content. Both receive PopupRef methods.
## Adapter options
Used by Dropdown, Tooltip, Poptip and Popconfirm to preserve existing appearance.
| Property | Description | Type | Default |
| ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------- | --------- |
| prefixCls | Root CSS prefix | string | k-popup |
| transitionName | Transition CSS prefix | string | prefixCls |
| panelOnly | Inline content only; no positioning, trigger, or global listeners | boolean | false |
| respectDefaultPrevented | Honor preventDefault on trigger click | boolean | true |
| contentStyle | Content container styles | CSSProperties | - |
| hideWhenDetached | Hide when the anchor is outside the viewport | boolean | false |
| triggerAttrs | Attributes forwarded to the trigger | Record | - |
| onTriggerKeydown | Business keyboard handler; preventDefault cancels the default action | (event: KeyboardEvent, popup: PopupRef) => void | - |
## Types and instance methods
| Property | Description | Type | Default |
| ------------------ | ------------------------------------------------------------------------ | -------------------------------------- | ------------ |
| raw | Reuse the single overlay root and preserve its DOM ref; no extra wrapper | boolean | false |
| outsideEvent | Outside pointer event used by legacy selector adapters | `click` \| `mousedown` | click |
| transitionDuration | Transition duration in milliseconds | number | CSS duration |
| getAnchorPosition | Optional viewport point resolver, for caret-anchored Mentions | () => { x: number; y: number } \| null | - |
Select, TreeSelect, Cascader, AutoComplete, Mentions, DatePicker and ColorPicker share this positioning and lifecycle implementation. Their selection, search and keyboard logic remains inside the business components.
- PopupTrigger: hover / click / focus / contextmenu / manual.
- PopupOpenChangeDetail: { reason: PopupOpenReason; event?: Event }.
- PopupOpenReason: trigger / hover / focus / contextmenu / outside / escape / programmatic / host.
- PopupRef: open(), close(), updatePosition(), cancelClose(), scheduleClose(), getTriggerElement(), getPopupElement().
- PopupTarget: HTMLElement or Ref.
- PopupContent: VNodeChild.
Use open to initialize and synchronize visibility. Interactions update internal state and emit onOpenChange. Only hover uses openDelay. External target anchors are position-only. Custom trigger components must forward attributes, events, and the DOM ref.
---
# Alert
Warning prompts to display information that needs attention.
## When to Use
- When a page needs to display warning information to the user.
- A non-overlay static display form, always displayed, does not disappear automatically, users can click to close.
## Examples
[Basic Usage](./demo/basic.vue)
- Control the display type via `type`.
[Icon](./demo/icon.vue)
- Use `showIcon` to control whether the icon is displayed.
[Closable](./demo/close.vue)
- Use `closable` to control whether the close button is displayed, with smooth and natural closing animation.
[Custom Icon](./demo/custom-icon.vue)
- Use `showIcon` to control whether the icon is displayed.
## Closing
Clicking the close button triggers `close`. After the exit animation, the content is removed and `afterClose` fires.
To unmount the entire component after closing, update the parent state in `afterClose` and use `v-if`.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| type | Alert type, optional values are `success`, `info`, `warning`, `error` or not set | `"info" \| "success" \| "warning" \| "error"` | warning |
| message | Alert content | `string` | - |
| description | Auxiliary text introduction for the alert | `string` | - |
| showIcon | Whether to show the icon | `boolean` | false |
| closable | Whether to show the close button | `boolean` | false |
| bordered | Whether to display the border | `boolean` | false |
| onClose | Triggered when the close button is clicked | `(event: MouseEvent) => void` | - |
| onAfterClose | Triggered after the exit animation | `() => void` | - |
| icon | Custom icon | `IconType[]` | - |
| theme | Appearance: `default`, `fill`, `outline`, or `plain` | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | default |
| shape | Shape: `round`, `circle`, or `square` | `"default" \| "circle" \| "square" \| "round"` | round |
---
# AutoComplete
Provide candidates based on the input while retaining the ability for free text entry.
## Examples
[Basic](./demo/basic.vue)
- Supports free input, filtering, and keyboard selection.
[Controlled value](./demo/controlled.vue)
- Manage and update the input through v-model.
[Custom filter](./demo/filter.vue)
- Define matching behavior with filterOption.
[Size, theme and shape](./demo/appearance.vue)
- Shows several appearance combinations.
[Show on empty](./demo/show-on-empty.vue)
- The dropdown stays closed for an empty input by default; enable `showOnEmpty` to show all suggestions.
[Remote search](./demo/remote.vue)
- Fetch suggestions on `search` and display the loading state with `loading`.
## AutoComplete API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Value (v-model) | `string` | - |
| value | Initial value | `string` | '' |
| options | Suggestions | `(string \| AutoCompleteOption)[]` | [] |
| open | open state | `boolean` | - |
| showOnEmpty | Show suggestions when an empty input is focused | `boolean` | false |
| clearable | Show the clear button on hover when a value exists | `boolean` | false |
| disabled | Disabled | `boolean` | false |
| readonly | Read-only; prevents editing, clearing and opening | `boolean` | false |
| loading | Loading state | `boolean` | false |
| loadingText | Loading text | `string` | Loading |
| placeholder | Placeholder | `string` | - |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| theme | Theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | default |
| filterOption | Filter strategy | `boolean \| ((input: string, option: AutoCompleteOption) => boolean)` | true |
| onChange | Value change | `(value: string) => void` | - |
| onClear | Clear callback | `() => void` | - |
| onSearch | Search callback | `(value: string) => void` | - |
| onSelect | Option selection | `(value: string, option: AutoCompleteOption) => void` | - |
| onOpenChange | Open state change | `(open: boolean) => void` | - |
---
# Anchor
It is necessary to display the anchor links available for navigation on the current page and enable quick jumps between anchors.
## Examples
[Basic Usage (Sidebar Navigation)](./demo/basic.vue?show=vertical)
- The most common scenario: displaying a long article on the right with fixed anchor navigation on the left or right side.
[Nested Anchors (Complex Document Structure)](./demo/nested-anchors.vue?show=vertical)
- Suitable for documents with multi-level headings.
[Specify container (positioning within a scrolling container)](./demo/within-container.vue?show=vertical)
- If your page does not scroll in full screen but within a specific div.
## Anchor API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| affix | Whether to use sticky positioning | `boolean` | true |
| offsetTop | Offset from the container top for positioning and activation | `number` | 0 |
| bounds | Anchor activation boundary | `number` | 5 |
| container | Scroll container | `string \| Window \| HTMLElement` | window |
| change | Emitted when the active anchor changes | `(activeLink: string) => void` | - |
| click | Emitted when an anchor is clicked | `(link: string) => void` | - |
## AnchorLink API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| href | Anchor link | `string` | - |
| title | Text content, customizable via the named slot | `string` | - |
---
# Anchor
It is necessary to display the anchor links available for navigation on the current page and enable quick jumps between anchors.
## Examples
[Basic Usage (Sidebar Navigation)](./demo/basic.vue?show=vertical)
- The most common scenario: displaying a long article on the right with fixed anchor navigation on the left or right side.
[Nested Anchors (Complex Document Structure)](./demo/nested-anchors.vue?show=vertical)
- Suitable for documents with multi-level headings.
[Specify container (positioning within a scrolling container)](./demo/within-container.vue?show=vertical)
- If your page does not scroll in full screen but within a specific div.
## Anchor API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| affix | Whether to use sticky positioning | `boolean` | true |
| offsetTop | Offset from the container top for positioning and activation | `number` | 0 |
| bounds | Anchor activation boundary | `number` | 5 |
| container | Scroll container | `string \| Window \| HTMLElement` | window |
| change | Emitted when the active anchor changes | `(activeLink: string) => void` | - |
| click | Emitted when an anchor is clicked | `(link: string) => void` | - |
## AnchorLink API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| href | Anchor link | `string` | - |
| title | Text content, customizable via the named slot | `string` | - |
---
# Avatar
Used to represent users or things, supports image, icon, or character display.
## Examples
[Basic](./demo/basic.vue)
- Avatars support preset and custom sizes, with three available shapes.
[Types](./demo/types.vue)
- Three types are supported: Image, Icon, and Text. Icon and Text avatars support custom icon color and background color.
[With logo and grouping](./demo/badge-group.vue)
- Typically used for message prompts and avatar combination display.
[Auto Font Size Adjustment](./demo/change.vue)
- For text avatars, when the string is long, the font size automatically adjusts based on the avatar width.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Avatar icon; overrides the default User fallback when an image fails | `IconType[]` | - |
| shape | Avatar shape | `"circle" \| "square" \| "round"` | circle |
| size | Avatar size | `AvatarSize` | default |
| src | Image source | `string` | - |
| alt | Alternative text when the image cannot be displayed | `string` | - |
| onError | Image error callback; return `false` to prevent rendering fallback | `((event: Event) => boolean \| void)` | - |
## AvatarGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| maxCount | Maximum number of avatars to display | `number` | - |
| size | Sets child size and adjusts their overlap proportionally | `AvatarSize` | default |
| spacing | Child avatar overlap in pixels; `0` disables overlap | `number` | auto |
| shape | Sets the shape of all child avatars | `"circle" \| "square" \| "round"` | circle |
---
# Avatar
Used to represent users or things, supports image, icon, or character display.
## Examples
[Basic](./demo/basic.vue)
- Avatars support preset and custom sizes, with three available shapes.
[Types](./demo/types.vue)
- Three types are supported: Image, Icon, and Text. Icon and Text avatars support custom icon color and background color.
[With logo and grouping](./demo/badge-group.vue)
- Typically used for message prompts and avatar combination display.
[Auto Font Size Adjustment](./demo/change.vue)
- For text avatars, when the string is long, the font size automatically adjusts based on the avatar width.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Avatar icon; overrides the default User fallback when an image fails | `IconType[]` | - |
| shape | Avatar shape | `"circle" \| "square" \| "round"` | circle |
| size | Avatar size | `AvatarSize` | default |
| src | Image source | `string` | - |
| alt | Alternative text when the image cannot be displayed | `string` | - |
| onError | Image error callback; return `false` to prevent rendering fallback | `((event: Event) => boolean \| void)` | - |
## AvatarGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| maxCount | Maximum number of avatars to display | `number` | - |
| size | Sets child size and adjusts their overlap proportionally | `AvatarSize` | default |
| spacing | Child avatar overlap in pixels; `0` disables overlap | `number` | auto |
| shape | Sets the shape of all child avatars | `"circle" \| "square" \| "round"` | circle |
---
# Breadcrumb
Displays the current page's position in the system hierarchy and allows navigation upwards.
## When to Use
- When the system has more than two levels of hierarchy.
- When you need to inform the user 'where you are'.
- When upward navigation functionality is needed.
## Examples
[Basic Usage](./demo/basic.vue)
- Add navigation links via `href`.
[Set Icon](./demo/icon.vue)
- Set the icon via `icon`.
[Separator](./demo/separator.vue)
- Set the separator via the `separator` property or slot.
## Breadcrumb API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| separator | Custom separator | `string \| number \| boolean \| void \| VNode \| VNodeArrayChildren \| null` | `/` |
## BreadcrumbItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| href | Link URL | `string` | - |
| target | Link browsing context | `string` | - |
| rel | Link relationship | `string` | - |
| icon | Item icon | `IconType[]` | - |
| onClick | Called when the item is clicked | `(event: MouseEvent) => void` | - |
---
# Breadcrumb
Displays the current page's position in the system hierarchy and allows navigation upwards.
## When to Use
- When the system has more than two levels of hierarchy.
- When you need to inform the user 'where you are'.
- When upward navigation functionality is needed.
## Examples
[Basic Usage](./demo/basic.vue)
- Add navigation links via `href`.
[Set Icon](./demo/icon.vue)
- Set the icon via `icon`.
[Separator](./demo/separator.vue)
- Set the separator via the `separator` property or slot.
## Breadcrumb API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| separator | Custom separator | `string \| number \| boolean \| void \| VNode \| VNodeArrayChildren \| null` | `/` |
## BreadcrumbItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| href | Link URL | `string` | - |
| target | Link browsing context | `string` | - |
| rel | Link relationship | `string` | - |
| icon | Item icon | `IconType[]` | - |
| onClick | Called when the item is clicked | `(event: MouseEvent) => void` | - |
---
# BackTop
Button to return to the top of the page.
## When to Use
- When the page content area is relatively long.
- When users need to frequently return to the top to view related content.
## Examples
[Basic Usage](./demo/basic.vue)
- The default position is 50px from the right and bottom of the page. It appears after scrolling 100px.
[Custom button](./demo/custom.vue)
- You can customize the back-to-top button style, for example setting `bottom` to `100px`.
[Custom scroll container](./demo/target.vue)
- Use `target` to specify the scroll container to observe and return to the top.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| height | The BackTop component is displayed only when the scroll height reaches this value | `number` | 100 |
| bottom | Distance from the bottom | `string \| number` | 50 |
| right | Distance from the right | `string \| number` | 50 |
| behavior | Scroll behavior | `"auto" \| "instant" \| "smooth"` | smooth |
| onClick | Triggered when the button is clicked | `(event: MouseEvent) => void` | - |
| onVisibleChange | Triggered when visibility changes | `(visible: boolean) => void` | - |
| target | Scroll container | `() => HTMLElement \| null` | () => document.body |
---
# Badge
Circular badge number in the upper right corner of an icon.
## When to Use
Generally appears in the upper right corner of notification icons or avatars, used to display the number of messages that need processing, attracting user attention through eye-catching visual forms.
## Examples
[Basic Usage](./demo/basic.vue)
- Basic usage of `Badge`.
[Dot](./demo/dot.vue)
- Set `dot` to display a dot.
[Max Value / Custom](./demo/max.vue)
- Use `max-count` with `count`. In numeric mode, values exceeding the max will be hidden. If `count` is not a number, it will not be calculated.
[Standalone Usage](./demo/mark.vue)
- Using without wrapping any element makes it standalone and allows custom styling. The badge in the top-right corner is limited to red.
[Controlled](./demo/dynamic.vue)
- Numeric counts roll upward when increasing and downward when decreasing. Text counts and overflow labels such as `99+` update without rolling.
[Status Dot](./demo/status.vue)
- A small dot used to indicate status.
[Colorful Badge](./demo/color.vue)
- Multiple preset color styles for different scenarios. If presets do not meet your needs, you can set a specific color value.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| count | The text to display | `string \| number` | - |
| color | Badge color | `string` | - |
| maxCount | The maximum numeric value to display. Values above this will be shown with a '+' sign | `number` | 99 |
| dot | Do not display the number, only a small red dot | `boolean` | false |
| pill | Use a pill appearance for a status badge | `boolean` | false |
| text | If status is set, text sets the display text of the status dot | `string \| VNode` | '' |
| status | Set Badge as a status dot | `"default" \| "success" \| "warning" \| "error"` | '' |
| active | The dot is in the active state. | `boolean` | false |
---
# Button
The icon prop accepts icon data imported from `kui-icons`, not a string or rendered `Icon` element. Use `:icon="Search"`, not `icon="Search"` or `:icon="h(Icon, ...)"`. Custom components belong in the default slot.
Buttons are used to initiate an immediate operation.
## When to Use
Marks one (or encapsulates a group of) operation commands, responds to user click behavior, and triggers the corresponding business logic.
## Component Registration
```js
import { Button } from "kui-vue";
Vue.use(Button);
```
## Examples
[Basic Usage](./demo/basic.vue)
- Use the `type` property to define a `Button`.
[Theme](./demo/theme.vue)
- Use `theme` to display different appearances.
[Color Variants](./demo/color.vue)
- Use `color` to create more button variants.
[With Icon](./demo/with-icon.vue)
- Set the button icon by adding the `icon` property.
[Size](./demo/size.vue)
- `small` for small size, `large` for large size.
[Disabled](./demo/disabled.vue)
- Add the `disabled` property to make the button unavailable.
[Loading State](./demo/loading.vue)
- Add the `loading` property to put the button in a loading state.
[Block Button](./demo/block.vue)
- The `block` property makes the button fit the width of its parent.
[Button Group](./demo/group.vue)
- Place multiple `Button` components inside `ButtonGroup` to group them.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| type | Set the button type | `"default" \| "link" \| "warning" \| "text" \| "primary" \| "danger"` | - |
| htmlType | Set the native type value of the button | `"button" \| "submit" \| "reset"` | button |
| disabled | Disabled state of the button | `boolean` | false |
| size | Button size, | `"small" \| "medium" \| "large"` | - |
| color | Preset semantic color | `"default" \| "red" \| "orange" \| "yellow" \| "olive" \| "green" \| "teal" \| "blue" \| "volcano" \| "violet" \| "cyan" \| "gold" \| "lime" \| "magenta" \| "purple" \| "pink" \| "brown" \| "gray"` | - |
| shape | When shape=circle, presents a circular button | `"default" \| "circle" \| "square" \| "round"` | false |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| icon | Icon definition imported from kui-icons (e.g. Search), not a string or rendered Icon element | `IconType[]` | - |
| loading | Whether the button is in loading mode | `boolean` | false |
| href | The address to jump to when clicked. Specifying this property makes the button behave like an a link | `string` | - |
| target | Equivalent to the target attribute of an a link, takes effect when href exists | `string` | - |
| block | Option to fit button width to its parent width | `boolean` | false |
---
# Button
The icon prop accepts icon data imported from `kui-icons`, not a string or rendered `Icon` element. Use `:icon="Search"`, not `icon="Search"` or `:icon="h(Icon, ...)"`. Custom components belong in the default slot.
Buttons are used to initiate an immediate operation.
## When to Use
Marks one (or encapsulates a group of) operation commands, responds to user click behavior, and triggers the corresponding business logic.
## Component Registration
```js
import { Button } from "kui-vue";
Vue.use(Button);
```
## Examples
[Basic Usage](./demo/basic.vue)
- Use the `type` property to define a `Button`.
[Theme](./demo/theme.vue)
- Use `theme` to display different appearances.
[Color Variants](./demo/color.vue)
- Use `color` to create more button variants.
[With Icon](./demo/with-icon.vue)
- Set the button icon by adding the `icon` property.
[Size](./demo/size.vue)
- `small` for small size, `large` for large size.
[Disabled](./demo/disabled.vue)
- Add the `disabled` property to make the button unavailable.
[Loading State](./demo/loading.vue)
- Add the `loading` property to put the button in a loading state.
[Block Button](./demo/block.vue)
- The `block` property makes the button fit the width of its parent.
[Button Group](./demo/group.vue)
- Place multiple `Button` components inside `ButtonGroup` to group them.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| type | Set the button type | `"default" \| "link" \| "warning" \| "text" \| "primary" \| "danger"` | - |
| htmlType | Set the native type value of the button | `"button" \| "submit" \| "reset"` | button |
| disabled | Disabled state of the button | `boolean` | false |
| size | Button size, | `"small" \| "medium" \| "large"` | - |
| color | Preset semantic color | `"default" \| "red" \| "orange" \| "yellow" \| "olive" \| "green" \| "teal" \| "blue" \| "volcano" \| "violet" \| "cyan" \| "gold" \| "lime" \| "magenta" \| "purple" \| "pink" \| "brown" \| "gray"` | - |
| shape | When shape=circle, presents a circular button | `"default" \| "circle" \| "square" \| "round"` | false |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| icon | Icon definition imported from kui-icons (e.g. Search), not a string or rendered Icon element | `IconType[]` | - |
| loading | Whether the button is in loading mode | `boolean` | false |
| href | The address to jump to when clicked. Specifying this property makes the button behave like an a link | `string` | - |
| target | Equivalent to the target attribute of an a link, takes effect when href exists | `string` | - |
| block | Option to fit button width to its parent width | `boolean` | false |
---
# Cascader
A cascading selection box.
## When to Use
- Used for selecting from a set of related data collections, such as provinces/cities/districts, company hierarchies, or category classifications.
- Ideal for selecting from large datasets by separating them into multiple hierarchical levels for easier navigation.
- Offers a better user experience compared to the Select component by allowing selections to be completed within a single floating layer.
## Examples
[Basic](./demo/basic.vue)
- The most basic cascader usage. Enable `showAllLevels` to display the complete administrative path selected by the user in the input box.
[Trigger and Levels](./demo/hover.vue)
- Hover trigger + Display only the last level. In e-commerce back-office systems when managing products or publishing listings, category trees are often extremely deep. Using `expandTrigger="hover"` significantly reduces the number of clicks required, while `showAllLevels="false"` keeps the interface cleaner after selection.
[Disabled](./demo/disabled.vue)
- When assigning system permissions or dispatching work orders, certain departments or inactive sub-branches (e.g., subsidiaries under rectification) need to be grayed out entirely. Utilizing the `disabled` property allows locking all paths underneath with one setting.
[Async Loading](./demo/async.vue)
- Load child options on demand. Loading state is shown and failed loads can be retried.
[Size](./demo/size.vue)
- Demonstrates the component's strong visual adaptability across different `size` constraints, suitable for various layouts such as compact modal forms or spacious configuration panels.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Array of path values bound through `v-model` (e.g., `['zhejiang', 'hangzhou', 'xihu']`). | `CascaderValue` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `CascaderValue` | `[]` |
| options | Tree-structured data source for cascading options. | `CascaderOption[]` | `[]` |
| placeholder | Fallback placeholder text displayed when no path is selected. | `string` | `"Please select"` |
| disabled | Whether to completely disable interaction for the entire component. | `boolean` | `false` |
| readonly | Read-only; prevents opening, clearing and changing. | `boolean` | `false` |
| clearable | Whether to support clearing the selected path with one click. | `boolean` | `true` |
| size | Size specification of the component. Options: `'large'` \| `'small'` \| `undefined`. | `"small" \| "medium" \| "large"` | `undefined` |
| expandTrigger | Interaction mode for expanding the next-level menu. Options: `'click'` or `'hover'`. | `"hover" \| "click"` | `'click'` |
| showAllLevels | Whether to display the full selected ancestor path. If `false`, only the final leaf node is shown in the input box. | `boolean` | `true` |
| separator | Separator between labels of different levels when `showAllLevels` is enabled. | `string` | `" / "` |
| bordered | Whether to display borders | `boolean` | true |
| theme | Theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| showArrow | Whether to display the dropdown button | `boolean` | true |
| icon | Custom Icon | `IconType[]` | - |
| shape | shape='circle' 时呈现圆角 | `"default" \| "circle" \| "square" \| "round"` | - |
| placement | Dropdown orientation | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | - |
| emptyText | No data available. | `string` | 'No Data' |
| loadData | Loads children asynchronously; return them or update `option.children` | `CascaderLoadData` | - |
| arrowIcon | Custom arrow icon | `IconType[]` | - |
## Events
| Event | Description | Signature |
| ------------ | ----------------------------------------- | -------------------------------- |
| change | Called when a path is selected or cleared | `(value: CascaderValue) => void` |
| expandChange | Called when the expanded path changes | `(value: CascaderValue) => void` |
| openChange | Called when dropdown visibility changes | `(open: boolean) => void` |
## CascaderOption
When configuring the `options` data source for `Cascader`, each node must conform to the `CascaderOption` object specification. It supports infinite nesting:
| Property | Description | Type | Default |
| :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------- | :---------- |
| value | **Required.** Unique identifier for the current node (often corresponds to backend `id` or `code`). When the full path is selected, `v-model` collects an array composed of these values. | string \| number | - |
| label | **Required.** Plain text content displayed to users in the dropdown menu and input box (e.g., `"Zhejiang"`, `"Hangzhou"`). | string | - |
| disabled | Whether to disable the current option. When enabled, the row appears grayed out and unclickable, and all its child levels will be locked synchronously. | boolean | `false` |
| children | Data source for the next-level child nodes. When this property exists and the array is not empty, a right-facing expansion arrow is automatically rendered on the component. | CascaderOption[] | `undefined` |
| isLeaf | Whether this is a leaf node. Set to `false` when children can be loaded. | boolean | `undefined` |
---
# Card
Universal card container.
## When to Use
The most basic card container, can carry text, lists, images, paragraphs, often used in backend overview pages.
## Examples
[Basic Usage](./demo/basic.vue)
- Set the title and icon via `title` and `icon`.
[Card Size](./demo/size.vue)
- Use `size` to adjust the spacing density of the card header and content.
[Border](./demo/border.vue)
- Use `bordered` to control whether the border is displayed.
[Border and Title](./demo/notitle.vue)
- Control the border with the `bordered` property and the title with the `title` property.
[Cover and Meta](./demo/cover.vue?show=vertical)
- Display a cover image with `cover`, and use `CardMeta` for an avatar, title, and description.
[Appearance](./demo/appearance.vue)
- Card shares the common `theme` and `shape` appearance system.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Card title | `string` | - |
| icon | Icon for the card title | `IconType[]` | - |
| bordered | Whether the card displays a border | `boolean` | true |
| theme | Surface theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Surface shape | `"square" \| "round"` | round |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| extra | Card title extension | slot | - |
| cover | Card cover; hides the card header when set | `VNodeChild` | - |
## CardMeta API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| avatar | Avatar | `VNodeChild` | - |
| title | Title | `VNodeChild` | - |
| description | Description | `VNodeChild` | - |
---
# Card
Universal card container.
## When to Use
The most basic card container, can carry text, lists, images, paragraphs, often used in backend overview pages.
## Examples
[Basic Usage](./demo/basic.vue)
- Set the title and icon via `title` and `icon`.
[Card Size](./demo/size.vue)
- Use `size` to adjust the spacing density of the card header and content.
[Border](./demo/border.vue)
- Use `bordered` to control whether the border is displayed.
[Border and Title](./demo/notitle.vue)
- Control the border with the `bordered` property and the title with the `title` property.
[Cover and Meta](./demo/cover.vue?show=vertical)
- Display a cover image with `cover`, and use `CardMeta` for an avatar, title, and description.
[Appearance](./demo/appearance.vue)
- Card shares the common `theme` and `shape` appearance system.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Card title | `string` | - |
| icon | Icon for the card title | `IconType[]` | - |
| bordered | Whether the card displays a border | `boolean` | true |
| theme | Surface theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Surface shape | `"square" \| "round"` | round |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| extra | Card title extension | slot | - |
| cover | Card cover; hides the card header when set | `VNodeChild` | - |
## CardMeta API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| avatar | Avatar | `VNodeChild` | - |
| title | Title | `VNodeChild` | - |
| description | Description | `VNodeChild` | - |
---
# Calendar
A monthly calendar for dates and events.
## Demos
[Basic](./demo/basic.vue?show=vertical)
- Display events, select a date and handle event clicks.
[Custom content](./demo/custom.vue?show=vertical)
- Customize events, overflow content and the toolbar with slots.
[Locale](./demo/locale.vue?show=vertical)
- Calendar and DatePicker read the same ConfigProvider locale while allowing local overrides.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected date in `YYYY-MM-DD` format; supports `v-model` | `string` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string` | - |
| events | Calendar events | `CalendarEventData[]` | `[]` |
| firstDayOfWeek | First weekday, where 0 is Sunday | `number` | locale |
| maxEvents | Maximum visible events per day | `number` | 3 |
| showToolbar | Show the calendar toolbar | `boolean` | true |
| todayText | Today button text | `string` | locale |
| weekdays | Labels ordered from Sunday to Saturday | `string[]` | locale |
| title | Custom month title, scoped with `{ year, month }` | VNodeChild | - |
| extra | Extra toolbar content | VNodeChild | - |
| dateCell | Custom date-cell heading, scoped with `CalendarDateCell` | VNodeChild | - |
| event | Custom event content, scoped with `{ event, cell }` | VNodeChild | - |
| more | Custom overflow indicator, scoped with `{ count, cell }` | VNodeChild | - |
Calendar and DatePicker do not share internal state, but both read the same `ConfigProvider locale`. DatePicker selects dates or times; Calendar presents a month and its events, so they can be used together.
When a date cell is focused, use the arrow keys to move, `Home` or `End` to move within the current week, and `Enter` or Space to select. Selecting a date from an adjacent month also changes the displayed month.
### CalendarEventData
| Field | Description | Type | Required |
| ----- | --------------------------------- | ---------------- | -------- |
| key | Unique event key | string \| number | yes |
| date | Event date in `YYYY-MM-DD` format | string | yes |
| title | Event title | string | yes |
| time | Time text | string | no |
| color | Event indicator color | string | no |
## Events
| Event | Description | Callback |
| ----------- | --------------------------------------------------- | ------------------------------------------------------------ |
| change | Emitted when a date or the Today button is selected | `(date: string, cell: CalendarDateCell) => void` |
| monthChange | Emitted when the displayed month changes | `(value: { year: number; month: number }) => void` |
| eventClick | Emitted when an event is clicked | `(event: CalendarEventData, cell: CalendarDateCell) => void` |
---
# FeatureCard
Used to present product features, navigation entries, or capability descriptions.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Use `icon`, `title`, and `desc` to present feature information.
[Border](./demo/bordered.vue?show=vertical)
- Use `bordered` to control whether the border is displayed.
[Sizes](./demo/size.vue?show=vertical)
- Use `size` to scale padding, icon and typography together.
[Navigation entry](./demo/interactive.vue?show=vertical)
- Combine `direction="vertical"` and `clickable` for a keyboard-accessible feature entry.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Icon, customizable via the named slot | `IconType[]` | - |
| title | Title, customizable via the named slot | `string` | - |
| desc | Description, customizable via the named slot | `string` | - |
| bordered | Whether to show border | `boolean` | false |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Card shape | `"square" \| "round"` | round |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| direction | Content direction | `"horizontal" \| "vertical"` | horizontal |
| clickable | Enable interaction and keyboard semantics | `boolean` | false |
| disabled | Disable interaction | `boolean` | false |
| color | Icon accent color | `string` | primary |
| iconBackground | Icon container background; derived from `color` when omitted | `string` | auto |
| extra | Trailing content | VNodeChild | - |
## Events
| Event | Description | Callback |
| ----- | -------------------- | ----------------------------- |
| click | Emitted when clicked | `(event: MouseEvent) => void` |
---
# FlameWrap
Draws animated flames, sparks, smoke, and heat refraction around live content.
## Browser support
Full burning and refraction rely on the experimental HTML-in-Canvas API. Test it in Chrome Canary 149+ with `chrome://flags/#canvas-draw-element` enabled. Production usage requires the HTML-in-Canvas Origin Trial. Other browsers preserve the content and fall back to the outer flame effect.
[Basic](./demo/basic.vue?show=vertical)
- Wraps interactive content with the default cool flame.
[Custom flame](./demo/custom.vue?show=vertical)
- Configures warm color, sparks, smoke, and animation speed.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| color | Flame RGB values in the 0–1 range | `[number, number, number]` | `[0.31, 0.54, 1]` |
| intensity | Overall brightness | `number` | `0.5` |
| height | Top flame reach in px | `number` | `170` |
| spread | Side and bottom glow reach | `number` | `8` |
| radius | Burning outline radius | `number` | `40` |
| speed | Animation speed multiplier | `number` | `0.25` |
| scale | Flame detail | `number` | `0.75` |
| turbulence | Turbulence amplitude | `number` | `0.5` |
| turbulenceScale | Turbulence frequency | `number` | `0.5` |
| turbulenceReach | Heat distortion reach | `number` | `25` |
| sparks | Spark brightness; `0` disables it | `number` | `1.5` |
| sparkSize | Spark size multiplier | `number` | `0.35` |
| sparkDensity | Spark density multiplier | `number` | `1` |
| sparkSpeed | Spark movement speed | `number` | `1` |
| rim | Molten rim strength | `number` | `2.5` |
| melt | Distance flames eat into the outline | `number` | `4.5` |
| distortion | Heat-refraction strength | `number` | `10` |
| smoke | Smoke amount | `number` | `1.5` |
| ember | Ember brightness | `number` | `2` |
| scorch | Charring strength | `number` | `0` |
Use the default slot for content wrapped by the effect.
---
# ListPanel
Provides a consistent layout for filters, result summaries, list content and pagination. It can contain a Table, Kanban or card list.
## Demos
[Query list](./demo/basic.vue?show=vertical)
- Organize filters and result counts with `filters` and `summary`.
[Toolbar actions](./demo/actions.vue?show=vertical)
- Place reset, create and other list-level controls in `actions`.
[Pagination and appearance](./demo/footer.vue?show=vertical)
- Put pagination in `footer` and adjust appearance with `size`, `shape` and `theme`.
[Bulk actions](./demo/selection.vue?show=vertical)
- Replace the regular toolbar with `selection` while Table rows are selected.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| summary | Result summary, customizable via the named slot | `VNodeChild` | - |
| bordered | Show border | `boolean` | true |
| theme | Panel theme | `"fill" \| "outline" \| "plain"` | outline |
| shape | Panel shape | `"square" \| "round"` | round |
| size | Panel size | `"small" \| "medium" \| "large"` | medium |
| selectedCount | Current selection count used to show bulk actions | `number` | 0 |
| filters | Query controls | VNodeChild | - |
| actions | Toolbar actions | VNodeChild | - |
| selection | Bulk action toolbar, scoped with `{ count }` | VNodeChild | - |
| footer | Pagination or footer actions | VNodeChild | - |
---
# Carousel
A set of rotating/carousel areas.
## When to Use
- When there is a set of peer content.
- When content space is insufficient, it can be accommodated in a carousel form for rotational display.
- Often used for a set of image or card carousels.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest usage. You can specify the initial value via `value (v-model)`.
[Vertical](./demo/vertical.vue?show=vertical)
- Enable vertical mode by setting `vertical`. In this mode, left and right arrows are hidden.
[Autoplay](./demo/autoplay.vue?show=vertical)
- Enable timed autoplay by setting `autoplay`. Use `delay` to set the interval. The default is `3000` milliseconds.
## API
Touch swiping and mouse dragging are enabled by default; set `swipeable` to `false` to disable both. Both horizontal and `vertical` modes follow the pointer.
Movement below 5px is ignored. Short swipes within 300ms advance in the gesture direction;
longer gestures advance when their own travel reaches half a slide or their release
velocity reaches 0.5px/ms in the drag direction. Unfinished animation travel is not
subtracted from the gesture distance. At most one adjacent slide is selected per gesture.
Velocity also affects the decelerating settling animation.
An ongoing animation can be grabbed again without waiting for it to finish.
Horizontal carousels preserve vertical page scrolling;
vertical carousels preserve horizontal scrolling. Inputs and buttons do not initiate dragging.
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | The index of the slide, starting from 0. Can use `v-model` for two-way binding | `number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `number` | 0 |
| loop | Whether to enable loop | `boolean` | true |
| swipeable | Enable touch swiping and mouse dragging with pointer-following movement | `boolean` | true |
| vertical | Whether to display in vertical mode | `boolean` | false |
| autoplay | Whether to auto-switch | `boolean` | false |
| delay | The time interval for auto-switching, in milliseconds | `number` | 3000 |
| height | The height of the slide | `number` | 256(px) |
| dots | Whether to show the dots at the bottom of the gallery | `boolean` | true |
## Events
| Event | Description | Type |
| --- | --- | --- |
| change | Emitted when the active slide changes | `(value: number) => void` |
## Expose
| Method | Description | Parameters |
| ------ | ------------------------- | --------------- |
| next | Go to the next slide | - |
| prev | Go to the previous slide | - |
| goTo | Go to the specified slide | (index: number) |
---
# CarouselItem
See https://k-ui.cn/components/carousel-item.
---
# Checkbox
Checkbox for multiple selections.
## When to Use
- When making multiple selections from a set of options.
- Used alone, it can represent switching between two states, similar to a switch. The difference is that switching a switch directly triggers a state change, while a checkbox is generally used for state marking and needs to cooperate with submission operations.
## Examples
[Single Selection](./demo/basic.vue)
- When used alone, a `v-model` value of `true` means checked, and `false` means unchecked.
[Multiple Selection](./demo/group.vue)
- You can use the `options` property to define options, or use child components instead.
[Group Layout](./demo/group-layout.vue)
- Group layout.
[Disabled / Controlled](./demo/disabled.vue)
- Set disabled state via `disabled`.
[Select All](./demo/check-all.vue)
- Select-all combination.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| checked | Checked state; supports `v-model:checked` | `boolean` | false |
| label | The text to display | `string \| number` | - |
| value | The value represented when used in combination | `string \| number \| boolean` | - |
| disabled | Whether the current item is disabled | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be toggled | `boolean` | false |
| indeterminate | Combined auxiliary option controls the indeterminate state | `boolean` | false |
| modelValue | Standalone state bound through `v-model` | `string \| number \| boolean` | - |
| theme | Component theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| valueType | The type of output value for the unit option | `"string" \| "number" \| "boolean"` | boolean |
| onChange | Callback when the option state changes | `(event: CheckboxChangeEvent) => void` | - |
## CheckboxGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected values; supports `v-model` | `CheckboxValue[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `CheckboxValue[]` | [] |
| disabled | Whether the component is disabled | `boolean` | false |
| readonly | Whether the group is read-only | `boolean` | false |
| onChange | Triggered when the option state changes, returns the currently selected item and state | `(value: CheckboxValue[]) => void` | - |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| options | Can specify child `checkbox` items | `CheckboxOption[]` | - |
| theme | Component theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| size | Checkbox size | `"small" \| "medium" \| "large"` | - |
Each item in `options` also supports `disabled` and `readonly`.
---
# Checkbox
Checkbox for multiple selections.
## When to Use
- When making multiple selections from a set of options.
- Used alone, it can represent switching between two states, similar to a switch. The difference is that switching a switch directly triggers a state change, while a checkbox is generally used for state marking and needs to cooperate with submission operations.
## Examples
[Single Selection](./demo/basic.vue)
- When used alone, a `v-model` value of `true` means checked, and `false` means unchecked.
[Multiple Selection](./demo/group.vue)
- You can use the `options` property to define options, or use child components instead.
[Group Layout](./demo/group-layout.vue)
- Group layout.
[Disabled / Controlled](./demo/disabled.vue)
- Set disabled state via `disabled`.
[Select All](./demo/check-all.vue)
- Select-all combination.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| checked | Checked state; supports `v-model:checked` | `boolean` | false |
| label | The text to display | `string \| number` | - |
| value | The value represented when used in combination | `string \| number \| boolean` | - |
| disabled | Whether the current item is disabled | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be toggled | `boolean` | false |
| indeterminate | Combined auxiliary option controls the indeterminate state | `boolean` | false |
| modelValue | Standalone state bound through `v-model` | `string \| number \| boolean` | - |
| theme | Component theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| valueType | The type of output value for the unit option | `"string" \| "number" \| "boolean"` | boolean |
| onChange | Callback when the option state changes | `(event: CheckboxChangeEvent) => void` | - |
## CheckboxGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected values; supports `v-model` | `CheckboxValue[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `CheckboxValue[]` | [] |
| disabled | Whether the component is disabled | `boolean` | false |
| readonly | Whether the group is read-only | `boolean` | false |
| onChange | Triggered when the option state changes, returns the currently selected item and state | `(value: CheckboxValue[]) => void` | - |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| options | Can specify child `checkbox` items | `CheckboxOption[]` | - |
| theme | Component theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| size | Checkbox size | `"small" \| "medium" \| "large"` | - |
Each item in `options` also supports `disabled` and `readonly`.
---
# CheckCard
Present richer choices with a title, description, and optional symbol.
## When to Use
- Standalone for a toggleable boolean choice, such as accepting an agreement.
- Inside `CheckCardGroup` for a single choice among multiple cards, such as an account or plan type.
## Examples
[Standalone](./demo/basic.vue?show=vertical)
- A standalone card can be selected and deselected.
[Single-selection group](./demo/group.vue?show=vertical)
- Groups use radio semantics and support arrow-key navigation.
[Custom symbol](./demo/custom.vue?show=vertical)
- Use the `symbol` slot to render custom content based on selection state.
[Appearance and disabled](./demo/appearance.vue?show=vertical)
- Themes, sizes, shapes, and disabled states.
## CheckCard API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Standalone state, supports `v-model` | `boolean` | - |
| checked | Initial checked state when used independently; modelValue takes precedence. | `boolean` | false |
| value | Option value inside a group | `CheckCardValue` | - |
| title | Title, customizable via the named slot | `string \| number` | - |
| description | Description, customizable via the named slot | `string` | - |
| symbol | Symbol icon, customizable via the named slot | `IconType[]` | - |
| checkedSymbol | Symbol icon used when checked | `IconType[]` | - |
| showIndicator | Show the top-right selection indicator | `boolean` | true |
| disabled | Disable the card | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be selected | `boolean` | false |
| theme | Appearance theme | `"fill" \| "outline"` | outline |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | round |
| change | Emitted when selection state changes | `(event: CheckCardChangeEvent) => void` | - |
## CheckCardGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected value, supports `v-model` | `CheckCardValue` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `CheckCardValue` | - |
| options | Card options | `CheckCardOption[]` | - |
| disabled | Disable the group | `boolean` | false |
| readonly | Make the group read-only | `boolean` | false |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| theme | Card theme | `"fill" \| "outline"` | outline |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| shape | Card shape | `"default" \| "circle" \| "square" \| "round"` | round |
| change | Emitted when the selected value changes | `(value: CheckCardValue) => void` | - |
Each item in `options` also supports `disabled` and `readonly`.
---
# CheckCard
Present richer choices with a title, description, and optional symbol.
## When to Use
- Standalone for a toggleable boolean choice, such as accepting an agreement.
- Inside `CheckCardGroup` for a single choice among multiple cards, such as an account or plan type.
## Examples
[Standalone](./demo/basic.vue?show=vertical)
- A standalone card can be selected and deselected.
[Single-selection group](./demo/group.vue?show=vertical)
- Groups use radio semantics and support arrow-key navigation.
[Custom symbol](./demo/custom.vue?show=vertical)
- Use the `symbol` slot to render custom content based on selection state.
[Appearance and disabled](./demo/appearance.vue?show=vertical)
- Themes, sizes, shapes, and disabled states.
## CheckCard API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Standalone state, supports `v-model` | `boolean` | - |
| checked | Initial checked state when used independently; modelValue takes precedence. | `boolean` | false |
| value | Option value inside a group | `CheckCardValue` | - |
| title | Title, customizable via the named slot | `string \| number` | - |
| description | Description, customizable via the named slot | `string` | - |
| symbol | Symbol icon, customizable via the named slot | `IconType[]` | - |
| checkedSymbol | Symbol icon used when checked | `IconType[]` | - |
| showIndicator | Show the top-right selection indicator | `boolean` | true |
| disabled | Disable the card | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be selected | `boolean` | false |
| theme | Appearance theme | `"fill" \| "outline"` | outline |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | round |
| change | Emitted when selection state changes | `(event: CheckCardChangeEvent) => void` | - |
## CheckCardGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected value, supports `v-model` | `CheckCardValue` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `CheckCardValue` | - |
| options | Card options | `CheckCardOption[]` | - |
| disabled | Disable the group | `boolean` | false |
| readonly | Make the group read-only | `boolean` | false |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| theme | Card theme | `"fill" \| "outline"` | outline |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| shape | Card shape | `"default" \| "circle" \| "square" \| "round"` | round |
| change | Emitted when the selected value changes | `(value: CheckCardValue) => void` | - |
Each item in `options` also supports `disabled` and `readonly`.
---
# Collapse
Content area that can be collapsed/expanded.
## When to Use
- Grouping and hiding complex areas to keep the page tidy.
- 'Accordion' is a special type of collapse panel that only allows a single content area to be expanded.
## Examples
[Basic Usage](./demo/basic.vue)
- By default, one or multiple panels can be expanded at the same time.
[Accordion](./demo/accordion.vue)
- Set `accordion` to allow only one panel to be expanded at a time.
[Nested Panels](./demo/nesting.vue)
- Nested collapse panels.
[Extra Nodes](./demo/extra.vue)
- Multiple panels can be expanded simultaneously.
[Simple Mode](./demo/sample.vue)
- Set `sample` to display a borderless, minimal style.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| openKeys | Keys of expanded panels. Supports two-way binding with `v-model:openKeys` | `(string \| number)[]` | [] |
| accordion | Whether to enable accordion mode. When enabled, at most one panel can be expanded at a time | `boolean` | false |
| sample | Whether to enable simple mode | `boolean` | false |
| onChange | Callback triggered when switching panels, returns the `name` of the current tab | `(key: CollapseKey) => void` | - |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | outline |
| shape | Panel shape | `"square" \| "round"` | round |
## Panel
| Property | Description | Type | Default |
| -------- | --------------------------------------------- | ------------------------------- | ------- |
| title | Panel title | VNodeChild | - |
| key | Unique panel identifier | string \| number | - |
| disabled | Whether the panel is disabled | boolean | false |
| extra | Extra title content | Slots | - |
| onExpand | Called when the panel expansion state changes | (key: string \| number) => void | - |
---
# Collapse
Content area that can be collapsed/expanded.
## When to Use
- Grouping and hiding complex areas to keep the page tidy.
- 'Accordion' is a special type of collapse panel that only allows a single content area to be expanded.
## Examples
[Basic Usage](./demo/basic.vue)
- By default, one or multiple panels can be expanded at the same time.
[Accordion](./demo/accordion.vue)
- Set `accordion` to allow only one panel to be expanded at a time.
[Nested Panels](./demo/nesting.vue)
- Nested collapse panels.
[Extra Nodes](./demo/extra.vue)
- Multiple panels can be expanded simultaneously.
[Simple Mode](./demo/sample.vue)
- Set `sample` to display a borderless, minimal style.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| openKeys | Keys of expanded panels. Supports two-way binding with `v-model:openKeys` | `(string \| number)[]` | [] |
| accordion | Whether to enable accordion mode. When enabled, at most one panel can be expanded at a time | `boolean` | false |
| sample | Whether to enable simple mode | `boolean` | false |
| onChange | Callback triggered when switching panels, returns the `name` of the current tab | `(key: CollapseKey) => void` | - |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | outline |
| shape | Panel shape | `"square" \| "round"` | round |
## Panel
| Property | Description | Type | Default |
| -------- | --------------------------------------------- | ------------------------------- | ------- |
| title | Panel title | VNodeChild | - |
| key | Unique panel identifier | string \| number | - |
| disabled | Whether the panel is disabled | boolean | false |
| extra | Extra title content | Slots | - |
| onExpand | Called when the panel expansion state changes | (key: string \| number) => void | - |
---
# ColorPickerPanel
See https://k-ui.cn/components/color-picker-panel.
---
# ColorPicker
Freely output colors.
## When to Use
- When custom colors are needed.
## Examples
[Basic Usage](./demo/basic.vue)
- Click to open the color panel.
[Size / Disabled](./demo/size.vue)
- `small` for small size, `large` for large size.
[Theme and Shape](./demo/appearance.vue)
- Supports `outline`, `fill`, and `plain` themes, plus `round`, `circle`, and `square` shapes.
[Custom Trigger](./demo/custom-trigger.vue)
- Customize the trigger for the color panel.
[Popup Placement](./demo/placement.vue)
- Supports 6 popup placements. If there is not enough space above, the panel will automatically appear below.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Color value, can use `v-model` for two-way binding | `string` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string` | - |
| opened | Whether the color panel is displayed by default | `boolean` | false |
| mode | Color display type, provides 3 modes (`hex` , `rgb` ,`hsl`) | `"hex" \| "rgb" \| "hsl"` | 'hex' |
| presets | Custom color palette | `string[]` | - |
| disabledAlpha | Whether to disable transparency | `boolean` | false |
| disabled | Is it in an invalid state? | `boolean` | false |
| readonly | Read-only; prevents opening or changing | `boolean` | false |
| trigger | Pull-down trigger mode | `"hover" \| "click"` | click |
| showText | Whether to display colored text | `boolean` | false |
| size | Size of the color picker | `"small" \| "medium" \| "large"` | - |
| theme | Appearance theme: `outline`, `fill`, or `plain`; inherits from Form when available | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | outline |
| shape | Shape: `round`, `circle`, or `square`; inherits from Form when available | `"default" \| "circle" \| "square" \| "round"` | - |
| placement | Placement of the color picker | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | bottom-left |
| onUpdateMode | Triggered when the color mode is updated | (mode: ColorMode) => void | - |
| onChange | Triggered when the color value changes, returns the color value | `(value: string) => void` | - |
| onOpenChange | Triggered when the color picker expands or collapses | `(open: boolean) => void` | - |
| panelOnly | Render only the color panel without the trigger input | `boolean` | false |
---
# DatePickerPanel
See https://k-ui.cn/components/date-picker-panel.
---
# DatePicker
Control for inputting or selecting a date.
## When to Use
When the user needs to input a date, they can click the standard input box to pop up a date panel for selection.
## Examples
[Basic Usage](./demo/basic.vue)
- Select or manually input a date. Use `v-model` for two-way data binding.
[Output Type](./demo/value-type.vue)
- Specify the output type via `valueType`.
[Date Range](./demo/range.vue)
- Supports date and time range selection. It's recommended to use `startDate` and `endDate` for values.
[Disabled Dates and Times](./demo/disabled-date.vue)
- Use `disabledDate` and `disabledTime` to disable selecting specific dates and times, respectively.
[Disabled and Non-editable](./demo/disabled.vue)
- The disabled, non-editable, and non-clearable states of the picker.
[Preset Ranges](./demo/presets.vue)
- You can preset common date ranges to improve user experience.
[Weird Theme](./demo/theme.vue)
- Strange things.
[Size](./demo/size.vue)
- Use `small` and `large` to set the size of the picker.
[Multi-language](./demo/lang.vue)
- DatePicker supports multiple languages,Default English, depending on `dayjs`.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Current date or time value | `DatePickerInput \| DatePickerInput[] \| null` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `DatePickerInput \| DatePickerInput[] \| null` | null |
| startDate | Start value for range selection | `DatePickerInput \| null` | null |
| endDate | End value for range selection | `DatePickerInput \| null` | null |
| mode | Use the `mode` property to customize the date display type. Options: `year`, `month`, `date`, `time`, `dateTime`, `dateRange`, `dateTimeRange` | `"time" \| "date" \| "year" \| "month" \| "dateTime" \| "dateRange" \| "dateTimeRange"` | date |
| disabled | Whether the component is disabled | `boolean` | false |
| readonly | Read-only; prevents opening, clearing and changing | `boolean` | false |
| size | Button size, optional values `small`, `large` | `"small" \| "medium" \| "large"` | - |
| clearable | Whether to show the clear icon | `boolean` | true |
| editable | Whether it is editable | `boolean` | true |
| placeholder | Placeholder text | `string \| string[]` | - |
| disabledDate | Disabled dates | `(date: Date) => boolean` | - |
| disabledTime | Disabled times | `(date: Date) => boolean` | - |
| format | Set the date format. When an array, supports multiple format matches, displayed according to the first one. Configuration reference http://day.js.org/ | `string` | YYYY-MM-DD |
| theme | When theme='fill', presents a fill theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| dateIcon | Custom icon | `IconType[]` | - |
| shape | The form in which the component is presented | `"default" \| "circle" \| "square" \| "round"` | - |
| bordered | Whether to display the border | `boolean` | true |
| placement | Direction displayed when pulled down | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | - |
| valueType | Output value type | `"string" \| "date" \| "timestamp" \| "unix"` | string |
| presets | Preset dates | `DatePickerPreset[]` | - |
| onChange | Callback after the value changes | `(value: DatePickerOutput \| DatePickerOutput[], text: string \| string[]) => void` | - |
| onOpenChange | Triggered when the dropdown box expands or collapses | `(open: boolean) => void` | - |
| onClear | Triggered when the clear button is clicked | `() => void` | - |
| opened | Whether the dropdown box is displayed by default | `boolean` | false |
| panelOnly | Render only the date panel without the trigger input | `boolean` | false |
---
# Descriptions
Display multiple read-only fields in groups.
## When to Use
Commonly seen in detail page information display.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Simple display.
[Bordered](./demo/bordered.vue?show=vertical)
- List with borders and background colors.
[Custom Size](./demo/size.vue?show=vertical)
- Customize the size to adapt to various containers.
[Responsive Columns](./demo/responsive.vue?show=vertical)
- Adjust the number of items per row according to the component container width.
[Vertical](./demo/vertical.vue?show=vertical)
- Vertical list.
[Vertical Bordered](./demo/vertical-bordered.vue?show=vertical)
- Vertical list with borders and background colors.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Whether to show the border | `boolean` | false |
| column | Items per row; supports responsive configuration | `DescriptionsColumn` | 3 |
| extra | The operation area of the description list, displayed in the upper right corner | `string` | - |
| layout | Description layout | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| size | List size | `"small" \| "medium" \| "large"` | large |
| title | The title of the description list, displayed at the very top | `string` | - |
## Item props
| Property | Description | Type | Default |
| -------- | --------------------------- | ------ | ------- |
| label | Description of the content | string | - |
| span | number of columns displayed | number | 1 |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Description list shape | `"square" \| "round"` | round |
---
# Descriptions
Display multiple read-only fields in groups.
## When to Use
Commonly seen in detail page information display.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Simple display.
[Bordered](./demo/bordered.vue?show=vertical)
- List with borders and background colors.
[Custom Size](./demo/size.vue?show=vertical)
- Customize the size to adapt to various containers.
[Responsive Columns](./demo/responsive.vue?show=vertical)
- Adjust the number of items per row according to the component container width.
[Vertical](./demo/vertical.vue?show=vertical)
- Vertical list.
[Vertical Bordered](./demo/vertical-bordered.vue?show=vertical)
- Vertical list with borders and background colors.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Whether to show the border | `boolean` | false |
| column | Items per row; supports responsive configuration | `DescriptionsColumn` | 3 |
| extra | The operation area of the description list, displayed in the upper right corner | `string` | - |
| layout | Description layout | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| size | List size | `"small" \| "medium" \| "large"` | large |
| title | The title of the description list, displayed at the very top | `string` | - |
## Item props
| Property | Description | Type | Default |
| -------- | --------------------------- | ------ | ------- |
| label | Description of the content | string | - |
| span | number of columns displayed | number | 1 |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Description list shape | `"square" \| "round"` | round |
---
# Drawer
A floating panel that slides in from the edge of the screen.
## When to Use
- The drawer slides in from the edge of the parent window, covering part of the parent window content. Users can operate within the drawer without leaving the current task. After the operation is completed, they can smoothly return to the original task.
- When an additional panel is needed to control the parent window content, this panel can be called out when needed. For example, controlling interface display styles, adding content to the interface.
- When temporary tasks need to be inserted into the current task flow, creating or previewing additional content. For example, displaying terms of agreement, creating sub-objects.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `v-model` for two-way binding to control whether the `Drawer` is displayed. If `title` is null or false, the title is not shown.
[Custom](./demo/custom.vue)
- Use `title` to set the title, `width` to control the width, and `placement` to control the direction.
[Form Mode](./demo/with-form.vue)
- Content will be presented in form mode, with a header and footer, and the footer can be customized.
[Inject into Target Element](./demo/target.vue)
- Can be expanded within the target element.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether the dialog is displayed, can use v-model for two-way binding. | `boolean` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `boolean` | false |
| escKey | Whether to support closing with Esc key | `boolean` | true |
| maskClosable | Whether clicking the mask allows closing | `boolean` | true |
| title | Drawer title | `string` | Title |
| width | Drawer width, used when `placement` is `left` or `right`, supports percentage | `string \| number` | 520 |
| height | Drawer height, used when `placement` is `top` or `bottom`, supports percentage | `string \| number` | 520 |
| placement | The display direction of the drawer. Provides 4 display methods: `left`, `top`, `right`, `bottom` | `"top" \| "bottom" \| "left" \| "right"` | right |
| footer | Whether to show the footer; the slot with the same name customizes its content | `boolean` | true |
| closable | Whether to show the close button | `boolean` | true |
| target | Display container; accepts a native element or component ref | `(() => HTMLElement \| ComponentPublicInstance \| null \| undefined)` | () => document.body |
| okText | OK button text | `string` | OK |
| cancelText | Cancel button text | `string` | Cancel |
| mask | Whether to show the mask | `boolean` | true |
| loading | When set to `true`, the confirm button will be in a loading state | `boolean` | false |
| onOk | Callback when OK is clicked | `() => void` | - |
| onClose | Callback when the drawer closes | `() => void` | - |
| onCancel | Callback when Cancel is clicked | `() => void` | - |
| onOpenChange | Callback for opening or closing the drawer | `(visible: boolean) => void` | - |
---
# Dropdown
A list that drops down.
## When to Use
When there are too many operation commands on the page, this component can be used to accommodate operation elements. Clicking or hovering over the trigger point will display a dropdown menu. Selections can be made in the list, and corresponding commands can be executed.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest dropdown menu.
[Right-click menu](./demo/right-menu.vue?show=vertical)
- By default, the menu is triggered by hovering, but it can also be triggered by clicking the right mouse button.
[Button with a dropdown menu](./demo/dropdown-buttons.vue)
- On the left is the button, and on the right is an additional related function menu. The icon property can be set to modify the icon on the right.
[Other Elements](./demo/divider.vue)
- Dividers and disabled menu items.
[Popup Position](./demo/placement.vue)
- Supports 6 popup positions.
[Arrow](./demo/arrow.vue)
- Set `arrow` to display an arrow pointing to the trigger.
[Multi-level Menu](./demo/cascading.vue)
- The passed menu has multiple levels.
## Dropdown API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| show | Whether the dropdown is visible (v-model) | `boolean` | false |
| trigger | Trigger method | `"hover" \| "click" \| "contextmenu"` | `hover` |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | `bottom-left` |
| arrow | Whether to display the arrow | `boolean` | false |
| target | Ref of an external trigger element or component | `Ref` | - |
| disabled | Whether triggering is disabled | `boolean` | false |
| onOpenChange | Called when the dropdown opens or closes | `(open: boolean) => void` | - |
| overlay slot | Dropdown overlay content | VNodeChild | - |
### DropdownButton API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| size | Button size | `"small" \| "medium" \| "large"` | - |
| shape | Button shape | `"default" \| "circle" \| "square" \| "round"` | - |
| disabled | Whether the button is disabled | `boolean` | false |
| icon | Custom dropdown trigger icon | `IconType[]` | Ellipsis |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| arrow | Whether to display the dropdown arrow | `boolean` | false |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | `bottom-right` |
| onClick | Triggered when the main button is clicked | `(event: MouseEvent) => void` | - |
---
# Dropdown
A list that drops down.
## When to Use
When there are too many operation commands on the page, this component can be used to accommodate operation elements. Clicking or hovering over the trigger point will display a dropdown menu. Selections can be made in the list, and corresponding commands can be executed.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest dropdown menu.
[Right-click menu](./demo/right-menu.vue?show=vertical)
- By default, the menu is triggered by hovering, but it can also be triggered by clicking the right mouse button.
[Button with a dropdown menu](./demo/dropdown-buttons.vue)
- On the left is the button, and on the right is an additional related function menu. The icon property can be set to modify the icon on the right.
[Other Elements](./demo/divider.vue)
- Dividers and disabled menu items.
[Popup Position](./demo/placement.vue)
- Supports 6 popup positions.
[Arrow](./demo/arrow.vue)
- Set `arrow` to display an arrow pointing to the trigger.
[Multi-level Menu](./demo/cascading.vue)
- The passed menu has multiple levels.
## Dropdown API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| show | Whether the dropdown is visible (v-model) | `boolean` | false |
| trigger | Trigger method | `"hover" \| "click" \| "contextmenu"` | `hover` |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | `bottom-left` |
| arrow | Whether to display the arrow | `boolean` | false |
| target | Ref of an external trigger element or component | `Ref` | - |
| disabled | Whether triggering is disabled | `boolean` | false |
| onOpenChange | Called when the dropdown opens or closes | `(open: boolean) => void` | - |
| overlay slot | Dropdown overlay content | VNodeChild | - |
### DropdownButton API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| size | Button size | `"small" \| "medium" \| "large"` | - |
| shape | Button shape | `"default" \| "circle" \| "square" \| "round"` | - |
| disabled | Whether the button is disabled | `boolean` | false |
| icon | Custom dropdown trigger icon | `IconType[]` | Ellipsis |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| arrow | Whether to display the dropdown arrow | `boolean` | false |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | `bottom-right` |
| onClick | Triggered when the main button is clicked | `(event: MouseEvent) => void` | - |
---
# Divider
Dividing line that separates content.
## When to Use
- To separate text paragraphs of different chapters.
- To separate inline text/links, such as the action column in a table.
## Examples
[Vertical Divider](./demo/basic.vue)
- Use type="vertical" to set an inline vertical divider.
[Horizontal Divider](./demo/default.vue)
- Default is a horizontal divider, with text that can be added in the middle.
[Divider with Text](./demo/with-text.vue)
- A divider with text in the middle, where `orientation` can specify the text position.
## API
| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| text | Divider text | `string` | - |
| dashed | Whether it is a dashed line | `boolean` | false |
| orientation | The position of the divider title : left right | `"left" \| "right" \| "center"` | center |
| type | Horizontal or vertical type: horizontal vertical | `"horizontal" \| "vertical" \| "inline"` | horizontal |
---
# Empty
Placeholder display for empty states.
## When to Use
- When there is currently no data, used for explicit user prompts.
- Guiding the creation process during initialization scenarios.
## Examples
[Basic Usage](./demo/basic.vue)
- Simple display.
[Custom](./demo/custom.vue)
- Customize the image, description, and extra content.
[Default Display](./demo/used.vue)
- Will be displayed by default in the above components.
[No Description](./demo/nodesc.vue)
- Display without description.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| description | Custom description content; set to `false` to hide it | `string \| boolean` | - |
| imageStyle | Image style | `CSSProperties` | - |
| image | Set the display image. When a string, it represents a custom image address | `string` | - |
---
# Form
A form with data collection, validation, and submission functions, including checkboxes, radio buttons, input fields, dropdown selectors, and other elements.
## When to Use
- Used to create an entity or collect information.
- When input data types need to be validated.
## Examples
In `Modal` or `Drawer`, if you need to reset the form when opening the Modal or Drawer, please use asynchronous methods:
```javascript
// The component is not fully rendered before opening, reading the dom object is undefined at this time,
// The child component is not fully rendered, this.$refs.form is undefined, so it cannot be reset.
// Use asynchronous method.
// Of course, you can also reset the form when Modal or Drawer @close.
export default {
methods: {
open() {
this.visible = true; // Open the modal first
this.reset();
},
close() {
this.reset();
this.visible = false; // Close the modal after
},
reset() {
this.$nextTick(() => {
this.$refs.form.reset();
});
// or
setTimeout(() => {
this.$refs.form.reset();
}, 0);
},
},
};
```
[Typical Form](./demo/basic.vue?show=vertical)
- Includes various form items, such as input fields, selectors, switches, radio buttons, checkboxes, etc.
[Alignment](./demo/align.vue?show=vertical)
- Choose the best label alignment based on specific goals and constraints.
[Form Validation](./demo/valid.vue?show=vertical)
- Help users discover and correct errors as early as possible, while preventing mistakes.
[Auxiliary Validation](./demo/length.vue?show=vertical)
- Validate certain data types.
[Multi-form Linkage](./demo/withmodal.vue?show=vertical)
- Outside the Form, submit the form via `submit` from the outside. Conversely, it's recommended to use `` to call the native submission logic.
[Custom Validation Rules](./demo/customvalid.vue?show=vertical)
- Use custom validation rules to complete form validation.
[Dynamic Validation Rules](./demo/dynamicvalid.vue?show=vertical)
- Execute different validation rules based on different conditions.
## Form API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| model | Form data object | `Record` | - |
| rules | Form validation rules | `FormRules` | - |
| name | Form name, will be used as the id prefix for form fields | `string` | - |
| labelCol | Label layout using `
` span and offset; ignored in inline layout | `ColProps` | - |
| wrapperCol | Control layout using `
` span and offset; ignored in inline layout | `ColProps` | - |
| theme | The component renders the theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| size | Sub component size | `"small" \| "medium" \| "large"` | - |
| layout | Form layout | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| shape | Child component shape | `"default" \| "circle" \| "square" \| "round"` | - |
| disabled | Whether the form is disabled | `boolean` | false |
| readonly | Make supported controls in the form read-only | `boolean` | false |
| colon | Whether to display a colon after labels | `boolean` | true |
| onChange | Called when a field value changes with the current form model | `(model: Record) => void` | - |
| onReset | Reset the entire form, reset all field values to empty and remove validation results | `() => void` | - |
| onSubmit | Called after submission validation with the validation result | `(result: FormSubmitEvent) => void` | - |
## Form Expose API
| Property | Description | Type | Default |
| -------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------- |
| test | Method for validating a single field in a form | (key:string)=>Promise\ | - |
| reset | Reset the entire form, clearing all field values and removing validation results | ()=>void | - |
| submit | Submit the form and validate | ()=>Promise\ | - |
| validate | Validate the form | (callback?: (result: { valid: boolean }) => void)=>Promise\<{ valid: boolean }\> | - |
## FormItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| prop | Corresponds to the field in the form domain model. Required for form validation | `string` | - |
| label | Label text | `string` | - |
| rules | Form validation rules | `FormRule \| FormRule[]` | - |
| colon | Whether to display a colon after the label; inherits the Form setting when unset | `boolean` | - |
## rules API
| Property | Description | Type | Default |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------- |
| required | Whether it is a required field | boolean | false |
| message | Prompt message when validation fails | string | - |
| validator | Custom validation method, see example | (rule: FormRule, value: any, callback: (error?: Error) => void) => void \| Promise\ | - |
| type | Data type validation. Provides three validation methods: `mobile` (phone), `mail` (email), `number` (numeric type judgment) | string | - |
| pattern | Custom regular expression validation. For example, password strength containing numbers, letters, and special symbols can be written as `/(?=.*[0-9])(?=.*[a-zA-Z])(?=.*[^a-zA-Z0-9]).{6,20}/` | string | - |
| trigger | When this rule runs. Defaults to `change` when unset; `validate` calls and submits ignore the trigger | change, blur or an array of them | - |
| min | Minimum field length validation | number | - |
| max | Maximum field length validation | number | - |
---
# Form
A form with data collection, validation, and submission functions, including checkboxes, radio buttons, input fields, dropdown selectors, and other elements.
## When to Use
- Used to create an entity or collect information.
- When input data types need to be validated.
## Examples
In `Modal` or `Drawer`, if you need to reset the form when opening the Modal or Drawer, please use asynchronous methods:
```javascript
// The component is not fully rendered before opening, reading the dom object is undefined at this time,
// The child component is not fully rendered, this.$refs.form is undefined, so it cannot be reset.
// Use asynchronous method.
// Of course, you can also reset the form when Modal or Drawer @close.
export default {
methods: {
open() {
this.visible = true; // Open the modal first
this.reset();
},
close() {
this.reset();
this.visible = false; // Close the modal after
},
reset() {
this.$nextTick(() => {
this.$refs.form.reset();
});
// or
setTimeout(() => {
this.$refs.form.reset();
}, 0);
},
},
};
```
[Typical Form](./demo/basic.vue?show=vertical)
- Includes various form items, such as input fields, selectors, switches, radio buttons, checkboxes, etc.
[Alignment](./demo/align.vue?show=vertical)
- Choose the best label alignment based on specific goals and constraints.
[Form Validation](./demo/valid.vue?show=vertical)
- Help users discover and correct errors as early as possible, while preventing mistakes.
[Auxiliary Validation](./demo/length.vue?show=vertical)
- Validate certain data types.
[Multi-form Linkage](./demo/withmodal.vue?show=vertical)
- Outside the Form, submit the form via `submit` from the outside. Conversely, it's recommended to use `` to call the native submission logic.
[Custom Validation Rules](./demo/customvalid.vue?show=vertical)
- Use custom validation rules to complete form validation.
[Dynamic Validation Rules](./demo/dynamicvalid.vue?show=vertical)
- Execute different validation rules based on different conditions.
## Form API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| model | Form data object | `Record` | - |
| rules | Form validation rules | `FormRules` | - |
| name | Form name, will be used as the id prefix for form fields | `string` | - |
| labelCol | Label layout using `
` span and offset; ignored in inline layout | `ColProps` | - |
| wrapperCol | Control layout using `
` span and offset; ignored in inline layout | `ColProps` | - |
| theme | The component renders the theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| size | Sub component size | `"small" \| "medium" \| "large"` | - |
| layout | Form layout | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| shape | Child component shape | `"default" \| "circle" \| "square" \| "round"` | - |
| disabled | Whether the form is disabled | `boolean` | false |
| readonly | Make supported controls in the form read-only | `boolean` | false |
| colon | Whether to display a colon after labels | `boolean` | true |
| onChange | Called when a field value changes with the current form model | `(model: Record) => void` | - |
| onReset | Reset the entire form, reset all field values to empty and remove validation results | `() => void` | - |
| onSubmit | Called after submission validation with the validation result | `(result: FormSubmitEvent) => void` | - |
## Form Expose API
| Property | Description | Type | Default |
| -------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------- |
| test | Method for validating a single field in a form | (key:string)=>Promise\ | - |
| reset | Reset the entire form, clearing all field values and removing validation results | ()=>void | - |
| submit | Submit the form and validate | ()=>Promise\ | - |
| validate | Validate the form | (callback?: (result: { valid: boolean }) => void)=>Promise\<{ valid: boolean }\> | - |
## FormItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| prop | Corresponds to the field in the form domain model. Required for form validation | `string` | - |
| label | Label text | `string` | - |
| rules | Form validation rules | `FormRule \| FormRule[]` | - |
| colon | Whether to display a colon after the label; inherits the Form setting when unset | `boolean` | - |
## rules API
| Property | Description | Type | Default |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------- |
| required | Whether it is a required field | boolean | false |
| message | Prompt message when validation fails | string | - |
| validator | Custom validation method, see example | (rule: FormRule, value: any, callback: (error?: Error) => void) => void \| Promise\ | - |
| type | Data type validation. Provides three validation methods: `mobile` (phone), `mail` (email), `number` (numeric type judgment) | string | - |
| pattern | Custom regular expression validation. For example, password strength containing numbers, letters, and special symbols can be written as `/(?=.*[0-9])(?=.*[a-zA-Z])(?=.*[^a-zA-Z0-9]).{6,20}/` | string | - |
| trigger | When this rule runs. Defaults to `change` when unset; `validate` calls and submits ignore the trigger | change, blur or an array of them | - |
| min | Minimum field length validation | number | - |
| max | Maximum field length validation | number | - |
---
# Flex
## When to Use
- Suitable for setting spacing between elements.
- Suitable for setting various horizontal and vertical alignment methods.
### Difference from Space Component
- Space provides spacing for inline elements, and it itself adds a wrapper element for each child element for inline alignment. Suitable for equidistant arrangement of multiple child elements in rows and columns.
- Flex provides spacing for block-level elements, and it itself does not add wrapper elements. Suitable for child element layout in vertical or horizontal directions, providing more flexibility and control capabilities.
## Examples
[Basic Layout](./demo/basic.vue?show=vertical)
- The simplest usage.
[Alignment](./demo/align.vue?show=vertical)
- Set the alignment mode.
[Spacing Size](./demo/size.vue?show=vertical)
- Use `size` to set the spacing between elements. Presets include `small`, `medium`, and `large`, or you can define a custom spacing.
[Set Wrapping](./demo/wrap.vue?show=vertical)
- When spacing is horizontal, use `wrap` to control whether items wrap automatically. The default is `false`.
## Flex API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| align | Cross-axis alignment | `"center" \| "start" \| "flex-start" \| "end" \| "flex-end" \| "baseline"` | `center` horizontally; `stretch` vertically |
| justify | Main-axis alignment | `"center" \| "flex-start" \| "flex-end" \| "space-between" \| "space-around" \| "space-evenly"` | `flex-start` |
| vertical | Whether to display vertically | `boolean` | false |
| size | Gap size; array format is `[horizontal, vertical]` | `FlexSizeType` | - |
| wrap | Whether to wrap | `boolean` | false |
---
# Grid
## Dimensionality and Control: Grid vs. Row / Col
This is the most commonly confused set of concepts.
- Row / Col (One-Dimensional Grid): Uses Flex to divide the available space into 24 parts.
- Limitations: It is essentially one-dimensional. Although it can wrap, it cannot precisely control placement across rows.
- Grid (Two-Dimensional Grid): Grid is two-dimensional. It can precisely control both rows and columns simultaneously.
- Advantages: No need for negative margins, directly control spacing through gaps. Supports rowSpan and dense mode, easily achieving "Bento Box" layouts.
### Logic Orientation: Grid vs. Flex
- Flex (Content-Oriented): Use Flex when you have a group of items with variable widths, and you want them to automatically shrink or expand based on their content size and align within a single row. It emphasizes flexibility.
- Grid (Layout-Oriented): Use Grid when you first have a fixed grid framework (like 8 cells for a dashboard) and then want to "fill" content into it. It emphasizes structure.
### Global Architecture vs. Local Arrangement: Layout Series
The Layout and its subcomponents (Header, Sider, Content, Footer) belong to the page skeleton-level components.
- Layout: Solves the semantic structure of the page's large background. It is responsible for managing the expansion/collapse of the sidebar, the fixed positioning of the top navigation, and the overall scrollbar management.
- Grid: Usually nested inside the Content (content area) of the Layout.
- Difference: Layout defines "how many rooms the house has"; Grid defines "how to arrange the furniture in each room".
## Examples
Responsive breakpoints use the Grid container width, not the viewport width. Resize the demo area to observe the changes.
[Basic Usage](./demo/basic.vue?show=vertical)
- Use `span` to control occupied columns, and `columnStart` or `rowStart` for precise placement.
[Dashboard Card Layout (Auto-fill + Min-Width)](./demo/auto-fill-min-width.vue?show=vertical)
- No need to manually set breakpoints. Rely on `itemMinWidth` to let the container automatically increase or decrease the number of columns based on its width.
> When `itemMinWidth` is set, the `cols` parameter becomes ineffective. This is a content-driven layout method, perfect for image galleries or card lists, ensuring cards maintain a suitable width without becoming too crowded during container resizing.
[Responsive Breakpoints and Fallback](./demo/breakpoint-fallback.vue?show=vertical)
- Values use mobile-first downward fallback. If `md` is defined and `lg` is omitted, `lg` continues to use the `md` value.
[Fixed Row Layout](./demo/fixed-rows-areas.vue?show=vertical)
- The vertical control power of `rows` and `rowSpan`.
[Responsive Hiding & Forced Sorting (Suffix & Display None)](./demo/suffix-display-none.vue?show=vertical)
- `span: 0` completely removes the DOM placeholder, and `suffix` spans across all dynamic items.
[Bento Grid Layout](./demo/bento-en.vue?show=vertical)
- Combines different `span` and `rowSpan` values with `row dense` auto-placement.
[Hero Section Overlay Layout (Layering)](./demo/hero-section.vue?show=vertical)
- Use `columnStart` and `rowStart` to place content in explicit grid regions and create layered layouts.
## Grid API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Set the number of grid columns. Supports numbers (equal division) or strings (e.g., 1fr 2fr) | `GridResponsive` | 24 |
| rows | Set the number of grid rows or height. Default is auto | `GridResponsive` | auto |
| autoRows | Implicit grid row height used to establish the base unit of a Bento layout. | `string` | auto |
| flow | CSS Grid auto-placement direction | `Property.GridAutoFlow` | row |
| xGap | Grid spacing (horizontal direction). Numeric type will automatically add px unit. | `GridResponsive` | 0 |
| yGap | Row spacing (vertical direction). Numeric type will automatically add px unit. | `GridResponsive` | 0 |
| itemMinWidth | Auto-fill mode. Grid calculates the number of columns from the minimum item width. | `string \| number` | - |
| align | Vertical alignment of child items within grid cells | `Property.AlignItems` | - |
| justify | Horizontal alignment of child items within grid cells | `Property.JustifyItems` | - |
| debug | Debug mode. When enabled, red transparent background columns are displayed to facilitate developer layout alignment. | `boolean` | false |
## GridItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| span | Number of columns occupied. `0` hides the item at that breakpoint | `GridResponsive` | 1 |
| rowSpan | Number of rows occupied | `GridResponsive` | 1 |
| columnStart | Explicit starting column line | `GridResponsive` | - |
| rowStart | Explicit starting row line | `GridResponsive` | - |
| suffix | Place the item at the end of the explicit grid | `boolean` | false |
## Breakpoints
| Identifier | Full Name | Threshold (width w) | Typical Scenario |
| ---------- | ----------------- | ------------------- | ------------------------------------------ |
| xs | Extra Small | 0≤w<576px | Phone portrait (Phones) |
| sm | Small | 576≤w<768px | Phone landscape / Small tablet |
| md | Medium | 768≤w<992px | Medium tablet (e.g., iPad) |
| lg | Large | 992≤w<1200px | Laptop / Small screen display |
| xl | Extra Large | 1200≤w<1600px | Standard desktop display |
| xxl | Extra Extra Large | w≥1600px | High-resolution large screen / Wide screen |
---
# Grid
## Dimensionality and Control: Grid vs. Row / Col
This is the most commonly confused set of concepts.
- Row / Col (One-Dimensional Grid): Uses Flex to divide the available space into 24 parts.
- Limitations: It is essentially one-dimensional. Although it can wrap, it cannot precisely control placement across rows.
- Grid (Two-Dimensional Grid): Grid is two-dimensional. It can precisely control both rows and columns simultaneously.
- Advantages: No need for negative margins, directly control spacing through gaps. Supports rowSpan and dense mode, easily achieving "Bento Box" layouts.
### Logic Orientation: Grid vs. Flex
- Flex (Content-Oriented): Use Flex when you have a group of items with variable widths, and you want them to automatically shrink or expand based on their content size and align within a single row. It emphasizes flexibility.
- Grid (Layout-Oriented): Use Grid when you first have a fixed grid framework (like 8 cells for a dashboard) and then want to "fill" content into it. It emphasizes structure.
### Global Architecture vs. Local Arrangement: Layout Series
The Layout and its subcomponents (Header, Sider, Content, Footer) belong to the page skeleton-level components.
- Layout: Solves the semantic structure of the page's large background. It is responsible for managing the expansion/collapse of the sidebar, the fixed positioning of the top navigation, and the overall scrollbar management.
- Grid: Usually nested inside the Content (content area) of the Layout.
- Difference: Layout defines "how many rooms the house has"; Grid defines "how to arrange the furniture in each room".
## Examples
Responsive breakpoints use the Grid container width, not the viewport width. Resize the demo area to observe the changes.
[Basic Usage](./demo/basic.vue?show=vertical)
- Use `span` to control occupied columns, and `columnStart` or `rowStart` for precise placement.
[Dashboard Card Layout (Auto-fill + Min-Width)](./demo/auto-fill-min-width.vue?show=vertical)
- No need to manually set breakpoints. Rely on `itemMinWidth` to let the container automatically increase or decrease the number of columns based on its width.
> When `itemMinWidth` is set, the `cols` parameter becomes ineffective. This is a content-driven layout method, perfect for image galleries or card lists, ensuring cards maintain a suitable width without becoming too crowded during container resizing.
[Responsive Breakpoints and Fallback](./demo/breakpoint-fallback.vue?show=vertical)
- Values use mobile-first downward fallback. If `md` is defined and `lg` is omitted, `lg` continues to use the `md` value.
[Fixed Row Layout](./demo/fixed-rows-areas.vue?show=vertical)
- The vertical control power of `rows` and `rowSpan`.
[Responsive Hiding & Forced Sorting (Suffix & Display None)](./demo/suffix-display-none.vue?show=vertical)
- `span: 0` completely removes the DOM placeholder, and `suffix` spans across all dynamic items.
[Bento Grid Layout](./demo/bento-en.vue?show=vertical)
- Combines different `span` and `rowSpan` values with `row dense` auto-placement.
[Hero Section Overlay Layout (Layering)](./demo/hero-section.vue?show=vertical)
- Use `columnStart` and `rowStart` to place content in explicit grid regions and create layered layouts.
## Grid API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Set the number of grid columns. Supports numbers (equal division) or strings (e.g., 1fr 2fr) | `GridResponsive` | 24 |
| rows | Set the number of grid rows or height. Default is auto | `GridResponsive` | auto |
| autoRows | Implicit grid row height used to establish the base unit of a Bento layout. | `string` | auto |
| flow | CSS Grid auto-placement direction | `Property.GridAutoFlow` | row |
| xGap | Grid spacing (horizontal direction). Numeric type will automatically add px unit. | `GridResponsive` | 0 |
| yGap | Row spacing (vertical direction). Numeric type will automatically add px unit. | `GridResponsive` | 0 |
| itemMinWidth | Auto-fill mode. Grid calculates the number of columns from the minimum item width. | `string \| number` | - |
| align | Vertical alignment of child items within grid cells | `Property.AlignItems` | - |
| justify | Horizontal alignment of child items within grid cells | `Property.JustifyItems` | - |
| debug | Debug mode. When enabled, red transparent background columns are displayed to facilitate developer layout alignment. | `boolean` | false |
## GridItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| span | Number of columns occupied. `0` hides the item at that breakpoint | `GridResponsive` | 1 |
| rowSpan | Number of rows occupied | `GridResponsive` | 1 |
| columnStart | Explicit starting column line | `GridResponsive` | - |
| rowStart | Explicit starting row line | `GridResponsive` | - |
| suffix | Place the item at the end of the explicit grid | `boolean` | false |
## Breakpoints
| Identifier | Full Name | Threshold (width w) | Typical Scenario |
| ---------- | ----------------- | ------------------- | ------------------------------------------ |
| xs | Extra Small | 0≤w<576px | Phone portrait (Phones) |
| sm | Small | 576≤w<768px | Phone landscape / Small tablet |
| md | Medium | 768≤w<992px | Medium tablet (e.g., iPad) |
| lg | Large | 992≤w<1200px | Laptop / Small screen display |
| xl | Extra Large | 1200≤w<1600px | Standard desktop display |
| xxl | Extra Extra Large | w≥1600px | High-resolution large screen / Wide screen |
---
# Image
Previewable images.
## When to Use
- Use when you need to display images.
- Display loading or error handling when loading large images.
## Examples
[Basic Usage](./demo/basic.vue)
- Simple display.
[Error Handling](./demo/errors.vue)
- Show an image placeholder on load failure.
[Photo Wall](./demo/group.vue)
- Click the left/right buttons to preview multiple images.
[Extension](./demo/extra.vue)
- Can extend custom tools and panels.
## Image API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| width | The width of the component | `string \| number` | - |
| height | The height of the component | `string \| number` | - |
| src | The default address of the image to display | `string` | - |
| alt | Alternative text when the image cannot be displayed | `string` | - |
| type | Preview content type | `"img" \| "media"` | `img` |
| origin | The large image displayed when clicking the image | `string` | - |
| placeholder | The placeholder displayed when the image fails to load | `string` | - |
| imgStyle | The style of the image | `CSSProperties` | - |
| showPanel | Whether to display the extension panel by default | `boolean` | false |
| onClose | Close trigger event | `() => void` | - |
| switch | Multi-image switch trigger event | `(index: number) => void` | - |
| tool | Custom toolbar buttons | slot | - |
| panel | Custom extension panel | slot | - |
## ImageGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| data | Image data | `string[]` | - |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | default |
| shape | Image shape | `"default" \| "circle" \| "square" \| "round"` | round |
---
# Image
Previewable images.
## When to Use
- Use when you need to display images.
- Display loading or error handling when loading large images.
## Examples
[Basic Usage](./demo/basic.vue)
- Simple display.
[Error Handling](./demo/errors.vue)
- Show an image placeholder on load failure.
[Photo Wall](./demo/group.vue)
- Click the left/right buttons to preview multiple images.
[Extension](./demo/extra.vue)
- Can extend custom tools and panels.
## Image API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| width | The width of the component | `string \| number` | - |
| height | The height of the component | `string \| number` | - |
| src | The default address of the image to display | `string` | - |
| alt | Alternative text when the image cannot be displayed | `string` | - |
| type | Preview content type | `"img" \| "media"` | `img` |
| origin | The large image displayed when clicking the image | `string` | - |
| placeholder | The placeholder displayed when the image fails to load | `string` | - |
| imgStyle | The style of the image | `CSSProperties` | - |
| showPanel | Whether to display the extension panel by default | `boolean` | false |
| onClose | Close trigger event | `() => void` | - |
| switch | Multi-image switch trigger event | `(index: number) => void` | - |
| tool | Custom toolbar buttons | slot | - |
| panel | Custom extension panel | slot | - |
## ImageGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| data | Image data | `string[]` | - |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | default |
| shape | Image shape | `"default" \| "circle" \| "square" \| "round"` | round |
---
# Icon
Version 5.x reintroduces icon sets, supporting more icons.
To use the icon component, you need to install the `kui-icons` package:
```bash
npm install --save kui-icons
```
Use
```html
```
[IconList](./demo/search.tsx?demo=false)
- Search and browse all icons provided by `kui-icons`.
[Basic Usage](./demo/basic.vue)
- You can set the icon's type, size, and color via the `type`, `size`, and `color` attributes, respectively. You can also use the `spin` attribute to achieve a rotating animation effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| type | Icon type. Follows the icon naming convention | `IconType[]` | - |
| size | The size of the icon, unit is px | `string \| number` | - |
| color | The color of the icon | `string` | - |
| spin | Whether to have rotation animation | `boolean` | false |
| strokeWidth | The line thickness of the icon | `string \| number` | 2 |
| onClick | Click event | `(event: MouseEvent) => void` | - |
| reverseFill | Icon borders and inverted fills are only supported for closed icons. | `boolean` | false |
| role | Accessibility role | `string` | - |
| tabindex | Keyboard focus order | `number` | - |
| aria-label | Accessible label | `string` | - |
| onPointerdown | Called when a pointer is pressed | `((event: PointerEvent) => void)` | - |
| onKeydown | Called when a key is pressed | `((event: KeyboardEvent) => void)` | - |
| onPointerup | Called when a pointer is released | `((event: PointerEvent) => void)` | - |
---
# Input
Input content via mouse or keyboard, the most basic wrapper for form fields.
## When to Use
- When user input is required for form fields.
- Provides combined input fields, searchable input fields, and size selection.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Theme](./demo/theme.vue)
- Use `theme` to set the theme, and `shape` for rounded corners.
[With Icon](./demo/icon.vue)
- By setting the `icon` attribute, you can add an icon to the input field, which is only effective for `input`. This allows for quick implementation of features like password visibility toggle or search.
[Addons, Prefix and Suffix](./demo/suffix.vue?show=vertical)
- `prefix` and `suffix` render inside the input. For complex content, use the named slots (recommended in `.vue`) or VNode props (TSX); both render identically. `addonBefore` and `addonAfter` render outside the input.
[Input Group](./demo/group.vue?show=vertical)
- Use `InputGroup` to tightly connect components and merge borders. Default is `true`.
[Size](./demo/size.vue)
- `large` for large size, `small` for small size.
[Events](./demo/event.vue)
- This example tests whether component events are triggered normally.
[Textarea](./demo/textarea.vue)
- Control the number of rows via `rows`.
## Input API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, can use `v-model` for two-way binding | `unknown` | - |
| value | Initial value for uncontrolled usage | `any` | - |
| type | Native input type | `InputTypeHTMLAttribute` | text |
| disabled | Whether the input is disabled | `boolean` | false |
| readonly | Read-only; focusable and copyable but not editable | `boolean` | false |
| shape | Input shape | `"default" \| "circle" \| "square" \| "round"` | - |
| size | Button size, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
| icon | Input box icon | `IconType[]` | - |
| suffix | Suffix inside the input; complex content can use the named slot | `VNodeChild` | - |
| prefix | Prefix inside the input; complex content can use the named slot | `VNodeChild` | - |
| addonBefore | Addon before the input; complex content can use the named slot | `VNodeChild` | - |
| addonAfter | Addon after the input; complex content can use the named slot | `VNodeChild` | - |
| theme | The theme of Input | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| clearable | Show the clear button on hover when a value exists | `boolean` | true |
| visiblePasswordIcon | Whether to show the toggle button or control password visibility | `boolean` | true |
| onSearch | Search event callback | `((value: string) => void)` | - |
| onIconClick | Callback for icon click event | `((event: MouseEvent) => void)` | - |
| onClear | Callback for pressing the clear button | `(() => void)` | - |
| onChange | Callback when the input box content changes | `((value: string) => void)` | - |
## TextArea API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, supports `v-model` | `string \| number \| readonly string[] \| null` | - |
| value | Initial value for uncontrolled use | `string \| number \| readonly string[] \| null` | - |
| rows | Number of visible text rows | `number` | 2 |
| placeholder | Input placeholder | `string` | - |
| disabled | Whether the textarea is disabled | `boolean` | false |
| readonly | Whether the textarea is read-only | `boolean` | false |
| theme | Textarea theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| size | Textarea size | `"small" \| "medium" \| "large"` | - |
| shape | Textarea shape | `"default" \| "circle" \| "square" \| "round"` | - |
| onChange | Triggered when the content changes | `((value: string) => void)` | - |
## Input Group API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| block | Whether to inherit the parent width | boolean | false |
| compact | Whether to use compact mode | boolean | true |
| size | Spacing of child components, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
---
# Input
Input content via mouse or keyboard, the most basic wrapper for form fields.
## When to Use
- When user input is required for form fields.
- Provides combined input fields, searchable input fields, and size selection.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Theme](./demo/theme.vue)
- Use `theme` to set the theme, and `shape` for rounded corners.
[With Icon](./demo/icon.vue)
- By setting the `icon` attribute, you can add an icon to the input field, which is only effective for `input`. This allows for quick implementation of features like password visibility toggle or search.
[Addons, Prefix and Suffix](./demo/suffix.vue?show=vertical)
- `prefix` and `suffix` render inside the input. For complex content, use the named slots (recommended in `.vue`) or VNode props (TSX); both render identically. `addonBefore` and `addonAfter` render outside the input.
[Input Group](./demo/group.vue?show=vertical)
- Use `InputGroup` to tightly connect components and merge borders. Default is `true`.
[Size](./demo/size.vue)
- `large` for large size, `small` for small size.
[Events](./demo/event.vue)
- This example tests whether component events are triggered normally.
[Textarea](./demo/textarea.vue)
- Control the number of rows via `rows`.
## Input API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, can use `v-model` for two-way binding | `unknown` | - |
| value | Initial value for uncontrolled usage | `any` | - |
| type | Native input type | `InputTypeHTMLAttribute` | text |
| disabled | Whether the input is disabled | `boolean` | false |
| readonly | Read-only; focusable and copyable but not editable | `boolean` | false |
| shape | Input shape | `"default" \| "circle" \| "square" \| "round"` | - |
| size | Button size, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
| icon | Input box icon | `IconType[]` | - |
| suffix | Suffix inside the input; complex content can use the named slot | `VNodeChild` | - |
| prefix | Prefix inside the input; complex content can use the named slot | `VNodeChild` | - |
| addonBefore | Addon before the input; complex content can use the named slot | `VNodeChild` | - |
| addonAfter | Addon after the input; complex content can use the named slot | `VNodeChild` | - |
| theme | The theme of Input | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| clearable | Show the clear button on hover when a value exists | `boolean` | true |
| visiblePasswordIcon | Whether to show the toggle button or control password visibility | `boolean` | true |
| onSearch | Search event callback | `((value: string) => void)` | - |
| onIconClick | Callback for icon click event | `((event: MouseEvent) => void)` | - |
| onClear | Callback for pressing the clear button | `(() => void)` | - |
| onChange | Callback when the input box content changes | `((value: string) => void)` | - |
## TextArea API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, supports `v-model` | `string \| number \| readonly string[] \| null` | - |
| value | Initial value for uncontrolled use | `string \| number \| readonly string[] \| null` | - |
| rows | Number of visible text rows | `number` | 2 |
| placeholder | Input placeholder | `string` | - |
| disabled | Whether the textarea is disabled | `boolean` | false |
| readonly | Whether the textarea is read-only | `boolean` | false |
| theme | Textarea theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| size | Textarea size | `"small" \| "medium" \| "large"` | - |
| shape | Textarea shape | `"default" \| "circle" \| "square" \| "round"` | - |
| onChange | Triggered when the content changes | `((value: string) => void)` | - |
## Input Group API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| block | Whether to inherit the parent width | boolean | false |
| compact | Whether to use compact mode | boolean | true |
| size | Spacing of child components, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
---
# Input
Input content via mouse or keyboard, the most basic wrapper for form fields.
## When to Use
- When user input is required for form fields.
- Provides combined input fields, searchable input fields, and size selection.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Theme](./demo/theme.vue)
- Use `theme` to set the theme, and `shape` for rounded corners.
[With Icon](./demo/icon.vue)
- By setting the `icon` attribute, you can add an icon to the input field, which is only effective for `input`. This allows for quick implementation of features like password visibility toggle or search.
[Addons, Prefix and Suffix](./demo/suffix.vue?show=vertical)
- `prefix` and `suffix` render inside the input. For complex content, use the named slots (recommended in `.vue`) or VNode props (TSX); both render identically. `addonBefore` and `addonAfter` render outside the input.
[Input Group](./demo/group.vue?show=vertical)
- Use `InputGroup` to tightly connect components and merge borders. Default is `true`.
[Size](./demo/size.vue)
- `large` for large size, `small` for small size.
[Events](./demo/event.vue)
- This example tests whether component events are triggered normally.
[Textarea](./demo/textarea.vue)
- Control the number of rows via `rows`.
## Input API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, can use `v-model` for two-way binding | `unknown` | - |
| value | Initial value for uncontrolled usage | `any` | - |
| type | Native input type | `InputTypeHTMLAttribute` | text |
| disabled | Whether the input is disabled | `boolean` | false |
| readonly | Read-only; focusable and copyable but not editable | `boolean` | false |
| shape | Input shape | `"default" \| "circle" \| "square" \| "round"` | - |
| size | Button size, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
| icon | Input box icon | `IconType[]` | - |
| suffix | Suffix inside the input; complex content can use the named slot | `VNodeChild` | - |
| prefix | Prefix inside the input; complex content can use the named slot | `VNodeChild` | - |
| addonBefore | Addon before the input; complex content can use the named slot | `VNodeChild` | - |
| addonAfter | Addon after the input; complex content can use the named slot | `VNodeChild` | - |
| theme | The theme of Input | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| clearable | Show the clear button on hover when a value exists | `boolean` | true |
| visiblePasswordIcon | Whether to show the toggle button or control password visibility | `boolean` | true |
| onSearch | Search event callback | `((value: string) => void)` | - |
| onIconClick | Callback for icon click event | `((event: MouseEvent) => void)` | - |
| onClear | Callback for pressing the clear button | `(() => void)` | - |
| onChange | Callback when the input box content changes | `((value: string) => void)` | - |
## TextArea API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, supports `v-model` | `string \| number \| readonly string[] \| null` | - |
| value | Initial value for uncontrolled use | `string \| number \| readonly string[] \| null` | - |
| rows | Number of visible text rows | `number` | 2 |
| placeholder | Input placeholder | `string` | - |
| disabled | Whether the textarea is disabled | `boolean` | false |
| readonly | Whether the textarea is read-only | `boolean` | false |
| theme | Textarea theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| size | Textarea size | `"small" \| "medium" \| "large"` | - |
| shape | Textarea shape | `"default" \| "circle" \| "square" \| "round"` | - |
| onChange | Triggered when the content changes | `((value: string) => void)` | - |
## Input Group API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| block | Whether to inherit the parent width | boolean | false |
| compact | Whether to use compact mode | boolean | true |
| size | Spacing of child components, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
---
# InputTag
Convert continuous input into an addable and removable tag collection.
## Examples
[Basic](./demo/basic.vue)
- Press Enter to add and Backspace to remove tags.
[Controlled tags](./demo/controlled.vue)
- Manage the collection through v-model.
[Maximum count](./demo/limit.vue)
- Use `max` to limit the total number of tags and `maxTagCount` to limit visible tags.
[Separators](./demo/separators.vue)
- Commit tags with comma or semicolon.
[Size](./demo/size.vue?show=vertical)
- Different sizes.
[Appearance and disabled](./demo/appearance.vue)
- Shows theme, shape, and disabled states.
## InputTag API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Tags (v-model) | `string[]` | - |
| value | Initial tags | `string[]` | [] |
| placeholder | Placeholder | `string` | - |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| theme | Theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | default |
| disabled | Disabled | `boolean` | false |
| readonly | Read-only; prevents adding, removing or clearing tags | `boolean` | false |
| clearable | Whether to show the clear button | `boolean` | true |
| block | Fill the parent width | `boolean` | false |
| allowDuplicates | Allow duplicates | `boolean` | false |
| max | Maximum count | `number` | - |
| maxTagCount | Maximum visible tags; the remainder is shown as +N | `number` | - |
| separators | Commit keys | `string[]` | [','] |
| onChange | Tags change | `(value: string[]) => void` | - |
| onAdd | Tag added | `(value: string) => void` | - |
| onRemove | Tag removed | `(value: string, index: number) => void` | - |
| onClear | Tags cleared | `() => void` | - |
---
# InputOTP
Used for SMS codes, email codes, and one-time passwords.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Supports per-character input, paste, keyboard navigation, and completion events.
[Custom Length](./demo/length.vue?show=vertical)
- Set the number of characters with `length`.
[Theme and Shape](./demo/theme.vue?show=vertical)
- Includes light, outline, and underlined themes, plus square, rounded, and circle shapes.
[Size](./demo/size.vue?show=vertical)
- Provides small, default, and large sizes.
[Disabled and Readonly](./demo/state.vue?show=vertical)
- Disabled fields cannot be interacted with; readonly fields can still be focused and copied.
[Separator](./demo/separator.vue?show=vertical)
- Set content between fields with `separator`.
[Paste Code](./demo/paste.vue?show=vertical)
- Pasting a complete code splits it automatically and fills each field in sequence.
[Validation](./demo/validator.vue?show=vertical)
- `type` provides built-in character validation; use `validator` for custom rules.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Bound value, supports `v-model` | `string \| number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string \| number` | - |
| length | Number of characters, normalized to a non-negative integer | `number` | 6 |
| type | Accepted character type | `"number" \| "text"` | number |
| size | Component size | `"small" \| "medium" \| "large"` | - |
| mask | Mask the entered value | `boolean` | false |
| disabled | Disable the inputs | `boolean` | false |
| readonly | Make the inputs readonly | `boolean` | false |
| autofocus | Focus the first input automatically | `boolean` | false |
| separator | Content between OTP fields | `VNodeChild` | - |
| validator | Custom validator for each character | `InputOTPValidator` | - |
| theme | Visual theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Field shape | `"default" \| "circle" \| "square" \| "round"` | - |
| complete | Emitted when all characters exist | `(value: string) => void` | - |
| change | Emitted when the input value changes | `(value: string) => void` | - |
| focus | Emitted when an input receives focus | `(event: FocusEvent) => void` | - |
| blur | Emitted when an input loses focus | `(event: FocusEvent) => void` | - |
---
# InputNumber
Input values within a range via mouse or keyboard.
## When to Use
When standard numerical values need to be obtained.
## Examples
[Basic Usage](./demo/basic.vue)
- Basic usage. The `keyboard` attribute can control keyboard behavior.
[High-Precision Decimals / Formatted Display](./demo/format.vue)
- Format numbers using `formatter` to display data with specific meaning, often used in conjunction with `parser`.
[Extension, Prefix and Suffix](./demo/ffix.vue)
- suffix, prefix extension
[Size](./demo/size.vue)
- `large` for large size, `small` for small size
## InputNumber API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| min | Minimum value | `number` | -Infinity |
| max | Maximum value | `number` | Infinity |
| step | Step value for each change, can be a decimal | `string \| number` | 1 |
| modelValue | The value of InputNumber(v-model) | `string \| number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string \| number` | - |
| formatter | Specifies the format of the value displayed in the input box | `((value: string \| number) => string)` | - |
| parser | Specifies how to convert back from formatter to number, used with formatter | `((value: string) => string \| number)` | - |
| size | Input box size | `"small" \| "medium" \| "large"` | - |
| disabled | Disabled | `boolean` | false |
| readonly | Whether the input is read-only | `boolean` | false |
| precision | Numerical precision | `number` | - |
| shape | Component appearance | `"default" \| "circle" \| "square" \| "round"` | - |
| suffix | Custom suffix | `string` | - |
| prefix | Prefix content | `string` | - |
| controls | Whether to show increase/decrease buttons | `boolean` | true |
| theme | Component theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| icon | Input icon | `IconType[]` | - |
| placeholder | Input placeholder | `string` | - |
| keyboard | Allow keyboard control | `boolean` | true |
| onChange | Change callback; returns `undefined` when cleared | `(value: number \| undefined) => void` | - |
| onBlur | Called when the input loses focus | `(event: FocusEvent) => void` | - |
| onKeydown | Called when a key is pressed in the input | `(event: KeyboardEvent) => void` | - |
---
# Content
See https://k-ui.cn/components/content.
---
# Footer
See https://k-ui.cn/components/footer.
---
# Header
See https://k-ui.cn/components/header.
---
# Layout
Assists with page-level overall layout.
## Component Overview
- `Layout`: Layout container, under which `Header`, `Sider`, `Content`, `Footer`, or `Layout` itself can be nested. Can be placed in any parent container.
- `Header`: Top layout, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
- `Sider`: Sidebar, comes with default styles and basic functions, any element can be nested under it, can only be placed in `Layout`.
- `Content`: Content section, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
- `Footer`: Bottom layout, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
> After version 3.0, `flex` layout is used, please pay attention to [flex](http://caniuse.com/#search=flex)
## Examples
[Basic Layout](./demo/basic.vue?show=vertical)
- Common combinations of Header, Sider, Content, and Footer.
[Collapsible Sider](./demo/collapsible-sider.vue?show=vertical)
- Control Sider with the `collapsible` and `collapsed` properties.
[Nested Layout](./demo/nested.vue?show=vertical)
- Nest Layout containers and combine left and right Siders.
[Fixed-height Layout](./demo/fixed-height.vue?show=vertical)
- Give Layout a fixed height and let Content scroll independently.
## Layout API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| hasSider | Whether the layout contains a sider; detected automatically when omitted | `boolean` | - |
| suffixCls | CSS class suffix, prefixed with `k-`; custom values require matching styles. | `string` | 'layout' |
## Layout.Sider API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| width | Expanded width | number \| string | 200 |
| collapsedWidth | Collapsed width | number \| string | 80 |
| collapsible | Whether collapsed styling is enabled | boolean | false |
| collapsed | Controlled collapsed state | boolean | false |
| suffixCls | CSS class suffix, prefixed with `k-`; custom values require matching styles. | `string` | 'layout-sider' |
---
# Layout
Assists with page-level overall layout.
## Component Overview
- `Layout`: Layout container, under which `Header`, `Sider`, `Content`, `Footer`, or `Layout` itself can be nested. Can be placed in any parent container.
- `Header`: Top layout, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
- `Sider`: Sidebar, comes with default styles and basic functions, any element can be nested under it, can only be placed in `Layout`.
- `Content`: Content section, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
- `Footer`: Bottom layout, comes with default styles, any element can be nested under it, can only be placed in `Layout`.
> After version 3.0, `flex` layout is used, please pay attention to [flex](http://caniuse.com/#search=flex)
## Examples
[Basic Layout](./demo/basic.vue?show=vertical)
- Common combinations of Header, Sider, Content, and Footer.
[Collapsible Sider](./demo/collapsible-sider.vue?show=vertical)
- Control Sider with the `collapsible` and `collapsed` properties.
[Nested Layout](./demo/nested.vue?show=vertical)
- Nest Layout containers and combine left and right Siders.
[Fixed-height Layout](./demo/fixed-height.vue?show=vertical)
- Give Layout a fixed height and let Content scroll independently.
## Layout API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| hasSider | Whether the layout contains a sider; detected automatically when omitted | `boolean` | - |
| suffixCls | CSS class suffix, prefixed with `k-`; custom values require matching styles. | `string` | 'layout' |
## Layout.Sider API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| width | Expanded width | number \| string | 200 |
| collapsedWidth | Collapsed width | number \| string | 80 |
| collapsible | Whether collapsed styling is enabled | boolean | false |
| collapsed | Controlled collapsed state | boolean | false |
| suffixCls | CSS class suffix, prefixed with `k-`; custom values require matching styles. | `string` | 'layout-sider' |
---
# Menu
Navigation menu list for pages and functions.
## When to Use
The navigation menu is the soul of a website. Users rely on navigation to jump between pages. Generally divided into top navigation and side navigation. Top navigation provides global categories and functions, while side navigation provides a multi-level structure to accommodate and arrange the website architecture.
## Examples
[Top Navigation](./demo/basic.vue?show=vertical)
- Horizontal top navigation menu.
[Inline Menu](./demo/inline.vue?show=vertical)
- Vertical menu, with submenus embedded within the menu area.
[Expand Only Current Parent Menu](./demo/accordion.vue?show=vertical)
- Clicking a menu item collapses all other expanded menus, keeping the menu focused and clean.
[Vertical Menu](./demo/vertical.vue?show=vertical)
- Submenus appear as popups.
[Theme](./demo/theme.vue?show=vertical)
- Supports local `light|dark` themes and inherits the global theme when omitted.
[Switch Menu Type](./demo/mode.vue?show=vertical)
- Demonstrates dynamic mode switching.
[Collapsible Inline Menu](./demo/collapsed.vue?show=vertical)
- Inline menus can be collapsed/expanded.
## API
### MenuAPI
| Property | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------- |
| modelValue | Currently selected menu items (v-model) | string[] | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | string[] | [] |
| theme | Local theme; inherits global theme when omitted | `light` \| `dark` | - |
| items | Menu data | MenuOptionsProps[] | - |
| openKeys | Currently expanded SubMenu menu item key array | string[] | [] |
| mode | Menu type | `vertical` \| `horizontal` \| `inline` | `vertical` |
| onSelect | Called when MenuItem is clicked | (data: MenuSelectEvent) => void | - |
| onOpenChange | Callback when SubMenu expands/collapses | (openKeys: string[]) => void | - |
| accordion | Whether only one menu item can be expanded | boolean | false |
| inlineCollapsed | Whether the menu is collapsed in inline mode | boolean | false |
| collapsedTooltip | Whether leaf items show a tooltip when collapsed | boolean | true |
### Menu(items)
| Property | Description | Type | Default |
| -------- | -------------------------- | ------------------ | ------- |
| icon | Item icon | IconType | - |
| disabled | Whether disabled | boolean | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | VNodeChild | - |
| children | Menu children | MenuOptionsProps[] | - |
### MenuItem
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | `VNodeChild` | - |
| onClick | Callback fired when item clicked | `(event: MouseEvent) => void` | - |
### SubMenu
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Submenu item content | `VNodeChild` | - |
### MenuGroup
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Group title | `VNodeChild` | - |
---
# MenuDivider
See https://k-ui.cn/components/menu-divider.
---
# Menu
Navigation menu list for pages and functions.
## When to Use
The navigation menu is the soul of a website. Users rely on navigation to jump between pages. Generally divided into top navigation and side navigation. Top navigation provides global categories and functions, while side navigation provides a multi-level structure to accommodate and arrange the website architecture.
## Examples
[Top Navigation](./demo/basic.vue?show=vertical)
- Horizontal top navigation menu.
[Inline Menu](./demo/inline.vue?show=vertical)
- Vertical menu, with submenus embedded within the menu area.
[Expand Only Current Parent Menu](./demo/accordion.vue?show=vertical)
- Clicking a menu item collapses all other expanded menus, keeping the menu focused and clean.
[Vertical Menu](./demo/vertical.vue?show=vertical)
- Submenus appear as popups.
[Theme](./demo/theme.vue?show=vertical)
- Supports local `light|dark` themes and inherits the global theme when omitted.
[Switch Menu Type](./demo/mode.vue?show=vertical)
- Demonstrates dynamic mode switching.
[Collapsible Inline Menu](./demo/collapsed.vue?show=vertical)
- Inline menus can be collapsed/expanded.
## API
### MenuAPI
| Property | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------- |
| modelValue | Currently selected menu items (v-model) | string[] | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | string[] | [] |
| theme | Local theme; inherits global theme when omitted | `light` \| `dark` | - |
| items | Menu data | MenuOptionsProps[] | - |
| openKeys | Currently expanded SubMenu menu item key array | string[] | [] |
| mode | Menu type | `vertical` \| `horizontal` \| `inline` | `vertical` |
| onSelect | Called when MenuItem is clicked | (data: MenuSelectEvent) => void | - |
| onOpenChange | Callback when SubMenu expands/collapses | (openKeys: string[]) => void | - |
| accordion | Whether only one menu item can be expanded | boolean | false |
| inlineCollapsed | Whether the menu is collapsed in inline mode | boolean | false |
| collapsedTooltip | Whether leaf items show a tooltip when collapsed | boolean | true |
### Menu(items)
| Property | Description | Type | Default |
| -------- | -------------------------- | ------------------ | ------- |
| icon | Item icon | IconType | - |
| disabled | Whether disabled | boolean | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | VNodeChild | - |
| children | Menu children | MenuOptionsProps[] | - |
### MenuItem
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | `VNodeChild` | - |
| onClick | Callback fired when item clicked | `(event: MouseEvent) => void` | - |
### SubMenu
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Submenu item content | `VNodeChild` | - |
### MenuGroup
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Group title | `VNodeChild` | - |
---
# Menu
Navigation menu list for pages and functions.
## When to Use
The navigation menu is the soul of a website. Users rely on navigation to jump between pages. Generally divided into top navigation and side navigation. Top navigation provides global categories and functions, while side navigation provides a multi-level structure to accommodate and arrange the website architecture.
## Examples
[Top Navigation](./demo/basic.vue?show=vertical)
- Horizontal top navigation menu.
[Inline Menu](./demo/inline.vue?show=vertical)
- Vertical menu, with submenus embedded within the menu area.
[Expand Only Current Parent Menu](./demo/accordion.vue?show=vertical)
- Clicking a menu item collapses all other expanded menus, keeping the menu focused and clean.
[Vertical Menu](./demo/vertical.vue?show=vertical)
- Submenus appear as popups.
[Theme](./demo/theme.vue?show=vertical)
- Supports local `light|dark` themes and inherits the global theme when omitted.
[Switch Menu Type](./demo/mode.vue?show=vertical)
- Demonstrates dynamic mode switching.
[Collapsible Inline Menu](./demo/collapsed.vue?show=vertical)
- Inline menus can be collapsed/expanded.
## API
### MenuAPI
| Property | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------- |
| modelValue | Currently selected menu items (v-model) | string[] | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | string[] | [] |
| theme | Local theme; inherits global theme when omitted | `light` \| `dark` | - |
| items | Menu data | MenuOptionsProps[] | - |
| openKeys | Currently expanded SubMenu menu item key array | string[] | [] |
| mode | Menu type | `vertical` \| `horizontal` \| `inline` | `vertical` |
| onSelect | Called when MenuItem is clicked | (data: MenuSelectEvent) => void | - |
| onOpenChange | Callback when SubMenu expands/collapses | (openKeys: string[]) => void | - |
| accordion | Whether only one menu item can be expanded | boolean | false |
| inlineCollapsed | Whether the menu is collapsed in inline mode | boolean | false |
| collapsedTooltip | Whether leaf items show a tooltip when collapsed | boolean | true |
### Menu(items)
| Property | Description | Type | Default |
| -------- | -------------------------- | ------------------ | ------- |
| icon | Item icon | IconType | - |
| disabled | Whether disabled | boolean | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | VNodeChild | - |
| children | Menu children | MenuOptionsProps[] | - |
### MenuItem
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | `VNodeChild` | - |
| onClick | Callback fired when item clicked | `(event: MouseEvent) => void` | - |
### SubMenu
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Submenu item content | `VNodeChild` | - |
### MenuGroup
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Group title | `VNodeChild` | - |
---
# Menu
Navigation menu list for pages and functions.
## When to Use
The navigation menu is the soul of a website. Users rely on navigation to jump between pages. Generally divided into top navigation and side navigation. Top navigation provides global categories and functions, while side navigation provides a multi-level structure to accommodate and arrange the website architecture.
## Examples
[Top Navigation](./demo/basic.vue?show=vertical)
- Horizontal top navigation menu.
[Inline Menu](./demo/inline.vue?show=vertical)
- Vertical menu, with submenus embedded within the menu area.
[Expand Only Current Parent Menu](./demo/accordion.vue?show=vertical)
- Clicking a menu item collapses all other expanded menus, keeping the menu focused and clean.
[Vertical Menu](./demo/vertical.vue?show=vertical)
- Submenus appear as popups.
[Theme](./demo/theme.vue?show=vertical)
- Supports local `light|dark` themes and inherits the global theme when omitted.
[Switch Menu Type](./demo/mode.vue?show=vertical)
- Demonstrates dynamic mode switching.
[Collapsible Inline Menu](./demo/collapsed.vue?show=vertical)
- Inline menus can be collapsed/expanded.
## API
### MenuAPI
| Property | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------- |
| modelValue | Currently selected menu items (v-model) | string[] | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | string[] | [] |
| theme | Local theme; inherits global theme when omitted | `light` \| `dark` | - |
| items | Menu data | MenuOptionsProps[] | - |
| openKeys | Currently expanded SubMenu menu item key array | string[] | [] |
| mode | Menu type | `vertical` \| `horizontal` \| `inline` | `vertical` |
| onSelect | Called when MenuItem is clicked | (data: MenuSelectEvent) => void | - |
| onOpenChange | Callback when SubMenu expands/collapses | (openKeys: string[]) => void | - |
| accordion | Whether only one menu item can be expanded | boolean | false |
| inlineCollapsed | Whether the menu is collapsed in inline mode | boolean | false |
| collapsedTooltip | Whether leaf items show a tooltip when collapsed | boolean | true |
### Menu(items)
| Property | Description | Type | Default |
| -------- | -------------------------- | ------------------ | ------- |
| icon | Item icon | IconType | - |
| disabled | Whether disabled | boolean | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | VNodeChild | - |
| children | Menu children | MenuOptionsProps[] | - |
### MenuItem
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Menu item content | `VNodeChild` | - |
| onClick | Callback fired when item clicked | `(event: MouseEvent) => void` | - |
### SubMenu
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Item icon | `IconType[]` | - |
| disabled | Whether disabled | `boolean` | false |
| key | Unique identifier for item | string | - |
| title | Submenu item content | `VNodeChild` | - |
### MenuGroup
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Group title | `VNodeChild` | - |
---
# Mentions
[Basic](./demo/basic.vue)
- Type @ and select a mention with the keyboard.
[Multiple triggers](./demo/triggers.vue)
- Supports both people and topic triggers.
[Custom filter](./demo/filter.vue)
- Customize suggestion matching.
[Remote search](./demo/remote.vue)
- After a trigger, typing at least one character emits `search` so suggestions can be updated asynchronously.
[Size](./demo/size.vue)
- Display different sizes.
[Size, theme and shape](./demo/appearance.vue)
- Shows several textarea appearances.
[Empty state](./demo/empty.vue)
- Displays Empty when no mention matches.
[Rows](./demo/rows.vue)
- Controls the input height with `rows`; use 1 for a single-line appearance.
[Placement](./demo/placement.vue)
- Anchors the menu to the caret and flips it when space is insufficient.
## Mentions API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Text (v-model) | `string` | - |
| value | Initial text | `string` | '' |
| options | Suggestions | `(string \| MentionOption)[]` | [] |
| triggers | Trigger strings | `string[]` | ['@'] |
| placeholder | Placeholder | `string` | - |
| disabled | Disabled | `boolean` | false |
| readonly | Read-only; prevents editing, selecting and clearing | `boolean` | false |
| clearable | Whether to show clear button | `boolean` | true |
| loading | Whether remote suggestions are loading | `boolean` | false |
| loadingText | Loading text | `string` | - |
| rows | Textarea rows | `number` | 1 |
| placement | Preferred dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | bottom-left |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| theme | Theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | default |
| emptyText | Empty-state text | `string` | No data |
| filterOption | Custom filter | `((query: string, option: MentionOption) => boolean)` | - |
| onChange | Text change | `(value: string) => void` | - |
| onSelect | Mention selection | `(option: MentionOption, trigger: string) => void` | - |
| onSearch | Remote search with query and trigger | `(value: string, trigger: string) => void` | - |
| onClear | Text cleared | `() => void` | - |
---
# MessagePanel
See https://k-ui.cn/components/message-panel.
---
# NoticePanel
See https://k-ui.cn/components/notice-panel.
---
# ModalPanel
See https://k-ui.cn/components/modal-panel.
---
# Modal
Modal dialog box.
## When to Use
- When users need to handle transactions without jumping to another page to interrupt the workflow, a Modal can be opened in the center of the current page to carry the corresponding operations.
- Additionally, when a simple confirmation box is needed to ask the user, syntax sugar methods like Modal.confirm() can be used.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Custom](./demo/custom.vue)
- Custom `Modal`.
[Other Properties](./demo/more.vue)
- When the footer is not needed, set `footer` to `null`.
[Global Mode](./demo/global.vue)
- Use global mode.
[Confirmation Dialog](./demo/confirm.vue)
- A global confirmation dialog that can be closed asynchronously.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether the dialog is displayed, can use v-model for two-way binding. | `boolean` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `boolean` | false |
| title | Dialog title | `string` | - |
| width | Dialog width | `string \| number` | 520 |
| okText | OK button text | `string` | OK |
| cancelText | Cancel button text | `string` | Cancel |
| draggable | Whether the modal can be dragged, not available in confirm mode | `boolean` | false |
| centered | Whether the window can be centered, not available in confirm mode | `boolean` | false |
| maximized | Whether the modal can be maximized, not available in confirm mode | `boolean` | false |
| maskClosable | Whether clicking the mask closes the modal, if not, Esc key will be invalid | `boolean` | true |
| escKey | Whether to support closing with Esc key | `boolean` | true |
| footer | When `footer=false`, the bottom button is not displayed. | `boolean` | true |
| loading | When set to `true`, the confirm button will be in a loading state | `boolean` | false |
| top | Distance from the top of the window | `number` | - |
| showClose | Whether to display the close button | `boolean` | false |
| mask | Whether to show the mask | `boolean` | true |
| onOk | Callback when OK is clicked, `Note: will not close Modal` | `() => void` | - |
| onCancel | Callback when Cancel is clicked | `() => void` | - |
| onClose | Callback when window closes | `() => void` | - |
| onOpenChange | Callback for opening or closing a window | `(visible: boolean) => void` | - |
## Modal.method()
The component provides some static methods, used as follows:
- modal.info(options)
- modal.success(options)
- modal.warning(options)
- modal.error(options)
- modal.confirm(options)
Also provides global configuration and global destruction methods:
- modal.show(options)
- modal.destroyAll()
Imperative modals are mounted globally under `body` and are not owned by the current page component. Destroy them from a router hook when they should close after navigation:
```ts
router.afterEach(() => {
modal.destroyAll();
});
```
Parameter options is an object, specific description as follows:
| Property | Description | Type | Default |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| title | Dialog title | string | - |
| content | Dialog content | string | - |
| okText | OK button text | string | OK |
| cancelText | Cancel button text | string | Cancel |
| icon | Modal icon, available when type is toast, default optional values are success, warning, error, info, can also be customized, refer to /components/icon values | string | - |
| color | Modal icon color, available when type is toast | string | - |
| onOk | Callback when OK is clicked | () => void | - |
| onCancel | Callback when Cancel is clicked | () => void | - |
### Panel presentation
| Property | Description | Type | Default |
| --------- | -------------------------------------------------------- | ------- | ------- |
| panelOnly | Render only the dialog panel without overlay or Teleport | boolean | false |
---
# Pagination
Separate long lists using pagination, loading only one page at a time.
## When to Use
- When loading/rendering all data would take a long time.
- When browsing data by switching page numbers.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Basic pagination.
[Items / Jump](./demo/sizer-elevator.vue?show=vertical)
- Change the number of items displayed per page.
[Size](./demo/size.vue?show=vertical)
- Displays small, medium, and large sizes.
[Simple](./demo/simple.vue?show=vertical)
- Only shows previous, current/total pages, and next controls; with `showElevator`, the current page becomes editable.
[Responsive pagination](./demo/responsive.vue?show=vertical)
- Drag the bottom-right corner to resize the container. Pagination first reduces page numbers, then switches to Simple when space is limited. The page-size selector remains available and may wrap. Widening the container restores the full layout without changing the page or emitting change events. Set `responsive` to `false` to disable adaptation; `simple` always forces Simple mode.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| page | Current page number(v-model) | `number` | 1 |
| disabled | Disabled status | `boolean` | false |
| total | Total data count | `number` | 0 |
| pageSize | Number of items per page (v-model:pageSize) | `number` | 10 |
| showSizer | Whether to show page size selector | `boolean` | false |
| showTotal | Whether to show total count | `boolean` | true |
| showElevator | Whether to show page elevator | `boolean` | false |
| simple | Use compact pagination | `boolean` | false |
| responsive | Adapt pagination to the available container width | `boolean` | true |
| sizeData | Custom page size data | `number[]` | [10,15,20,30,40] |
| size | Size | `"small" \| "medium" \| "large"` | `medium` |
| theme | Theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | `fill` |
| onChange | Called when the page or page size changes | `(page: number, pageSize: number) => void` | - |
| shape | Pagination item shape | `"default" \| "circle" \| "square" \| "round"` | round |
---
# PageHeader
Provides a consistent layout for page titles, descriptions and actions.
## Demos
[Basic](./demo/basic.vue?show=vertical)
- Combine a page title, description and common actions.
[Full structure](./demo/slots.vue?show=vertical)
- Compose breadcrumbs, a back action, title and actions, then combine with `ListPanel` to build a list page.
[Simple header](./demo/simple.vue?show=vertical)
- Render a title and description using props only.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Page title, customizable via the named slot | `string` | - |
| description | Page description, customizable via the named slot | `string` | - |
| breadcrumb | Breadcrumb area | VNodeChild | - |
| back | Back action area | VNodeChild | - |
| actions | Page actions | VNodeChild | - |
---
# PoptipPanel
See https://k-ui.cn/components/poptip-panel.
---
# Poptip
Click/mouse over an element to pop up a bubble-style card floating layer.
## When to Use
When a target element has further descriptions and related operations, they can be accommodated in a card and displayed based on user actions.
The difference from `Tooltip` is that users can operate on elements in the floating layer, so it can carry more complex content, such as links or buttons.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage, where the floating layer's size is determined by the content area.
[Trigger Mode](./demo/trigger.vue)
- Control the trigger mode via `trigger`, with options for mouse hover (`hover`) or click (`click`).
[Close from Inside the Floating Layer](./demo/closeinside.vue)
- Use the `v-model` attribute to control the floating layer's visibility.
[Position](./demo/placement.vue)
- Control the direction via `placement`, with twelve available positions.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| trigger | Trigger method: `hover`, `click`, or `focus` | `"hover" \| "click" \| "focus"` | hover |
| title | Displayed title | `VNodeChild` | - |
| content | Displayed main content | `string` | - |
| placement | Position where the tooltip appears | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "left-bottom" \| "left-top" \| "right" \| "right-top" \| "right-bottom"` | top |
| width | Display width, defaults to content area size | `string \| number` | - |
| show | Whether to display | `boolean` | false |
| dark | Use dark theme | `boolean` | false |
| onClose | Callback when closed | `() => void` | - |
| panelOnly | Render only the popover panel without a trigger | `boolean` | false |
---
# PopconfirmPanel
See https://k-ui.cn/components/popconfirm-panel.
---
# Popconfirm
Click an element to pop up a bubble-style confirmation box.
## When to Use
When an operation on a target element requires further user confirmation, a floating layer prompt appears near the target element to ask the user.
Compared to the full-screen centered modal dialog box popped up by 'confirm', the interaction form is lighter.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage.
[Internationalization](./demo/local.vue)
- Use `okText` and `cancelText` to customize button text.
[Position](./demo/placement.vue)
- Control the direction via `placement`, with twelve available positions.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Displayed title | `VNodeChild` | - |
| placement | Position where the tooltip appears, optional values: `top`, `top-left`, `top-right`, `bottom`, `bottom-left`, `bottom-right`, `left`, `left-top`, `left-bottom`, `right`, `right-top`, `right-bottom` | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "left-bottom" \| "left-top" \| "right" \| "right-top" \| "right-bottom"` | top |
| width | Display width; numbers and numeric strings use px | `string \| number` | - |
| okText | OK button text | `string` | OK |
| cancelText | Cancel button text | `string` | Cancel |
| show | Whether to display by default | `boolean` | false |
| dark | Whether to display dark theme | `boolean` | false |
| onCancel | Callback when cancel is clicked | `() => void` | - |
| onOk | Callback when OK is clicked | `() => void` | - |
| panelOnly | Render only the confirmation panel without a trigger | `boolean` | false |
---
# Progress
Display the current progress of an operation.
## When to Use
When an operation takes a long time to complete, display the current progress and status to the user.
- When an operation interrupts the current interface or needs to run in the background, and may take more than 2 seconds.
- When displaying the completion percentage of an operation.
## Examples
[Progress Bar](./demo/basic.vue)
- A standard progress bar.
[Circular Progress](./demo/circle.vue)
- A circular progress bar.
[Dashboard-style Progress Bar](./demo/dashboard.vue)
- Dashboard-style progress bar. Adjust the gap size via `gapDegree`. Use `strokeLinecap="square|round"` to adjust the shape of the progress bar's edges.
[Dynamic Display](./demo/dynamic.vue)
- A moving progress bar is a good progress bar.
[Color and Format](./demo/color.vue)
- Customize color and format.
[Size](./demo/size.vue)
- Suitable for placement in narrower areas.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| percent | Progress percentage | `number` | 0 |
| color | Progress bar color | `string` | - |
| strokeLinecap | Progress bar style | `"square" \| "round" \| "butt"` | round |
| width | Circular progress bar canvas width, in px | `number` | - |
| size | When value is `small`, displays small size | `"small" \| "medium" \| "large"` | - |
| format | Custom progress bar text | `((percent: number) => VNodeChild)` | - |
| status | Progress bar status, provides four types: `active`, `exception`, `success`, `normal` | `"success" \| "active" \| "normal" \| "exception"` | normal |
| type | Progress bar type, provides three types: `line`, `circle`, `dashboard` | `"circle" \| "line" \| "dashboard"` | - |
| showInfo | Whether to show progress text | `boolean` | true |
| gapDegree | Dashboard progress bar gap angle, can be 0 ~ 295 | `number` | 75 |
| strokeWidth | Circular progress bar line width | `number` | 6 |
| strokeHeight | Progress bar line height | `number` | - |
---
# Ripple
Adds WebGL-rendered water ripples and refraction over live DOM content.
## Browser support
Full refraction relies on the experimental HTML-in-Canvas API. Test it in Chrome Canary 149+ with `chrome://flags/#canvas-draw-element` enabled. Production usage requires the HTML-in-Canvas Origin Trial. Other browsers fall back to a WebGL ripple overlay.
[Basic](./demo/basic.vue?show=vertical)
- Click the content area to create a ripple.
[Custom effect](./demo/options.vue?show=vertical)
- Uses hover triggering with customized wave parameters.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| trigger | Ripple trigger | `"hover" \| "click" \| "none"` | `'click'` |
| amplitude | Wave height, recommended range 0–3 | `number` | `0.5` |
| speed | Propagation speed multiplier | `number` | `0.65` |
| wavelength | Distance between crests in px | `number` | `80` |
| rings | Crests in each wave train | `number` | `2` |
| decay | Energy decay rate | `number` | `1` |
| refraction | Refraction strength in px | `number` | `100` |
| dispersion | Chromatic dispersion | `number` | `0.5` |
| shine | Crest highlight intensity | `number` | `0.5` |
| interval | Ambient ripple interval; `0` disables it | `number` | `0` |
---
# QRCode
A component that converts text into QR codes, supporting custom colors and logo configuration.
## When to Use
- Use this component when you need to convert text into a scannable QR code.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage.
[Different states](./demo/status.vue)
- Control the QR code state via the `status` prop. Supported values: `active`, `expired`, `loading`, and `scanned`.
[Custom Properties](./demo/custom.vue)
- Customize the QR code display using various configurable properties.
[Cards and Downloads](./demo/download.vue)
- Display the QR code within a card and enable downloading.
[Custom Status](./demo/custom-status.vue)
- Customize the display for different status states.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| value | Text content or redirect URL encoded in the QR code. | `string` | Required |
| size | Side length of the square QR code in `px`. Optimized for high-DPI displays to prevent blurring on large screens. | `number` | `160` |
| colorDark | Foreground color (the color of QR code modules). Supports hex, RGB, and CSS variables. Automatically re-renders when the root attribute `theme-mode` changes. | `string` | `"var(--kui-color-reverse)"` |
| colorLight | Background color. Supports hex, RGB, and CSS variables. For dark mode, use dark tones and avoid full transparency to ensure scan reliability. | `string` | `"var(--kui-color-bg)"` |
| bordered | Whether to keep the outer border and padding container. | `boolean` | `true` |
| status | Current business state of the QR code. Options: • `'active'`: Scannable • `'loading'`: Loading secure link • `'expired'`: Expired (shows refresh button) • `'scanned'`: Successfully scanned (customizable overlay via slots) | `"loading" \| "active" \| "expired" \| "scanned"` | `'active'` |
| logo | URL (network or Base64) of the logo displayed at the center of the QR code. | `string` | - |
| logoSize | Size of the centered logo in `px`. If omitted, defaults to 22% of the QR code size. | `number` | - |
| logoRadius | Border radius of the centered logo in `px`. | `number` | `4` |
| logoBorder | Whether to add a white protective border around the logo. Prevents visual clutter by separating QR modules from the logo. | `boolean` | `true` |
| margin | Quiet zone (white border) width around the QR code matrix, measured in module counts. | `number` | `0` |
| errorLevel | Error correction level. Options: `'L'` (7%), `'M'` (15%), `'Q'` (25%), `'H'` (30%). _Note: When embedding a logo, it is recommended to use `'M'` or `'H'` to ensure reliable scanning even if the center is obscured._ | `"M" \| "L" \| "Q" \| "H"` | `'M'` |
| loading | Custom overlay for `status="loading"` | VNodeChild | - |
| expired | Custom overlay for `status="expired"` | VNodeChild | - |
| scanned | Custom overlay for `status="scanned"` | VNodeChild | - |
### Events
| Event Name | Description | Callback Signature |
| :--------- | :------------------------------------------------------------------------------------------------------------------ | :----------------- |
| refresh | Triggered when clicking the refresh button on the overlay while `status` is `'expired'`. Used to fetch new QR data. | () => void |
### Expose
| Method | Description | Type |
| -------- | ------------------------------------------------------------- | -------------------------------------- |
| download | Wait for the QR code and logo to finish, then download a PNG. | `(fileName?: string) => Promise` |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| theme | QR appearance | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | outline |
| shape | QR container shape | `"default" \| "circle" \| "square" \| "round"` | round |
---
# Radio
Radio button.
## When to Use
- Used to select a single state from multiple options.
- The legendary choose one of two.
## Examples
[Single Selection](./demo/basic.vue)
- When used alone, the `v-model` value is `true` for selected and `false` for unselected.
[Radio Group](./demo/group.vue)
- You can use the `options` attribute to set options, or use child components to set options.
[Group Layout](./demo/vertical.vue)
- Group layout.
[Disabled / Controllable](./demo/disabled.vue)
- Set `disabled` to make it unavailable.
[Combined with Button](./demo/radio-buttons.vue)
- Combine `RadioGroup` and `RadioButton` for usage.
## Radio API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether selected (v-model) | `boolean` | false |
| checked | Whether selected | `boolean` | false |
| label | Text prompt | `string` | - |
| value | Value when used in combination | `string \| number` | - |
| name | Native radio group name | `string` | - |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; cannot be toggled | `boolean` | false |
| onChange | Callback when option state changes | `(event: ChangeEvent) => void` | - |
### RadioButton API
`RadioButton` supports Radio properties and adds:
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Button icon | `IconType[]` | - |
Use `RadioButton` through `RadioGroup type="button"`.
Use the standalone [Segmented](../segmented/index.en_US.md) component for slider-style selection. `RadioGroup` no longer supports `theme="card"`.
## RadioGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Used to set the currently selected value. Can use `v-model` for two-way binding data | `string \| number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string \| number` | - |
| disabled | Disable the entire group | `boolean` | false |
| readonly | Whether the group is read-only | `boolean` | false |
| size | Button size | `"small" \| "medium" \| "large"` | - |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| shape | Button shape | `"default" \| "circle" \| "square" \| "round"` | - |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| onChange | Triggered when option state changes, returns currently selected item | `(value: string \| number) => void` | - |
| options | Can specify child `radio` items | `RadioOption[]` | - |
| type | Use radio or button-style items | `"button" \| "radio"` | radio |
---
# Radio
Radio button.
## When to Use
- Used to select a single state from multiple options.
- The legendary choose one of two.
## Examples
[Single Selection](./demo/basic.vue)
- When used alone, the `v-model` value is `true` for selected and `false` for unselected.
[Radio Group](./demo/group.vue)
- You can use the `options` attribute to set options, or use child components to set options.
[Group Layout](./demo/vertical.vue)
- Group layout.
[Disabled / Controllable](./demo/disabled.vue)
- Set `disabled` to make it unavailable.
[Combined with Button](./demo/radio-buttons.vue)
- Combine `RadioGroup` and `RadioButton` for usage.
## Radio API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether selected (v-model) | `boolean` | false |
| checked | Whether selected | `boolean` | false |
| label | Text prompt | `string` | - |
| value | Value when used in combination | `string \| number` | - |
| name | Native radio group name | `string` | - |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; cannot be toggled | `boolean` | false |
| onChange | Callback when option state changes | `(event: ChangeEvent) => void` | - |
### RadioButton API
`RadioButton` supports Radio properties and adds:
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Button icon | `IconType[]` | - |
Use `RadioButton` through `RadioGroup type="button"`.
Use the standalone [Segmented](../segmented/index.en_US.md) component for slider-style selection. `RadioGroup` no longer supports `theme="card"`.
## RadioGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Used to set the currently selected value. Can use `v-model` for two-way binding data | `string \| number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string \| number` | - |
| disabled | Disable the entire group | `boolean` | false |
| readonly | Whether the group is read-only | `boolean` | false |
| size | Button size | `"small" \| "medium" \| "large"` | - |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| shape | Button shape | `"default" \| "circle" \| "square" \| "round"` | - |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| onChange | Triggered when option state changes, returns currently selected item | `(value: string \| number) => void` | - |
| options | Can specify child `radio` items | `RadioOption[]` | - |
| type | Use radio or button-style items | `"button" \| "radio"` | radio |
---
# Radio
Radio button.
## When to Use
- Used to select a single state from multiple options.
- The legendary choose one of two.
## Examples
[Single Selection](./demo/basic.vue)
- When used alone, the `v-model` value is `true` for selected and `false` for unselected.
[Radio Group](./demo/group.vue)
- You can use the `options` attribute to set options, or use child components to set options.
[Group Layout](./demo/vertical.vue)
- Group layout.
[Disabled / Controllable](./demo/disabled.vue)
- Set `disabled` to make it unavailable.
[Combined with Button](./demo/radio-buttons.vue)
- Combine `RadioGroup` and `RadioButton` for usage.
## Radio API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether selected (v-model) | `boolean` | false |
| checked | Whether selected | `boolean` | false |
| label | Text prompt | `string` | - |
| value | Value when used in combination | `string \| number` | - |
| name | Native radio group name | `string` | - |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; cannot be toggled | `boolean` | false |
| onChange | Callback when option state changes | `(event: ChangeEvent) => void` | - |
### RadioButton API
`RadioButton` supports Radio properties and adds:
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Button icon | `IconType[]` | - |
Use `RadioButton` through `RadioGroup type="button"`.
Use the standalone [Segmented](../segmented/index.en_US.md) component for slider-style selection. `RadioGroup` no longer supports `theme="card"`.
## RadioGroup API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Used to set the currently selected value. Can use `v-model` for two-way binding data | `string \| number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string \| number` | - |
| disabled | Disable the entire group | `boolean` | false |
| readonly | Whether the group is read-only | `boolean` | false |
| size | Button size | `"small" \| "medium" \| "large"` | - |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| shape | Button shape | `"default" \| "circle" \| "square" \| "round"` | - |
| theme | Button theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| onChange | Triggered when option state changes, returns currently selected item | `(value: string \| number) => void` | - |
| options | Can specify child `radio` items | `RadioOption[]` | - |
| type | Use radio or button-style items | `"button" \| "radio"` | radio |
---
# Segmented
Switch quickly between mutually exclusive options.
## Examples
[Basic](./demo/basic.vue)
- Bind the selected option with `v-model`.
[Size and layout](./demo/options.vue)
- Supports sizes, block layout, vertical layout, and disabled options.
[Options with icons](./demo/icon.vue)
- Add an icon with `options[].icon`.
[Custom labels](./demo/label.vue)
- Customize option content with the scoped `label` slot and access `option` and `selected`.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Selected value | `SegmentedValue` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `SegmentedValue` | - |
| options | Option data | `SegmentedOption[]` | [] |
| disabled | Disable all options | `boolean` | false |
| readonly | Read-only state | `boolean` | false |
| block | Fill the parent width | `boolean` | false |
| direction | Layout direction | `"horizontal" \| "vertical"` | horizontal |
| size | Size | `"small" \| "medium" \| "large"` | medium |
| shape | Shape | `"default" \| "circle" \| "square" \| "round"` | round |
| label | Custom option content with `{ option, selected }` | VNodeChild | - |
## Events
| Event | Description | Type |
| --- | --- | --- |
| change | Triggered when selection changes | `(value: SegmentedValue) => void` |
### SegmentedOption
| Property | Description | Type | Default |
| -------- | ------------------- | ---------------- | ------- |
| label | Option content | VNodeChild | - |
| value | Option value | string \| number | - |
| icon | Option icon | IconType[] | - |
| disabled | Disable this option | boolean | false |
---
# Rate
Rating component.
## When to Use
- Display evaluations.
- Quickly rate things.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage.
[Text Display / Allow Clear](./demo/tips.vue)
- Add text display to the rating component.
[Other Characters](./demo/character.vue)
- Stars can be replaced with other characters, such as letters, numbers, font icons, or even Chinese characters.
## Rate API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Current controlled value, used with `v-model` | `number` | - |
| value | Initial value in uncontrolled mode | `number` | 0 |
| allowClear | Whether to allow clearing by clicking again | `boolean` | true |
| allowHalf | Whether to allow half selection | `boolean` | false |
| showScore | Whether to show score | `boolean` | false |
| character | Custom character | `string \| ((index: number) => VNodeChild)` | - |
| count | Total number of stars | `number` | 5 |
| icon | Custom display icon | `IconType[] \| ((index: number) => IconType[])` | - |
| size | Icon size | `number \| SizeType` | - |
| color | Icon color | `string` | - |
| disabled | Read-only, cannot interact | `boolean` | false |
| readonly | Read-only with normal appearance | `boolean` | false |
| tooltips | Custom prompt information for each item | `string[]` | - |
| onChange | Callback when selecting | `(value: number) => void` | - |
| symbolReverseFill | Symbol Inverted Fill Color | `boolean` | false |
| strokeWidth | Symbol Border Unit | `number` | 1 |
---
# Result
Presents the outcome of an operation or task.
## Examples
[Success](./demo/basic.vue?show=vertical)
- Display successful result feedback.
[Info](./demo/info.vue?show=vertical)
- Display information result page.
[Warning](./demo/warning.vue?show=vertical)
- Display warning result information.
[Error](./demo/error.vue?show=vertical)
- Display error operation result.
[Custom](./demo/custom.vue?show=vertical)
- Customize result page content and actions.
[404](./demo/404.vue?show=vertical)
- Page not found error page.
[403](./demo/403.vue?show=vertical)
- Permission denied error page.
[500](./demo/500.vue?show=vertical)
- Server error page.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| status | Result status | `"info" \| "success" \| "warning" \| "error" \| "403" \| "404" \| "500"` | info |
| title | Title | `VNodeChild` | - |
| subTitle | Subtitle | `VNodeChild` | - |
| icon | Custom icon | `IconType[]` | - |
---
# FeedbackPanel
Embeds status, supporting information, and next steps within page content.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Basic Usage
[Feedback Kinds](./demo/kinds.vue?show=vertical)
- Define feedback types using 'kind'
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| kind | Feedback kind | `"positive" \| "negative" \| "caution" \| "neutral"` | neutral |
| heading | Primary message | `VNodeChild` | - |
| description | Supporting message | `VNodeChild` | - |
| symbol | Custom marker | `IconType[]` | - |
| compact | Compact layout | `boolean` | false |
| theme | Appearance theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | default |
| shape | Panel shape | `"square" \| "round"` | round |
---
# Select
Dropdown selector.
## When to Use
- Pop up a dropdown menu for user selection operations, used to replace native selectors, or when a more elegant multi-selector is needed.
- When there are few options (less than 5), it is recommended to lay out the options directly. Using Radio is a better choice.
## Examples
[Single Selection](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Multiple Selection](./demo/multiple.vue)
- Set the `multiple` value to present multi-select mode.
[Disabled and Non-clearable](./demo/disabled.vue)
- Use `v-model` for two-way data binding.
[Filtering and Searching](./demo/filterable.vue)
- Set the `filterable` value to present filtering mode. > `filterable` and `onSearch` cannot be used simultaneously; search results will be filtered.
[Create Options](./demo/allow-create.vue)
- In multiple mode, enable `allowCreate` to create and select a missing option by pressing Enter.
[Size](./demo/size.vue)
- Control component size via `width` and `size`.
[Weird Definition](./demo/theme.vue)
- Some strange things.
[Virtual scrolling](./demo/virtual.vue?show=vertical)
- Renders only nearby options for large data sets while preserving search and keyboard controls.
## Select API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Specifies the `value` of the selected item, can use `v-model` for two-way binding | `SelectValue \| SelectValue[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `SelectValue \| SelectValue[]` | - |
| width | Component width | `number` | - |
| placeholder | Default text of selector | `string` | Please select |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; prevents opening, clearing and changing | `boolean` | false |
| size | Component size, provides two sizes: `small`, `large`, default is normal | `"small" \| "medium" \| "large"` | - |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | bottom-left |
| emptyText | Prompt displayed when no data | `string` | 'No data yet' |
| maxTagCount | Maximum visible tags in multiple mode; excess tags are shown in a Tooltip | `number` | - |
| multiple | Whether to display in multiple selection mode | `boolean` | false |
| allowCreate | Whether multiple mode can create missing options from entered text | `boolean` | false |
| loading | Whether to show asynchronous loading | `boolean` | false |
| loadingText | Loading state text | `string` | - |
| block | Whether to fill the parent width | `boolean` | false |
| filterable | Whether input filtering is enabled | `boolean` | false |
| clearable | Whether options can be cleared | `boolean` | true |
| bordered | Whether to show border | `boolean` | true |
| extendWidth | Whether dropdown width matches input width | boolean | true |
| showArrow | Whether to show dropdown button | `boolean` | true |
| options | options data, if set, no need to manually construct Option nodes | `SelectOption[]` | [] |
| theme | The theme of Select | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| icon | Custom icon | `IconType[]` | - |
| shape | When shape='circle', displays rounded corners | `"default" \| "circle" \| "square" \| "round"` | - |
| onSelect | Triggered when an item is selected | `(option: OptionSelectEvent) => void` | - |
| onChange | Triggered when option state changes, returns selected value | `(value: SelectValue \| SelectValue[]) => void` | - |
| onOpenChange | Triggered when dropdown expands or collapses | `(open: boolean) => void` | - |
| onSearch | Triggered during search | `(event: InputEvent) => void` | - |
| onClear | Triggered when the clear button is clicked | `() => void` | - |
| arrowIcon | Custom arrow icon | `IconType[]` | - |
| virtual | Enable virtual scrolling | `boolean` | false |
| itemHeight | Fixed virtual option height | `number` | 33 |
| overscan | Extra virtual options rendered around the viewport | `number` | 5 |
## Option API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| key | Same meaning as value. If Vue requires this setting, this value should be the same as value, then value setting can be omitted | string \| number | - |
| value | Option value, used for filtering by default, required | `string \| number` | - |
| label | Option display content | `VNodeChild` | - |
| disabled | Whether current item is disabled | `boolean` | false |
| active | Whether this is the current keyboard-focused option | `boolean` | false |
| checked | Whether the option is selected | `boolean` | false |
---
# Select
Dropdown selector.
## When to Use
- Pop up a dropdown menu for user selection operations, used to replace native selectors, or when a more elegant multi-selector is needed.
- When there are few options (less than 5), it is recommended to lay out the options directly. Using Radio is a better choice.
## Examples
[Single Selection](./demo/basic.vue)
- Use `v-model` for two-way data binding.
[Multiple Selection](./demo/multiple.vue)
- Set the `multiple` value to present multi-select mode.
[Disabled and Non-clearable](./demo/disabled.vue)
- Use `v-model` for two-way data binding.
[Filtering and Searching](./demo/filterable.vue)
- Set the `filterable` value to present filtering mode. > `filterable` and `onSearch` cannot be used simultaneously; search results will be filtered.
[Create Options](./demo/allow-create.vue)
- In multiple mode, enable `allowCreate` to create and select a missing option by pressing Enter.
[Size](./demo/size.vue)
- Control component size via `width` and `size`.
[Weird Definition](./demo/theme.vue)
- Some strange things.
[Virtual scrolling](./demo/virtual.vue?show=vertical)
- Renders only nearby options for large data sets while preserving search and keyboard controls.
## Select API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Specifies the `value` of the selected item, can use `v-model` for two-way binding | `SelectValue \| SelectValue[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `SelectValue \| SelectValue[]` | - |
| width | Component width | `number` | - |
| placeholder | Default text of selector | `string` | Please select |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; prevents opening, clearing and changing | `boolean` | false |
| size | Component size, provides two sizes: `small`, `large`, default is normal | `"small" \| "medium" \| "large"` | - |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | bottom-left |
| emptyText | Prompt displayed when no data | `string` | 'No data yet' |
| maxTagCount | Maximum visible tags in multiple mode; excess tags are shown in a Tooltip | `number` | - |
| multiple | Whether to display in multiple selection mode | `boolean` | false |
| allowCreate | Whether multiple mode can create missing options from entered text | `boolean` | false |
| loading | Whether to show asynchronous loading | `boolean` | false |
| loadingText | Loading state text | `string` | - |
| block | Whether to fill the parent width | `boolean` | false |
| filterable | Whether input filtering is enabled | `boolean` | false |
| clearable | Whether options can be cleared | `boolean` | true |
| bordered | Whether to show border | `boolean` | true |
| extendWidth | Whether dropdown width matches input width | boolean | true |
| showArrow | Whether to show dropdown button | `boolean` | true |
| options | options data, if set, no need to manually construct Option nodes | `SelectOption[]` | [] |
| theme | The theme of Select | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| icon | Custom icon | `IconType[]` | - |
| shape | When shape='circle', displays rounded corners | `"default" \| "circle" \| "square" \| "round"` | - |
| onSelect | Triggered when an item is selected | `(option: OptionSelectEvent) => void` | - |
| onChange | Triggered when option state changes, returns selected value | `(value: SelectValue \| SelectValue[]) => void` | - |
| onOpenChange | Triggered when dropdown expands or collapses | `(open: boolean) => void` | - |
| onSearch | Triggered during search | `(event: InputEvent) => void` | - |
| onClear | Triggered when the clear button is clicked | `() => void` | - |
| arrowIcon | Custom arrow icon | `IconType[]` | - |
| virtual | Enable virtual scrolling | `boolean` | false |
| itemHeight | Fixed virtual option height | `number` | 33 |
| overscan | Extra virtual options rendered around the viewport | `number` | 5 |
## Option API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| key | Same meaning as value. If Vue requires this setting, this value should be the same as value, then value setting can be omitted | string \| number | - |
| value | Option value, used for filtering by default, required | `string \| number` | - |
| label | Option display content | `VNodeChild` | - |
| disabled | Whether current item is disabled | `boolean` | false |
| active | Whether this is the current keyboard-focused option | `boolean` | false |
| checked | Whether the option is selected | `boolean` | false |
---
# ConfigProvider
Provides locale, popup-container, and component appearance configuration to descendants.
[Basic Usage](./demo/basic.vue?show=vertical)
- Use `locale` to configure component language.
- Use `getPopupContainer` to select the mount container for overlays such as Select and DatePicker.
- Use `size`, `theme`, and `shape` to configure compatible component appearance defaults.
- Nest ConfigProvider to override configuration for a local region.
- Precedence: component props > Form props > nearest ConfigProvider > component defaults.
- Components inherit only the appearance properties they support. Data and surface containers such as Table, Descriptions, and Collapse normalize a global `circle` shape to `round`.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| locale | Component locale | `Record` | global locale |
| getPopupContainer | Returns the popup mount container | `PopupContainerGetter` | document.body |
| size | Default size for compatible components | `"small" \| "medium" \| "large"` | - |
| theme | Default theme for compatible components | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | - |
| shape | Default shape for compatible components | `"default" \| "circle" \| "square" \| "round"` | - |
---
# Skeleton
Provide a placeholder graphic combination at positions where content needs to be loaded.
## When to Use
- When the network is slow and requires a long waiting time for loading processing.
- In lists/cards with rich graphic and text information.
- Only used when loading data for the first time.
- Can be completely replaced by Spin, but can provide better visual effects and user experience in available scenarios.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest placeholder effect.
[Combination](./demo/group.vue?show=vertical)
- You can configure the number of skeleton screen paragraphs to better approximate the real rendering effect. The first line will be rendered as a paragraph start of 35% length.
[Animation Effect](./demo/animated.vue?show=vertical)
- Show animation effect.
[Child Component](./demo/child.vue?show=vertical)
- Loading placeholder includes child components.
[List](./demo/list.vue?show=vertical)
- Use loading placeholders in list components.
[Button/Avatar/Image](./demo/items.vue?show=vertical)
- Skeleton buttons, avatars, and images.
[Custom](./demo/custom.vue?show=vertical)
- Custom effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| animated | Whether to show animation effect | `boolean` | false |
| avatar | Whether to show avatar placeholder | `boolean \| { size?: SizeType; shape?: ShapeType; }` | false |
| loading | When true, show placeholder. Otherwise directly display child components | `boolean` | false |
| rows | Set the number of paragraph placeholder lines | `number` | 3 |
| delay | Delay showing the skeleton to avoid flickering, in milliseconds | `number` | 500 |
| titleWidth | Title placeholder width, from 0 to 100 | `number` | 35 |
| title | Deprecated. Use `titleWidth` instead | `number` | - |
## Avatar Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| radius | Specify the border radius of the image | number | - |
| shape | Specify the shape of the avatar | 'circle' \| 'square' | circle |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| size | Set the size of avatar placeholder | number \| 'small' \| 'medium' \| 'large' \| 'default' | - |
## Button Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| shape | Specify the shape of the button | 'circle' \| 'square' \| 'round' \| 'default' | - |
| size | Set the button size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| block | Option to adjust button width to its parent width | boolean | false |
| width | Button width | number | - |
## Text Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| size | Set the text size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| width | Text width | number | - |
## Image Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------ | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| radius | Specify the border radius of the image | number | - |
| size | Image width (height) | number \| number[] | - |
---
# Skeleton
Provide a placeholder graphic combination at positions where content needs to be loaded.
## When to Use
- When the network is slow and requires a long waiting time for loading processing.
- In lists/cards with rich graphic and text information.
- Only used when loading data for the first time.
- Can be completely replaced by Spin, but can provide better visual effects and user experience in available scenarios.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest placeholder effect.
[Combination](./demo/group.vue?show=vertical)
- You can configure the number of skeleton screen paragraphs to better approximate the real rendering effect. The first line will be rendered as a paragraph start of 35% length.
[Animation Effect](./demo/animated.vue?show=vertical)
- Show animation effect.
[Child Component](./demo/child.vue?show=vertical)
- Loading placeholder includes child components.
[List](./demo/list.vue?show=vertical)
- Use loading placeholders in list components.
[Button/Avatar/Image](./demo/items.vue?show=vertical)
- Skeleton buttons, avatars, and images.
[Custom](./demo/custom.vue?show=vertical)
- Custom effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| animated | Whether to show animation effect | `boolean` | false |
| avatar | Whether to show avatar placeholder | `boolean \| { size?: SizeType; shape?: ShapeType; }` | false |
| loading | When true, show placeholder. Otherwise directly display child components | `boolean` | false |
| rows | Set the number of paragraph placeholder lines | `number` | 3 |
| delay | Delay showing the skeleton to avoid flickering, in milliseconds | `number` | 500 |
| titleWidth | Title placeholder width, from 0 to 100 | `number` | 35 |
| title | Deprecated. Use `titleWidth` instead | `number` | - |
## Avatar Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| radius | Specify the border radius of the image | number | - |
| shape | Specify the shape of the avatar | 'circle' \| 'square' | circle |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| size | Set the size of avatar placeholder | number \| 'small' \| 'medium' \| 'large' \| 'default' | - |
## Button Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| shape | Specify the shape of the button | 'circle' \| 'square' \| 'round' \| 'default' | - |
| size | Set the button size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| block | Option to adjust button width to its parent width | boolean | false |
| width | Button width | number | - |
## Text Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| size | Set the text size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| width | Text width | number | - |
## Image Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------ | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| radius | Specify the border radius of the image | number | - |
| size | Image width (height) | number \| number[] | - |
---
# Skeleton
Provide a placeholder graphic combination at positions where content needs to be loaded.
## When to Use
- When the network is slow and requires a long waiting time for loading processing.
- In lists/cards with rich graphic and text information.
- Only used when loading data for the first time.
- Can be completely replaced by Spin, but can provide better visual effects and user experience in available scenarios.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest placeholder effect.
[Combination](./demo/group.vue?show=vertical)
- You can configure the number of skeleton screen paragraphs to better approximate the real rendering effect. The first line will be rendered as a paragraph start of 35% length.
[Animation Effect](./demo/animated.vue?show=vertical)
- Show animation effect.
[Child Component](./demo/child.vue?show=vertical)
- Loading placeholder includes child components.
[List](./demo/list.vue?show=vertical)
- Use loading placeholders in list components.
[Button/Avatar/Image](./demo/items.vue?show=vertical)
- Skeleton buttons, avatars, and images.
[Custom](./demo/custom.vue?show=vertical)
- Custom effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| animated | Whether to show animation effect | `boolean` | false |
| avatar | Whether to show avatar placeholder | `boolean \| { size?: SizeType; shape?: ShapeType; }` | false |
| loading | When true, show placeholder. Otherwise directly display child components | `boolean` | false |
| rows | Set the number of paragraph placeholder lines | `number` | 3 |
| delay | Delay showing the skeleton to avoid flickering, in milliseconds | `number` | 500 |
| titleWidth | Title placeholder width, from 0 to 100 | `number` | 35 |
| title | Deprecated. Use `titleWidth` instead | `number` | - |
## Avatar Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| radius | Specify the border radius of the image | number | - |
| shape | Specify the shape of the avatar | 'circle' \| 'square' | circle |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| size | Set the size of avatar placeholder | number \| 'small' \| 'medium' \| 'large' \| 'default' | - |
## Button Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| shape | Specify the shape of the button | 'circle' \| 'square' \| 'round' \| 'default' | - |
| size | Set the button size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| block | Option to adjust button width to its parent width | boolean | false |
| width | Button width | number | - |
## Text Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| size | Set the text size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| width | Text width | number | - |
## Image Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------ | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| radius | Specify the border radius of the image | number | - |
| size | Image width (height) | number \| number[] | - |
---
# Skeleton
Provide a placeholder graphic combination at positions where content needs to be loaded.
## When to Use
- When the network is slow and requires a long waiting time for loading processing.
- In lists/cards with rich graphic and text information.
- Only used when loading data for the first time.
- Can be completely replaced by Spin, but can provide better visual effects and user experience in available scenarios.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest placeholder effect.
[Combination](./demo/group.vue?show=vertical)
- You can configure the number of skeleton screen paragraphs to better approximate the real rendering effect. The first line will be rendered as a paragraph start of 35% length.
[Animation Effect](./demo/animated.vue?show=vertical)
- Show animation effect.
[Child Component](./demo/child.vue?show=vertical)
- Loading placeholder includes child components.
[List](./demo/list.vue?show=vertical)
- Use loading placeholders in list components.
[Button/Avatar/Image](./demo/items.vue?show=vertical)
- Skeleton buttons, avatars, and images.
[Custom](./demo/custom.vue?show=vertical)
- Custom effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| animated | Whether to show animation effect | `boolean` | false |
| avatar | Whether to show avatar placeholder | `boolean \| { size?: SizeType; shape?: ShapeType; }` | false |
| loading | When true, show placeholder. Otherwise directly display child components | `boolean` | false |
| rows | Set the number of paragraph placeholder lines | `number` | 3 |
| delay | Delay showing the skeleton to avoid flickering, in milliseconds | `number` | 500 |
| titleWidth | Title placeholder width, from 0 to 100 | `number` | 35 |
| title | Deprecated. Use `titleWidth` instead | `number` | - |
## Avatar Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| radius | Specify the border radius of the image | number | - |
| shape | Specify the shape of the avatar | 'circle' \| 'square' | circle |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| size | Set the size of avatar placeholder | number \| 'small' \| 'medium' \| 'large' \| 'default' | - |
## Button Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| shape | Specify the shape of the button | 'circle' \| 'square' \| 'round' \| 'default' | - |
| size | Set the button size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| block | Option to adjust button width to its parent width | boolean | false |
| width | Button width | number | - |
## Text Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| size | Set the text size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| width | Text width | number | - |
## Image Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------ | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| radius | Specify the border radius of the image | number | - |
| size | Image width (height) | number \| number[] | - |
---
# Skeleton
Provide a placeholder graphic combination at positions where content needs to be loaded.
## When to Use
- When the network is slow and requires a long waiting time for loading processing.
- In lists/cards with rich graphic and text information.
- Only used when loading data for the first time.
- Can be completely replaced by Spin, but can provide better visual effects and user experience in available scenarios.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest placeholder effect.
[Combination](./demo/group.vue?show=vertical)
- You can configure the number of skeleton screen paragraphs to better approximate the real rendering effect. The first line will be rendered as a paragraph start of 35% length.
[Animation Effect](./demo/animated.vue?show=vertical)
- Show animation effect.
[Child Component](./demo/child.vue?show=vertical)
- Loading placeholder includes child components.
[List](./demo/list.vue?show=vertical)
- Use loading placeholders in list components.
[Button/Avatar/Image](./demo/items.vue?show=vertical)
- Skeleton buttons, avatars, and images.
[Custom](./demo/custom.vue?show=vertical)
- Custom effect.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| animated | Whether to show animation effect | `boolean` | false |
| avatar | Whether to show avatar placeholder | `boolean \| { size?: SizeType; shape?: ShapeType; }` | false |
| loading | When true, show placeholder. Otherwise directly display child components | `boolean` | false |
| rows | Set the number of paragraph placeholder lines | `number` | 3 |
| delay | Delay showing the skeleton to avoid flickering, in milliseconds | `number` | 500 |
| titleWidth | Title placeholder width, from 0 to 100 | `number` | 35 |
| title | Deprecated. Use `titleWidth` instead | `number` | - |
## Avatar Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| radius | Specify the border radius of the image | number | - |
| shape | Specify the shape of the avatar | 'circle' \| 'square' | circle |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| size | Set the size of avatar placeholder | number \| 'small' \| 'medium' \| 'large' \| 'default' | - |
## Button Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| shape | Specify the shape of the button | 'circle' \| 'square' \| 'round' \| 'default' | - |
| size | Set the button size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| block | Option to adjust button width to its parent width | boolean | false |
| width | Button width | number | - |
## Text Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| size | Set the text size | 'small' \| 'medium' \| 'large' \| 'default' | - |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| width | Text width | number | - |
## Image Props
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------ | ------------------ | ------- |
| animated | Whether to show animation effect | boolean | false |
| loading | When true, show placeholder. Otherwise directly display child components | boolean | false |
| delay | Delay showing the skeleton, in milliseconds | number | 500 |
| radius | Specify the border radius of the image | number | - |
| size | Image width (height) | number \| number[] | - |
---
# StatCard
Statistical indicators, can set title, value, description.
## When to Use
Can be used in BI/Dashboard scenarios, business backend oriented, intuitive.
## Examples
[Card Display](./demo/card.vue?show=vertical)
- Used in Dashboard scenarios. Combined with `Grid`, it can adapt well to various devices.
[Trend Information](./demo/trend.vue?show=vertical)
- Use `trend` for supplementary information and `trendStatus` for its status color; cards remain equal-height in a Grid when some items omit the trend.
[Combination Display](./demo/with-card.vue)
- Show more custom data combined with the `Card` component
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Card title, customizable via the named slot | `VNodeChild` | - |
| items | Data to display | `StatNumberItem[]` | [] |
| precision | Numerical precision | `number` | 0 |
| statNumberType | Numerical change type | `"rollup" \| "countup"` | 'countup' |
| separator | Separator | `string` | - |
| reverse | Whether to reverse number/number description arrangement | `boolean` | false |
| bordered | Show border or not | `boolean` | false |
| size | Card size | `"small" \| "medium" \| "large"` | medium |
| prefix | Default prefix for all values, scoped with `{ item, index }` | VNodeChild | - |
| suffix | Default suffix for all values, scoped with `{ item, index }` | VNodeChild | - |
### items Options
| Property | Description | Type | Default |
| --------------- | ------------------------------------------------- | ----------------------------------------------- | ------- |
| key | Unique key used to preserve animation state | string \| number | - |
| value | Numerical value | number | - |
| desc | Numerical description | VNodeChild | - |
| trend | Trend or supplementary content | VNodeChild | - |
| trendStatus | Trend status | 'default' \| 'success' \| 'danger' \| 'warning' | default |
| prefix | Prefix content of numerical value | string \| VNode | - |
| suffix | Suffix content of numerical value | string \| VNode | - |
| precision | Numerical precision | number | 0 |
| separator | Separator | string | - |
| duration | Numerical dynamic display time (seconds) | number | 1.2 |
| autoAnimate | Trigger animation when target becomes visible | boolean | true |
| autoAnimateOnce | Run animation only once for auto-animate triggers | boolean | true |
For standalone animated values, formatting, and animation controls, see [StatNumber](/components/stat-number-en).
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| theme | Appearance theme | `"fill" \| "outline" \| "plain"` | fill |
| shape | Card shape | `"square" \| "round"` | round |
---
# StatNumber
Animate numerical values independently or combine them with cards and dashboards.
## When to Use
Use for counters, amounts, and metrics that change over time. For a complete metric card with a title, description, and trend, see [StatCard](/components/stat-card-en).
## Examples
[Animation and Formatting](./demo/basic.vue)
- Compare the default numerical transition with `type="rollup"`. Try `12,345 → 54,321`, increments, decrements, and random values; examples also cover decimal precision and prefixes/suffixes.
- In rollup mode, each digit chooses its own direction: increasing digits roll upward, decreasing digits roll downward, and unchanged digits stay still. Digits scroll through intermediate values and settle at staggered times.
[Animation Duration](./demo/duration.vue)
- Compare animation durations in seconds. Set `duration` to `0` for an immediate update. Rollup animations also respect the system's reduced-motion preference.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Numerical value | `number` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `number` | 0 |
| duration | Numerical dynamic display time (seconds) | `number` | 1.2 |
| prefix | Prefix content of numerical value | `string` | - |
| suffix | Suffix content of numerical value | `string` | - |
| precision | Numerical precision | `number` | 0 |
| type | Numerical change type | `"rollup" \| "countup"` | 'countup' |
| separator | Separator | `string` | - |
| autoAnimate | Trigger animation when target becomes visible | `boolean` | true |
| autoAnimateOnce | Run animation only once for auto-animate triggers | `boolean` | true |
## Slots
| Name | Description |
| ------ | --------------------------------------- |
| prefix | Custom prefix content, such as an icon. |
| suffix | Custom suffix content, such as a unit. |
---
# Slider
Slider input, displaying current value and optional range.
## When to Use
When users need to select within a numerical range/custom range, it can be continuous or discrete values.
## Examples
[Basic Usage](./demo/basic.vue)
- Basic usage.
[Size/Custom](./demo/size.vue)
- `size` can control the size of the handle.
[Controlled](./demo/with-number.vue)
- Controlled and synchronized with Input.
[Custom Tooltip](./demo/formatter.vue)
- Use `tipFormatter` to set the display format of the Tooltip. When `tooltipVisible` is true, the Tooltip will always be shown; when false, it will never be shown, even during dragging or hovering.
[With Labels](./demo/marks.vue?show=vertical)
- Use the `marks` attribute to mark slider ticks, and use `value` to specify the slider position.
[Vertical](./demo/vertical.vue?show=vertical)
- Vertical Slider.
[Reverse](./demo/reverse.vue?show=vertical)
- Set `reverse` to invert the slider.
## Slider API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Set current value (v-model) | `number \| number[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `number \| number[]` | 0 |
| min | Minimum value | `number` | 0 |
| max | Maximum value | `number` | 100 |
| range | Whether to support sliding on both sides simultaneously | `boolean` | false |
| disabled | Whether the slider is disabled | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be dragged or changed with keys | `boolean` | false |
| step | Step size, must be greater than 0 and divisible by (max - min) | `number \| null` | 1 |
| tipFormatter | Set Tooltip display format, defaults to current value | `((value: number) => string \| number)` | number |
| vertical | Whether to set direction to vertical | `boolean` | false |
| marks | Scale marks, key type must be number and value in closed interval [min, max] | `Record` | - |
| included | Effective when marks is not empty object, true means inclusive relationship, false means parallel | `boolean` | true |
| tooltipVisible | When true, Tooltip will always display; otherwise never display, even when dragging and hovering | `boolean` | false |
| reverse | Sort in reverse order | `boolean` | false |
| size | The size of Slider | `number \| "small"` | - |
| onChange | Triggered when Slider value changes, passes the changed value as parameter | `(value: number \| number[]) => void` | - |
---
# Space
Set the spacing between components.
## When to Use
Avoid components sticking together, create uniform space.
- Suitable for horizontal spacing of inline elements.
- Can set various horizontal alignment methods.
## Examples
[Basic Usage](./demo/basic.vue)
- Horizontal spacing between adjacent components.
[Vertical Spacing](./demo/vertical.vue)
- Vertical spacing between adjacent components.
[Spacing Size](./demo/size.vue)
- Preset spacing sizes: large, medium, and small. Set `size` to `large` or `medium` to set the spacing to large or medium, respectively. If `size` is not set, the spacing is small.
[Alignment](./demo/align.vue?show=vertical)
- Set the alignment mode.
[Custom Size](./demo/custom-size.vue?show=vertical)
- Customize spacing size.
[Set Wrapping](./demo/wrap.vue)
- Wrapping is disabled by default. Set `wrap` explicitly to enable automatic wrapping.
[Divider](./demo/split.vue)
- Divider between adjacent components.
[Compact Layout Group](./demo/compact.vue?show=vertical)
- Use `compact` to tightly connect form components and merge borders.
[Button Compact Layout](./demo/compact-button.vue?show=vertical)
- Example of compactly arranged Button components.
[Vertical Compact Layout](./demo/compact-vertical.vue)
- Vertical compact layout, currently only supporting Button combinations.
## Space API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| align | Alignment method | `"center" \| "start" \| "end" \| "baseline"` | center |
| vertical | Whether to display vertically | `boolean` | false |
| direction | Layout direction; takes priority over `vertical` | `"horizontal" \| "vertical"` | - |
| size | Spacing; array values are horizontal and vertical gaps | `number \| SizeType \| (string \| number)[]` | - |
| wrap | Whether to wrap | `boolean` | false |
| split | Content rendered between adjacent children | VNodeChild | - |
| compact | Whether to use compact mode | `boolean` | false |
| block | Option to adjust width to parent element width | `boolean` | false |
---
# Spin
Used for loading states of pages and blocks.
## When to Use
When part of the page is waiting for asynchronous data or being rendered, appropriate loading animations can effectively alleviate user anxiety.
## Examples
[Basic Usage](./demo/basic.vue)
- A simple loading state.
[Card Loading](./demo/container.vue)
- You can directly embed content into Spin to turn an existing container into a loading state.
[Spin Type](./demo/mode.vue)
- You can directly embed content into Spin to turn an existing container into a loading state.
## Spin API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Whether loading state, can use `v-model` for two-way binding | `boolean` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `boolean` | true |
| mode | Loading animation type | `"bounce" \| "flip" \| "rotate" \| "zoom"` | rotate |
| delay | Delay before showing to prevent flickering | `number` | 0 |
| size | Loading indicator size | `"small" \| "medium" \| "large"` | medium |
---
# Steps
Displays progress through a task or workflow.
## Examples
[Basic](./demo/basic.vue?show=vertical)
- Supports data items, clickable steps, and vertical layout.
[Vertical](./demo/vertical.vue?show=vertical)
- Presents detailed workflows vertically.
[Statuses](./demo/status.vue?show=vertical)
- Shows error and per-step custom statuses.
[Clickable steps](./demo/clickable.vue?show=vertical)
- Handle change to switch the current step.
[Custom icons](./demo/icon.vue?show=vertical)
- Sets a custom icon for each step.
[Controlled](./demo/controlled.vue?show=vertical)
- Controls the current step with external state and buttons.
## Steps API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| current | Current step | `number` | 0 |
| direction | Direction | `"horizontal" \| "vertical"` | `horizontal` |
| status | Current status | `"error" \| "process"` | `process` |
| items | Step data | `StepItem[]` | - |
| onChange | Step click | `(current: number) => void` | - |
## Step API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Title | `VNodeChild` | - |
| description | Description | `VNodeChild` | - |
| icon | Custom marker | `VNodeChild` | - |
| status | Step status | `"error" \| "wait" \| "process" \| "finish"` | - |
| disabled | Disable clicking | `boolean` | false |
---
# Steps
Displays progress through a task or workflow.
## Examples
[Basic](./demo/basic.vue?show=vertical)
- Supports data items, clickable steps, and vertical layout.
[Vertical](./demo/vertical.vue?show=vertical)
- Presents detailed workflows vertically.
[Statuses](./demo/status.vue?show=vertical)
- Shows error and per-step custom statuses.
[Clickable steps](./demo/clickable.vue?show=vertical)
- Handle change to switch the current step.
[Custom icons](./demo/icon.vue?show=vertical)
- Sets a custom icon for each step.
[Controlled](./demo/controlled.vue?show=vertical)
- Controls the current step with external state and buttons.
## Steps API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| current | Current step | `number` | 0 |
| direction | Direction | `"horizontal" \| "vertical"` | `horizontal` |
| status | Current status | `"error" \| "process"` | `process` |
| items | Step data | `StepItem[]` | - |
| onChange | Step click | `(current: number) => void` | - |
## Step API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Title | `VNodeChild` | - |
| description | Description | `VNodeChild` | - |
| icon | Custom marker | `VNodeChild` | - |
| status | Step status | `"error" \| "wait" \| "process" \| "finish"` | - |
| disabled | Disable clicking | `boolean` | false |
---
# Switch
Switch selector.
## When to Use
- When representing switch state/transition between two states.
- The difference from checkbox is that switching a switch directly triggers a state change, while checkbox is generally used for state marking and needs to cooperate with submission operations.
## Examples
[Basic Usage](./demo/basic.vue)
- Can use `v-model` for two-way data binding.
[Text / Icon](./demo/with-text.vue)
- Use `true-text` and `false-text` to set the text displayed when selected and unselected. Use the `slot` `(checked|unchecked)` to control the content.
[Disabled / Controllable](./demo/disabled.vue)
- Use the `disabled` attribute to set whether the component is disabled.
[Two Sizes](./demo/size.vue)
- `size="small"` indicates a small switch.
[Loading](./demo/loading.vue)
- Indicates that the switch operation is still in progress.
### API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| checked | Boolean checked state; supports two-way binding with `v-model:checked` | `boolean` | false |
| modelValue | Value bound through `v-model` | `string \| number \| boolean` | - |
| disabled | Disable switch | `boolean` | false |
| readonly | Read-only; remains focusable but cannot be toggled | `boolean` | false |
| loading | Show a loading state and disable interaction | `boolean` | false |
| type | Theme color, can pass `success`, `warning`, `danger`, `primary` | `string` | - |
| color | Custom checked color; takes precedence over `type` | `string` | - |
| size | Component size, when value is `small` displays small size | `"small" \| "medium" \| "large"` | - |
| checked(unchecked) | Content when selected (not selected) | `boolean` | - |
| true-text | Text displayed when `checked` is `true` | `string` | - |
| false-text | Text displayed when `checked` is `false` | `string` | - |
| valueType | The type of output value for the unit option | `"string" \| "number" \| "boolean"` | boolean |
| onChange | Triggered on change; output type is determined by `valueType` | `(value: string \| number \| boolean) => void` | - |
| shape | Switch shape: `round` or `square` | `"default" \| "circle" \| "square" \| "round"` | round |
---
# Splitter Panel
## When to Use
- Can divide areas horizontally or vertically.
- When you need to freely drag and adjust the size of each area.
- When you need to specify the maximum and minimum width or height of an area.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Initialize panel size, panel size limit.
[Vertical direction](./demo/vertical.vue?show=vertical)
- Use vertical layout.
# API
## Splitter
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| resize | Emitted while panel sizes change | `(sizes: number[]) => void` | - |
| resizeStart | Emitted when resizing starts | `(sizes: number[]) => void` | - |
| resizeEnd | Emitted when resizing ends | `(sizes: number[]) => void` | - |
## SplitterPanel
| Attribute | Description | Type | Default |
| --- | --- | --- | --- |
| size | Initial size; numbers are px, strings support px or percentages | `string \| number` | - |
| min | Minimum size; numbers are px, strings support px or percentages | `string \| number` | 0 |
| max | Maximum size; numbers are px, strings support px or percentages | `string \| number` | - |
---
# Splitter Panel
## When to Use
- Can divide areas horizontally or vertically.
- When you need to freely drag and adjust the size of each area.
- When you need to specify the maximum and minimum width or height of an area.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- Initialize panel size, panel size limit.
[Vertical direction](./demo/vertical.vue?show=vertical)
- Use vertical layout.
# API
## Splitter
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| direction | Layout direction | `"horizontal" \| "vertical" \| "inline"` | horizontal |
| resize | Emitted while panel sizes change | `(sizes: number[]) => void` | - |
| resizeStart | Emitted when resizing starts | `(sizes: number[]) => void` | - |
| resizeEnd | Emitted when resizing ends | `(sizes: number[]) => void` | - |
## SplitterPanel
| Attribute | Description | Type | Default |
| --- | --- | --- | --- |
| size | Initial size; numbers are px, strings support px or percentages | `string \| number` | - |
| min | Minimum size; numbers are px, strings support px or percentages | `string \| number` | 0 |
| max | Maximum size; numbers are px, strings support px or percentages | `string \| number` | - |
---
# Table
Display row and column data.
## When to Use
- When there is a large amount of structured data to display.
- When complex behaviors such as sorting, searching, pagination, and custom operations are needed on the data.
## Simple Example
Specify the table's data source data as an array.
```js
const dataSource = [
{
key: '1',
name: 'Li Lei',
age: 32,
address: 'Wu Han Guanggu No. 328',
},
{
key: '2',
name: 'Hu Cong',
age: 28,
address: 'Wu Han Guanggu No. 198',
},
];
const columns = [
{
title: 'Name',
key: 'name',
},
{
title: 'Age',
key: 'age',
},
{
title: 'Address',
key: 'address',
},
];
;
```
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- A regular table.
[Tree Data](./demo/tree.vue?show=vertical)
- Tree mode is enabled automatically when records contain `children`. Controlled expansion, default expansion, indentation, selection, and row-click expansion are supported.
[Basic Usage (Using render)](./demo/base-render.vue?show=vertical)
- Use custom `render` to initialize the table.
[Custom Table Header](./demo/custom-header.vue?show=vertical)
- A table with a customizable header. You can define the header via `#header-`.
[Custom Header and Footer](./demo/bordered.vue?show=vertical)
- Add table border lines, header, and footer.
[Sorting](./demo/table-sorter.vue?show=vertical)
- `sorter=true` sorts existing data. When set to a `function`, you can define custom sorting rules.
[Table Row/Column Span](./demo/col-row-span.vue?show=vertical)
- Headers support only column spanning; use colSpan inside column definitions to configure. The table supports row and column spanning; in renders, use cell props colSpan or rowSpan. When set to 0, the cell will not render.
[Editable Cells](./demo/table-edit.vue?show=vertical)
- A table with cell editing functionality.
[Fixed Header/Columns](./demo/fixed-col-header.vue?show=vertical)
- For data with many columns, fix leading or trailing columns and scroll horizontally. `scroll.x` sets the minimum content width, while `scroll.y` sets the vertical viewport height.
[Header Grouping](./demo/header-span.vue?show=vertical)
- `columns[n]` can nest `children` to render grouped headers.
[Checkbox Selection](./demo/table-check.vue?show=vertical)
- Set `checkable=true` to automatically enable multi-selection. > Note: The default selection dependency is `key`. You can customize it via the `rowKey` attribute, e.g., `rowKey="ID"`.
[Dynamically Control Table Properties](./demo/control.vue?show=vertical)
- Select different configuration combinations to see the effects.
[Virtual scrolling](./demo/virtual.vue?show=vertical)
- Virtualizes large fixed-height data sets with `scroll.y`; do not combine virtual mode with merged cells.
[Column settings](./demo/column-setting.vue?show=vertical)
- `TableColumnSetting` generates a visibility panel from the same column definitions used by Table. Use it with `hiddenColumnKeys`; `disabledKeys` keeps essential columns fixed.
## Table API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Whether to display borders | `boolean` | false |
| checkable | Whether to show checkboxes | `boolean` | false |
| selectedKeys | Collection of selected keys | `TableKey[]` | - |
| disabledKeys | Disabled key set | `TableKey[]` | - |
| size | Display compact mode when the value is `small` | `"small" \| "medium" \| "large"` | - |
| emptyText | Prompt displayed when there is no data | `string` | No Data |
| loading | Table asynchronous loading mode | `boolean` | false |
| data | Structured data to be displayed | `TableRecord[]` | [] |
| columns | Configuration description of table columns | `Column[]` | [] |
| hiddenColumnKeys | Hidden column keys, including grouped columns | `string[]` | [] |
| rowKey | Basis for selection | `string` | key |
| childrenColumnName | Field containing child records | `string` | children |
| expandedKeys | expanded row keys; supports `v-model:expanded-keys` | `TableKey[]` | - |
| expandAllRows | Expand every tree node on initialization or when this prop changes (explicit expandedKeys takes precedence) | `boolean` | false |
| expandRowByClick | Toggle expansion by clicking a row | `boolean` | false |
| indentSize | Indentation per tree level | `number` | 20 |
| striped | Whether to display zebra stripes | `boolean` | false |
| onRowClick | Triggered when clicking a row | `(record: TableRecord, index: number) => void` | - |
| onSort | Triggered when clicking to sort | `(state: SortState) => void` | - |
| onSelect | Triggered when clicking the checkbox | `(record: TableRecord, selected: boolean, keys: TableKey[]) => void` | - |
| onSelectAll | Triggered when clicking the header checkbox of the Table | `(selected: boolean, keys: TableKey[]) => void` | - |
| onExpand | Called when a row expands or collapses | `(expanded: boolean, record: TableRecord) => void` | - |
| onExpandedKeysChange | Called when expanded keys change | `(keys: TableKey[]) => void` | - |
| virtual | Enable virtual scrolling; requires `scroll.y` | `boolean` | false |
| itemHeight | Fixed virtual row height | `number` | 44 |
| overscan | Extra rows rendered above and below the viewport | `number` | 5 |
## TableColumnSetting API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| columns | Column definitions shared with Table | `Column[]` | [] |
| hiddenKeys | Hidden keys; supports `v-model:hidden-keys` | `string[]` | [] |
| disabledKeys | Essential columns excluded from the settings UI | `string[]` | [] |
| title | Panel title and default trigger label | `string` | Column settings |
| resetText | Reset button label | `string` | Reset |
| size | Trigger and checkbox size | `"small" \| "medium" \| "large"` | - |
| showReset | Whether to show the reset action | `boolean` | true |
| onChange | Called when hidden column keys change | `(keys: string[]) => void` | - |
Slot: `default` customizes the trigger.
## Column API
| Property | Description | Type | Default |
| -------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------- |
| title | Header display text | string | - |
| key | Corresponding column field name | string | - |
| fixed | Column fixed direction | 'left' \| 'right' | - |
| sorter | Sorting, when `true`, local sorting is enabled | boolean \| (state: SortState) => void | - |
| width | Column width | number | - |
| rowSpan | Row merge unit, when 0, the current row will not be rendered | number | - |
| colSpan | Column merge unit, when 0, the current column will not be rendered | number | - |
| render | Custom rendering | (h, record, colIndex, rowIndex, col) => VNodeChild | - |
| scroll | Scroll configuration; `x` is the minimum content width and `y` is the vertical viewport height | `{ x?: number \| string; y?: number \| string }` | - |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Table shape | `"square" \| "round"` | round |
---
# Table
Display row and column data.
## When to Use
- When there is a large amount of structured data to display.
- When complex behaviors such as sorting, searching, pagination, and custom operations are needed on the data.
## Simple Example
Specify the table's data source data as an array.
```js
const dataSource = [
{
key: '1',
name: 'Li Lei',
age: 32,
address: 'Wu Han Guanggu No. 328',
},
{
key: '2',
name: 'Hu Cong',
age: 28,
address: 'Wu Han Guanggu No. 198',
},
];
const columns = [
{
title: 'Name',
key: 'name',
},
{
title: 'Age',
key: 'age',
},
{
title: 'Address',
key: 'address',
},
];
;
```
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- A regular table.
[Tree Data](./demo/tree.vue?show=vertical)
- Tree mode is enabled automatically when records contain `children`. Controlled expansion, default expansion, indentation, selection, and row-click expansion are supported.
[Basic Usage (Using render)](./demo/base-render.vue?show=vertical)
- Use custom `render` to initialize the table.
[Custom Table Header](./demo/custom-header.vue?show=vertical)
- A table with a customizable header. You can define the header via `#header-`.
[Custom Header and Footer](./demo/bordered.vue?show=vertical)
- Add table border lines, header, and footer.
[Sorting](./demo/table-sorter.vue?show=vertical)
- `sorter=true` sorts existing data. When set to a `function`, you can define custom sorting rules.
[Table Row/Column Span](./demo/col-row-span.vue?show=vertical)
- Headers support only column spanning; use colSpan inside column definitions to configure. The table supports row and column spanning; in renders, use cell props colSpan or rowSpan. When set to 0, the cell will not render.
[Editable Cells](./demo/table-edit.vue?show=vertical)
- A table with cell editing functionality.
[Fixed Header/Columns](./demo/fixed-col-header.vue?show=vertical)
- For data with many columns, fix leading or trailing columns and scroll horizontally. `scroll.x` sets the minimum content width, while `scroll.y` sets the vertical viewport height.
[Header Grouping](./demo/header-span.vue?show=vertical)
- `columns[n]` can nest `children` to render grouped headers.
[Checkbox Selection](./demo/table-check.vue?show=vertical)
- Set `checkable=true` to automatically enable multi-selection. > Note: The default selection dependency is `key`. You can customize it via the `rowKey` attribute, e.g., `rowKey="ID"`.
[Dynamically Control Table Properties](./demo/control.vue?show=vertical)
- Select different configuration combinations to see the effects.
[Virtual scrolling](./demo/virtual.vue?show=vertical)
- Virtualizes large fixed-height data sets with `scroll.y`; do not combine virtual mode with merged cells.
[Column settings](./demo/column-setting.vue?show=vertical)
- `TableColumnSetting` generates a visibility panel from the same column definitions used by Table. Use it with `hiddenColumnKeys`; `disabledKeys` keeps essential columns fixed.
## Table API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Whether to display borders | `boolean` | false |
| checkable | Whether to show checkboxes | `boolean` | false |
| selectedKeys | Collection of selected keys | `TableKey[]` | - |
| disabledKeys | Disabled key set | `TableKey[]` | - |
| size | Display compact mode when the value is `small` | `"small" \| "medium" \| "large"` | - |
| emptyText | Prompt displayed when there is no data | `string` | No Data |
| loading | Table asynchronous loading mode | `boolean` | false |
| data | Structured data to be displayed | `TableRecord[]` | [] |
| columns | Configuration description of table columns | `Column[]` | [] |
| hiddenColumnKeys | Hidden column keys, including grouped columns | `string[]` | [] |
| rowKey | Basis for selection | `string` | key |
| childrenColumnName | Field containing child records | `string` | children |
| expandedKeys | expanded row keys; supports `v-model:expanded-keys` | `TableKey[]` | - |
| expandAllRows | Expand every tree node on initialization or when this prop changes (explicit expandedKeys takes precedence) | `boolean` | false |
| expandRowByClick | Toggle expansion by clicking a row | `boolean` | false |
| indentSize | Indentation per tree level | `number` | 20 |
| striped | Whether to display zebra stripes | `boolean` | false |
| onRowClick | Triggered when clicking a row | `(record: TableRecord, index: number) => void` | - |
| onSort | Triggered when clicking to sort | `(state: SortState) => void` | - |
| onSelect | Triggered when clicking the checkbox | `(record: TableRecord, selected: boolean, keys: TableKey[]) => void` | - |
| onSelectAll | Triggered when clicking the header checkbox of the Table | `(selected: boolean, keys: TableKey[]) => void` | - |
| onExpand | Called when a row expands or collapses | `(expanded: boolean, record: TableRecord) => void` | - |
| onExpandedKeysChange | Called when expanded keys change | `(keys: TableKey[]) => void` | - |
| virtual | Enable virtual scrolling; requires `scroll.y` | `boolean` | false |
| itemHeight | Fixed virtual row height | `number` | 44 |
| overscan | Extra rows rendered above and below the viewport | `number` | 5 |
## TableColumnSetting API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| columns | Column definitions shared with Table | `Column[]` | [] |
| hiddenKeys | Hidden keys; supports `v-model:hidden-keys` | `string[]` | [] |
| disabledKeys | Essential columns excluded from the settings UI | `string[]` | [] |
| title | Panel title and default trigger label | `string` | Column settings |
| resetText | Reset button label | `string` | Reset |
| size | Trigger and checkbox size | `"small" \| "medium" \| "large"` | - |
| showReset | Whether to show the reset action | `boolean` | true |
| onChange | Called when hidden column keys change | `(keys: string[]) => void` | - |
Slot: `default` customizes the trigger.
## Column API
| Property | Description | Type | Default |
| -------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------- |
| title | Header display text | string | - |
| key | Corresponding column field name | string | - |
| fixed | Column fixed direction | 'left' \| 'right' | - |
| sorter | Sorting, when `true`, local sorting is enabled | boolean \| (state: SortState) => void | - |
| width | Column width | number | - |
| rowSpan | Row merge unit, when 0, the current row will not be rendered | number | - |
| colSpan | Column merge unit, when 0, the current column will not be rendered | number | - |
| render | Custom rendering | (h, record, colIndex, rowIndex, col) => VNodeChild | - |
| scroll | Scroll configuration; `x` is the minimum content width and `y` is the vertical viewport height | `{ x?: number \| string; y?: number \| string }` | - |
### Common appearance
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Table shape | `"square" \| "round"` | round |
---
# Kanban
Displays items grouped by status and supports drag-and-drop transitions.
## Demos
[Basic](./demo/basic.vue?show=vertical)
- Render cards with a slot and move them between columns by dragging.
[Custom sections](./demo/custom.vue?show=vertical)
- Customize headings, cards, empty states and footers, with dragging disabled.
[Custom fields](./demo/fields.vue?show=vertical)
- Adapt another data shape with `rowKey`, `statusKey` and `minColumnWidth`.
[Themes](./demo/theme.vue?show=vertical)
- Switch Kanban columns between filled and outlined appearances.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| columns | Column definitions | `KanbanColumnData[]` | [] |
| data | Kanban items | `KanbanItemData[]` | [] |
| rowKey | Unique item key field | `string` | id |
| statusKey | Item status field | `string` | status |
| draggable | Enable drag and drop | `boolean` | true |
| emptyText | Empty column description; defaults to the global locale | `string` | - |
| minColumnWidth | Minimum column width | `string \| number` | 250 |
| theme | Column appearance | `"fill" \| "outline"` | fill |
| columnTitle | Custom column heading, scoped with `{ column, items }` | VNodeChild | - |
| item | Custom card content, scoped with `{ item, column, index }` | VNodeChild | - |
| empty | Custom empty-column content, scoped with `{ column }` | VNodeChild | - |
| footer | Custom column footer, scoped with `{ column, items }` | VNodeChild | - |
### KanbanColumnData
| Field | Description | Type | Required |
| ----- | ----------------------------------------- | ---------------- | -------- |
| key | Unique column key matching an item status | string \| number | yes |
| title | Column title | string | yes |
| color | Column indicator color | string | no |
## Events
| Event | Description | Callback |
| --------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| move | Emitted after a card is dropped into another column; source data is not mutated | `(event: KanbanMoveEvent) => void` |
| itemClick | Emitted when a card is clicked | `(item: KanbanItemData, column: KanbanColumnData) => void` |
`KanbanMoveEvent` contains the moved `item`, source column key `from` and target column key `to`.
When a card is focused, press `Alt + ←` or `Alt + →` to move it to an adjacent column.
---
# TooltipPanel
See https://k-ui.cn/components/tooltip-panel.
---
# Tooltip
Simple text prompt bubble box.
## When to Use
Mouse over to display prompt, disappears when moved away, bubble floating layer does not carry complex text and operations.
Can be used to replace the system default `title` prompt, providing a text explanation for a `button/text/operation`.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage. The size of the floating layer is determined by the content area.
[Position](./demo/placement.vue)
- Control the direction via `placement`. There are twelve available positions.
[Colorful Text Tips](./demo/color.vue)
- Multiple preset colors for text tips, used in different scenarios.
## API
Use trigger="manual" when visibility is managed by business state (such as Slider dragging). Pointer entry/exit no longer changes visibility automatically; ordinary tooltips keep the default hover behavior.
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| trigger | Automatic hover or manual visibility | `"hover" \| "manual"` | hover |
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| title | Displayed title | `VNodeChild` | - |
| color | Background color | `string` | - |
| placement | Position where tooltip appears, optional values: `top`, `top-left`, `top-right`, `bottom`, `bottom-left`, `bottom-right`, `left`, `left-top`, `left-bottom`, `right`, `right-top`, `right-bottom` | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "left-bottom" \| "left-top" \| "right" \| "right-top" \| "right-bottom"` | top |
| width | Display width; numbers and numeric strings use px | `string \| number` | - |
| disabled | Disabled status | `boolean` | false |
| show | Whether to display during initialization | `boolean` | false |
| panelOnly | Render only the tooltip panel without a trigger | `boolean` | false |
---
# Tour
Gradually introduce features around the actual goals on the page.
## Examples
[Basic](./demo/basic.vue)
- Positions each guide step around a real page target.
[Placements](./demo/placement.vue)
- Places guide cards around different targets.
[Controlled steps](./demo/controlled.vue)
- Controls visibility and current step externally.
[Without mask](./demo/mask.vue)
- Keeps the surrounding page visible.
## Tour API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Visibility (v-model) | `boolean` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `boolean` | false |
| open | Visibility; takes precedence over modelValue, supports v-model:open | `boolean` | false |
| current | Current step | `number` | - |
| steps | Tour steps | `TourStep[]` | [] |
| mask | Show mask | `boolean` | true |
| closable | Show close button | `boolean` | true |
| escKey | Close with Escape | `boolean` | true |
| onChange | Step change | `(current: number) => void` | - |
| onOpenChange | Visibility change | `(open: boolean) => void` | - |
| onFinish | Tour completed | `() => void` | - |
---
# Transfer
Move and select items between two lists.
## Examples
[Basic](./demo/basic.vue?show=vertical)
- Select source items and move them to the target list.
[Search and operations](./demo/search.vue?show=vertical)
- Search list content and customize operation labels.
[Theme](./demo/theme.vue?show=vertical)
- Supports `outline` and `fill`; the search input follows the Transfer theme.
[Disabled](./demo/disabled.vue?show=vertical)
- Disable individual items or the entire transfer.
[Custom content](./demo/custom.vue?show=vertical)
- Customize items, footers, and filtering with slots and a filter function.
[Events](./demo/events.vue?show=vertical)
- Listen for selection and movement changes.
[Pagination](./demo/pagination.vue?show=vertical)
- Compose simple pagination in the footer slot for larger data sets.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Target keys, supports `v-model` | `TransferKey[]` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `TransferKey[]` | [] |
| dataSource | Data source | `TransferItem[]` | [] |
| titles | List titles | `[string, string]` | ['Source', 'Target'] |
| operations | Right and left operation labels | `[string, string]` | ['', ''] |
| searchable | Enable search | `boolean` | false |
| disabled | Disable the component | `boolean` | false |
| readonly | Read-only; searchable but items cannot be selected or moved | `boolean` | false |
| theme | Appearance theme | `"fill" \| "outline"` | outline |
| filterOption | Custom filter | `((keyword: string, item: TransferItem) => boolean)` | - |
| render | Custom item renderer | `((item: TransferItem) => VNodeChild)` | - |
| item | Custom item, scoped with `{ item: TransferItem }` | VNodeChild | - |
| change | Emitted after moving items | `(targetKeys: TransferKey[], direction: "left" \| "right", movedKeys: TransferKey[]) => void` | - |
| search | Emitted on search | `(direction: "left" \| "right", value: string) => void` | - |
| selectChange | Emitted when selection changes | `(sourceKeys: TransferKey[], targetKeys: TransferKey[]) => void` | - |
| footer | Custom list footer, scoped with `{ direction }` | VNodeChild | - |
### TransferItem
| Property | Description | Type | Default |
| ----------- | ----------------- | ---------------- | ------- |
| key | Unique key | string \| number | - |
| title | Item title | string | - |
| description | Item description | string | - |
| disabled | Disable this item | boolean | false |
---
# Typography
Consistent semantics and visual hierarchy for titles, paragraphs and inline text.
## Examples
[Basic](./demo/basic.vue?show=vertical)
- Build content hierarchy with titles, paragraphs, and inline text.
[Title levels](./demo/title.vue?show=vertical)
- Use `tag` to render heading levels from h1 through h6.
[Semantic text](./demo/type.vue?show=vertical)
- Use `type` for secondary, success, warning, and danger semantics.
[Text styles](./demo/style.vue?show=vertical)
- Bold, italic, underline, deleted, marked, and inline code styles.
[Ellipsis](./demo/ellipsis.vue?show=vertical)
- Supports multi-line truncation, full-text tooltips, and expand/collapse actions.
[Copy and edit](./demo/interactive.vue?show=vertical)
- Copy text or edit it in place and listen to the corresponding events.
## API
`Typography`, `TypographyText`, `TypographyParagraph` and `TypographyTitle` share these properties.
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Text content, supports `v-model` | `string` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `string` | - |
| tag | HTML tag | `"span" \| "div" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "p"` | - |
| type | Semantic color | `"success" \| "warning" \| "danger" \| "secondary"` | - |
| strong | Bold text | `boolean` | false |
| italic | Italic text | `boolean` | false |
| underline | Underlined text | `boolean` | false |
| delete | Deleted text | `boolean` | false |
| mark | Marked text | `boolean` | false |
| code | Inline code style | `boolean` | false |
| disabled | Disabled state | `boolean` | false |
| copyable | Enable copy and action tooltips | `boolean \| TypographyCopyableOptions` | false |
| editable | Enable editing and action tooltips | `boolean \| TypographyEditableOptions` | false |
| ellipsis | Truncation, tooltip and expansion | `number \| boolean \| TypographyEllipsisOptions` | false |
| copy | Emitted after copying | `(value: string) => void` | - |
| change | Emitted after editing | `(value: string) => void` | - |
### TypographyCopyableOptions
| Property | Description | Type | Default |
| ------------- | --------------------------- | ------ | ------- |
| tooltip | Copy action tooltip | string | - |
| copiedTooltip | Tooltip shown after copying | string | - |
### TypographyEditableOptions
| Property | Description | Type | Default |
| -------- | ------------------- | ------ | ------- |
| tooltip | Edit action tooltip | string | - |
### TypographyEllipsisOptions
| Property | Description | Type | Default |
| ------------ | ----------------------------------------- | ----------------- | -------- |
| rows | Maximum visible lines | number | 1 |
| expandable | Show the expand/collapse action | boolean | false |
| expandText | Expand action label | string | More |
| collapseText | Collapse action label | string | Collapse |
| tooltip | Show full text or a custom collapsed hint | boolean \| string | false |
---
# TypographyParagraph
See https://k-ui.cn/components/typography-paragraph.
---
# TypographyText
See https://k-ui.cn/components/typography-text.
---
# TypographyTitle
See https://k-ui.cn/components/typography-title.
---
# Tabs
Tab switching component.
## When to Use
Provide peer areas to accommodate and display large chunks of content, keeping the interface clean.
- Card-style tabs, providing closable styles, often used at the top of containers.
- Standard line-style tabs, used for main function switching inside containers, this is the most commonly used Tabs.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The first item is selected by default.
[Disabled](./demo/disabled.vue?show=vertical)
- Disable a specific tab.
[Centered](./demo/centered.vue?show=vertical)
- Tabs are centered.
[Icon](./demo/icon.vue?show=vertical)
- Tabs with icons.
[Extra Content](./demo/extra.vue?show=vertical)
- You can add extra operations to the right of the tabs.
[Card-style Tabs](./demo/card.vue?show=vertical)
- Another style of tabs.
[Browser-style Tabs](./demo/browser.vue?show=vertical)
- Suitable for multi-document, editor, and workspace scenarios.
[Add and Close Tabs](./demo/closable.vue?show=vertical)
- Card-style and browser-style tabs support closing. Use `closable={false}` to disable closing.
[Minimalist Tabs](./demo/sample.vue?show=vertical)
- Simple card presentation mode.
## Tabs API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Currently active tab panel's key | `string \| number` | - |
| value | Initially active key in uncontrolled mode | `string \| number` | First enabled panel |
| variant | Tab presentation | `"sample" \| "line" \| "card" \| "browser"` | `line` |
| card | Whether to use card style; retained for compatibility | `boolean` | false |
| sample | Whether to use sample style; retained for compatibility | `boolean` | false |
| animated | Whether to use animation to switch Tabs | `boolean` | true |
| centered | Whether to center the label | `boolean` | false |
| onRemove | Callback when tab is closed, returns the closed tab's key value | `(name: string) => void` | - |
| onChange | Callback when switching panels | `(name: string) => void` | - |
| onTabClick | Callback when tab is clicked | `(name: string) => void` | - |
## Tabs.TabPanel API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| key | Key value required by Vue | string \| number | - |
| title | Content displayed in tab header | `VNodeChild` | - |
| icon | Icon displayed in tab header | `IconType[]` | - |
| disabled | Whether tab is disabled | `boolean` | false |
| closable | Whether tab shows close button | `boolean` | false |
---
# Tabs
Tab switching component.
## When to Use
Provide peer areas to accommodate and display large chunks of content, keeping the interface clean.
- Card-style tabs, providing closable styles, often used at the top of containers.
- Standard line-style tabs, used for main function switching inside containers, this is the most commonly used Tabs.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The first item is selected by default.
[Disabled](./demo/disabled.vue?show=vertical)
- Disable a specific tab.
[Centered](./demo/centered.vue?show=vertical)
- Tabs are centered.
[Icon](./demo/icon.vue?show=vertical)
- Tabs with icons.
[Extra Content](./demo/extra.vue?show=vertical)
- You can add extra operations to the right of the tabs.
[Card-style Tabs](./demo/card.vue?show=vertical)
- Another style of tabs.
[Browser-style Tabs](./demo/browser.vue?show=vertical)
- Suitable for multi-document, editor, and workspace scenarios.
[Add and Close Tabs](./demo/closable.vue?show=vertical)
- Card-style and browser-style tabs support closing. Use `closable={false}` to disable closing.
[Minimalist Tabs](./demo/sample.vue?show=vertical)
- Simple card presentation mode.
## Tabs API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Currently active tab panel's key | `string \| number` | - |
| value | Initially active key in uncontrolled mode | `string \| number` | First enabled panel |
| variant | Tab presentation | `"sample" \| "line" \| "card" \| "browser"` | `line` |
| card | Whether to use card style; retained for compatibility | `boolean` | false |
| sample | Whether to use sample style; retained for compatibility | `boolean` | false |
| animated | Whether to use animation to switch Tabs | `boolean` | true |
| centered | Whether to center the label | `boolean` | false |
| onRemove | Callback when tab is closed, returns the closed tab's key value | `(name: string) => void` | - |
| onChange | Callback when switching panels | `(name: string) => void` | - |
| onTabClick | Callback when tab is clicked | `(name: string) => void` | - |
## Tabs.TabPanel API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| key | Key value required by Vue | string \| number | - |
| title | Content displayed in tab header | `VNodeChild` | - |
| icon | Icon displayed in tab header | `IconType[]` | - |
| disabled | Whether tab is disabled | `boolean` | false |
| closable | Whether tab shows close button | `boolean` | false |
---
# Timeline
Vertically displayed timeline information.
## When to Use
When an operation takes a long time to complete, display the current progress and status to the user.
- When there is a series of information that needs to be arranged in chronological order, it can be in positive or reverse order.
- When a timeline is needed for visual connection.
## Examples
[Basic Usage](./demo/basic.vue)
- `TimeLine` must contain `TimeLineItem`.
[Icon](./demo/icon.vue)
- Set the `icon` and `color` properties on `TimeLineItem` to change the icon display.
[Display Direction](./demo/mode.vue)
- Specify the `mode` to change the display direction.
## TimeLine API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| mode | Relative position of the timeline and its content | `"left" \| "right" \| "center" \| "alternate"` | `'left'` |
## TimeLineItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Timeline node icon | `IconType[]` | - |
| color | Timeline node color | `string` | - |
| time | Time content | `VNodeChild` | - |
| extra | Auxiliary content, customizable via the named slot | `VNodeChild` | - |
| dot | Custom timeline node | `VNodeChild` | - |
---
# Timeline
Vertically displayed timeline information.
## When to Use
When an operation takes a long time to complete, display the current progress and status to the user.
- When there is a series of information that needs to be arranged in chronological order, it can be in positive or reverse order.
- When a timeline is needed for visual connection.
## Examples
[Basic Usage](./demo/basic.vue)
- `TimeLine` must contain `TimeLineItem`.
[Icon](./demo/icon.vue)
- Set the `icon` and `color` properties on `TimeLineItem` to change the icon display.
[Display Direction](./demo/mode.vue)
- Specify the `mode` to change the display direction.
## TimeLine API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| mode | Relative position of the timeline and its content | `"left" \| "right" \| "center" \| "alternate"` | `'left'` |
## TimeLineItem API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| icon | Timeline node icon | `IconType[]` | - |
| color | Timeline node color | `string` | - |
| time | Time content | `VNodeChild` | - |
| extra | Auxiliary content, customizable via the named slot | `VNodeChild` | - |
| dot | Custom timeline node | `VNodeChild` | - |
---
# Tree
## When to Use
Folders, organizational structures, biological classifications, countries and regions, etc. Most structures in the world are tree structures. Using `tree control` can fully display the hierarchical relationships and have interactive functions such as expand/collapse and selection.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage, showing selectable items with default expansion.
[Checkable](./demo/checkable.vue)
- Set the `checkable` attribute to allow nodes to be checked.
[Extended Node](./demo/custom-render.vue)
- Extended node for a tree item.
[Disabled Node](./demo/disabled.vue)
- Set the `disabled` attribute to disable a node.
[Asynchronous Loading](./demo/sync.vue)
- Click to expand a node and load data dynamically. `isLeaf=true` indicates the current node is a leaf node and has no children.
[Custom Icon](./demo/icon.vue)
- You can customize icons for different nodes.
[Group Control](./demo/directory.vue?show=vertical)
- Displays directories, connecting lines, drag-and-drop, checkboxes, icons, and extensions.
[Virtual Scrolling](./demo/virtual.vue)
- Set `virtual` for large data sets to render only visible nodes. Virtual nodes must have a fixed height.
[Field Mapping and Instance Methods](./demo/advanced.vue?show=vertical)
- Adapt backend fields with `fieldNames`, customize nodes through the `title` slot, and control the tree with instance methods.
Tree supports focus management and Arrow, Home, End, Enter, and Space keyboard operations.
## Tree API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| data | Array of nestable node properties, data to generate `tree` | `TreeNodeData[]` | [] |
| checkable | Whether to show checkbox | `boolean` | false |
| draggable | Whether it can be dragged | `boolean` | false |
| showLine | Whether to show connecting lines | `boolean` | false |
| showIcon | Whether to show icons | `boolean` | true |
| extra | Extension element | slot(node) | - |
| showExtra | Whether to show extension elements by default | `boolean` | false |
| checkStrictly | In checkable state, node selection is completely controlled (parent-child node selection state no longer related) | `boolean` | false |
| checkedKeys | Tree nodes with checked checkboxes | `string[]` | [] |
| expandedKeys | Specify expanded nodes | `string[]` | [] |
| selectedKeys | Selected nodes | `string[]` | [] |
| multiple | Whether to support multiple selection | `boolean` | false |
| loading | Asynchronous loading state | `boolean` | false |
| loadData | Loads children asynchronously; a successful node is not loaded repeatedly | `((node: TreeNode) => Promise)` | - |
| fieldNames | Custom node field names | `TreeFieldNames` | - |
| directory | Whether to display a directory tree | `boolean` | false |
| virtual | Whether to enable virtual scrolling | `boolean` | false |
| height | Virtual viewport height | `string \| number` | 300 |
| itemHeight | Fixed virtual node height | `number` | 28 |
| overscan | Number of nodes rendered outside the viewport | `number` | 5 |
## TreeNode API
| Property | Description | Type | Default |
| -------- | ------------------------------------------------------------------------------------- | ---------- | ------- |
| title | Node title; the `title` slot can also be used | string | - |
| icon | Custom icon | string | - |
| disabled | Whether node is disabled | boolean | false |
| children | Child nodes | TreeNode[] | - |
| isLeaf | Set as leaf node (effective when loadData is set). false will force it as parent node | boolean | false |
### Events
| Property | Description | Type |
| --- | --- | --- |
| onSelect | Triggered when a tree node is clicked | `(node: TreeNode) => void` |
| onCheck | Triggered when a checkbox is clicked | `(node: TreeNode, checked: boolean, keys: string[]) => void` |
| onExpand | Triggered when a node expands or collapses | `(result: TreeExpandEvent) => void` |
| onDragStart | Triggered when dragging starts | `(node: TreeNode, event: DragEvent) => void` |
| onDragEnd | Triggered when dragging ends | `(node: TreeNode, event: DragEvent) => void` |
| onDragEnter | Triggered when a dragged node enters | `(node: TreeNode, event: DragEvent) => void` |
| onDragLeave | Triggered when a dragged node leaves | `(node: TreeNode, event: DragEvent) => void` |
| onDrop | Triggered when a node is dropped | `(nodes: TreeDropEvent, event: DragEvent) => void` |
| onLoadError | Triggered when asynchronous loading fails | `(_error: unknown, node: TreeNode) => void` |
The first `onDrop` argument also contains `dropPosition: 'before' | 'inside' | 'after'`.
## Instance Methods
| Method | Description |
| ---------------- | -------------------------- |
| getNode | Gets a node by key |
| getCheckedNodes | Gets checked nodes |
| getSelectedNodes | Gets selected nodes |
| scrollTo | Scrolls to a node |
| expandAll | Expands all non-leaf nodes |
| collapseAll | Collapses all nodes |
---
# TreeSelect
Tree selection control.
## When to Use
Similar to the Select selection control, when the selectable data structure is a tree structure, TreeSelect can be used, such as company hierarchy, subject system, classification directory, etc.
## Examples
[Basic Usage](./demo/basic.vue)
- The simplest usage.
[Multiple Selection](./demo/multiple.vue)
- A tree select component that supports multiple selections.
[Checkable](./demo/checkable.vue)
- Use checkboxes to enable multi-selection.
[Disabled](./demo/disabled.vue)
- Disabled state.
[Asynchronous Loading](./demo/sync.vue)
- Click to expand a node and load data dynamically.
[Size](./demo/size.vue)
- The select box sizes are: `small`, `default`, `large`.
[Weird Definition](./demo/theme.vue)
- Some strange and unusual things.
[Virtual Scrolling](./demo/virtual.vue)
- Enable virtual scrolling for large data sets to render only visible tree nodes in the dropdown.
## TreeSelect API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| modelValue | Specify the `value` of the selected item, can use `v-model` for two-way binding | `TreeSelectValue` | - |
| value | Initial value, read only on mount. Use modelValue for subsequent updates; modelValue takes precedence when both are provided. | `TreeSelectValue` | - |
| width | Component width | `number` | - |
| placeholder | Default text of selector | `string` | Please select |
| disabled | Whether current item is disabled | `boolean` | false |
| readonly | Read-only; prevents opening, clearing and changing | `boolean` | false |
| size | Component size, provides two sizes: `small`, `large`, default is normal | `"small" \| "medium" \| "large"` | - |
| placement | Dropdown placement | `"top" \| "top-left" \| "top-right" \| "bottom" \| "bottom-left" \| "bottom-right"` | bottom-left |
| emptyText | Prompt displayed when no data | `string` | 'No data yet' |
| multiple | Whether to display in multiple selection mode | `boolean` | false |
| block | Whether to fill the parent width | `boolean` | false |
| maxTagCount | Maximum visible tags in multiple mode; excess tags are shown in a Tooltip | `number` | - |
| filterable | Whether search filtering is enabled | `boolean` | false |
| loading | Asynchronous loading state | `boolean` | false |
| clearable | Whether options can be cleared | `boolean` | true |
| bordered | Whether to show border | `boolean` | true |
| showArrow | Whether to show dropdown button | `boolean` | true |
| arrowIcon | Custom dropdown arrow icon | `IconType[]` | - |
| theme | The theme of TreeSelect | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| icon | Custom icon | `IconType[]` | - |
| shape | When shape='circle', displays rounded corners | `"default" \| "circle" \| "square" \| "round"` | - |
| treeLoadData | Method to asynchronously load data | `((node: TreeNode) => Promise)` | - |
| treeData | Array of nestable node properties, data to generate `tree` | `TreeNode[]` | [] |
| treeCheckable | Whether to show checkbox | `boolean` | false |
| treeCheckStrictly | Whether parent and child check states are independent | `boolean` | false |
| showLine | Whether to show connecting lines | boolean | false |
| showIcon | Whether to show icons | boolean | true |
| treeShowIcon | Whether to show tree node icons | `boolean` | true |
| treeShowLine | Whether to show tree connection lines | `boolean` | false |
| treeExpandedKeys | Specify expanded nodes | `string[]` | [] |
| virtual | Whether to enable virtual scrolling for tree nodes | `boolean` | false |
| virtualHeight | Virtual dropdown viewport height | `string \| number` | 260 |
| itemHeight | Fixed virtual node height | `number` | 28 |
| overscan | Number of nodes rendered outside the viewport | `number` | 5 |
## TreeSelect Events
| Property | Description | Type |
| --- | --- | --- |
| onTreeSelect | Triggered when tree node is clicked | `(value: string, label: VNodeChild, selected: boolean) => void` |
| onSearch | Triggered during search | `(event: InputEvent) => void` |
| onChange | Triggered when the value changes | `(value: TreeSelectValue) => void` |
| onTreeExpand | Triggered when a tree node is expanded | `(event: TreeExpandEvent) => void` |
| onOpenChange | Triggered when the dropdown expands or collapses | `(open: boolean) => void` |
| onClear | Triggered when cleared | `() => void` |
---
# Tag
Small labels for marking and categorization.
## When to Use
- Used to mark attributes and dimensions of things.
- For classification.
## Examples
[Basic Usage](./demo/basic.vue)
- Use `closeable` to show a close button. Clicking closes the tag and triggers `close`.
[Size and Shape](./demo/size.vue)
- Control size via `size`.
[Icon](./demo/icon.vue)
- You can set the `icon` attribute or directly use the Icon component inside the Tag.
[Colorful Tags](./demo/color.vue)
- Multiple preset tag colors for different scenarios. If the presets don't meet your needs, you can set a specific color value.
[Dynamic Add and Remove](./demo/dynamic.vue)
- Use `closeable` to show a close button.
## Closing
Clicking the close button triggers `close`. After the exit animation, the content is removed and `afterClose` fires.
For dynamic lists, remove the corresponding item from the array in `afterClose` to preserve the exit animation.
## Tag API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| closeable | Whether to show close button | `boolean` | false |
| compact | Whether to use the compact size for embedding in input controls | `boolean` | false |
| color | Tag color | `string` | - |
| icon | Tag icon | `IconType[]` | - |
| onClose | Triggered when the close button is clicked | `() => void` | - |
| onAfterClose | Triggered after the exit animation | `() => void` | - |
| size | Button size, optional values `small`, `large`, default not selected | `"small" \| "medium" \| "large"` | - |
| theme | The component renders the theme | `"default" \| "fill" \| "outline" \| "plain" \| "solid" \| "dashed" \| "underlined"` | fill |
| shape | The shape in which the component is presented | `"default" \| "circle" \| "square" \| "round"` | circle |
---
# Row / Col
Uses a 24-grid system, dividing the area into 24 equal parts, making it easy to handle most layout problems.
Two concepts: row `row` and column `col`. Specific usage is as follows:
- Use `row` to create a row horizontally
- Insert a group of `col` into the `row`
- Type your own content in each `col`
- Specify the span range by setting the `span` parameter of `col`, ranging from 1 to 24
- The sum of `col` in each `row` should be 24
> Note: In non-template/render mode, use k-col.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- `col` must be placed inside `row`.
[Column Gutter](./demo/gutter.vue?show=vertical)
- Use the `gutter` attribute to set the spacing between columns. For vertical spacing, it can be written as an array [horizontal spacing, vertical spacing].
[Grid Offset](./demo/offset.vue?show=vertical)
- By setting the `offset` attribute, columns can be offset left or right, with the offset grid count being the value of `offset`.
[Responsive Grid](./demo/responsive.vue?show=vertical)
- Six responsive sizes are available: `xs`, `sm`, `md`, `lg`, `xl`, and `xxl`. Pass a span number directly, or an object containing `span`, `offset`, `order`, `push`, and `pull`.
[Flex Alignment](./demo/align.vue?show=vertical)
- Vertical alignment of Flex child elements.
[Flex Layout](./demo/flex.vue?show=vertical)
- Row uses Flex layout by default. Set `justify` to control the horizontal alignment of its children.
[Flex Fill](./demo/fill.vue?show=vertical)
- Col provides a flex property to support filling.
## Row API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| align | Vertical alignment in flex layout: `top` `middle` `bottom` | `"top" \| "bottom" \| "middle"` | `top` |
| justify | Horizontal arrangement in flex layout: `start` `end` `center` `space-around` `space-between` | `"center" \| "start" \| "end" \| "space-between" \| "space-around"` | `start` |
| gutter | Grid spacing in px. Use `[horizontal, vertical]` to set both directions | `number \| [number, number]` | - |
## Col API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| span | Occupied columns from 0~24; `0` hides the column | `number` | - |
| offset | Left offset from 0~24 | `number` | - |
| order | Column order from 0~24 | `number` | - |
| push | Move the column right by 0~24 columns | `number` | - |
| pull | Move the column left by 0~24 columns | `number` | - |
| flex | Flex fill, such as `1`, `auto`, `100px`, or `1 1 200px` | `string \| number` | - |
| xs | `<576px`; accepts a span number or a responsive object | `ColResponsiveSize` | - |
| sm | `≥576px` | `ColResponsiveSize` | - |
| md | `≥768px` | `ColResponsiveSize` | - |
| lg | `≥992px` | `ColResponsiveSize` | - |
| xl | `≥1200px` | `ColResponsiveSize` | - |
| xxl | `≥1600px` | `ColResponsiveSize` | - |
```ts
interface ColSize {
span?: number;
offset?: number;
order?: number;
push?: number;
pull?: number;
}
```
---
# Row / Col
Uses a 24-grid system, dividing the area into 24 equal parts, making it easy to handle most layout problems.
Two concepts: row `row` and column `col`. Specific usage is as follows:
- Use `row` to create a row horizontally
- Insert a group of `col` into the `row`
- Type your own content in each `col`
- Specify the span range by setting the `span` parameter of `col`, ranging from 1 to 24
- The sum of `col` in each `row` should be 24
> Note: In non-template/render mode, use k-col.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- `col` must be placed inside `row`.
[Column Gutter](./demo/gutter.vue?show=vertical)
- Use the `gutter` attribute to set the spacing between columns. For vertical spacing, it can be written as an array [horizontal spacing, vertical spacing].
[Grid Offset](./demo/offset.vue?show=vertical)
- By setting the `offset` attribute, columns can be offset left or right, with the offset grid count being the value of `offset`.
[Responsive Grid](./demo/responsive.vue?show=vertical)
- Six responsive sizes are available: `xs`, `sm`, `md`, `lg`, `xl`, and `xxl`. Pass a span number directly, or an object containing `span`, `offset`, `order`, `push`, and `pull`.
[Flex Alignment](./demo/align.vue?show=vertical)
- Vertical alignment of Flex child elements.
[Flex Layout](./demo/flex.vue?show=vertical)
- Row uses Flex layout by default. Set `justify` to control the horizontal alignment of its children.
[Flex Fill](./demo/fill.vue?show=vertical)
- Col provides a flex property to support filling.
## Row API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| align | Vertical alignment in flex layout: `top` `middle` `bottom` | `"top" \| "bottom" \| "middle"` | `top` |
| justify | Horizontal arrangement in flex layout: `start` `end` `center` `space-around` `space-between` | `"center" \| "start" \| "end" \| "space-between" \| "space-around"` | `start` |
| gutter | Grid spacing in px. Use `[horizontal, vertical]` to set both directions | `number \| [number, number]` | - |
## Col API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| span | Occupied columns from 0~24; `0` hides the column | `number` | - |
| offset | Left offset from 0~24 | `number` | - |
| order | Column order from 0~24 | `number` | - |
| push | Move the column right by 0~24 columns | `number` | - |
| pull | Move the column left by 0~24 columns | `number` | - |
| flex | Flex fill, such as `1`, `auto`, `100px`, or `1 1 200px` | `string \| number` | - |
| xs | `<576px`; accepts a span number or a responsive object | `ColResponsiveSize` | - |
| sm | `≥576px` | `ColResponsiveSize` | - |
| md | `≥768px` | `ColResponsiveSize` | - |
| lg | `≥992px` | `ColResponsiveSize` | - |
| xl | `≥1200px` | `ColResponsiveSize` | - |
| xxl | `≥1600px` | `ColResponsiveSize` | - |
```ts
interface ColSize {
span?: number;
offset?: number;
order?: number;
push?: number;
pull?: number;
}
```
---
# Upload
Uploading is the process of publishing information (web pages, text, images, videos, etc.) to a remote server through a web page or upload tool.
## When to Use
- When one or some files need to be uploaded.
- When upload progress needs to be displayed.
- When drag-and-drop interaction needs to be used.
## Examples
[Click to Upload](./demo/basic.vue)
- Classic style. When the user clicks the button, a file selection dialog pops up.
[Upload Multiple Files](./demo/file-list.vue)
- By setting the `multiple` attribute, you can support selecting and uploading multiple files simultaneously. If not set, only one file can be uploaded by default.
[Upload Folder](./demo/directory.vue)
- By setting `directory` to `true`, you can support uploading all files from a folder.
[Upload File Types](./demo/accept.vue)
- Use the `accept` attribute (a native HTML input attribute) to restrict the types of files that can be uploaded. `accept` supports two types of string values: - A set of file extensions (recommended), such as `.jpg`, `.png`, etc.
- A set of MIME types for files. Refer to the [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types) documentation. For example, to only allow users to upload PNG and PDF files, `accept` can be written as: `accept = '.pdf,.png'` or `accept = 'application/pdf,image/png'` (simply connect the MIME types for PNG and PDF with a comma).
[Pre-upload Image Processing](./demo/transform.vue)
- Use `transformFile` to process the file before it is uploaded, for example, to compress it.
[Upload Restrictions](./demo/exceed.vue)
- `limit` restricts the number of uploads. The `minSize` and `maxSize` attributes allow you to customize file size limits for uploads.
[Manual Upload / Custom Properties](./demo/custom.vue)
- By setting `data` and `headers`, you can add custom upload properties. When `autoTrigger='false'`, selecting a file will not automatically trigger the upload. You need to manually call the `upload` method on the ref to trigger it. `name` is the uploaded filename.
[Custom Request and Upload Queue](./demo/custom-request.vue)
- Integrates a custom upload service with pre-upload validation, concurrency limits, progress, cancellation, and retry.
[File Validation](./demo/validation.vue)
- Validates the actual type and size of selected or dropped files.
[Photo Wall](./demo/pictures.vue)
- Set `type="picture"` to display thumbnails. Enable `sortable` to drag whole cards with live animated reordering. Release to confirm, or press `Esc` or release outside the list to cancel. Click an image to preview it.
[Upload Avatar](./demo/avatar.vue)
- When `limit` equals the number of uploaded files, the file selection component will not be displayed.
[Drag and Drop Upload](./demo/draggable.vue)
- Set `draggable='true'` to enable drag-and-drop functionality.
[Form Validation](./demo/forms.vue)
- Upload form validation.
## Upload API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| accept | Accepted upload file types, see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept | `string` | - |
| action | Upload address | `string` | - |
| method | HTTP method for upload request | `string` | post |
| data | Other parameters that may be required for upload | `Record` | {} |
| disabled | Whether disabled | `boolean` | false |
| readonly | Read-only; displays files without selecting, uploading or removing | `boolean` | false |
| headers | Set upload request headers | `Record` | - |
| withCredentials | Include credentials in cross-origin requests | `boolean` | false |
| timeout | Request timeout in milliseconds | `number` | 0 |
| customRequest | Custom upload implementation | `UploadCustomRequest` | - |
| parseResponse | Custom XHR response parser | `((xhr: XMLHttpRequest) => unknown)` | - |
| multiple | Whether to support multiple file selection | `boolean` | false |
| directory | Whether to support directory upload | `boolean` | false |
| showUploadList | Whether to show upload list | `boolean` | true |
| autoTrigger | Whether to auto upload | `boolean` | true |
| draggable | Whether to support drag and drop upload | `boolean` | false |
| sortable | Whether pictures can be reordered | `boolean` | false |
| preview | Whether clicking a picture opens image preview | `boolean` | true |
| validateAccept | Whether to validate file types | `boolean` | true |
| maxConcurrent | Maximum concurrent uploads | `number` | Infinity |
| fileList | Uploaded file list | `UploadFile[]` | - |
| name | File parameter name sent to backend, default `file` | `string` | 'file' |
| uploadIcon | Auxiliary icon for upload area | `IconType[]` | Add |
| uploadText | Auxiliary text for upload area | `string` | - |
| uploadSubText | Secondary auxiliary text for upload area | `string` | - |
| limit | Maximum number of files allowed to upload | `number` | - |
| minSize | Minimum file size unit for upload (KB) | `number` | - |
| maxSize | Maximum file size unit for upload (KB) | `number` | - |
| transformFile | Transform file before uploading | `((file: File) => File \| Blob \| Promise)` | - |
| type | Display style after selecting files | `"picture" \| "list"` | list |
## Event API
| Property | Description | Type |
| --- | --- | --- |
| onChange | Triggered during upload, completion, failure | `(event: UploadChangeEvent) => void` |
| onSelectFiles | Triggered when files are selected, returns selected files | `(files: UploadFile[]) => void` |
| onRemove | Callback when file is removed | `(event: UploadChangeEvent) => void` |
| onExceed | Callback when limit is exceeded | `() => void` |
| onSizeError | Callback when minSize, maxSize error occurs | `(event: UploadChangeEvent) => void` |
| onTypeError | Called when a file does not match accept | `(event: UploadChangeEvent) => void` |
| onSort | Called after picture order changes | `(event: UploadSortEvent) => void` |
| onBeforeUpload | Validate or transform before upload; return `false` to stop | `((item: UploadFile, file: File) => boolean \| File \| Blob \| void \| Promise)` |
## Methods
| Name | Description | Parameters |
| ------ | ----------------------------------- | ----------------- |
| upload | Upload waiting files | - |
| abort | Abort one file, or all when omitted | file?: UploadFile |
| retry | Retry a file | file: UploadFile |
---
# Watermark
Add a watermark to a specific area of the page.
## When to Use
- Use when you need to add a watermark to identify copyright ownership.
- Suitable for preventing information theft.
## Examples
[Basic Usage](./demo/basic.vue?show=vertical)
- The simplest usage.
[Image watermark](./demo/image.vue?show=vertical)
- Specify the image source via the `image` prop. To ensure high definition and prevent distortion, please set the `width` and `height`, and upload an image (e.g., a logo) at least twice the display dimensions.
[Multi-line text watermark](./demo/multiple-lines.vue?show=vertical)
- Set multi-line text content by passing a string or an array composed of `WatermarkText` objects via `content`. Styles can be adjusted independently for each line.
[Used in Modals and Drawers](./demo/in-modal-drawer.vue)
- Using watermarks within Modals and Drawers.
[Custom Configuration](./demo/custom.vue?show=vertical)
- Preview the watermark effect by configuring custom parameters.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| content | The text content of the watermark. Accepts a string or an array for multi-line support. Passing an array of objects allows independent styling for each line. | `string \| string[] \| WatermarkTextItem[]` | `""` |
| image | The source URL (Base64 or URL) of the image watermark. If provided, the image watermark takes priority over text. | `string` | `""` |
| width | Width of a single watermark cell, in `px`. | `number` | `240` |
| height | Height of a single watermark cell, in `px`. | `number` | `189` |
| rotate | Rotation angle of the watermark in degrees. | `number` | `-22` |
| zIndex | The z-index of the watermark container. It is recommended to increase this value when used inside high-level components like Modals or Drawers. | `number` | `999` |
| fullscreen | Whether to enable fullscreen mode. If `true`, the watermark will be mounted directly to the `body`. | `boolean` | `false` |
| antiTamper | Whether to enable high-level anti-tampering protection (monitors DOM node removal and attribute modifications via `MutationObserver`). | `boolean` | `true` |
| font | Global fallback styles for the watermark text (including color, font size, weight, family, and style). | `WatermarkFont` | - |
| gap | The horizontal and vertical spacing between watermark cells, formatted as `[x, y]`. | `number[]` | `[40, 40]` |
| offset | The starting offset origin for the watermark grid tiling, formatted as `[x, y]`. Useful for fine-tuning edge whitespace. | `number[]` | `[20, 20]` |
| layout | Layout mode of the watermark. Options: `'grid'` (traditional orthogonal grid) or `'stagger'` (advanced staggered grid with alternating row offsets). | `"stagger" \| "grid"` | `'grid'` |
### WatermarkTextItem
When passing an array of objects to `content`, each element is a `WatermarkTextItem`. This allows you to override global configurations and define fine-grained, heterogeneous styles for each individual line:
| Property | Description | Type | Default |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- | :------------------------- |
| text | The text content for the current line. | string | Required |
| color | Independent control over the text color for the current line. Supports various CSS color formats (e.g., hex, RGBA). Often used to highlight warnings or de-emphasize audit backgrounds. | string | Inherits `font.color` |
| fontSize | Independent control over the font size for the current line, in `px`. Ideal for creating visual hierarchy (e.g., large titles paired with smaller subtitles). | number | Inherits `font.fontSize` |
| fontWeight | Independent control over the font weight for the current line (e.g., `bold` or numeric values like `500`). | string \| number | Inherits `font.fontWeight` |
| fontStyle | Independent control over the font style. Options include `'normal'`, `'italic'`, or `'oblique'`. Helps break the monotony of standard layouts. | 'normal' \| 'italic' \| 'oblique' | Inherits `font.fontStyle` |
---
# VirtualList
Render only data near the viewport to improve large-list performance.
## Examples
[Basic](./demo/basic.vue?show=vertical)
- Renders 10,000 fixed-height records with a small overscan buffer.
## Usage in Components
[Usage in Select](../select/demo/virtual.vue)
- Select uses virtual scrolling for large option sets while preserving keyboard navigation.
[Usage in Table](../table/demo/virtual.vue?show=vertical)
- Table combines virtual scrolling with a fixed header, horizontal scrolling, stripes, and a fixed column.
[Usage in Tree](../tree/demo/virtual.vue)
- Tree renders only visible nodes near the current viewport.
[Usage in TreeSelect](../tree-select/demo/virtual.vue)
- TreeSelect uses virtual scrolling in its dropdown tree for large data sets.
## API
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| data | List data | `unknown[]` | [] |
| height | Viewport height | `string \| number` | 300 |
| itemHeight | Fixed item height | `number` | 32 |
| overscan | Extra items rendered above/below | `number` | 5 |
| itemKey | Key field or key resolver | `string \| ((item: unknown, index: number) => VirtualListKey)` | - |
| onScroll | Called when the list scrolls | `(event: Event) => void` | - |
## Methods
| Name | Description | Parameters |
| ------------- | ----------------- | --------------- |
| scrollToIndex | Scroll to an item | (index, align?) |