Icons

Icons (아이콘)

Material UI와 함께 아이콘을 사용하는 방법에 대한 안내입니다. Material 아이콘, SvgIcon, 커스텀 폰트 아이콘 등 세 가지 방식을 다룹니다.

출처: 문서

본문

Material UI에서 아이콘을 사용하는 방법에 대한 안내와 제안입니다.

Material UI는 세 가지 방식으로 아이콘을 지원합니다.

1. React 컴포넌트로 내보낸 Material Icons(SVG 아이콘).
2. 커스텀 SVG 아이콘을 위한 React 래퍼인 SvgIcon 컴포넌트.
3. 커스텀 폰트 아이콘을 위한 React 래퍼인 Icon 컴포넌트.

Material SVG 아이콘

Google은 2,100개가 넘는 공식 Material 아이콘을 만들었으며, 각각 다섯 가지 "테마"(아래 참조)로 제공됩니다. 각 SVG 아이콘에 대해 우리는 @mui/icons-material 패키지에서 해당 React 컴포넌트를 내보냅니다. 이 아이콘들의 전체 목록을 검색할 수 있어요.

설치 (Installation)

다음 명령 중 하나를 실행해 설치하고 package.json 의존성에 저장하세요.

pnpm add @mui/icons-material

yarn add @mui/icons-material

이 컴포넌트들은 Material UI SvgIcon 컴포넌트로 각 아이콘의 SVG 경로를 렌더링하므로, @mui/material에 대한 peer-dependency를 가집니다.

프로젝트에서 아직 Material UI를 사용하지 않는다면, 설치 가이드에 따라 추가할 수 있어요.

사용 (Usage)

다음 두 가지 옵션 중 하나로 아이콘을 import하세요.

• Option 1:

  import AccessAlarmIcon from '@mui/icons-material/AccessAlarm';
  import ThreeDRotation from '@mui/icons-material/ThreeDRotation';
  

• Option 2:

  import { AccessAlarm, ThreeDRotation } from '@mui/icons-material';
  

번들 크기 측면에서 가장 안전한 것은 Option 1이지만, 일부 개발자는 Option 2를 선호합니다. 두 번째 방법을 사용하기 전에 번들 크기 최소화 가이드를 꼭 읽어 보세요.

각 Material 아이콘에는 "테마"도 있습니다: Filled(기본), Outlined, Rounded, Two-tone, Sharp. 기본이 아닌 테마로 아이콘 컴포넌트를 import하려면 아이콘 이름에 테마 이름을 붙이면 됩니다. 예를 들어 @mui/icons-material/Delete 아이콘은 다음과 같습니다.

• Filled 테마(기본)는 @mui/icons-material/Delete로 내보내집니다.
• Outlined 테마는 @mui/icons-material/DeleteOutlined으로 내보내집니다.
• Rounded 테마는 @mui/icons-material/DeleteRounded로 내보내집니다.
• Twotone 테마는 @mui/icons-material/DeleteTwoTone으로 내보내집니다.
• Sharp 테마는 @mui/icons-material/DeleteSharp로 내보내집니다.

:::warning Material Design 가이드라인은 아이콘 이름을 "snake_case" 네이밍(예: delete_forever, add_a_photo)으로 짓는 반면, @mui/icons-material은 해당 아이콘을 "PascalCase" 네이밍(예: DeleteForever, AddAPhoto)으로 내보냅니다. 이 네이밍 규칙에는 세 가지 예외가 있습니다: 3d_rotation은 ThreeDRotation으로, 4k는 FourK로, 360은 ThreeSixty로 내보내집니다. :::

