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

yarn add @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:

{
  "dependencies": {
    "@mui/material": "npm:@mui/joy@latest"
  },
  "resolutions": {
    "@mui/material": "npm:@mui/joy@latest"
  }
}

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

npm install @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

 module.exports = {
   //...
+  resolve: {
+    alias: {
+      '@mui/material': '@mui/joy',
+    },
+  },
 };

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

tsconfig.json

 {
   "compilerOptions": {
+    "paths": {
+      "@mui/material": ["./node_modules/@mui/joy"]
+    }
   }
 }

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").

<Person fontSize="xs" />
<Person fontSize="sm" />
<Person fontSize="md" />
<Person fontSize="lg" />
<Person fontSize="xl" />
<Person fontSize="xl2" />
<Person fontSize="xl3" />
<Person fontSize="xl4" />

<Person fontSize="xs" />
<Person fontSize="sm" />
<Person fontSize="md" />
<Person fontSize="lg" />
<Person fontSize="xl" />
<Person fontSize="xl2" />
<Person fontSize="xl3" />
<Person fontSize="xl4" />

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:

import { CssVarsProvider } from '@mui/joy/styles';
import GlobalStyles from '@mui/joy/GlobalStyles';
// The `GlobalStyles` component is used to create a global style sheet.
// You can replace it with your preferred CSS solution.

function App() {
  return (
    <CssVarsProvider>
      <GlobalStyles styles={{
        // The {selector} is the CSS selector to target the icon.
        // We recommend using a class over a tag if possible.
        '{selector}': {
          color: "var(--Icon-color)",
          margin: "var(--Icon-margin)",
          fontSize: "var(--Icon-fontSize, 20px)",
          width: "1em",
          height: "1em"
        }
      }}>
    </CssVarsProvider>
  )
}

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