Icon Fields
Icon fields allow the user to pick icons that fit the control panel’s style from the FontAwesome (opens new window) library. The field’s value can be used to decorate related or nested element chips and cards by enabling Use this field’s values for element thumbnails or Include this field in element cards when adding it to a field layout.
Prior to Craft 5.8.0, only a portion of the FontAwesome library was available. We no longer editorialize, and expose the entire 6.x suite.
# Settings
The icons field has these settings:
- Include Pro Icons — Makes FontAwesome Pro icons available for selection. You may need to purchase a FontAwesome Pro license to use icons in your site’s front-end.
- Advanced
- GraphQL Mode
5.8.0+ — Choose how this field is represented in the GraphQL API. Name only returns only the icon identifier; Full data allows selection of the
name
andstyles
.
- GraphQL Mode
5.8.0+ — Choose how this field is represented in the GraphQL API. Name only returns only the icon identifier; Full data allows selection of the
Icon fields created prior to Craft 5.8.0 retain the Name only mode. New fields default to Full data.
# Development
The saved value is suitable for use in the front-end with your own FontAwesome library.
# Webfonts
Following the official web fonts tutorial (opens new window), you might display an icon like this:
<i class="fa-solid fa-{{ entry.myIconField }}"></i>
Change fa-solid
to another style identifier to suit your site’s appearance!
If you added the FontAwesome files in web/assets/fontawesome/*
, you would link to one or more style sheets like this:
{% css '/assets/fontawesome/fontawesome.css' %}
{% css '/assets/fontawesome/solid.css' %}
You can add css
tags like this anywhere in your code and Craft will hoist them into the <head>
of the document!
# SVG + JS
The same HTML will work with the recommendations in the SVG + JS tutorial (opens new window).
# Styles 5.8.0+
Some icons are present in multiple sets or “styles.” You can check support for a given style using the styles
property of an icon field:
{{ tag('i', {
class: [
'brands' in entry.myIconField.styles ? 'fa-brands' : 'fa-solid',
"fa-#{entry.myIconField.name}",
],
}) }}
# Saving Icon Field Data
The process for submitting icon field data to Craft (via an element or entry form (opens new window)) is the same as any other field that contains text, like a dropdown field:
{# Set up a custom map of icon names and labels: #}
{% set iconMap = {
'github': 'Github',
'stack-overflow': 'StackOverflow',
'gitlab': 'Gitlab',
} %}
<select name="fields[myIconFieldHandle]">
{% for name, label in iconMap %}
{{ tag('option', {
text: label,
value: name,
selected: entry.myIconFieldHandle.name == name,
}) }}
{% endfor %}
</select>
The FontAwesome library does not include user-facing labels for icons. We recommend maintaining your own abbreviated list of icons, or populating a dropdown field with a subset of icon names that you expect users to need.
Note that validation of icon field values is performed against the entire library.
# GraphQL
Depending on the GraphQL Mode setting 5.8.0+, the icon field will contain different sub-selections:
query Contacts {
entries(
section: "contacts"
) {
id
title
... on contact_Entry {
phone
myIconFieldHandle
}
}
}
Name only returns a string; Full data requires a selection of name
and/or styles
fields. The name
sub-selection is equivalent to the value returned by Name only.