tdesign-vue-next

name	tdesign-vue-next
description	TDesign Vue 3 component library usage guide, covering tdesign-vue-next 1.x series, including basic components, forms, tables, theme customization, dark mode, and AI Chat components

TDesign Vue Next

S - Scope

• Target: tdesign-vue-next@^1 with Vue 3.3+
• Cover: Basic components, layout components, navigation components, input components, data display components, feedback components, theme customization, dark mode, Chat component
• Avoid: Undocumented internal APIs, DOM manipulation hacks, other TDesign tech stacks (React/Miniprogram)

Default assumptions (when not explicitly specified)

• Language: TypeScript + <script setup> syntax
• Styling: Use CSS variables and ConfigProvider for theme configuration, avoid directly overriding internal component class names
• Provider: Use a single ConfigProvider at the app root for unified configuration
• Icons: Use tdesign-icons-vue-next icon library
• Imports: Import components on demand import { Button } from 'tdesign-vue-next'

Scope rules (must follow)

1. Only use APIs documented in TDesign official documentation
2. Do not invent props, events, or component names
3. Never use @ts-ignore to bypass type checking; consult official type definitions first for type issues
4. If encountering potential bugs or documentation-behavior inconsistencies, clearly inform users and guide them to submit an Issue
5. Example code must be directly runnable, no pseudo-code or ellipsis placeholders

Complex triggers (must open corresponding Reference)

Trigger Condition	Reference
Dynamic forms (FormItem add/remove), cross-field validation, async validation	references/form-advanced.md
Server-side sorting/filtering/pagination, virtual scroll, editable table, tree table	references/table-advanced.md
Remote search, large datasets, paginated loading, custom rendering	references/select-advanced.md
Controlled file list, resumable upload, custom upload request	references/upload-advanced.md
Async node loading, checkStrictly, virtual scroll	references/tree-advanced.md
Async loading, dynamic options, custom panel	references/cascader-advanced.md
Dialog/Drawer nesting, imperative calls, close interception	references/dialog-drawer-advanced.md
Deep theme customization, dynamic theme switching, component-level style override	references/theming-advanced.md
Dark mode toggle, system preference sync, local dark mode	references/dark-mode.md
AI chat component, streaming response, custom message rendering	references/chat-advanced.md
TDesign Vue Next 1.x version differences, upgrade guide	references/tdesign-v1.md

Reference index

Topic	Description	Reference
Version Reference	1.x version scope, upgrade notes	references/tdesign-v1.md
Form Advanced	Dynamic forms, linked validation, async validation	references/form-advanced.md
Table Advanced	Virtual scroll, server-side data, editable cells	references/table-advanced.md
Select Advanced	Remote search, pagination, custom options	references/select-advanced.md
Upload Advanced	Controlled upload, custom request, resumable upload	references/upload-advanced.md
Tree Advanced	Async loading, checkStrictly, virtual scroll	references/tree-advanced.md
Cascader Advanced	Async loading, dynamic panel	references/cascader-advanced.md
Dialog/Drawer Advanced	Nested layers, imperative calls	references/dialog-drawer-advanced.md
Theme Customization	CSS variables, Design Token, dynamic theme	references/theming-advanced.md
Dark Mode	Mode toggle, system preference, local dark mode	references/dark-mode.md
Chat Component	AI chat, streaming response, message rendering	references/chat-advanced.md

---

P - Process

1) Identify component hierarchy

User requirements
  ├── Basic display → Button / Link / Icon / Typography
  ├── Layout structure → Layout / Grid / Space / Divider
  ├── Navigation interaction → Menu / Tabs / Breadcrumb / Steps / Pagination
  ├── Data input → Form / Input / Select / DatePicker / Upload / ...
  ├── Data display → Table / List / Tree / Card / Descriptions / ...
  ├── Feedback → Message / Notification / Dialog / Drawer / Loading
  └── Advanced scenarios → Chat (AI conversation)

2) Clarify context before making suggestions

Before providing component recommendations, confirm:

• Vue version (3.3+ recommended)
• Whether ConfigProvider is configured
• Whether dark mode support is needed
• Whether there are special i18n requirements
• Data volume (affects whether virtual scroll is needed)

3) ConfigProvider configuration first

<template>
  <ConfigProvider :global-config="globalConfig">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import { ConfigProvider } from "tdesign-vue-next";

const globalConfig = {
  // Global configuration
};
</script>

4) Component selection rules

