Getting Started

After installing the plugin, you can start in a few minutes by following the steps in this quick-guide. After the setup, the Font Awesome script will be loaded automatically in both your front- and backend.

1. You can get your API key from your Account Page or register your account at fontawesome.com/plans.
2. Ensure that you choose Read Kits data and Pro icons and metadata when creating an API key, otherwise the plugin can't function properly.
3. Go to Settings > Font Awesome > Setup.
4. Paste your API key and submit it.
5. Choose the kit that you want to use, we'll retrieve the details after you submit your choice.
6. That's it! You can start using Font Awesome on your website now.

Loading Font Awesome in the frontend

Make sure that you include the {% scripts %} tag in your layouts. The Font Awesome script will be rendered over there.

Customizing the Font Awesome Plugin

Most of your customisations are done in the Kit settings on the Font Awesome website. You can customize some aspects in the plugin settings panel:

Icon styles

Choose what icon styles are available for your users. These will appear in the settings menu, based on the available styles in your kit.

Search appearance

You can choose between an System style, which fits the backend style or the Font Awesome style, which mimics the Font Awesome search page.

Using the form widget inside your forms

The Font Awesome plugin comes with a handy form field to search for icons and include them in your forms. Simply add a new field to your form with the icon-picker type:

icon:
    label: Icon
    type: icon-picker

Saved values include the Font Awesome style and name. The only thing you have to add is a some HTML when rendering the icon:

<i class="{{ icon.class }}"></i>

You can also nest the icons inside other elements, for example in a title:

<h1>
    <i class="{{ icon.class }}"></i>
    Welcome to my website
</h1>

The icon variable consists of 3 properties:

• class the complete classname: fal fa-checkmark
• icon the icon name: checkmark
• style the Font Awesome style: fal

This enables you to customize the icons style easier, for example when you have an active menu item:

<a href="{{ url }}" class="button">
    <i class="{{ isActive ? 'fad' : icon.style }} {{ icon.name }}"></i>
    About us
</a>

Using the icon picker in the Rich Editor

You can add the Font Awesome Icon Picker to the rich editor by adding insertIcon to your toolbar buttons. Navigate to Settings > Editor Settings > Toolbar Buttons and add insertIcon, for example:

bold, italic, underline, |, insertIcon, |, insertSnippet, insertPageLink, insertImage, |, html

Using custom icons in your plugin or code

Using custom icons is simple, but make sure that your Kit has all styles that you want to use available. You can also use styles that aren't selected in the settings panel, as long as they are enabled in your Kit.

You can include the icons everywhere, for example in a button:

<a href="/" class="button">
    <span class="button__label">Check out our offers</span>
    <i class="button__icon fas fa-arrow-right"></i>
</a>

Using icons in the OctoberCMS Backend

You can use Font Awesome icons on places where OctoberCMS and Phosphor icons are available.

When creating forms with tabs:

icons:
    General: fal fa-clipboard-list-check
    Settings: fal fa-gear

fields:
    title:
        label: Title
        tab: General

Or when registering menu items in your plugin:

public function registerNavigation(): array
{
    return [
        'my_plugin' => [
            'label' => 'My Plugin',
            'url'   => Backend::url('vendor/plugin/controller'),
            'icon'  => 'fal fa-vials',
        ],
    ];
}

What if I'm using Font Awesome on my website already?

That shouldn't be a problem, but you should do some clean up:

• Make sure that other references to the Font Awesome CDN or Kits are removed, so you don't load Font Awesome twice.
• If you're still using Version 4, don't forget to enable Older Version Compatibility or update your font awesome icons names.

Upgrading from version 5 to version 6

You'll be set in a few seconds: simply change the Font Awesome version in your kit from version 5 to 6. Everything should work out of the box.

Upgrading from version 4 to version 6

Font Awesome 6 contains new styles and renamed a lot of icons compared to version 4. You can check out the new syntax and all updated icon names in the guide: upgrade from version 4.

Don't want to change all icon names right now? You can simply enable Older Version Compatibility in your Kit settings.

Feature Requests and Support

You can contact us by sending a mail to support@helder.work if you have any questions, feature requests or problems with the plugin.

We want to ask you to not use the feedback system to get support on the plugin. E-mail us if you're stuck. We try to get back to you within 24 hours, but usually it's within a few hours (depending on our opening times).

We're open to new ideas, since this plugin was originally build for internal usage. Chances are that you have a use case that we haven't thought about yet.

Contributing translations

If you're interested in translating the plugin, let us know! You can clone the language file in the plugin and mail it to support@helder.work.