Skip to main content

Icons: Iconify

Quick reference

  • To insert an icon, use the IIcon MDX component with the icon's full name (set:name): <IIcon icon="mdi:github" />.
  • Find an icon name on the Iconify Icon Explorer — it covers 200,000+ icons across dozens of free sets (Material Design Icons, Simple Icons for brand logos, etc.), unlike Font Awesome's free tier.
  • IIcon is registered globally in MDXComponents.js, so no import is needed in any .md/.mdx file — it just works.
  • Pass height="1em" to size an icon to match the surrounding text instead of a fixed pixel size.
  • Homepage tagline icons: edit taglineItems in docusaurus.config.js ({ icon, text } per line). Most lines now use custom SVGs from static/img/home-page/; an icon that doesn't start with / is treated as an Iconify id. See Hero tagline.
  • To style one tagline icon differently, add iconClass: 'myClassName' to its item and define .myClassName in index.module.css. It's applied on top of .taglineIcon, and the name must match exactly.

Setup followed the Docusaurus Community guide to Iconify. It was added alongside Font Awesome to pull in icon sets Font Awesome's free tier doesn't cover — brand logos in particular, like cib:zendesk from Simple Icons.

Packages​

Iconify's React bindings are installed as a single dependency — unlike Font Awesome, there's no separate package per icon set, since Iconify fetches icon data on demand:

package.json
"@iconify/react": "^6.0.2",

Wiring it up​

In MDXComponents.js:

src/theme/MDXComponents.js
import { Icon } from '@iconify/react';

export default {
  ...MDXComponents,
  IIcon: Icon,
};

Aliasing Icon to IIcon (to avoid colliding with other Icon components/imports) and adding it to the exported component map makes <IIcon icon="..." /> available in every .md/.mdx file site-wide — the same mechanism used for FAIcon, Gallery, and Panel.

Using it in MDX​

Click the GitHub icon (<IIcon icon="mdi:github" height="1em" />) at top right.

The icon prop is the set-prefixed name shown on each icon's page in the Icon Explorer — e.g. mdi:github, cib:zendesk, logos:slack-icon. No per-set import or registration step is needed; Iconify resolves and loads icon data for whatever name is passed.

Sizing to match text​

Unlike Font Awesome icons (which inherit the surrounding font size by default), Iconify's Icon renders at a fixed pixel size unless told otherwise. Pass height="1em" so the icon scales with whatever text it sits next to:

<IIcon icon="cib:zendesk" height="1em" />

For an icon placed inline with text (rather than standalone), a small vertical nudge usually reads better too:

<Icon icon="cib:zendesk" height="1em" style={{ verticalAlign: '-0.15em' }} />

Using it outside MDX (plain JS/JSX)​

The homepage tagline lines are defined in docusaurus.config.js as customFields.taglineItems, an array of { icon, text } objects. index.js maps them to a styled <ul>, rendering each icon as an <img> if it's a path starting with /, or as an Iconify <Icon/> otherwise (styles in index.module.css; see Hero tagline). The top-level tagline field is a plain-text join of the same items, because it feeds page <meta> tags and can't contain markup. If you need icons driven from config elsewhere, store structured data like this and render it in JSX rather than embedding markup in a string or reaching for dangerouslySetInnerHTML, which can only inject raw HTML and can't execute a React component like Icon.

Styling a single tagline icon​

Every tagline icon gets the .taglineIcon class. To give one icon its own style, add an optional iconClass to its item (no current item uses this; the example is illustrative):

docusaurus.config.js
{ icon: 'cib:zendesk', text: 'Zendesk master', iconClass: 'taglineIconZendesk' },

Then define a class with that exact name in the CSS module:

src/pages/index.module.css
.taglineIconZendesk {
  color: #03363d;
}

index.js looks the name up in the CSS module (styles[iconClass]) and applies it alongside .taglineIcon, so the extra class only needs the properties that differ. CSS module class names are hashed at build time, which is why the config stores the module key rather than a literal class name. A misspelled name doesn't break anything; the extra style just doesn't apply.

Finding an icon​

Browse the Iconify Icon Explorer, search by keyword, and copy the set:name string shown for whichever icon you pick. Useful sets for this site: Material Design Icons (mdi:*) for general UI icons, Simple Icons (cib:* / simple-icons:*) for brand/product logos.