import Box from '@mui/material/Box';
import Grid from '@mui/material/Grid';
import Typography from '@mui/material/Typography';
import DeleteIcon from '@mui/icons-material/Delete';
import DeleteOutlinedIcon from '@mui/icons-material/DeleteOutlined';
import DeleteRoundedIcon from '@mui/icons-material/DeleteRounded';
import DeleteTwoToneIcon from '@mui/icons-material/DeleteTwoTone';
import DeleteSharpIcon from '@mui/icons-material/DeleteSharp';
import DeleteForeverIcon from '@mui/icons-material/DeleteForever';
import DeleteForeverOutlinedIcon from '@mui/icons-material/DeleteForeverOutlined';
import DeleteForeverRoundedIcon from '@mui/icons-material/DeleteForeverRounded';
import DeleteForeverTwoToneIcon from '@mui/icons-material/DeleteForeverTwoTone';
import DeleteForeverSharpIcon from '@mui/icons-material/DeleteForeverSharp';
import ThreeDRotationIcon from '@mui/icons-material/ThreeDRotation';
import FourKIcon from '@mui/icons-material/FourK';
import ThreeSixtyIcon from '@mui/icons-material/ThreeSixty';

export default function SvgMaterialIcons() {
  return (
    <Box sx={{ flexGrow: 1 }}>
      <Grid container sx={{ color: 'text.primary' }}>
        <Grid size={4}>
          <Typography>Filled</Typography>
        </Grid>
        <Grid size={8}>
          <DeleteIcon />
          <DeleteForeverIcon />
        </Grid>
        <Grid size={4}>
          <Typography>Outlined</Typography>
        </Grid>
        <Grid size={8}>
          <DeleteOutlinedIcon />
          <DeleteForeverOutlinedIcon />
        </Grid>
        <Grid size={4}>
          <Typography>Rounded</Typography>
        </Grid>
        <Grid size={8}>
          <DeleteRoundedIcon />
          <DeleteForeverRoundedIcon />
        </Grid>
        <Grid size={4}>
          <Typography>Two Tone</Typography>
        </Grid>
        <Grid size={8}>
          <DeleteTwoToneIcon />
          <DeleteForeverTwoToneIcon />
        </Grid>
        <Grid size={4}>
          <Typography>Sharp</Typography>
        </Grid>
        <Grid size={8}>
          <DeleteSharpIcon />
          <DeleteForeverSharpIcon />
        </Grid>
        <Grid size={4}>
          <Typography>Edge-cases</Typography>
        </Grid>
        <Grid size={8}>
          <ThreeDRotationIcon />
          <FourKIcon />
          <ThreeSixtyIcon />
        </Grid>
      </Grid>
    </Box>
  );
}

SvgIcon

Material Icons에 없는 커스텀 SVG 아이콘이 필요하다면 SvgIcon 래퍼를 사용할 수 있어요. 이 컴포넌트는 네이티브 <svg> 요소를 확장합니다.

• 접근성이 내장되어 있습니다.
• SVG 요소는 24x24px 뷰포트용으로 스케일링되어야 합니다. 그래야 결과 아이콘을 그대로 사용하거나, 아이콘을 사용하는 다른 Material UI 컴포넌트의 자식으로 포함할 수 있어요. 이는 viewBox 속성으로 커스터마이즈할 수 있습니다. 원본 이미지에서 viewBox 값을 상속하려면 inheritViewBox prop을 사용할 수 있어요.
• 기본적으로 컴포넌트는 현재 색상을 상속합니다. 선택적으로 color prop으로 테마 색상 중 하나를 적용할 수 있어요.
• 자식으로 <svg> 요소를 지원하므로 SVG를 SvgIcon 컴포넌트에 직접 복사해 붙여 넣을 수 있습니다.

import SvgIcon from '@mui/material/SvgIcon';

