[docs] Add a guide on using icon libraries with Joy UI

docs/data/joy/guides/using-icon-libraries/IconFontSizes.js

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { useTheme } from '@mui/joy/styles';
+import Stack from '@mui/joy/Stack';
+import Person from '@mui/icons-material/Person';
+
+export default function JoyMaterialIcon() {
+  const theme = useTheme();
+  return (
+    <Stack
+      spacing={2}
+      direction="row"
+      sx={{ gridColumn: '1 / -1', alignItems: 'center', justifyContent: 'center' }}
+    >
+      {Object.keys(theme.fontSize).map((size) => (
+        <Person key={size} fontSize={size} />
+      ))}
+    </Stack>
+  );
+}

docs/data/joy/guides/using-icon-libraries/IconFontSizes.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { useTheme } from '@mui/joy/styles';
+import Stack from '@mui/joy/Stack';
+import Person from '@mui/icons-material/Person';
+
+export default function JoyMaterialIcon() {
+  const theme = useTheme();
+  return (
+    <Stack
+      spacing={2}
+      direction="row"
+      sx={{ gridColumn: '1 / -1', alignItems: 'center', justifyContent: 'center' }}
+    >
+      {Object.keys(theme.fontSize).map((size) => (
+        <Person key={size} fontSize={size} />
+      ))}
+    </Stack>
+  );
+}

docs/data/joy/guides/using-icon-libraries/IconFontSizes.tsx.preview

@@ -0,0 +1,3 @@
+{Object.keys(theme.fontSize).map((size) => (
+  <Person key={size} fontSize={size} />
+))}

docs/data/joy/guides/using-icon-libraries/JoyMaterialIcon.js

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+import Button from '@mui/joy/Button';
+import Input from '@mui/joy/Input';
+import Typography from '@mui/joy/Typography';
+import Stack from '@mui/joy/Stack';
+import Person from '@mui/icons-material/Person';
+
+export default function JoyMaterialIcon() {
+  return (
+    <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 2 }}>
+      <Stack spacing={2}>
+        {['sm', 'md', 'lg'].map((size) => (
+          <Button key={size} size={size} startDecorator={<Person />}>
+            Button
+          </Button>
+        ))}
+      </Stack>
+      <Stack spacing={2}>
+        {['sm', 'md', 'lg'].map((size) => (
+          <Input
+            key={size}
+            size={size}
+            startDecorator={<Person />}
+            placeholder="Placeholder"
+          />
+        ))}
+      </Stack>
+      <Stack spacing={2}>
+        {['sm', 'md', 'lg', 'xl'].map((size) => (
+          <Typography key={size} fontSize={size} startDecorator={<Person />}>
+            Hello World
+          </Typography>
+        ))}
+      </Stack>
+    </Box>
+  );
+}

docs/data/joy/guides/using-icon-libraries/JoyMaterialIcon.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+import Button from '@mui/joy/Button';
+import Input from '@mui/joy/Input';
+import Typography from '@mui/joy/Typography';
+import Stack from '@mui/joy/Stack';
+import Person from '@mui/icons-material/Person';
+
+export default function JoyMaterialIcon() {
+  return (
+    <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 2 }}>
+      <Stack spacing={2}>
+        {(['sm', 'md', 'lg'] as const).map((size) => (
+          <Button key={size} size={size} startDecorator={<Person />}>
+            Button
+          </Button>
+        ))}
+      </Stack>
+      <Stack spacing={2}>
+        {(['sm', 'md', 'lg'] as const).map((size) => (
+          <Input
+            key={size}
+            size={size}
+            startDecorator={<Person />}
+            placeholder="Placeholder"
+          />
+        ))}
+      </Stack>
+      <Stack spacing={2}>
+        {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+          <Typography key={size} fontSize={size} startDecorator={<Person />}>
+            Hello World
+          </Typography>
+        ))}
+      </Stack>
+    </Box>
+  );
+}

docs/data/joy/guides/using-icon-libraries/using-icon-libraries.md

