Good use of icons on a website can really lift its overall design. Of course, you can’t just slap them on and expect a site to look brilliant. It’s all about choosing the right type of icons to match the design.
Once your designer has chosen a font library like Font Awesome, or made their own, what is the best way of displaying them in Drupal? The quick and simple way is to get the designer to style them using CSS but this is not flexible.
What if an editor wants to choose which icon is displayed in a menu? If you’ve added them to the menu manually via CSS then the editor won’t have the ability to change the icon in the future.
The Icon API module integrates common icon bundles like Font Awesome, Bootstrap and more within Drupal. The module offers integration with a suite of sub-modules. For example, if you want to add icons to menus then install the icon_menu module.
In this tutorial, we’ll configure Icon API to allow an editor to add icons to menus and directly into content. We’ll do this using the Font Awesome icon bundle.
Getting Started
Icon API doesn’t ship actual icons, as the name suggests, it just an API.
To display icons we’ll need to install an icon bundle so before we jump in, let’s install the Font Awesome module.
Installing Font Awesome
Go download Font Awesome and Libraries API and install both modules.
Drush command:
drush dl fontawesome libraries drush en fontawesome
Download Library
The module attempts to download the Font Awesome library when you enable it. However, this didn’t work for me so I had to manually download the library and add it to the libraries directory. The module has a Drush command to download Font Awesome, unfortunately this didn’t work.
Download v4.2.0 and extract the zip into your libraries directory. Make sure the path to the CSS directory is /sites/all/libraries/fontawesome/css.
Installing Icon API
Now that we have Font Awesome installed, go download Icon API, then enable “Icon API: Menu” and “Icon API: Filter” sub-module.
Drush command:
drush dl icon drush en icon_menu icon_filter
To test and make sure the module has been setup. Login as the administrator and go to Configuration and click on the Icons link in the Media section.
From this page you can see all the available icon bundles and you can enable or disable them. Here we have two bundles available: “Font Awesome” and “Lullacons: Pack 1”.
Lullacons is a free icon pack from Lullabot which comes with Icon API. But most importantly you can see “Font Awesome” which means it’s been setup properly. If you click on “View Icons” you should see all the icons.
Menu Icons
Now that we’ve got Icon API and “Font Awesome” setup, let’s display some actual icons in Drupal. The most common place for icons is in a menu so let’s add some to the main menu.
1. Go to Structure, Menus and click on “list links” in the “Main menu” row.
2. Edit the Home menu item and scroll to the bottom. You should see an Icon field-set.
From here you select and configure the icon.
3. Seeing that we’re editing the Home link, let’s add a home icon. Search for home in the drop-down.
When you select an icon, extra options will appear below. All of them are self-explanatory, leave them in their default state and click on Save.
If you go to the homepage you should see a home icon next to the Home link.
Inline Icons
In the last section we added icons to the main menu. Let’s now learn how to add them directly into content.
For this you’ll need the “Icon API: Filter” sub-module, make sure it’s enabled.
The sub-module renders icons via a filter on a text format. All you need to do is setup the “Convert [icon:%bundle:%icon] tags” filter and add an icon tag like [icon:%bundle:%icon], the filter will then render the icon. Let’s now configure the filter.
1. Go to Configuration, “Text formats” and click on configure the “Filtered HTML” row.
2. Check the “Convert [icon:%bundle:%icon] tags” filter.
3. Icons are rendered using an <i> tag and because we’re using the “Limit allowed HTML tags” filter, these tags will get filtered out. To workaround this issue, you have two options: reorder the filters or add <i> into the “Allowed HTML tags” text field.
The easiest thing to do is just move “Convert [icon:%bundle:%icon] tags” so it’s after “Limit allowed HTML tags”.
Once configured click on “Save configuration”.
4. Go create a test article and add [icon:fontawesome:home] as the icon. If everything has been configured correctly you should see an icon.
Summary
The thing that I like about this module is that it’s editor friendly, with little training an editor can manage icons throughout a Drupal site themselves. This not only makes them happy but saves you, as a site builder, time because you won’t have to push out a code release just to change a basic icon in the menu.
FAQs
Q: Why does the “Font Awesome” module use 4.2, it’s old?
You can use the latest version, however, the new icon won’t appear in the drop-down. Here’s an issue about the problem.
Q: I’m trying to add inline icons using the [icon:fontawesome:home] token but it’s not working
Review step 3 again and make sure the “Limit allowed HTML tags” filter allows <i> tags.
I really like the articles you write. They are very understandable and I never had problems tu use the modules you explained. Today I tried the Icon APi with fontawesome. I did everything like you explained, but the icons are not shown in media > icons. I do see the Lullacons but not the FontAwesome icons.
Any idea what I am doing wrong?
Did you get any PHP errors when installing the FontAwesome library?
I would check the following:
– Was the FontAwesome library downloaded into the libraries directory? I had to manually download the 4.2 version.
– Make sure you have libraries API module installed.
I downloaded the FontAwesome library to my pc and transferred it to the webserver with filezilla. I got an error when I went to Modules in order to activate Icon ApI, but I tried again the error disappeared. The Livraries API is installed and running. The module works when I use the icons from Lullacons.
When I put an icon [just for testing] in front of a menu-item, the icon and the link don’t show on the same line, it’s broken into 2 lines. I think I’ll start from scratch tomorrow.
Thanks for your time
I uninstalled everything and installed it again and it works! Thanks a lot.
Awesome.
Great write-up. Thank you very much for taking the time and share in this way.
No problems, thanks.
I know this is a long shot but I have just found this post and have tired everything to get the font awsome thing to work. Downlaoded it to the libraries folder and did everything your guide has said and nope the icons will not show up even when I have manually downloaded the icon pack and put it into the libraries folder.
And yes Libraries is enabled and working as it works with another module as well.
Hi Toams,
Sorry to hear you couldn’t get it working. This tutorial is old and could be out-of-date. Best to check out the documentation in the module or ask in the issue queue.
Cheers,
Ivan