tdesign-vue-next

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)

Reference index

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

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