@@ -0,0 +1,137 @@
+# Using icon libraries
+
+<p class="description">Learn how to use your favorite icon library with Joy UI.</p>
+
+## MUI Material icon
+
+[@mui/icons-material](https://www.npmjs.com/package/@mui/icons-material)
+includes the 2,100+ official [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) converted to [`SvgIcon`](/material-ui/api/svg-icon/) components.
+
+### Installation
+
+This section assumes that you've already installed Joy UI in your app—see [Installation](/joy-ui/getting-started/installation/) for instructions.
+
+:::warning
+To use `@mui/icons-material` with Joy UI, you will have to install Material UI (`@mui/material`) because it is a required dependency. The increase of the production bundle size is very little if you configure [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) in your build process.
+
+We are aware of this limitation and considering removing the dependency. You can keep track of the progress from [this issue](https://github.com/mui/material-ui/issues/34489).
+:::
+
+#### npm
+
+```sh
+npm install @mui/icons-material @mui/material
+```
+
+#### yarn
+
+```sh
+yarn add @mui/icons-material @mui/material
+```
+
+### Usage
+
+By default, Joy UI components are able to control the color, font-size, and margin of the icons when their size, or variant change.
+
+{{"demo": "JoyMaterialIcon.js"}}
+
+### 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"`).
+
+{{"demo": "IconFontSizes.js"}}
+
+## 3rd-party icons
+
+To use icon libraries, web font icons, or plain svg icons with Joy UI, apply the styles with specific CSS variables like the example below.
+
+```jsx
+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 to use a class over a tag if it is 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.
+
+---
+
+Here is a collection of well-known icon libraries that you can use with Joy UI.
+
+### React icons
+
+- [Browse icons](https://react-icons.github.io/react-icons/search)
+- [Installation](https://react-icons.github.io/react-icons)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-react-icons-n6jljq?fontsize=12&hidenavigation=1&module=%2Fdemo.tsx&theme=dark"
+     style="width:100%; height:250px; border:0; border-radius: 4px; overflow:hidden;"
+     title="joy-ui-react-icons"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>
+
+### Ionicons
+
+- [Browse icons](https://ionic.io/ionicons)
+- [Installation](https://ionic.io/ionicons/usage)
+
+<iframe src="https://codesandbox.io/embed/inspiring-visvesvaraya-etcc3x?fontsize=12&hidenavigation=1&module=%2Fdemo.tsx&theme=dark"
+     style="width:100%; height:250px; border:0; border-radius: 4px; overflow:hidden;"
+     title="inspiring-visvesvaraya-etcc3x"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>
+
+### Heroicons
+
+- [Browse icons](hhttps://heroicons.com/)
+- [Installation](https://github.com/tailwindlabs/heroicons#react)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-heroicons-wv2ev1?fontsize=12&hidenavigation=1&module=%2Fdemo.tsx&theme=dark"
+     style="width:100%; height:250px; border:0; border-radius: 4px; overflow:hidden;"
+     title="joy-ui-heroicons"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>
+
+### Bootstrap icons
+
+- [Browse icons](https://icons.getbootstrap.com/)
+- [Installation](https://icons.getbootstrap.com/#install)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-bootstrap-icons-x8g0cm?fontsize=12&hidenavigation=1&module=%2Fdemo.tsx&theme=dark"
+     style="width:100%; height:250px; border:0; border-radius: 4px; overflow:hidden;"
+     title="joy-ui-bootstrap"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>
+
+### Fontawesome
+
+- [Browse icons](https://fontawesome.com/icons)
+- [Installation](https://fontawesome.com/docs/web/use-with/react/)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-fontawesome-kjbnqj?fontsize=12&hidenavigation=1&module=%2Fdemo.tsx&theme=dark"
+     style="width:100%; height:250px; border:0; border-radius: 4px; overflow:hidden;"
+     title="joy-ui-fontawesome"
+     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+   ></iframe>

docs/data/joy/pages.ts

@@ -108,6 +108,10 @@ const pages = [
         pathname: '/joy-ui/guides/using-joy-ui-and-material-ui-together',
         title: 'Joy UI and Material UI together',
       },
+      {
+        pathname: '/joy-ui/guides/using-icon-libraries',
+        title: 'Using icon libraries',
+      },
     ],
   },
 ];

docs/pages/joy-ui/guides/using-icon-libraries.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/joy/guides/using-icon-libraries/using-icon-libraries.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}