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

)

FormItem

references/form-advanced.md

references/table-advanced.md

references/select-advanced.md

references/upload-advanced.md

references/tree-advanced.md

references/cascader-advanced.md

references/dialog-drawer-advanced.md

references/theming-advanced.md

references/dark-mode.md

references/chat-advanced.md

references/tdesign-v1.md

Reference

index

Reference

references/tdesign-v1.md

references/form-advanced.md

references/table-advanced.md

references/select-advanced.md

references/upload-advanced.md

references/tree-advanced.md

references/cascader-advanced.md

references/dialog-drawer-advanced.md

references/theming-advanced.md

references/dark-mode.md

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

• 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

List

Table

Table

virtual-scroll

TreeSelect

Cascader

Select

Select

filterable

remote

Upload

Form

FormItem

Message

Notification

Dialog

Popconfirm

Drawer

Chat

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

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