Introducing Font Awesome 5 and SVG icons

(Penar Musaraj) #1

We will shortly merge into master a branch that upgrades Discourse to Font Awesome 5.4.1 (the free version) and switches to using SVG icons instead of an icon font. This is a substantial change, with lots of benefits, and one significant change for developers.

Here is a quick rundown of the changes:

  • using SVG icons will provide crisper icons, better for accessibility and easier to customize, see this Github article for more details
  • since the Font Awesome icon set has grown to 1300+ icons in version 5, we have built an internal API that delivers to clients a subset of all FA icons, that is, only those icons used by that Discourse instance
  • the subset thankfully has a smaller size footprint: it’s already running here in Meta, and it is only 27.5 kb vs the 75.7 kb of the FA 4.7 icon font
  • plugins and themes (including theme components) can add additional FA icons to the set
  • group flair and badge icons will automatically be included in the set, and site administrators can also use a new site setting called svg icon subset to register their chosen icons and add them to their site’s subset
  • breaking change: plugin and theme developers can no longer use <i class="fa fa-icon"></i> to reference icons, these elements should now be replaced by using Discourse functions that inject SVGs in the page

Below, you can find instructions on how to update plugins and themes to use icons from the new set.

What’s new in Font Awesome 5

Font Awesome 5 has introduced many new icons but also some naming changes. For a full discussion of the changes please see the Font Awesome upgrade documentation. The main change is that icons in FA come in separate styles now. There are three styles:

  1. solid (default) – fas
  2. regular – far
  3. brands – fab

For the regular or brands styles, FA 5 introduces new class prefixes, “far” and “fab” respectively. To use an icon from the regular or brands styles, then, we need to use this new naming convention: "far fa-address-book" or "fab fa-facebook". (Solid icons can simply be referenced as before “fa-icon-name”).

To allow bundling the three styles into one SVG sprite, icons in the regular and brand styles in Discourse are converted to far-icon-name and fab-icon-name internally. Plugins, themes, group flair and badges can use the standard FontAwesome 5 naming convention. Site admins adding icons to the set via the svg icon subset site setting must use the internal naming convention.

Developers: how to use or add an SVG icon to your plugin or theme

  1. Adding new icons


    register the icon in your plugin’s plugin.rb file:

    register_svg_icon "user-times" if respond_to?(:register_svg_icon)

    (Note: you need to restart your Rails server in your development environment for this change to take effect.)

    themes or components:

    add a setting with a name ending in _icon and Discourse will automatically add that icon to the subset (provided it’s a valid FA5 icon, of course)

  2. Using icons in your javascript


    import { iconNode } from "discourse-common/lib/icon-library";
    let icon = iconNode('user-times');

    or use the iconHTML helper

    import { iconHTML } from "discourse-common/lib/icon-library";
    let icon = iconHTML('user-times');

    themes or components:

    const { iconNode } = require("discourse-common/lib/icon-library");
    let icon = iconNode('user-times');

    or use the iconHTML helper

    const { iconHTML } = require("discourse-common/lib/icon-library");
    let icon = iconHTML('user-times');

    the helpers can also take a second parameter with properties like title or class. This works in plugins and themes / components in the same way, for example

    iconHTML('user-times', { class: "reply-to-glyph" })
  3. Using icons in your handlebars templates
    In Handlebars templates, you can use d-icon, like this:

    {{d-icon 'user-times'}}

    this also works in the same way for plugins and themes / components

Avoiding broken plugins and themes

Plugins and themes that use <i> icons or SCSS variables from Font Awesome 4.7 will need to be updated. We have already started updating the official plugins, and I will proactively create PRs for some of the most common plugins in our ecosystem affected by this change. By doing this, we hope that most plugins in our ecosystem will be ready by the time this update is merged into master.

Supported formats / sizes for Group Flair URL?