QtAwesome: a font file becomes a Qt icon API

One font file instead of a folder full of artwork

QtAwesome exists for a specific annoyance: a Qt desktop application that needs a few dozen recognizable icons and does not want to ship a web stack or hand-place vector files. It is a C library, and the README describes it plainly as a library to add Font Awesome icons to a Qt application. The icons are glyphs in a font file, so there is one asset to distribute rather than one file per icon, and the same drawing scales with whatever widget renders it. The trade is that you are working with a font, not a vector pipeline: shape weight is fixed by the style you choose, and the rendering path is Qt's own text rendering. It suits teams that already ship a Qt Widgets or QML application and want an icon set people recognise. It does not suit a project whose artwork needs per-shape editing.

The qmake include that decides which icon set you get

Adding the library to a project means copying the QtAwesome directory into your project tree and including the qmake .pri file. There is no package manager step in the instructions and no separate library to build. For the free icon set, the project file gets these two lines:

CONFIG+=fontAwesomeFree
include(QtAwesome/QtAwesome.pri)

That selects the free font files, which the project includes, and points qmake at the include file so the sources and headers join the build. The commercial variant swaps the config token:

CONFIG+=fontAwesomePro
include(QtAwesome/QtAwesome.pri)

For Pro and Pro Plus you additionally copy the Pro font files into the QtAwesome/fonts/pro folder yourself, since the repository does not carry them. Defining fontAwesomePro implies the FONT_AWESOME_PRO and FONT_AWESOME_PRO_PLUS definitions. A top-level CMakeLists.txt sits next to the sample applications, so the project is not tied to qmake alone, but the setup steps that are written down are qmake steps, and the second command above is what selects a Pro Plus build.

One QtAwesome object, and the init call you cannot skip

The core of the library is a single object you create once for the whole application, plus one call on it that has to happen before anything is drawn. The README asks for this shape:

fa::QtAwesome* awesome = new fa::QtAwesome(qApp)
awesome->initFontAwesome();     // This line is important as it loads the font and initializes the named icon map

The inline comment is explicit that this line loads the font and fills the named icon map. Everything afterwards is a lookup into that map, so an application that constructs the object but forgets the initialization call has a map with nothing in it. Passing qApp as the parent ties the lifetime to the application, and the instructions then ask you to add an accessor, described as a global function, a member of your application object, or whatever you like, so widgets can reach the same instance and therefore the same loaded font rather than each one loading its own copy.

Name lookups that fall back to solid and never complain

Once the map is populated, icons come out of one method and there are two ways to ask. The typed form passes a style constant and a named glyph, and bringing the fa namespace into scope shortens the call:

using namespace fa;
QPushButton* btn = new QPushButton(awesome->icon(fa_solid, fa_wine_glass), "Cheers!");

The string form takes Font Awesome's own class and name syntax, and it is forgiving. The fa- prefix can be dropped, the style can be dropped, and the style falls back to solid when it is absent:

// The most performant operation the get an icon
QPushButton* btn = new QPushButton(awesome->icon(fa::fa_solid, fa::fa_wine_glass), "Cheers!");

// You can also use 'string' names to access the icons.
QPushButton* btn = new QPushButton(awesome->icon("fa-solid fa-coffee" ), "Black please!");

// The string items passed to the icon method  can be used without the 'fa-' prefix
QPushButton* btn = new QPushButton(awesome->icon("solid coffee" ), "Black please!");

// The style is also optional and will fallback to the 'solid' style
QPushButton* btn = new QPushButton(awesome->icon("coffee" ), "Black please!");

The forgiving parsing is also the sharp edge. A wrong glyph name is not reported at compile time or at startup: the style quietly falls back to solid and an unknown name resolves to nothing visible, so a typo shows up as a missing or wrong symbol in the running interface. The typed constants avoid that class of mistake, and the comment in the source calls the typed form the most performant operation.

Colours that follow the application palette

