Skip to content

Latest commit

 

History

History
85 lines (59 loc) · 5.03 KB

readme.md

File metadata and controls

85 lines (59 loc) · 5.03 KB
Raw

Built With Stencil

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.

Font Awesome Icon Chooser Screenshot

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

  • 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}"]`

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.

Contributors

The Font Awesome team:

Name GitHub
Mike Wilkerson @mlwilkerson
Frances Botsford @frrrances
Kelsey Jackson @kelseythejackson