How to Integrate Custom Icons into an Ant Design Project: SVG and Iconfont Methods

You can integrate custom icons into an Ant Design project by using the Icon component from @ant-design/icons to render SVG components, or by using the createFromIconfontCN helper to load icons from an external Iconfont script.

The ant-design/ant-design repository relies on the @ant-design/icons package for all iconography, providing two primary APIs for extending the default icon set with bespoke graphics. Both methods ensure your custom icons inherit Ant Design's theming capabilities, including automatic color and size handling.

Understanding Ant Design's Icon Architecture

Ant Design's icon system is decoupled from the main UI library through the @ant-design/icons package. This package exports two critical utilities for custom icon integration: the Icon component and the createFromIconfontCN factory function.

The Icon component accepts a component prop that expects a React component returning an SVG element. When you integrate custom icons using this approach, the SVG should use fill="currentColor" and dimensions relative to 1em to ensure proper inheritance of text color and font size from parent elements.

Method 1: Integrating SVG-Based Custom Icons

SVG-based integration provides the highest fidelity and is ideal for logos, complex illustrations, or icons requiring precise vector control. This method involves creating a React component that returns your SVG markup, then passing that component to Ant Design's Icon wrapper.

Creating the SVG Component

First, define a React component that renders your SVG. The component must return a valid SVG element with specific attributes to ensure theme compatibility.

import React from 'react';

const HeartSvg: React.FC = () => (
  <svg width="1em" height="1em" fill="currentColor" viewBox="0 0 1024 1024">
    <title>heart icon</title>
    <path d="M923 283.6c-13.4-31.1-32.6-58.9-56.9-82.8-24.3-23.9-52.5-42.4-83.8-54.9-32.6-13-67.2-19.6-102.9-19.6-35.7 0-70.3 6.6-102.9 19.6-31.3 12.5-59.5 31-83.8 54.9-24.3 23.9-43.5 51.7-56.9 82.8-13.4 31.1-20.2 64.6-20.2 99.6 0 35 6.8 68.5 20.2 99.6 13.4 31.1 32.6 58.9 56.9 82.8 24.3 23.9 52.5 42.4 83.8 54.9 32.6 13 67.2 19.6 102.9 19.6 35.7 0 70.3-6.6 102.9-19.6 31.3-12.5 59.5-31 83.8-54.9 24.3-23.9 43.5-51.7 56.9-82.8 13.4-31.1 20.2-64.6 20.2-99.6 0-35-6.8-68.5-20.2-99.6z" />
  </svg>
);

Wrapping with the Icon Component

Next, import the Icon component from @ant-design/icons and create a wrapper that passes your SVG component via the component prop. This wrapper accepts all standard icon props including style and className.

import React from 'react';
import Icon, { HomeOutlined } from '@ant-design/icons';
import { Space } from 'antd';
import type { GetProps } from 'antd';

type CustomIconComponentProps = GetProps<typeof Icon>;

const HeartIcon: React.FC<Partial<CustomIconComponentProps>> = (props) => (
  <Icon component={HeartSvg} {...props} />
);

const App: React.FC = () => (
  <Space>
    <HeartIcon style={{ color: 'hotpink', fontSize: '24px' }} />
    <HomeOutlined />
  </Space>
);

Source: components/icon/demo/custom.tsx in the ant-design/ant-design repository.

Method 2: Loading Custom Icons from Iconfont

For projects with extensive custom icon libraries or when working with design teams using Alibaba's Iconfont service, the createFromIconfontCN helper provides a script-based loading mechanism. This method generates a React component that fetches icons from an external URL.

Generating the Iconfont Component

Import createFromIconfontCN from @ant-design/icons and invoke it with a configuration object containing the scriptUrl property. This URL should point to a JavaScript file generated by Iconfont or a similar service that defines the icon symbols.

import React from 'react';
import { createFromIconfontCN } from '@ant-design/icons';
import { Space } from 'antd';

const IconFont = createFromIconfontCN({
  scriptUrl: '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js',
});

Using the Custom Font Icons

The generated component accepts a type prop that corresponds to the icon names defined in the script. You can apply standard styling props including style for color and size adjustments.

const App: React.FC = () => (
  <Space>
    <IconFont type="icon-tuichu" />
    <IconFont type="icon-facebook" style={{ color: '#1877F2', fontSize: '18px' }} />
    <IconFont type="icon-twitter" />
  </Space>
);

Source: components/icon/demo/iconfont.tsx in the ant-design/ant-design repository.

Comparing Custom Icon Integration Approaches

When deciding how to integrate custom icons into your Ant Design project, consider the following factors:

• SVG-based integration – Best for one-off custom icons, logos, or when you need precise vector control. Icons render immediately without external network requests and support complex SVG features like gradients. However, each icon increases your bundle size.
• Iconfont-based integration – Ideal for large icon libraries managed by design teams or when using Alibaba's Iconfont service. This approach loads icons on-demand via a script tag, keeping your JavaScript bundle smaller. However, it requires an external network request and offers less flexibility for individual icon styling.

Both methods support Ant Design's Space component for layout and accept style and className props for customization.

Summary

Integrating custom icons into an Ant Design project requires using the @ant-design/icons package, which provides two distinct APIs for extending the default icon set:

• Use the Icon component with a custom SVG React component via the component prop for vector-based icons that inherit theme colors and sizes.
• Use createFromIconfontCN with a scriptUrl pointing to an Iconfont JavaScript file for loading entire icon libraries from external sources.

Both approaches maintain compatibility with Ant Design's theming system and layout components, ensuring your custom icons behave identically to built-in icons.

Frequently Asked Questions

How do I change the color of a custom SVG icon in Ant Design?

Set the fill attribute in your SVG to currentColor and pass a color via the style prop when rendering the Icon component. For example: <Icon component={HeartSvg} style={{ color: 'hotpink' }} />. The icon inherits the color from the CSS color property, allowing dynamic theming.

Can I use custom icons with Ant Design's Button component?

Yes. Pass your custom icon component to the icon prop of the Button component. Ant Design internally uses IconWrapper (located at components/button/IconWrapper.tsx) to handle icon rendering consistently across button states and sizes. Both SVG-based and Iconfont-based custom icons work seamlessly with buttons.

What is the performance difference between SVG and Iconfont custom icons?

SVG-based icons increase your JavaScript bundle size because the SVG markup compiles into your application code, but they render immediately without network requests. Iconfont-based icons require an external HTTP request to fetch the JavaScript file, which adds latency but keeps your bundle smaller when using large icon libraries. For applications requiring offline capability or strict Content Security Policies, SVG integration is preferable.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}