TDesign Icons for Vue 2

Common errors

• [Vue warn]: Unknown custom element: <Icon> - did you register the component correctly?

  cause The `Icon` component (or any specific icon component like `CloseIcon`) was used in a Vue template without being properly imported and registered in the component's `components` option or globally with `Vue.component()`.
  fix Ensure `import { Icon } from 'tdesign-icons-vue';` is present and the component is registered: `components: { Icon }` or `Vue.component('TIcon', Icon);`.

• Icons not displaying, showing an empty box, or question mark characters when using <IconFont>

  cause The CSS file containing the `@font-face` declaration and character mappings for the TDesign icon font is not loaded or is misconfigured.
  fix Verify that the icon font CSS file (e.g., from TDesign's main package or a specific icon font distribution) is imported into your main application entry point (e.g., `main.js`) or linked in your `index.html`. For example: `import 'tdesign-vue/es/style/webcomponents.css'` (path may vary).

• TypeError: Cannot read properties of undefined (reading 'name') for an icon component.

  cause This typically occurs if a specific icon component (e.g., `CloseIcon`) is imported but somehow accessed incorrectly, or if `Icon` is used without a `name` prop where required, indicating the icon data is missing.
  fix Double-check the import path for individual icons. If using the general `<Icon>` component, ensure the `name` prop is provided and spelled correctly, matching an existing icon.

Warnings

• breaking This package, `tdesign-icons-vue`, is specifically for Vue 2.x applications. For Vue 3.x, you must use `tdesign-icons-vue-next` instead. Using the wrong package will result in compatibility issues or runtime errors.
  Fix: For Vue 3 projects, install `tdesign-icons-vue-next` (npm i tdesign-icons-vue-next). For Vue 2, ensure `tdesign-icons-vue` is installed.
• breaking Icon names and availability can change between minor and major versions. Some icons may be renamed, removed, or have their definitions updated, potentially breaking existing usages, especially in major releases like 0.3.0.
  Fix: Always check the CHANGELOG or release notes before upgrading to identify any icon-related breaking changes. Update icon `name` props or imports as necessary.
• gotcha When using the `IconFont` component, you must ensure that the corresponding icon font CSS file (which defines the `@font-face` and icon classes) is properly loaded in your application. Without the CSS, icons will not render correctly.
  Fix: Include the TDesign icon font CSS in your project (e.g., in `main.js` or `index.html`) if you intend to use `IconFont`. Refer to TDesign's official documentation for the correct path.
• gotcha The `Icon` component (SVG sprite) and individual icon components can be customized with `size`, `color`, and `style` props. However, inconsistent application of these props or conflicting global styles can lead to unexpected visual results.
  Fix: Prioritize direct props for sizing and coloring individual icons. For global styling, ensure CSS specificity rules are understood, and consider using CSS variables or scoped styles.

Install

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

Imports

• Icon
  wrong:

  const Icon = require('tdesign-icons-vue')

  correct:

  import { Icon } from 'tdesign-icons-vue'

  Imports the SVG sprite component. Use named import. CommonJS require is not supported.
• IconFont
  wrong:

  import IconFont from 'tdesign-icons-vue'

  correct:

  import { IconFont } from 'tdesign-icons-vue'

  Imports the IconFont component for font-based icons. Requires additional CSS setup. Use named import.
• CloseIcon
  wrong:

  import { CloseIcon } from 'tdesign-icons-vue/es/close'

  correct:

  import { CloseIcon } from 'tdesign-icons-vue'

  Imports a specific icon as a Vue component. This library supports tree-shaking, making direct import efficient.

Quickstart

Demonstrates how to install and use TDesign icons in a Vue 2 application, showcasing global registration of SVG sprite icons, usage of the IconFont component (with a note about CSS), and direct import of individual icon components.

import Vue from 'vue';
import { Icon, IconFont, CloseIcon, TimeIcon } from 'tdesign-icons-vue';

// Globally register the SVG sprite icon component
Vue.component('TIcon', Icon);

// Optionally, globally register the IconFont component
// Vue.component('TIconFont', IconFont);

new Vue({
  el: '#app',
  components: { CloseIcon, TimeIcon, IconFont },
  template: `
    <div id="app">
      <h1>TDesign Icons for Vue 2</h1>
      <h2>SVG Sprite Icon</h2>
      <TIcon name="close" size="24px" style="color: #f00;" />
      <TIcon name="time" size="32px" style="color: #00f;" />
      
      <h2>Icon Font (requires external CSS for font-face)</h2>
      <!-- Ensure the iconfont CSS is loaded globally, e.g., in your main.js or index.html -->
      <!-- Example: <link rel="stylesheet" href="path/to/tdesign-iconfont.css"> -->
      <IconFont name="setting" size="20px" />
      <IconFont name="file" size="28px" />

      <h2>Individual Icon Components</h2>
      <CloseIcon size="24px" style="margin-left: 10px;" />
      <TimeIcon size="24px" />
    </div>
  `
});