Using icon libraries

Learn how to use your favorite icon library with Joy UI.

Material UI Icons

@mui/icons-material includes the 2,100+ official Material Icons converted to SVG Icon components.

Installation

This section assumes that you've already installed Joy UI in your app—see Installation for instructions.

yarn

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

Because @mui/material is a required dependency of @mui/icons-material, you have to add a workaround with yarn resolutions:

<span class="token punctuation">{</span>
  <span class="token property">"dependencies"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"@mui/material"</span><span class="token operator">:</span> <span class="token string">"npm:@mui/joy@latest"</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"resolutions"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"@mui/material"</span><span class="token operator">:</span> <span class="token string">"npm:@mui/joy@latest"</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

After that, run yarn install in your terminal.

We are aware of this limitation and are considering removing the dependency. You can keep track of the progress in this issue.

npm

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

Because @mui/material is a required dependency of @mui/icons-material, you have to update your bundler's config to add an alias.

Here is an example of how you can do it, if you use webpack:

webpack.config.js

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">module.exports = {
</span><span class="token prefix unchanged"> </span><span class="token line">  //...
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  resolve: {
</span><span class="token prefix inserted">+</span><span class="token line">    alias: {
</span><span class="token prefix inserted">+</span><span class="token line">      '@mui/material': '@mui/joy',
</span><span class="token prefix inserted">+</span><span class="token line">    },
</span><span class="token prefix inserted">+</span><span class="token line">  },
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">};</span></span>

If you use TypeScript, you will need to update the TSConfig.

tsconfig.json

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">{
</span><span class="token prefix unchanged"> </span><span class="token line">  "compilerOptions": {
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">    "paths": {
</span><span class="token prefix inserted">+</span><span class="token line">      "@mui/material": ["./node_modules/@mui/joy"]
</span><span class="token prefix inserted">+</span><span class="token line">    }
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">  }
</span><span class="token prefix unchanged"> </span><span class="token line">}</span></span>

Usage

By default, Joy UI components are able to control an icon's color, font size, and margins when its size or variant changes.

Hello World

Size

To control the size of the icon, use fontSize prop. The value can be one of the keys in theme.fontSize (the default value is "xl").

{Object.keys(theme.fontSize).map((size) => (
  <Person key={size} fontSize={size} />
))}

{Object.keys(theme.fontSize).map((size) => (
  <Person key={size} fontSize={size} />
))}

Press Enter to start editing

Third-party icons

To use other icon libraries, web font icons, or plain SVG icons with Joy UI, apply the styles with specific CSS variables as shown in the example below:

<span class="token keyword">import</span> <span class="token punctuation">{</span> CssVarsProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> GlobalStyles <span class="token keyword">from</span> <span class="token string">'@mui/joy/GlobalStyles'</span><span class="token punctuation">;</span>
<span class="token comment">// The `GlobalStyles` component is used to create a global style sheet.</span>
<span class="token comment">// You can replace it with your preferred CSS solution.</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</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">CssVarsProvider</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">GlobalStyles</span></span> <span class="token attr-name">styles</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>
        <span class="token comment">// The {selector} is the CSS selector to target the icon.</span>
        <span class="token comment">// We recommend using a class over a tag if possible.</span>
        <span class="token string-property property">'{selector}'</span><span class="token operator">:</span> <span class="token punctuation">{</span>
          <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">"var(--Icon-color)"</span><span class="token punctuation">,</span>
          <span class="token literal-property property">margin</span><span class="token operator">:</span> <span class="token string">"var(--Icon-margin)"</span><span class="token punctuation">,</span>
          <span class="token literal-property property">fontSize</span><span class="token operator">:</span> <span class="token string">"var(--Icon-fontSize, 20px)"</span><span class="token punctuation">,</span>
          <span class="token literal-property property">width</span><span class="token operator">:</span> <span class="token string">"1em"</span><span class="token punctuation">,</span>
          <span class="token literal-property property">height</span><span class="token operator">:</span> <span class="token string">"1em"</span>
        <span class="token punctuation">}</span>
      <span class="token punctuation">}</span><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">CssVarsProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span>
<span class="token punctuation">}</span>

Joy UI components can control those variables based on their size and variant to make the icons fit perfectly.

Using icon libraries

Material UI Icons

Installation

yarn

npm

Usage

Size

Third-party icons

react-icons

Ionicons

Heroicons

Bootstrap Icons

Font Awesome Icons

Iconify

Lucide