Ant Design Vue UI Library

Common errors

• [Vue warn]: Failed to resolve component: a-button

  cause Ant Design Vue components are not globally registered or imported into the current component.
  fix Ensure you `import { Button } from 'ant-design-vue';` and register it locally in your component's `components` option, or globally via `app.use(Button);`.

• Error: `message` is not a function or is undefined

  cause The global `message` API (and similar for `notification`, `Modal`) has not been properly provided through the `App` component or mounted to `app.config.globalProperties`.
  fix Wrap your root application with `<a-app>` component from Ant Design Vue. Alternatively, if using `ConfigProvider` directly without `App`, manually provide it: `app.config.globalProperties.$message = message;` after importing `message`.

• TypeError: Cannot read properties of undefined (reading 'setup') in your build output or console

  cause Often occurs when using Ant Design Vue with a version of Vue.js older than required (e.g., Vue 2.x with Ant Design Vue v4.x).
  fix Upgrade your Vue.js dependency to `^3.2.0` or higher, as Ant Design Vue v4.x requires Vue 3.

Warnings

• breaking Ant Design Vue v4.x introduced significant breaking changes from v3.x, especially regarding styling, theme customization, and component APIs. Direct migration without consulting the official migration guide will lead to errors.
  Fix: Refer to the official Ant Design Vue 4.0 migration guide. Major changes include migrating from Less to CSS-in-JS for styling, updated theme configuration via `ConfigProvider`, and potential API changes for individual components. Ensure your build setup supports CSS-in-JS if customizing themes.
• breaking Ant Design Vue v3.x and earlier versions supported Vue 2.x and Vue 3.x with separate packages or branches. Version 4.x is exclusively for Vue 3.x, requiring a Vue 3.2.0+ peer dependency.
  Fix: Ensure your project is running Vue 3.2.0 or newer. If you are on Vue 2, you must use Ant Design Vue v1.x, or migrate your entire application to Vue 3 before upgrading to Ant Design Vue v4.
• gotcha Default styling might not load if the `ant-design-vue/dist/reset.css` or `ant-design-vue/dist/antd.min.css` (for older versions) is not explicitly imported into your project. Components will appear unstyled.
  Fix: Add `import 'ant-design-vue/dist/reset.css';` to your main entry file (e.g., `main.ts` or `main.js`). If you use custom themes or a build system that handles CSS import, ensure the theme variables are correctly overridden and compiled.
• gotcha Global utility functions like `message`, `notification`, and `Modal.confirm` are often used without being properly provided by the `App` component or globally imported, leading to errors or inconsistent styling.
  Fix: Wrap your root Vue component with `<a-config-provider>` and `<a-app>`: `<a-config-provider><a-app>...</a-app></a-config-provider>`. This provides the necessary context for these global methods. Alternatively, import `message` or `notification` directly and use `app.config.globalProperties.$message = message;` for global access.

Install

• npm install ant-design-vue npm
• yarn add ant-design-vue yarn
• pnpm add ant-design-vue pnpm

Imports

• Button
  wrong:

  const Button = require('ant-design-vue/lib/button');

  correct:

  import { Button } from 'ant-design-vue';

  For modern Vue 3 setups, use named ESM imports. Direct CommonJS requires for individual components are not the recommended pattern for tree-shaking.
• ConfigProvider
  wrong:

  import ConfigProvider from 'ant-design-vue/es/config-provider';

  correct:

  import { ConfigProvider } from 'ant-design-vue';

  Commonly used for global configurations like theme, locale, and prefix. All core components are named exports from the main package entry point.
• App
  wrong:

  import * as Antd from 'ant-design-vue';

  correct:

  import { App } from 'ant-design-vue';

  The 'App' component provides global message, notification, and modal contexts. Importing everything with '*' can increase bundle size unnecessarily.
• Table
  wrong:

  import Table from 'ant-design-vue/lib/table';

  correct:

  import { Table } from 'ant-design-vue';

  Starting with v4, Ant Design Vue strongly promotes direct named imports for better tree-shaking and consistency. Legacy direct path imports might still work but are discouraged.

Quickstart

This quickstart demonstrates how to set up Ant Design Vue in a Vue 3 application, import components like Button, ConfigProvider, and Table, and use the global message service, along with importing the necessary CSS.

import { createApp } from 'vue';
import { Button, ConfigProvider, Table, message } from 'ant-design-vue';
import 'ant-design-vue/dist/reset.css';

const App = {
  setup() {
    const columns = [
      { title: 'Name', dataIndex: 'name', key: 'name' },
      { title: 'Age', dataIndex: 'age', key: 'age' },
      { title: 'Address', dataIndex: 'address', key: 'address' },
    ];

    const data = [
      { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { key: '3', name: 'Joe Black', age: 32, address: 'Sidney No. 1 Lake Park' },
    ];

    const showMessage = () => {
      message.info('Hello from Ant Design Vue!');
    };

    return {
      columns,
      data,
      showMessage,
    };
  },
  template: `
    <ConfigProvider>
      <div style="padding: 24px;">
        <h1>Ant Design Vue Quickstart</h1>
        <Button type="primary" @click="showMessage">Show Message</Button>
        <br/><br/>
        <Table :columns="columns" :data-source="data" />
      </div>
    </ConfigProvider>
  `,
};

createApp(App)
  .use(Button)
  .use(ConfigProvider)
  .use(Table)
  .mount('#app');

// To run this, create an index.html with <div id="app"></div> and include a script tag for this code.
// Ensure you have Vue 3 and ant-design-vue installed in your project.
// e.g., <script type="module"> // Your quickstart code </script>