export default function SvgIconChildren() {
  return (
    <SvgIcon>
      {/* credit: cog icon from https://heroicons.com */}
      <svg fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
        <path
          strokeLinecap="round"
          strokeLinejoin="round"
          d="M4.5 12a7.5 7.5 0 0015 0m-15 0a7.5 7.5 0 1115 0m-15 0H3m16.5 0H21m-1.5 0H12m-8.457 3.077l1.41-.513m14.095-5.13l1.41-.513M5.106 17.785l1.15-.964m11.49-9.642l1.149-.964M7.501 19.795l.75-1.3m7.5-12.99l.75-1.3m-6.063 16.658l.26-1.477m2.605-14.772l.26-1.477m0 17.726l-.26-1.477M10.698 4.614l-.26-1.477M16.5 19.794l-.75-1.299M7.5 4.205L12 12m6.894 5.785l-1.149-.964M6.256 7.178l-1.15-.964m15.352 8.864l-1.41-.513M4.954 9.435l-1.41-.514M12.002 12l-3.75 6.495"
        />
      </svg>
    </SvgIcon>
  );
}

색상 (Color)

import Stack from '@mui/material/Stack';
import { pink } from '@mui/material/colors';
import SvgIcon, { SvgIconProps } from '@mui/material/SvgIcon';

function HomeIcon(props: SvgIconProps) {
  return (
    <SvgIcon {...props}>
      <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
    </SvgIcon>
  );
}

export default function SvgIconsColor() {
  return (
    <Stack direction="row" spacing={3}>
      <HomeIcon />
      <HomeIcon color="primary" />
      <HomeIcon color="secondary" />
      <HomeIcon color="success" />
      <HomeIcon color="action" />
      <HomeIcon color="disabled" />
      <HomeIcon sx={{ color: pink[500] }} />
    </Stack>
  );
}

크기 (Size)

import Stack from '@mui/material/Stack';
import SvgIcon, { SvgIconProps } from '@mui/material/SvgIcon';

function HomeIcon(props: SvgIconProps) {
  return (
    <SvgIcon {...props}>
      <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
    </SvgIcon>
  );
}

export default function SvgIconsSize() {
  return (
    <Stack direction="row" spacing={3} sx={{ alignItems: 'flex-end' }}>
      <HomeIcon fontSize="small" />
      <HomeIcon />
      <HomeIcon fontSize="large" />
      <HomeIcon sx={{ fontSize: 40 }} />
    </Stack>
  );
}

Component prop

아이콘이 .svg 형식으로 저장되어 있어도 SvgIcon 래퍼를 사용할 수 있어요. svgr에는 SVG 파일을 import해 React 컴포넌트로 사용할 수 있는 로더가 있습니다. 예를 들어 webpack과 함께 사용한다면:

// webpack.config.js
{
  test: /\.svg$/,
  use: ['@svgr/webpack'],
}

// ---
import StarIcon from './star.svg';

<SvgIcon component={StarIcon} inheritViewBox />

"url-loader"나 "file-loader"와 함께 사용할 수도 있습니다. 이는 Create React App에서 사용하는 방식입니다.

// webpack.config.js
{
  test: /\.svg$/,
  use: ['@svgr/webpack', 'url-loader'],
}

// ---
import { ReactComponent as StarIcon } from './star.svg';

<SvgIcon component={StarIcon} inheritViewBox />

createSvgIcon

createSvgIcon 유틸리티 컴포넌트는 Material Icons를 만드는 데 사용됩니다. SvgIcon 컴포넌트의 자식으로 전달되는 <svg> 요소나 SVG 경로를 감싸는 데 사용할 수 있어요.

const HomeIcon = createSvgIcon(
  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />,
  'Home',
);

// or with custom SVG
const PlusIcon = createSvgIcon(
  <svg
    fill="none"
    viewBox="0 0 24 24"
    strokeWidth={1.5}
    stroke="currentColor"
    className="h-6 w-6"
  >
    <path strokeLinecap="round" strokeLinejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
  </svg>,
  'Plus',
);

import Stack from '@mui/material/Stack';
import { createSvgIcon } from '@mui/material/utils';

const HomeIcon = createSvgIcon(
  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />,
  'Home',
);

const PlusIcon = createSvgIcon(
  // credit: plus icon from https://heroicons.com
  <svg fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
    <path strokeLinecap="round" strokeLinejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
  </svg>,
  'Plus',
);

