아이콘

아이콘 (Icon)

시맨틱하고 일관된 SVG 아이콘 세트를 제공하는 컴포넌트예요. 버튼, 메뉴, 피드백 요소 등에 아이콘을 넣어 의미를 전달할 수 있어요.

출처: 문서

본문

사용 방법 (How to use)

아이콘을 사용하기 전에 먼저 @ant-design/icons 패키지를 설치해야 해요.

# npm
npm install @ant-design/[email protected] --save
# yarn
yarn add @ant-design/[email protected]
# pnpm
pnpm install @ant-design/[email protected] --save
# bun
bun add @ant-design/[email protected]

:::info{title=Tips} @ant-design/[email protected]는 [email protected]와 함께 사용해야 해요. 자세한 내용은 #53275를 참고해요. :::

아이콘 목록 (List of icons)

아이콘 목록은 공식 문서의 검색 기능을 통해 찾아볼 수 있어요. (IconSearch)

예시 (Examples)

기본 (Basic)

@ant-design/icons에서 아이콘을 가져와요. 테마가 다른 아이콘의 컴포넌트 이름은 아이콘 이름 뒤에 테마 이름이 붙어요. spin 속성을 지정하면 회전하는 애니메이션을 보여 줘요.

import React from 'react';
import {
  HomeOutlined,
  LoadingOutlined,
  SettingFilled,
  SmileOutlined,
  SyncOutlined,
} from '@ant-design/icons';
import { Space } from 'antd';

const App: React.FC = () => (
  <Space>
    <HomeOutlined />
    <SettingFilled />
    <SmileOutlined />
    <SyncOutlined spin />
    <SmileOutlined rotate={180} />
    <LoadingOutlined />
  </Space>
);

export default App;

투톤 아이콘과 컬러 아이콘 (Two-tone icon and colorful icon)

twoToneColor 속성을 특정 기본 색으로 지정하면 투톤 아이콘의 색을 바꿀 수 있어요.

import React from 'react';
import { CheckCircleTwoTone, HeartTwoTone, SmileTwoTone } from '@ant-design/icons';
import { Space } from 'antd';

const App: React.FC = () => (
  <Space>
    <SmileTwoTone />
    <HeartTwoTone twoToneColor="#eb2f96" />
    <CheckCircleTwoTone twoToneColor="#52c41a" />
  </Space>
);

export default App;

커스텀 아이콘 (Custom Icon)

<Icon component={...} />을 사용해 재사용 가능한 React 컴포넌트를 만들어요. component 속성은 svg 요소로 렌더링되는 React 컴포넌트를 받아요.

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 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.8-52.5-42.4-84-55.5-32.5-13.5-66.9-20.3-102.4-20.3-49.3 0-97.4 13.5-139.2 39-10 6.1-19.5 12.8-28.5 20.1-9-7.3-18.5-14-28.5-20.1-41.8-25.5-89.9-39-139.2-39-35.5 0-69.9 6.8-102.4 20.3-31.4 13-59.7 31.7-84 55.5-24.4 23.9-43.5 51.7-56.9 82.8-13.9 32.3-21 66.6-21 101.9 0 33.3 6.8 68 20.3 103.3 11.3 29.5 27.5 60.1 48.2 91 32.8 48.9 77.9 99.9 133.9 151.6 92.8 85.7 184.7 144.9 188.6 147.3l23.7 15.2c10.5 6.7 24 6.7 34.5 0l23.7-15.2c3.9-2.5 95.7-61.6 188.6-147.3 56-51.7 101.1-102.7 133.9-151.6 20.7-30.9 37-61.5 48.2-91 13.5-35.3 20.3-70 20.3-103.3 0.1-35.3-7-69.6-20.9-101.9z" />
  </svg>
);

