Mike WilkersonWell, hey there, developer. Have you ever built an icon chooser so users can choose Font Awesome icons in your app? It requires knowing all about what icons are available, in which styles, for which versions, and so on. That’s metadata: information about the icons_._
How do you know which icons to offer them? What if they only have Font Awesome 5 Free set up? What if they are using a Font Awesome 6 beta2 Pro Kit that includes their own icon uploads? Building an icon chooser can get complicated, and without accurate and current metadata, users could feel frustrated when they can’t find what they know should be there.
Good news. You don’t have to hack metadata anymore. Just query it.
In this post, we’ll outline the five possible problems you could encounter building an icon chooser, and how the Font Awesome GraphQL API solves those problems, including examples.
Side note: We’re using an icon chooser as an example metadata application because it’s so common. If you really do need to provide an icon chooser, consider snapping in the Font Awesome Icon Chooser web component instead of building your own.
5 Potential Challenges When Building an Icon Chooser
New Icons = New Software Releases
In olden times, circa Font Awesome 4, the set of available icons didn’t change very often, and they were only available in one style. So it wouldn’t have been too much trouble to just include the metadata (the list of all of the icon names and/or CSS classes) in your software, which may have had a static dependency on Font Awesome 4.7.
With Font Awesome 5, new icons started coming out regularly. If your icon chooser is primed with metadata for today’s icons, what happens when we ship a bunch more tomorrow? Your users can’t use the new icons until you release another version of your software with updated metadata. How often do you want to release your software just to stay on top of the new icons that become available?
Pro Licensing Prohibits Redistribution
The Font Awesome Pro Standard license does not permit software vendors to redistribute the icon assets, such as SVGs, CSS, or font files. End users purchase licenses and install Font Awesome (those icon assets), and your software can support them in using it. Don’t you want your users, who are Font Awesome Pro subscribers, to be able to use your icon chooser to access all of their Pro icons — including the new ones we just released five minutes ago?
Icon Style Availability Varies by License
Font Awesome 5 Free includes about 1,600 icons. Most of them are available only in the Solid style, although about 150 are available in the Regular style. About 400 are in the Brands style.
With Font Awesome 5 Pro, there are lots more icons, and all of them are available across multiple styles: Solid, Regular, Light, Duotone.
My goto fave icon (beer, for example) is available on Font Awesome 5 Free Solid, but not Free Regular. It’s available in all styles in Pro, of course.
But the “bell” icon is available in both Solid and Regular styles in Font Awesome 5 Free.
The “apple-core” icon is new to Font Awesome 6.
Do you know what else is new to v6? The entire Thin style.
Ideally, an icon chooser would let the user work with all of the icons available to them. Speaking of which, they might design their own.
Icon Uploads in Font Awesome 6
With Font Awesome 6, users can now upload their own icons to their Font Awesome Kits. So the icons available to any particular user include more than what you could possibly discover in our public Icon Gallery.
Wouldn’t it be great if they were able to include those in their searching and choosing in your icon chooser?
String Matching Icon Search is Limited
Your Font Awesome 5 Pro user knows there’s a “lightsaber” in there somewhere. But if they search for “lightsaber,” will they find the sword-laser icon? Not if your search works only by string matching on icon names!
In short, the Font Awesome GraphQL API solves all of the above-mentioned problems including:
- Icon search that’s smarter and fuzzier.
- Metadata about Pro icons without distributing Pro assets.
- Giving users access to new icons as soon as they’re released.
- Including icon uploads.
- License-specific icon availability.
Examples of the GraphQL API Solution
In the following examples, I’ll just show the GraphQL query itself and the results of running the query. How you get your code to run the query and process the results depends upon the programming language or frameworks you may be using.
If you want to follow along, playing our home game, you could install the GraphiQL client, set the GraphQL Endpoint to https://api.fontawesome.com, and use it to run these sample queries. You can also find examples using curl on the command line in our GraphQL API reference or other examples in our official WordPress plugin developer documentation showing usage in JavaScript.
How to List Available Icons by Version
This query returns all icons available in Font Awesome 5.15.4 with metadata about which ones appear in which styles in Free and Pro:
query {
release(version: "5.15.4") {
icons {
id
unicode
membership {
pro
free
}
}
}
}How to Search to Find Icon Availability
This query would show us the first 15 icon names and unicodes for any icons matching the search, along with information about each icon’s style availability under either free or pro licenses:
query {
search(version: "5.15.3", query: "lightsaber", first: 15) {
id
unicode
membership {
free
pro
}
}
}I won’t show the bulky results here, but give it a try for yourself, and you’ll see that it returns three icons, named “sword-laser,” “sword-laser-alt,” and “swords-laser.” Also, none of them are present in “free,” for any style, but all of them are available under “pro” in styles: “solid,” “regular,” “light,” and “duotone.”
The icon itself is not included in the results — only metadata about the icon. What’s that good for? The metadata is all you need to build an HTML that could be written to a file or added to the DOM, including in your icon chooser UI. As long as the user has Font Awesome loaded, all your code needs is the icons’ metadata to support the user’s use of the icons.
For example, if your icon chooser receives the above search result, it has all the information it needs to build the following HTML content and add it to the DOM for presentation to the user:
<i class="fad fa-sword-laser"></i>(“fad” is the CSS class that serves as the style prefix for the “duotone” style).
Or, if your program uses the JavaScript API to render SVG DOM elements, the metadata above could be used with the Font Awesome JavaScript API to lookup the IconDefinition object using findDefinition():
const swordLaserIcon = findIconDefinition({
iconName: 'sword-laser', prefix: 'fad'
})which could then be used to render the SVG as HTML with icon().html:
icon(swordLaserIcon).html;How to Query Icon Uploads
Let’s say you want to bring the user’s icon uploads into your icon chooser. Icon uploads are specific to a Kit. So let’s say the user has installed and configured the Kit identified by the token abc123.
The GraphQL API documentation shows that accessing a user’s icon uploads requires a kits_read Authorization Scope. To send a request with that level of authorization, the user should provide you with their API Token from their fontawesome.com account:
Side note: If you are actually building a theme or plugin for WordPress, the user may have the Font Awesome WordPress plugin installed and used it to set up and activate a Kit using their API Token.
If so, you could use the plugin’s PHP API to find out which kit token they’re using, and you could issue your GraphQL queries through the Font Awesome WordPress plugin’s REST endpoint. The plugin will automatically handle adding the user’s authorization to your requests. See this example in the plugin’s API docs.
Normally, to authorize query requests, you first make a request to the API’s token endpoint to resolve the user’s API Token into a short-lived access token:
curl -H "Authorization: Bearer DEADBEEF-F00D-4242-1000-4815162342FF" \
-X POST https://api.fontawesome.com/tokenSuppose it gives you back the access_token: 123.abc.456def
Use that to authorize your request:
curl -H "Authorization: Bearer 123.abc.456def" #...Then the query document you put in that request can access the user’s Kits and iconUploads, like this:
query {
me {
kits {
token
iconUploads {
name
unicode
width
height
path
}
}
}
}In the case of icon uploads, you get back not only metadata about the icon; you get everything you need to construct an SVG element for that icon if you like. For example, in the pseudo-code below, just replace ${width}, ${height}, and ${path} with the values returned for those fields for a given icon upload from the query above:
<svg class="svg-inline--fa" viewBox="0 0 ${width} ${height}">
<path d="${path}" />
</svg>Or you could construct an <i> tag, replacing ${name} with the name of an icon upload return from the above query:
<i class="fak fa-${name}"></i>Notice that “fak” class. That’s significant. It represents “Font Awesome Kit,” which will match the CSS rules that cause this icon to be looked up in a user’s Kit instead of in one of the standard Font Awesome styles.
The GraphQL API: The Best Tool for a Growing Metadata-verse
If you want to get your arms around the ever-expanding Font Awesome metadata-verse, the GraphQL API is your best bet. Check out the API docs. Play with some running code that uses the API in the Font Awesome Icon Chooser repo. Or, if you’re into WordPress, go install our WordPress plugin and try its Icon Chooser in context, and have a look at the plugin code in the GitHub repo.