export default function CreateSvgIcon() {
  return (
    <Stack direction="row" spacing={3}>
      <HomeIcon />
      <HomeIcon color="primary" />
      <PlusIcon />
      <PlusIcon color="secondary" />
    </Stack>
  );
}

다른 라이브러리 (Other libraries)

MDI

materialdesignicons.com은 2,000개 이상의 아이콘을 제공합니다. 원하는 아이콘에 대해 제공되는 SVG path를 복사해 SvgIcon 컴포넌트의 자식으로 사용하거나 createSvgIcon()과 함께 사용하세요.

Note: mdi-material-ui가 이미 각 SVG 아이콘을 SvgIcon 컴포넌트로 감싸 두었으므로, 직접 할 필요가 없어요.

Icon (폰트 아이콘)

Icon 컴포넌트는 리가처(ligature)를 지원하는 어떤 아이콘 폰트에서든 아이콘을 표시합니다. 전제 조건으로, Material Icons 폰트 같은 것을 프로젝트에 포함해야 해요. 아이콘을 사용하려면 아이콘 이름(폰트 리가처)을 Icon 컴포넌트로 감싸면 됩니다. 예를 들어:

import Icon from '@mui/material/Icon';

<Icon>star</Icon>;

기본적으로 Icon은 현재 텍스트 색상을 상속합니다. 선택적으로 테마 색상 속성 중 하나(primary, secondary, action, error, disabled)로 아이콘 색상을 설정할 수 있어요.

Material 폰트 아이콘 (Font Material Icons)

Icon은 기본적으로 Material Icons 폰트(filled 변형)의 올바른 기본 클래스 이름을 설정합니다. 필요한 것은 폰트를 로드하는 것뿐입니다. 예를 들어 Google Web Fonts를 통해:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>

import Stack from '@mui/material/Stack';
import { green } from '@mui/material/colors';
import Icon from '@mui/material/Icon';

export default function Icons() {
  return (
    <Stack direction="row" spacing={3}>
      <Icon>add_circle</Icon>
      <Icon color="primary">add_circle</Icon>
      <Icon sx={{ color: green[500] }}>add_circle</Icon>
      <Icon fontSize="small">add_circle</Icon>
      <Icon sx={{ fontSize: 30 }}>add_circle</Icon>
    </Stack>
  );
}

커스텀 폰트 (Custom font)

다른 폰트의 경우 baseClassName prop으로 기본 클래스 이름을 커스터마이즈할 수 있어요. 예를 들어 Material Design의 two-tone 아이콘을 표시할 수 있습니다.

import Icon from '@mui/material/Icon';

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Material+Icons+Two+Tone"
  // Import the two tones MD variant                           ^^^^^^^^
/>;

import { useTheme } from '@mui/material/styles';
import Icon from '@mui/material/Icon';

const useIsDarkMode = () => {
  const theme = useTheme();
  return theme.palette.mode === 'dark';
};

export default function TwoToneIcons() {
  const isDarkMode = useIsDarkMode();

  return (
    <Icon
      sx={[isDarkMode && { filter: 'invert(1)' }]}
      baseClassName="material-icons-two-tone"
    >
      add_circle
    </Icon>
  );
}

전역 기본 클래스 이름 (Global base class name)

컴포넌트 사용마다 baseClassName prop을 수정하는 것은 반복적입니다. 테마로 기본 prop을 전역적으로 변경할 수 있어요.

const theme = createTheme({
  components: {
    MuiIcon: {
      defaultProps: {
        // Replace the `material-icons` default value.
        baseClassName: 'material-icons-two-tone',
      },
    },
  },
});

그러면 two-tone 폰트를 직접 사용할 수 있습니다.

<Icon>add_circle</Icon>

Font Awesome

Font Awesome은 Icon 컴포넌트로 다음과 같이 사용할 수 있어요.