const PandaSvg: React.FC = () => (
  <svg viewBox="0 0 1024 1024" width="1em" height="1em" fill="currentColor">
    <title>Panda icon</title>
    <path
      d="M99.096 315.634s-82.58-64.032-82.58-132.13c0-66.064 33.032-165.162 148.646-148.646 83.37 11.91 99.096 165.162 99.096 165.162l-165.162 115.614zM924.906 315.634s82.58-64.032 82.58-132.13c0-66.064-33.032-165.162-148.646-148.646-83.37 11.91-99.096 165.162-99.096 165.162l165.162 115.614z"
      fill="#6B676E"
    />
    <path
      d="M1024 561.548c0 264.526-229.23 429.42-512.002 429.42S0 826.076 0 561.548 283.96 66.064 512.002 66.064 1024 297.022 1024 561.548z"
      fill="#FFEBD2"
    />
    <path
      d="M330.324 842.126c0 82.096 81.34 148.646 181.678 148.646s181.678-66.55 181.678-148.646H330.324z"
      fill="#E9D7C3"
    />
    <path
      d="M644.13 611.098C594.582 528.516 561.55 512 512.002 512c-49.548 0-82.58 16.516-132.13 99.096-42.488 70.814-78.73 211.264-49.548 247.742 66.064 82.58 165.162 33.032 181.678 33.032 16.516 0 115.614 49.548 181.678-33.032 29.18-36.476-7.064-176.93-49.55-247.74z"
      fill="#FFFFFF"
    />
    <path
      d="M611.098 495.484c0-45.608 36.974-82.58 82.58-82.58 49.548 0 198.194 99.098 198.194 165.162s-79.934 144.904-148.646 99.096c-49.548-33.032-132.128-148.646-132.128-181.678zM412.904 495.484c0-45.608-36.974-82.58-82.58-82.58-49.548 0-198.194 99.098-198.194 165.162s79.934 144.904 148.646 99.096c49.548-33.032 132.128-148.646 132.128-181.678z"
      fill="#6B676E"
    />
    <path
      d="M512.002 726.622c-30.06 0-115.614 5.668-115.614 33.032 0 49.638 105.484 85.24 115.614 82.58 10.128 2.66 115.614-32.944 115.614-82.58-0.002-27.366-85.556-33.032-115.614-33.032z"
      fill="#464655"
    />
    <path
      d="M330.324 495.484m-33.032 0a33.032 33.032 0 1 0 66.064 0 33.032 33.032 0 1 0-66.064 0Z"
      fill="#464655"
    />
    <path
      d="M693.678 495.484m-33.032 0a33.032 33.032 0 1 0 66.064 0 33.032 33.032 0 1 0-66.064 0Z"
      fill="#464655"
    />
  </svg>
);

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

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

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

export default App;

iconfont.cn 사용하기 (Use iconfont.cn)

iconfont.cn을 사용한다면 프로젝트에서 아이콘을 우아하게 사용할 수 있어요.

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',
});

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

export default App;

iconfont.cn의 여러 리소스 (Multiple resources from iconfont.cn)

@ant-design/[email protected]부터 scriptUrl을 배열로 사용할 수 있어요. 여러 iconfont.cn 리소스의 아이콘을 하나의 <Icon />에서 관리할 수 있어요. 리소스에 중복된 이름의 아이콘이 있으면 배열 순서에 따라 덮어써져요.

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

const IconFont = createFromIconfontCN({
  scriptUrl: [
    '//at.alicdn.com/t/font_1788044_0dwu4guekcwr.js', // icon-javascript, icon-java, icon-shoppingcart (overridden)
    '//at.alicdn.com/t/font_1788592_a5xf2bdic3u.js', // icon-shoppingcart, icon-python
  ],
});

const App: React.FC = () => (
  <Space>
    <IconFont type="icon-javascript" />
    <IconFont type="icon-java" />
    <IconFont type="icon-shoppingcart" />
    <IconFont type="icon-python" />
  </Space>
);

export default App;

API

공통 아이콘 (Common Icon)

