TDesign Mobile Vue 3 UI Library

Common errors

• Error: A component name can only contain alphanumeric characters or dashes, but got 't-ActionSheetPlugin'.

  cause Attempting to use a functional API (like `ActionSheetPlugin`) as a Vue component in the template.
  fix Functional APIs are typically called programmatically (e.g., `ActionSheetPlugin.show()`) and are not meant to be rendered directly as `<t-action-sheet-plugin>`. Use `<t-action-sheet>` for the component.

• Failed to resolve component: t-button. If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.

  cause TDesign components were not properly registered with the Vue application.
  fix Ensure you have `import TDesign from 'tdesign-mobile-vue';` and `app.use(TDesign);` in your main application entry file (e.g., `main.ts` or `main.js`). If using individual imports, make sure each component is imported and used correctly.

• Module not found: Error: Can't resolve 'tdesign-mobile-vue/es/style/index.css'

  cause The main CSS file for TDesign Mobile Vue is missing or the import path is incorrect.
  fix Verify that `tdesign-mobile-vue` is correctly installed (`npm install tdesign-mobile-vue`) and ensure the import path `import 'tdesign-mobile-vue/es/style/index.css';` is correct for the global styles. For component-specific styles, check the documentation.

Warnings

• breaking The export method for `ActionSheet` was adjusted in v1.13.0. The component and its functional API are now separated.
  Fix: For the functional API, import `ActionSheetPlugin` (e.g., `import { ActionSheetPlugin } from 'tdesign-mobile-vue';`). For the component, continue to import `ActionSheet`.
• breaking In v1.11.0, several icons were removed from the `Icon` component (`video-camera-3`, `video-camera-3-filled`, `list`). New icons were also added.
  Fix: Review existing icon usage for removed icons. Replace them with available alternatives or update your `tdesign-icons-vue-next` dependency if you are using specific icon versions.
• gotcha In v1.10.0, the `CheckboxGroup` component changed its behavior when `value` is `undefined`. It will no longer warn and instead implicitly convert the data to an `Array` upon user selection.
  Fix: Ensure `CheckboxGroup`'s `value` prop is initialized with an array (e.g., `[]`) or `null` if you wish to strictly control its initial state, rather than relying on `undefined`.
• gotcha The library primarily supports modern browsers. Ensure your target browser versions meet the minimum requirements (e.g., Edge >=97, Firefox >=96, Chrome >=96, Safari >=14.1).
  Fix: If supporting older browsers is critical, consider polyfills or alternative UI libraries. Always verify browser support matrix before deployment.

Install

• npm install tdesign-mobile-vue npm
• yarn add tdesign-mobile-vue yarn
• pnpm add tdesign-mobile-vue pnpm

Imports

• TDesign
  wrong:

  const TDesign = require('tdesign-mobile-vue');

  correct:

  import TDesign from 'tdesign-mobile-vue';

  This is the recommended way to import and globally register all TDesign components for a Vue 3 application. TDesign Mobile Vue is ESM-first.
• Button
  wrong:

  import Button from 'tdesign-mobile-vue/lib/button';

  correct:

  import { Button } from 'tdesign-mobile-vue';

  For tree-shaking and on-demand component loading, import individual components as named exports. No extra setup is typically needed with modern build tools. This also applies to other components like `Dialog`, `ActionSheet`, etc.
• ActionSheetPlugin
  wrong:

  import { ActionSheet } from 'tdesign-mobile-vue'; // Then try to use as function

  correct:

  import { ActionSheetPlugin } from 'tdesign-mobile-vue';

  Since v1.13.0, ActionSheet's functional API is separated and exported as `ActionSheetPlugin`. Other plugins might follow similar patterns. The component itself is still imported as `{ ActionSheet }`.
• types

  import type { ButtonProps } from 'tdesign-mobile-vue';

  The library ships with TypeScript types. Use type imports for props or other utility types.

Quickstart

Sets up a basic Vue 3 application, registers TDesign globally, and demonstrates a TDesign Button component and a functional Toast API.

import { createApp } from 'vue';
import TDesign, { Button, Toast } from 'tdesign-mobile-vue';
import 'tdesign-mobile-vue/es/style/index.css'; // Import global styles

const App = {
  setup() {
    const showToast = () => {
      Toast.info('This is a toast message!');
    };
    return { showToast };
  },
  template: `
    <div style="padding: 20px;">
      <h1>TDesign Mobile Vue Quickstart</h1>
      <t-button block @click="showToast">Show Toast</t-button>
      <t-button block variant="outline" style="margin-top: 10px;">Outline Button</t-button>
      <p style="margin-top: 20px; font-size: 14px; color: #666;">
        This example demonstrates global registration, individual component usage, and a functional API.
      </p>
    </div>
  `,
};

const app = createApp(App);
app.use(TDesign); // Globally registers all TDesign components
app.mount('#app');