Scenario	Recommended Component	Notes
Simple list display	List	Small data, no complex interaction
Complex data table	Table	Supports sorting, filtering, pagination
Large data table	Table + virtual-scroll	Enable virtual scroll
Tree data selection	TreeSelect	Single/multiple tree selection
Cascading selection	Cascader	Multi-level linked selection
Simple dropdown	Select	Moderate number of options
Remote search select	Select + filterable + remote	Disable local filtering
File upload	Upload	Supports drag, multi-file
Form collection	Form + FormItem	Unified validation and submit
Light notification	Message	Operation feedback, auto-dismiss
Important notification	Notification	Requires user confirmation or contains actions
Confirmation action	Dialog / Popconfirm	Choose based on context
Side panel details	Drawer	Without interrupting page flow
AI conversation	Chat	Streaming messages, multi-turn dialogue

5) Form decision chain

Need to collect user input?
  ├── Yes → Use Form wrapper
  │     ├── Need dynamic add/remove fields? → See form-advanced.md
  │     ├── Need cross-field linking? → See form-advanced.md
  │     └── Simple form → Use FormItem + rules
  └── No → Use input component directly

6) Table decision chain

Need to display list data?
  ├── Data > 1000 rows? → Enable virtual scroll, see table-advanced.md
  ├── Need server-side pagination/sorting? → See table-advanced.md
  ├── Need editable cells? → See table-advanced.md
  └── Simple table → Use Table + columns + data

7) Theme customization decision chain

Need to customize theme?
  ├── Only modify brand color → ConfigProvider theme prop
  ├── Modify multiple tokens → Override CSS variables
  ├── Deep customization → See theming-advanced.md
  └── Dark mode → See dark-mode.md

8) Route complex scenarios to Reference

When identifying trigger conditions from the Complex triggers table, must:

1. Inform user this is a complex scenario
2. Open the corresponding Reference document
3. Provide suggestions based on recommended patterns in Reference

9) Accessibility and performance checks

• Ensure form controls have appropriate label
• Enable virtual scroll or pagination for large data scenarios
• Avoid complex calculations in template, use computed
• Ensure stable key for list rendering

---

O - Output

Output should include (as needed)

1. Component recommendation: Component name and selection rationale
2. Minimal configuration: Required ConfigProvider setup
3. Code example: Directly runnable <script setup> code
4. Performance tips: Notes for large data, frequent updates scenarios
5. Reference path: Point to corresponding reference docs for complex scenarios
6. Official documentation link: Related component's official documentation URL

Output forbidden

1. Unverified APIs or props
2. Hack code relying on specific internal implementations
3. Incomplete code snippets (missing imports or key configurations)
4. Code for other TDesign tech stacks (React/Miniprogram)
5. Syntax incompatible with user's Vue version

Regression checklist

• ConfigProvider: Is root component configured, are theme tokens effective
• Form: Are rules defined, is validation trigger (trigger) correct, is model two-way binding correct
• Table: Does row-key provide stable unique value, is columns cached with computed
• Select: Is local filtering disabled for remote search (filterable + :filter returns true)
• Upload: Is controlled mode v-model:files updating correctly, is action or requestMethod configured
• Tree/TreeSelect: Does keys config match data structure, does async load load function return Promise
• Dialog/Drawer: v-model:visible two-way binding, destroyOnClose configured based on scenario
• Dark Mode: Is theme-mode attribute added to <html> or root element
• Icons: Are icons correctly imported from tdesign-icons-vue-next
• TypeScript: Are component props types correct, do event callback parameter types match

---

Quick Reference

Installation

npm install tdesign-vue-next
# Icon library
npm install tdesign-icons-vue-next

Full Import

// main.ts
import { createApp } from "vue";
import TDesign from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

createApp(App).use(TDesign).mount("#app");

On-demand Import (Recommended)

// main.ts
import { createApp } from "vue";
import { Button, Input, Form, FormItem } from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

const app = createApp(App);
app.use(Button).use(Input).use(Form).use(FormItem);
app.mount("#app");

Minimal Example

<template>
  <ConfigProvider>
    <Form :model="formData" :rules="rules" @submit="onSubmit">
      <FormItem label="Username" name="username">
        <Input v-model="formData.username" placeholder="Enter username" />
      </FormItem>
      <FormItem>
        <Button theme="primary" type="submit">Submit</Button>
      </FormItem>
    </Form>
  </ConfigProvider>
</template>

<script setup lang="ts">
import { reactive } from "vue";
import {
  ConfigProvider,
  Form,
  FormItem,
  Input,
  Button,
} from "tdesign-vue-next";
import type { FormRules, SubmitContext } from "tdesign-vue-next";

const formData = reactive({
  username: "",
});

const rules: FormRules<typeof formData> = {
  username: [{ required: true, message: "Username is required" }],
};

const onSubmit = ({ validateResult }: SubmitContext) => {
  if (validateResult === true) {
    console.log("Submit successful", formData);
  }
};
</script>

Official Resources

• Official Documentation: https://tdesign.tencent.com/vue-next/overview
• GitHub: https://github.com/Tencent/tdesign-vue-next
• Design Specifications: https://tdesign.tencent.com/design/values