Skip to content

Icons

Guidance and suggestions for using icons with Material UI.

Material UI provides icon support in three ways:

  1. Standardized Material Icons exported as React components (SVG icons).
  2. With the SvgIcon component, a React wrapper for custom SVG icons.
  3. With the Icon component, a React wrapper for custom font icons.

Material SVG icons

Google has created over 2,100 official Material icons, each in five different "themes" (see below). For each SVG icon, we export the respective React component from the @mui/icons-material package. You can search the full list of these icons.

Installation

To install and save in your package.json dependencies, run the command below using npm:

<span class="token function">npm</span> <span class="token function">install</span> @mui/icons-material

Or yarn:

<span class="token function">yarn</span> <span class="token function">add</span> @mui/icons-material

These components use the Material UI SvgIcon component to render the SVG path for each icon, and so have a peer-dependency on @mui/material.

If you aren't already using Material UI in your project, you can add it following the installation guide.

Usage

Import icons using one of these two options:

  • Option 1:

    <span class="token keyword">import</span> AccessAlarmIcon <span class="token keyword">from</span> <span class="token string">'@mui/icons-material/AccessAlarm'</span><span class="token punctuation">;</span>
    <span class="token keyword">import</span> ThreeDRotation <span class="token keyword">from</span> <span class="token string">'@mui/icons-material/ThreeDRotation'</span><span class="token punctuation">;</span>
    
  • Option 2:

    <span class="token keyword">import</span> <span class="token punctuation">{</span> AccessAlarm<span class="token punctuation">,</span> ThreeDRotation <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/icons-material'</span><span class="token punctuation">;</span>
    

The safest for bundle size is Option 1, but some developers prefer Option 2. Make sure you follow the minimizing bundle size guide before using the second approach.

Each Material icon also has a "theme": Filled (default), Outlined, Rounded, Two-tone, and Sharp. To import the icon component with a theme other than the default, append the theme name to the icon name. For example @mui/icons-material/Delete icon with:

  • Filled theme (default) is exported as @mui/icons-material/Delete,
  • Outlined theme is exported as @mui/icons-material/DeleteOutlined,
  • Rounded theme is exported as @mui/icons-material/DeleteRounded,
  • Twotone theme is exported as @mui/icons-material/DeleteTwoTone,
  • Sharp theme is exported as @mui/icons-material/DeleteSharp.

Filled

Outlined

Rounded

Two Tone

Sharp

Edge-cases

Testing

For testing purposes, each icon exposed from @mui/icons-material has a data-testid attribute with the name of the icon. For instance:

<span class="token keyword">import</span> DeleteIcon <span class="token keyword">from</span> <span class="token string">'@mui/icons-material/Delete'</span><span class="token punctuation">;</span>

has the following attribute once mounted:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>svg</span> <span class="token attr-name">data-testid</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>DeleteIcon<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>svg</span><span class="token punctuation">></span></span>

SvgIcon

If you need a custom SVG icon (not available in the Material Icons) you can use the SvgIcon wrapper. This component extends the native <svg> element:

  • It comes with built-in accessibility.
  • SVG elements should be scaled for a 24x24px viewport so that the resulting icon can be used as is, or included as a child for other Material UI components that use icons. This can be customized with the viewBox attribute. To inherit the viewBox value from the original image, the inheritViewBox prop can be used.
  • By default, the component inherits the current color. Optionally, you can apply one of the theme colors using the color prop.
  • It supports <svg> element as a child so you can copy and paste your SVG directly to SvgIcon component.
Press Enter to start editing

Color

Press Enter to start editing

Size

Press Enter to start editing

Component prop

You can use the SvgIcon wrapper even if your icons are saved in the .svg format. svgr has loaders to import SVG files and use them as React components. For example, with webpack:

<span class="token comment">// webpack.config.js</span>
<span class="token punctuation">{</span>
  <span class="token literal-property property">test</span><span class="token operator">:</span> <span class="token regex"><span class="token regex-delimiter">/</span><span class="token regex-source language-regex">\.svg$</span><span class="token regex-delimiter">/</span></span><span class="token punctuation">,</span>
  <span class="token literal-property property">use</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">'@svgr/webpack'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span>

<span class="token comment">// ---</span>
<span class="token keyword">import</span> StarIcon <span class="token keyword">from</span> <span class="token string">'./star.svg'</span><span class="token punctuation">;</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">SvgIcon</span></span> <span class="token attr-name">component</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>StarIcon<span class="token punctuation">}</span></span> <span class="token attr-name">inheritViewBox</span> <span class="token punctuation">/></span></span>

It's also possible to use it with "url-loader" or "file-loader". This is the approach used by Create React App.

<span class="token comment">// webpack.config.js</span>
<span class="token punctuation">{</span>
  <span class="token literal-property property">test</span><span class="token operator">:</span> <span class="token regex"><span class="token regex-delimiter">/</span><span class="token regex-source language-regex">\.svg$</span><span class="token regex-delimiter">/</span></span><span class="token punctuation">,</span>
  <span class="token literal-property property">use</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">'@svgr/webpack'</span><span class="token punctuation">,</span> <span class="token string">'url-loader'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span>

<span class="token comment">// ---</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> ReactComponent <span class="token keyword">as</span> StarIcon <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'./star.svg'</span><span class="token punctuation">;</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">SvgIcon</span></span> <span class="token attr-name">component</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>StarIcon<span class="token punctuation">}</span></span> <span class="token attr-name">inheritViewBox</span> <span class="token punctuation">/></span></span>

createSvgIcon

The createSvgIcon utility component is used to create the Material Icons. It can be used to wrap an <svg> element or an SVG path which is passed as a child to the SvgIcon component.

<span class="token keyword">const</span> HomeIcon <span class="token operator">=</span> <span class="token function">createSvgIcon</span><span class="token punctuation">(</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>path</span> <span class="token attr-name">d</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span><span class="token punctuation">,</span>
  <span class="token string">'Home'</span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// or with custom SVG</span>
<span class="token keyword">const</span> PlusIcon <span class="token operator">=</span> <span class="token function">createSvgIcon</span><span class="token punctuation">(</span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>svg</span>
    <span class="token attr-name">xmlns</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>http://www.w3.org/2000/svg<span class="token punctuation">"</span></span>
    <span class="token attr-name">fill</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>none<span class="token punctuation">"</span></span>
    <span class="token attr-name">viewBox</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>0 0 24 24<span class="token punctuation">"</span></span>
    <span class="token attr-name">strokeWidth</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token number">1.5</span><span class="token punctuation">}</span></span>
    <span class="token attr-name">stroke</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>currentColor<span class="token punctuation">"</span></span>
    <span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>h-6 w-6<span class="token punctuation">"</span></span>
  <span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>path</span> <span class="token attr-name">strokeLinecap</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>round<span class="token punctuation">"</span></span> <span class="token attr-name">strokeLinejoin</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>round<span class="token punctuation">"</span></span> <span class="token attr-name">d</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>M12 4.5v15m7.5-7.5h-15<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>svg</span><span class="token punctuation">></span></span><span class="token punctuation">,</span>
  <span class="token string">'Plus'</span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>
Press Enter to start editing

Font Awesome

If you find that there are layout issues when using FontAwesomeIcon from @fortawesome/react-fontawesome, you can try passing the Font Awesome SVG data directly to SvgIcon.

Below is a comparison of the FontAwesomeIcon component and a wrapped SvgIcon component.

Press Enter to start editing

FontAwesomeIcon's fullWidth prop can also be used to approximate the correct dimensions, but it isn't perfect.

Other Libraries

MDI

materialdesignicons.com provides over 2,000 icons. For the wanted icon, copy the SVG path they provide, and use it as the child of the SvgIcon component, or with createSvgIcon().

Note: mdi-material-ui has already wrapped each of these SVG icons with the SvgIcon component, so you don't have to do it yourself.

Icon (Font icons)

The Icon component will display an icon from any icon font that supports ligatures. As a prerequisite, you must include one, such as the Material Icons font in your project. To use an icon simply wrap the icon name (font ligature) with the Icon component, for example:

<span class="token keyword">import</span> Icon <span class="token keyword">from</span> <span class="token string">'@mui/material/Icon'</span><span class="token punctuation">;</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span>star<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>

By default, an Icon will inherit the current text color. Optionally, you can set the icon color using one of the theme color properties: primary, secondary, action, error & disabled.

Font Material Icons

Icon will by default set the correct base class name for the Material Icons font (filled variant). All you need to do is load the font, for instance, via Google Web Fonts:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>link</span>
  <span class="token attr-name">rel</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>stylesheet<span class="token punctuation">"</span></span>
  <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://fonts.googleapis.com/icon?family=Material+Icons<span class="token punctuation">"</span></span>
<span class="token punctuation">/></span></span>
Press Enter to start editing

Custom font

For other fonts, you can customize the baseline class name using the baseClassName prop. For instance, you can display two-tone icons with Material Design:

<span class="token keyword">import</span> Icon <span class="token keyword">from</span> <span class="token string">'@mui/material/Icon'</span><span class="token punctuation">;</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>link</span>
  <span class="token attr-name">rel</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>stylesheet<span class="token punctuation">"</span></span>
  <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://fonts.googleapis.com/css?family=Material+Icons+Two+Tone<span class="token punctuation">"</span></span>
  <span class="token comment">// Import the two tones MD variant                           ^^^^^^^^</span>
<span class="token punctuation">/></span></span><span class="token punctuation">;</span>
Press Enter to start editing

Global base class name

Modifying the baseClassName prop for each component usage is repetitive. You can change the default prop globally with the theme

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">MuiIcon</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token comment">// Replace the `material-icons` default value.</span>
        <span class="token literal-property property">baseClassName</span><span class="token operator">:</span> <span class="token string">'material-icons-two-tone'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

Then, you can use the two-tone font directly:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span>add_circle<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span>

Font Awesome

Font Awesome can be used with the Icon component as follows:

Press Enter to start editing

Note that the Font Awesome icons weren't designed like the Material Icons (compare the two previous demos). The fa icons are cropped to use all the space available. You can adjust for this with a global override:

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">MuiIcon</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">styleOverrides</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token comment">// Match 24px = 3 * 2 + 1.125 * 16</span>
          <span class="token literal-property property">boxSizing</span><span class="token operator">:</span> <span class="token string">'content-box'</span><span class="token punctuation">,</span>
          <span class="token literal-property property">padding</span><span class="token operator">:</span> <span class="token number">3</span><span class="token punctuation">,</span>
          <span class="token literal-property property">fontSize</span><span class="token operator">:</span> <span class="token string">'1.125rem'</span><span class="token punctuation">,</span>
        <span class="token punctuation">}</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
Call me
Call me
Press Enter to start editing

Font vs SVG. Which approach to use?

Both approaches work fine, however there are some subtle differences, especially in terms of performance and rendering quality. Whenever possible SVG is preferred as it allows code splitting, supports more icons, and renders faster and better.

For more details, take a look at why GitHub migrated from font icons to SVG icons.

Accessibility

Icons can convey all sorts of meaningful information, so it's important to ensure they are accessible where appropriate. There are two use cases you'll want to consider:

  • Decorative icons that are only being used for visual or branding reinforcement. If they were removed from the page, users would still understand and be able to use your page.
  • Semantic icons are ones that you're using to convey meaning, rather than just pure decoration. This includes icons without text next to them that are used as interactive controls — buttons, form elements, toggles, etc.

Decorative icons

If your icons are purely decorative, you're already done! The aria-hidden=true attribute is added so that your icons are properly accessible (invisible).

Semantic icons

Semantic SVG icons

You should include the titleAccess prop with a meaningful value. The role="img" attribute and the <title> element are added so that your icons are correctly accessible.

In the case of focusable interactive elements, for example when used with an icon button, you can use the aria-label prop:

<span class="token keyword">import</span> IconButton <span class="token keyword">from</span> <span class="token string">'@mui/material/IconButton'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> SvgIcon <span class="token keyword">from</span> <span class="token string">'@mui/material/SvgIcon'</span><span class="token punctuation">;</span>

<span class="token comment">// ...</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">IconButton</span></span> <span class="token attr-name">aria-label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>delete<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">SvgIcon</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>path</span> <span class="token attr-name">d</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>M20 12l-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8 8-8z<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">SvgIcon</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">IconButton</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>

Semantic font icons

You need to provide a text alternative that is only visible to assistive technologies.

<span class="token keyword">import</span> Box <span class="token keyword">from</span> <span class="token string">'@mui/material/Box'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Icon <span class="token keyword">from</span> <span class="token string">'@mui/material/Icon'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> visuallyHidden <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/utils'</span><span class="token punctuation">;</span>

<span class="token comment">// ...</span>

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span>add_circle<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Icon</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Box</span></span> <span class="token attr-name">component</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>span<span class="token punctuation">"</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>visuallyHidden<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>Create a user<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Box</span></span><span class="token punctuation">></span></span>

Reference

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.