속성 (Property) 설명 (Description) 타입 (Type) 기본값 (Default) 버전 (Version) 글로벌 설정
className 아이콘의 className string - ×
rotate n도만큼 회전해요. (IE9에서는 동작하지 않아요.) number - ×
spin 아이콘을 애니메이션으로 회전시켜요. boolean false ×
style 아이콘의 스타일 속성, 예: fontSize, color CSSProperties - ×
twoToneColor 투톤 아이콘에서만 지원해요. 기본 색 또는 기본·보조 색을 지정해요. string | [string, string] - ×

아이콘에는 세 가지 테마가 있으며, 컴포넌트 이름은 아이콘 이름 뒤에 테마 이름이 붙어요.

import { StarOutlined, StarFilled, StarTwoTone } from '@ant-design/icons';

<StarOutlined />
<StarFilled />
<StarTwoTone twoToneColor="#eb2f96" />

커스텀 아이콘 (Custom Icon)

속성 (Property) 설명 (Description) 타입 (Type) 기본값 (Default) 버전 (Version) 글로벌 설정
component 루트 노드에 사용되는 컴포넌트 ComponentType<CustomIconComponentProps> - ×
rotate 회전 각도 (IE9에서는 동작하지 않아요.) number - ×
spin 아이콘을 애니메이션으로 회전시켜요. boolean false ×
style 아이콘의 스타일 속성, 예: fontSize, color CSSProperties - ×

SVG 아이콘에 대해 (About SVG icons)

버전 3.9.0에서 폰트 아이콘을 대체하는 SVG 아이콘을 도입했어요. 여기에는 다음과 같은 장점이 있어요.

  • CDN에 호스팅된 폰트 아이콘 파일에 의존하지 않고 아이콘을 완전히 오프라인으로 사용할 수 있어요. (다운로드 중에 빈 사각형이 보이지 않고, 아이콘 폰트 파일을 로컬에 배포할 필요도 없어요!)
  • 저해상도 화면에서 훨씬 더 정확하게 표시돼요.
  • 아이콘 색을 선택할 수 있어요.
  • 컴포넌트에 더 많은 props를 제공해 스타일을 덮어쓰지 않고도 내장 아이콘을 바꿀 수 있어요.

SVG 아이콘에 대한 더 많은 논의는 #10353에서 확인할 수 있어요.

⚠️ 3.9.0에서 모든 SVG 아이콘을 가져오면서 번들 크기가 커졌어요. 그래서 개발자가 필요할 때 아이콘을 가져올 수 있는 새로운 API를 제공할 예정이며, 업데이트는 #12011에서 추적할 수 있어요.

기다리는 동안 커뮤니티의 webpack plugin을 사용해 아이콘 파일을 분할할 수 있어요.

theme, component, twoToneColor 속성은 3.9.0에서 추가됐어요. 가장 좋은 방법은 모든 <Icon /> 컴포넌트에 theme 속성을 전달하는 거예요.

import { MessageOutlined } from '@ant-design/icons';

<MessageOutlined style={{ fontSize: '16px', color: '#08c' }} />;

모든 아이콘은 <svg>로 렌더링돼요. 아이콘의 크기와 색을 위해 style과 className을 여전히 설정할 수 있어요.

<Icon type="message" style={{ fontSize: '16px', color: '#08c' }} theme="outlined" />

투톤 색 설정 (Set TwoTone Color)

투톤 아이콘을 사용할 때 정적 메서드 getTwoToneColor()와 setTwoToneColor(colorString)로 기본 색을 지정할 수 있어요.

import { getTwoToneColor, setTwoToneColor } from '@ant-design/icons';

setTwoToneColor('#eb2f96');
getTwoToneColor(); // #eb2f96

커스텀 폰트 아이콘 (Custom Font Icon)

개발자가 iconfont.cn에 배포한 자신만의 아이콘을 편리하게 사용할 수 있도록 createFromIconfontCN 함수를 추가했어요.

이 메서드는 iconfont.cn을 위해 특별히 만들어졌어요.

import React from 'react';
import { createFromIconfontCN } from '@ant-design/icons';
import ReactDOM from 'react-dom/client';

