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

> Learn to integrate custom icons into your Ant Design project using SVG components or Iconfont scripts. Master icon customization for a unique UI.

- Repository: [Ant Design Team/ant-design](https://github.com/ant-design/ant-design)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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.

```tsx
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`.

```tsx
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`](https://github.com/ant-design/ant-design/blob/main/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.

```tsx
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.

```tsx
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`](https://github.com/ant-design/ant-design/blob/main/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`](https://github.com/ant-design/ant-design/blob/main/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.