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 added 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 interface

You can customize the search interface to suit your needs. Choose between themes and set up suggested icons to show when opening the search interface.

Interface style

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

Suggested icons

Suggested icons will improve your workflow by setting icons that are available by default. Suggested icons can be set in 3 ways:

• Global icons can be chosen in the settings panel and will always be shown in the search interface
• Popular icons can be enabled in the settings panel and will track and show the most popular icons for each user.
• Field icons can be set for each field instance in the suggestions property.

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. It's also possible to set a default icon in the field.

icon:
    label: Icon
    type: icon-picker
    allowEmpty: false
    suggestions:
        - arrow-right
        - chevron-down
        - arrow-up-right-from-square
    default:
        icon: arrow-right
        style: fal

Displaying icons

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: fa-light fa-duotone 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>

The icon column

There is an icon type column available to show the selected icon in your list controllers.

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: fa-light fa-duotone fa-clipboard-list-check
    Settings: fa-light fa-duotone 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'  => 'fa-light fa-duotone 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

Upgrading your kit from version 5 and up will be as easy as changing te version number when using a kit. When self-hosting your files, you should replace the old files with the latest version and

Upgrade guides

The upgrade guides have a detailed guide on how to upgrade your kit or self-hosted set-up. In case your still running version 4, you should check out that guide first.

• Upgrading to version 7
• Upgrading to version 6
• Upgrading from version 4

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. Instead, e-mail us if you're stuck. We strive 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.