import * as React from 'react';
import { loadCSS } from 'fg-loadcss';
import Stack from '@mui/material/Stack';
import { green } from '@mui/material/colors';
import Icon from '@mui/material/Icon';

export default function FontAwesomeIcon() {
  React.useEffect(() => {
    const href = 'https://use.fontawesome.com/releases/v5.14.0/css/all.css';
    if (document.querySelector(`link[href="${href}"]`)) {
      return undefined;
    }

    const node = loadCSS(
      href,
      // Inject before JSS
      (document.querySelector('#font-awesome-css') ||
        document.head.firstChild) as HTMLElement,
    );

    return () => {
      node.parentNode!.removeChild(node);
    };
  }, []);

  return (
    <Stack direction="row" spacing={4} sx={{ alignItems: 'flex-end' }}>
      <Icon baseClassName="fas" className="fa-plus-circle" />
      <Icon baseClassName="fas" className="fa-plus-circle" color="primary" />
      <Icon
        baseClassName="fas"
        className="fa-plus-circle"
        sx={{ color: green[500] }}
      />
      <Icon baseClassName="fas" className="fa-plus-circle" fontSize="small" />
      <Icon baseClassName="fas" className="fa-plus-circle" sx={{ fontSize: 30 }} />
    </Stack>
  );
}

Font Awesome 아이콘은 Material 아이콘처럼 설계되지 않았다는 점에 유의하세요(앞의 두 데모를 비교해 보세요). fa 아이콘은 사용 가능한 공간을 모두 쓰도록 잘려 있습니다. 전역 오버라이드로 이를 조정할 수 있어요.

const theme = createTheme({
  components: {
    MuiIcon: {
      styleOverrides: {
        root: {
          // Match 24px = 3 * 2 + 1.125 * 16
          boxSizing: 'content-box',
          padding: 3,
          fontSize: '1.125rem',
        },
      },
    },
  },
});

import * as React from 'react';
import { loadCSS } from 'fg-loadcss';
import { ThemeProvider, createTheme } from '@mui/material/styles';
import Stack from '@mui/material/Stack';
import Icon from '@mui/material/Icon';
import MdPhone from '@mui/icons-material/Phone';
import Chip from '@mui/material/Chip';

const theme = createTheme({
  colorSchemes: { light: true, dark: true },
  components: {
    MuiIcon: {
      styleOverrides: {
        root: {
          // Match 24px = 3 * 2 + 1.125 * 16
          boxSizing: 'content-box',
          padding: 3,
          fontSize: '1.125rem',
        },
      },
    },
  },
});

export default function FontAwesomeIconSize() {
  React.useEffect(() => {
    const href = 'https://use.fontawesome.com/releases/v5.14.0/css/all.css';
    if (document.querySelector(`link[href="${href}"]`)) {
      return undefined;
    }

    const node = loadCSS(
      href,
      // Inject before JSS
      (document.querySelector('#font-awesome-css') ||
        document.head.firstChild) as HTMLElement,
    );

    return () => {
      node.parentNode!.removeChild(node);
    };
  }, []);

  return (
    <Stack direction="row" spacing={2}>
      <ThemeProvider theme={theme}>
        <Chip icon={<MdPhone />} label="Call me" />
        <Chip icon={<Icon className="fas fa-phone-alt" />} label="Call me" />
      </ThemeProvider>
    </Stack>
  );
}

폰트 vs SVG: 어떤 방식을 써야 할까요? (Font vs. SVGs: Which approach to use?)

두 접근 방식 모두 잘 동작하지만, 특히 성능과 렌더링 품질 측면에서 미묘한 차이들이 있습니다. 가능하다면 SVG가 선호됩니다. 코드 분할을 허용하고, 더 많은 아이콘을 지원하며, 더 빠르고 더 좋게 렌더링되기 때문이죠.

자세한 내용은 GitHub가 폰트 아이콘에서 SVG 아이콘으로 마이그레이션한 이유를 살펴보세요.

접근성 (Accessibility)

