Font Awesome Icon Chooser

A Web Component built with Stencil, for use in other projects that want to provide a Font Awesome Icon search and discovery experience.

It's powered by the same Algolia search as the Font Awesome Icon Gallery.

Used, for example, in the Font Awesome official WordPress plugin.

Using this component requires front end development directly in JavaScript and the DOM. It's intended for developers integrating Font Awesome into their apps and components.

Overview

The Icon Chooser can be configured to work with a Font Awesome Kit, using that kit's unique token, or without a kit, given just a Font Awesome version number.

In non-kit mode, only Font Awesome Free is available.

When used with a kit, everything is available, according to that kit's configuration.

• Font Awesome Pro
• Font Awesome 6 Font Awesome 6 is currently in beta, but if the given kit is set to a version like 6.x or 6.0.0-beta1, the Icon Chooser knows what to do.
• Kit Icon Uploads: any icons uploaded to the kit are available in the chooser.

A user configures their own kit on that kit's settings page on fontawesome.com and generates an API Token that authorizes access to their kit's settings via the GraphQL API.

The user provides that kit token and API token to your code. Your code provides the kit token as a prop to fa-icon-chooser. Your code uses the API Token to get an access token from the token endpoint, and then uses that resulting access token to authorize any queries in your handleQuery() callback function.

You provide your own implementations of a few different callback functions for handling queries and the results of the user's interaction with the Icon Chooser.

Example Interaction

1. User takes some action in your app to insert a Font Awesome Icon, like clicking an "insert icon" buton.
2. Your code mounts this Icon Chooser providing the various required props and listens for the finish event to be fired in the DOM.
3. Your code uses the IconChooserResult object delivered by that event to render the results of the user's choice.

For example, an IconChooserResult might be:

{ prefix: "fad", iconName: "alien" }

If your code is a React app using the FontAwesomeIcon component, you might that to build this:

<FontAwesomeIcon icon={[prefix, iconName]} />

If your code is written JavaScript and needs to build an HTML element as a string, it might look like this:

const icon = `<i class="${prefix} ${iconName}"></i>`

If your code is a WordPress plugin or theme, it might produce a shortcode like this:

const icon = `[icon prefix="${prefix}" name="${iconName}"]`

Heads Up! the IconChooserResult type allows for more complex shapes than just a single icon's prefix and iconName. It's designed to be able to express most of the structures necessary for Layering, Masks, and Power Transforms. Those more advanced features are not yet available in the Icon Chooser UI. In the meantime, just be careful about the assumptions you make about the shape of that IconChooserResult object.

Setup

Choose one of the following:

1. Use the fa-icon-chooser web component directly. Find those setup instructions in that component's package.
2. Use a JavaScript framework integration. Currently, the only one available is for React.