const MyIcon = createFromIconfontCN({
  scriptUrl: '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js', // generate in iconfont.cn
});

ReactDOM.createRoot(mountNode).render(<MyIcon type="icon-example" />);

본질적으로 SVG sprite를 사용하는 컴포넌트를 만들어요.

다음 옵션을 사용할 수 있어요.

속성 (Property) 설명 (Description) 타입 (Type) 기본값 (Default) 버전 (Version) 글로벌 설정
extraCommonProps 컴포넌트에 추가 속성을 정의해요. { [key: string]: any } {} ×
scriptUrl iconfont.cn 프로젝트가 생성한 URL예요. @ant-design/[email protected]부터 string[]을 지원해요. string | string[] - ×

scriptUrl 속성은 SVG sprite 심볼을 가져오도록 설정해야 해요.

scriptUrl을 생성하는 방법은 iconfont.cn 문서를 참고해요.

커스텀 SVG 아이콘 (Custom SVG Icon)

webpack과 @svgr/webpack을 사용해 SVG 아이콘을 React 컴포넌트로 가져올 수 있어요. @svgr/webpack의 options 참고.

// webpack.config.js
module.exports = {
  // ... other config
  test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
  use: [
    {
      loader: 'babel-loader',
    },
    {
      loader: '@svgr/webpack',
      options: {
        babel: false,
        icon: true,
      },
    },
  ],
};

vite와 vite-plugin-svgr을 사용해 SVG 아이콘을 React 컴포넌트로 가져올 수도 있어요.

// vite.config.js
export default defineConfig(() => ({
  // ... other config
  plugins: [svgr({ svgrOptions: { icon: true } })],
}));

import React from 'react';
import Icon from '@ant-design/icons';
import MessageSvg from 'path/to/message.svg'; // path to your '*.svg' file.

// import MessageSvg from 'path/to/message.svg?react'; // use vite path to your '*.svg?react' file.
import ReactDOM from 'react-dom/client';

// in create-react-app:
// import { ReactComponent as MessageSvg } from 'path/to/message.svg';

ReactDOM.createRoot(mountNode).render(<Icon component={MessageSvg} />);

컴포넌트에 대해 다음 속성을 사용할 수 있어요.

속성 (Property) 설명 (Description) 타입 (Type) 기본값 (Readonly) 버전 (Version) 글로벌 설정
className svg 요소의 계산된 class name string - ×
fill svg 요소를 그리는 데 사용하는 색을 정의해요. string currentColor ×
height svg 요소의 높이 string | number 1em ×
style svg 요소의 계산된 스타일 CSSProperties - ×
width svg 요소의 너비 string | number 1em ×

디자인 토큰 (Design Token)

Icon의 컴포넌트 토큰 테이블은 공식 문서에서 확인할 수 있어요. (ComponentTokenTable)

FAQ

가끔 아이콘 스타일이 전역 스타일 오류를 일으키는 이유는 무엇인가요? {#faq-icon-bad-style}

관련 이슈: #54391

layer를 활성화하면 아이콘 스타일의 우선순위가 @layer antd보다 낮아져 모든 컴포넌트가 비정상적으로 스타일링될 수 있어요.

이 문제는 다음 두 단계로 해결할 수 있어요.

  1. @ant-design/[email protected]를 [email protected]와 함께 사용해요.
  2. message, Modal, notification의 정적 메서드 사용을 멈추고, hooks 버전이나 App에서 제공하는 인스턴스를 사용해요.

정적 메서드를 꼭 사용해야 한다면, App 바로 아래에 아이콘 컴포넌트를 하나 배치하면 정적 메서드로 인한 스타일 영향을 피할 수 있어요.

<StyleProvider layer>
  <ConfigProvider>
    <App>
+     {/* any icon */}
+     <RightOutlined />
      {/* your pages */}
    </App>
  </ConfigProvider>
</StyleProvider>

더 알아보기 (Learn more)