Iconify Extension for Quarto

This extension provides support to free and open source icons provided by Iconify.

Icons can be used only in HTML-based documents.

Installation

quarto add mcanouil/quarto-iconify@3.3.0

This will install the extension under the _extensions subdirectory.

If you're using version control, you will want to check in this directory.

Usage

To embed an icon, use the {{< iconify >}} shortcode.

For convenience, a special {{< quarto >}} shortcode is also available to quickly insert the Quarto logo with preset styling.

For example:

{{< iconify copilot-24 >}}
{{< iconify fluent-emoji exploding-head >}}
{{< iconify fluent-emoji:exploding-head >}}
{{< iconify copilot-24 size=2xl >}}
{{< iconify copilot-24 size=5x rotate=180deg >}}
{{< iconify copilot-24 size=Huge >}}
{{< iconify fluent-emoji-high-contrast 1st-place-medal >}}
{{< iconify twemoji 1st-place-medal >}}
{{< iconify line-md loading-alt-loop >}}
{{< iconify fa6-brands apple width=50px height=10px rotate=90deg flip=vertical >}}
{{< iconify simple-icons:quarto style="color:#74aadb;" >}}
{{< quarto >}}

This extension includes support for thousands of icons (including animated icons). You can browse all of the available sets of icons here:

https://icon-sets.iconify.design/

Iconify Attributes

Iconify API provides additional attributes: https://docs.iconify.design/iconify-icon/.

Currently, this extension supports the following attributes:

{{< iconify <set=...> <icon> <size=...> <width=...> <height=...> <flip=...> <rotate=...> <title=...> <label=...> <inline=...> <mode=...> <style=...> >}}
{{< iconify <set:icon> <size=...> <width=...> <height=...> <flip=...> <rotate=...> <title=...> <label=...> <inline=...> <mode=...> <style=...> >}}

Available Attributes

• set: The icon set to use. Default is octicon (source: https://github.com/microsoft/fluentui-emoji).

• size: Sets both width and height. When size is defined, width and height are ignored. See Sizing Icons for available size options.

• width and height: Set icon dimensions whilst keeping aspect ratio. Not used if size is defined.

• flip: Flip the icon horizontally, vertically, or both.

• rotate: Rotate the icon by a specified angle (e.g., 90deg, 180deg).

• title: Tooltip text for the icon. Default: Icon <icon> from <set> Iconify.design set..

• label (i.e., aria-label): Accessibility label for screen readers. Default: Icon <icon> from <set> Iconify.design set..

• inline: Boolean attribute (true or false). When true, the icon is displayed inline with text. Default is true.

• mode: Rendering mode. Can be "svg" (default), "style", "bg", or "mask". See Iconify renderings mode for more details.

• style: CSS style string to apply custom styling to the icon.

• fallback: Text or emoji shown when the icon cannot be loaded (unknown name, offline, or CDN unreachable). See Fallback for details.

Setting Default Values

You can define default values for most attributes in the YAML header using the nested structure under extensions.iconify:

extensions:
  iconify:
    set: "octicon"
    size: "Huge"
    width: "1em"
    height: "1em"
    flip: "horizontal"
    rotate: "90deg"
    inline: true
    mode: "svg"
    style: "color: #b22222;"

Note: The attributes icon, title, and label must be defined in the shortcode itself and cannot have default values in the YAML header.

Deprecation warning: The top-level iconify: configuration is deprecated but still supported for backward compatibility. A warning is emitted at least once per attribute name when the deprecated format is used. Please migrate to the new nested structure shown above.

Input Validation

Since version 3.3.0, the extension validates a few common authoring mistakes and warns at render time:

• Invalid icon or set names (anything outside lowercase letters, digits, and single hyphens) produce a warning. The icon is still emitted so the malformed name is visible in the output.
• Invalid size values (not a known keyword, not a CSS length) produce a warning and the size is dropped, matching the README contract that "When the size is invalid, no size changes are made.".

Fallback

The fallback attribute lets you declare text or an emoji that is shown when the icon fails to load. Loading can fail for three reasons:

• The icon set or icon name does not exist.
• The browser is offline.
• The Iconify CDN is unreachable from the reader's network.

The wrapper renders the <iconify-icon> web component plus a hidden fallback span; a small companion script monitors the icon and reveals the fallback once the component reports a failure.

{{< iconify fluent-emoji exploding-head fallback="🤯" >}}

You can also set a document-wide default fallback under extensions.iconify.fallback.

Offline / Preloaded Icons

For documents that must render offline (or simply do not want to rely on the Iconify CDN for known icons), you can preload one or more Iconify icon-collection JSON files. This requires the iconify filter to be enabled.

filters:
  - iconify
extensions:
  iconify:
    preload:
      - icons/octicon.json
      - icons/fluent-emoji.json

Each file must contain a valid Iconify icon collection (an object beginning with {). The extension injects them as window.IconifyPreload, which the Iconify Web Component consumes at boot instead of calling the CDN.

You can download icon collections from https://github.com/iconify/icon-sets or from the Iconify API (https://api.iconify.design/<prefix>.json?icons=<comma-separated-names>).

Sizing Icons

This extension provides relative, literal, and LaTeX-style sizing for icons.

When the size is invalid, no size changes are made.

• CSS-style sizing: {{< iconify fluent-emoji:exploding-head size=42px >}}.

• Relative sizing: {{< iconify fluent-emoji:exploding-head size=2xl >}}.

  Relative Sizing	Font Size	Equivalent in Pixels
  2xs	0.625em	10px
  xs	0.75em	12px
  sm	0.875em	14px
  lg	1.25em	20px
  xl	1.5em	24px
  2xl	2em	32px

• Literal sizing: {{< iconify fluent-emoji:exploding-head size=5x >}}.

  Literal Sizing	Font Size
  1x	1em
  2x	2em
  3x	3em
  4x	4em
  5x	5em
  6x	6em
  7x	7em
  8x	8em
  9x	9em
  10x	10em

• LaTeX-style sizing: {{< iconify fluent-emoji:exploding-head size=Huge >}}.

  Sizing Command	Font Size (HTML)
  tiny (= \tiny)	0.5em
  scriptsize (= \scriptsize)	0.7em
  footnotesize (= \footnotesize)	0.8em
  small (= \small)	0.9em
  normalsize (= \normalsize)	1em
  large (= \large)	1.25em
  Large (= \Large)	1.5em
  LARGE (= \LARGE)	1.75em
  huge (= \huge)	2em
  Huge (= \Huge)	2.5em

• width or height can be set to define icon's property whilst keeping aspect ratio. Note: width and height are not set if size was defined.

Example

Here is the source code for a minimal example: example.qmd.

Output of example.qmd:

• HTML

---

Iconify by Vjacheslav Trushkin under MIT License.