Icons can be recoloured per call, and defaults can be set for the whole process. Colour travels as a QVariantMap of options:

QVariantMap options;
options.insert("color" , QColor(255, 0 ,0));
QPushButton* musicButton = new QPushButton(awesome->icon(fa::fa_solid, fa::music, options), "Music");

Application-wide defaults are registered on the same object, and they mirror the application palette rather than hard-coded values:

setDefaultOption("color", QApplication::palette().color(QPalette::Normal, QPalette::Text));
setDefaultOption("color-disabled", QApplication::palette().color(QPalette::Disabled, QPalette::Text));
setDefaultOption("color-active", QApplication::palette().color(QPalette::Active, QPalette::Text));
setDefaultOption("color-selected", QApplication::palette().color(QPalette::Active, QPalette::Text));

Disabled, active and selected each get their own entry, which is what lets an icon dim correctly on a disabled button instead of staying full strength. A scale-factor of 0.9 is the other listed default, and the text entries are marked as internal options. Pro adds duotone colour entries with their own palette role, and a single change applies to every icon drawn afterwards:

awesome->setDefaultOption("color-disabled", QColor(0, 255, 0));

The catch is timing: the defaults are read from the palette at the moment they are set, so a palette change made later is not picked up automatically.

The custom painter escape hatch for icons the font does not have

When the symbol you need is not in the font at all, the library offers a painter interface. You subclass QtAwesomeIconPainter, implement paint with the icon rectangle, the mode and the state, and register an instance under a name of your choosing:

awesome->give("duplicate", new DuplicateIconPainter());

After that the registered name behaves like any built-in name:

awesome->icon("duplicate")

The worked example in the README draws two plus marks offset from each other, and its paint signature takes the mode and state, so a custom icon can still respond to disabled and selected rendering rather than looking the same in every condition. This is the mechanism that keeps an application on one icon API even when a few symbols are house artwork. For a QML interface the project points at an embedded QtAwesomeSampleQml project instead, so the binding path is demonstrated rather than described.

One branch per Font Awesome generation, and a licence to read first

The library tracks the upstream icon set rather than versioning on its own schedule, and the repository keeps a branch per major generation: main carries the Font Awesome 7 code, while fontawesome-6, fontawesome-5 and fontawesome-4 hold the older sets, with the former master branch renamed to fontawesome-4. The most recent release is font-awesome-7.0.0 on 2025-08-28, after font-awesome-6.7.2-p1 on 2025-07-15 and font-awesome-6.7.2 on 2025-04-07. The last push to the repository was on 2026-06-03. Upgrading therefore means re-checking the glyph names your interface uses, because each branch holds a different generation of the icon set and a name that exists in one generation is not guaranteed to exist in another. The Pro Plus tier adds extra styles: Chisel, Etch, Jelly, Notdog, Slab, Thumbprint and Whiteboard.

Licensing needs attention before adoption. The licence field on the repository says Other, a custom licence that GitHub cannot classify, and the terms live in the LICENSE.md file at the top level. That matters more here than in most libraries, because the free fonts are bundled while the Pro and Pro Plus font files are not: you obtain those separately and place them in the QtAwesome/fonts/pro folder. What the bundled fonts oblige a commercial Qt product to do is a question for that licence text, not for a review. The instructions also do not describe how to roll back an icon set upgrade, so treat the branch names as the only available fallback.

Editorial conclusion

QtAwesome earns its place in a Qt codebase that already uses Font Awesome elsewhere and wants one icon vocabulary across widgets and QML. It is the wrong choice for a project that needs vector icons with per-shape tweaking, or for one that cannot supply its own Pro font files. Check three things before you commit: the terms in LICENSE.md, whether the glyph names in your interface exist in the Font Awesome generation you plan to build against, and whether your build really is qmake.

Frequently asked questions

Official sources

1. gamecreature/QtAwesome on GitHub
2. Issues
3. README
4. Releases