아이콘은 모든 종류의 의미 있는 정보를 전달할 수 있으므로, 적절한 곳에서 접근 가능하게 만드는 것이 중요합니다. 고려해야 할 두 가지 사용 사례가 있어요.

• 장식용 아이콘(Decorative icons) 은 시각적 또는 브랜드 강화를 위해서만 사용됩니다. 페이지에서 제거해도 사용자는 여전히 페이지를 이해하고 사용할 수 있어야 해요.
• 의미론적 아이콘(Semantic icons) 은 단순한 장식이 아니라 의미를 전달하기 위해 사용하는 아이콘입니다. 옆에 텍스트가 없는 채 인터랙티브 컨트롤—버튼, 폼 요소, 토글 등—로 사용되는 아이콘을 포함합니다.

장식용 아이콘 (Decorative icons)

아이콘이 순전히 장식용이라면 이미 끝났습니다! 아이콘이 제대로 접근 가능(보이지 않게)하도록 aria-hidden=true 속성이 추가됩니다.

의미론적 아이콘 (Semantic icons)

의미론적 SVG 아이콘 (Semantic SVG icons)

의미 있는 값으로 titleAccess prop을 포함해야 합니다. role="img" 속성과 <title> 요소가 추가되어 아이콘이 올바르게 접근 가능하게 됩니다.

포커스 가능한 인터랙티브 요소의 경우, 예를 들어 아이콘 버튼과 함께 사용할 때 aria-label prop을 사용할 수 있어요.

import IconButton from '@mui/material/IconButton';
import SvgIcon from '@mui/material/SvgIcon';

// ...

<IconButton aria-label="delete">
  <SvgIcon>
    <path d="M20 12l-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8 8-8z" />
  </SvgIcon>
</IconButton>;

의미론적 폰트 아이콘 (Semantic font icons)

보조 기술에만 보이는 텍스트 대안을 제공해야 합니다.

import Box from '@mui/material/Box';
import Icon from '@mui/material/Icon';
import { visuallyHidden } from '@mui/utils';

// ...

<Icon>add_circle</Icon>
<Box component="span" sx={visuallyHidden}>Create a user</Box>

참고 (Reference)

• https://www.tpgi.com/using-aria-enhance-svg-accessibility/

Icon API

Demos

이 React 컴포넌트의 사용 예시와 자세한 내용은 컴포넌트 데모 페이지에서 확인할 수 있어요.

• Icons
• Material Icons

Import

import Icon from '@mui/material/Icon';
// or
import { Icon } from '@mui/material';

Props

참고: ref는 루트 요소 (HTMLSpanElement).

그 외에 제공된 props는 루트 요소 (native element).

Theme default props

MuiIcon을 사용하면 테마에서 이 컴포넌트의 기본 props를 바꿀 수 있어요.

CSS

Rule name

Source code

이 페이지에서 원하는 정보를 찾지 못했다면, 더 자세한 내용은 컴포넌트 구현을 살펴보는 것도 좋아요.

• /packages/mui-material/src/Icon/Icon.js

SvgIcon API

Demos

이 React 컴포넌트의 사용 예시와 자세한 내용은 컴포넌트 데모 페이지에서 확인할 수 있어요.

• Icons
• Material Icons

Import

import SvgIcon from '@mui/material/SvgIcon';
// or
import { SvgIcon } from '@mui/material';

Props

참고: ref는 루트 요소 (SVGSVGElement).

그 외에 제공된 props는 루트 요소 (native element).

Theme default props

MuiSvgIcon을 사용하면 테마에서 이 컴포넌트의 기본 props를 바꿀 수 있어요.

CSS

Rule name

Source code

이 페이지에서 원하는 정보를 찾지 못했다면, 더 자세한 내용은 컴포넌트 구현을 살펴보는 것도 좋아요.

• /packages/mui-material/src/SvgIcon/SvgIcon.js

더 알아보기 (Learn more)

• Icons 문서
• Material Icons