Skip to content

Font icons

superqt.fonticon creates QIcons from the characters (glyphs) of icon fonts, such as Font Awesome or Material Design Icons. Icon fonts are installed as plugins: superqt doesn't come with any.

Compared with QIconifyIcon, font icons don't need network access, can be animated, and can be the text of a label or button (see the comparison).

Installing a font

These icon fonts are available as plugins, and as extras of superqt:

Font Install Browse the icons
Font Awesome 6 pip install "superqt[font-fa6]" https://fontawesome.com/v6/search
Font Awesome 5 pip install "superqt[font-fa5]" https://fontawesome.com/v5/search
Material Design Icons 7 pip install "superqt[font-mi7]" https://pictogrammers.com/library/mdi/
Material Design Icons 6 pip install "superqt[font-mi6]" https://pictogrammers.com/library/mdi/ (shows version 7: see the changes from version 6)

Other fonts are available as separate packages:

GlyphSearch searches several icon libraries at once. If you'd like to use a font that isn't available as a plugin, please open a feature request.

Basic example

Font icons Font icons
from fonticon_fa5 import FA5S
from qtpy.QtCore import QSize
from qtpy.QtWidgets import QApplication, QPushButton

from superqt.fonticon import icon

app = QApplication([])

button = QPushButton()
button.setIcon(icon(FA5S.smile, color="royalblue"))
button.setIconSize(QSize(96, 96))
button.show()

app.exec()

Glyphs are named by keys in the form "prefix.name", such as "fa5s.smile", or by the constants of the classes that the plugins provide, such as FA5S.smile, which IDEs autocomplete (and check for typos).

Colors and states

icon takes the color, scale, opacity, and transform of the glyph. Without a color, glyphs are black, whatever the widget's palette: for a dark theme, pass a color (for example, one from the palette).

states gives other options (including another glyph) for other states and modes of the icon. Its keys are a state ("on", "off"), a mode ("normal", "active", "selected", "disabled"), or both (as in "on_disabled"). For example, a red heart when a checkable button is checked:

button.setCheckable(True)
button.setIcon(
    icon(
        FA5S.smile,
        color="gray",
        states={"on": {"glyph_key": FA5S.heart, "color": "red"}},
    )
)

In modes other than normal (such as disabled), a glyph without a color for that mode is adjusted by the style, like any other icon (for example, grayed out when disabled).

Animations

The animation argument of icon() takes an Animation, such as spin or pulse, created with the widget that shows the icon:

Font icons Font icons
from fonticon_fa5 import FA5S
from qtpy.QtGui import QPalette
from qtpy.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget

from superqt.fonticon import icon, pulse, spin

app = QApplication([])

window = QWidget()
layout = QHBoxLayout(window)
color = window.palette().color(QPalette.ColorRole.ButtonText).name()  # (dark themes)

spinning = QPushButton("spin")
spinning.setIcon(icon(FA5S.sync, color=color, animation=spin(spinning)))
layout.addWidget(spinning)

pulsing = QPushButton("pulse")
pulsing.setIcon(icon(FA5S.spinner, color=color, animation=pulse(pulsing)))
layout.addWidget(pulsing)

window.show()
app.exec()

Glyphs as text

setTextIcon makes a glyph the text of a widget, such as a label or a button, by setting its text to the glyph and its font to the icon font. The glyph is then drawn as text, in the widget's text color, so it follows the palette and style sheets:

label = QLabel()
setTextIcon(label, FA5S.smile, size=32)
label.setStyleSheet("color: orange")

font returns the QFont of an icon font (by its prefix, such as "fa5s"), for drawing glyphs yourself.

Writing a plugin

Font packages register themselves with the "superqt.fonticon" entry point (superqt.fonticon.ENTRY_POINT), and define their glyphs with an IconFont subclass (whose metaclass, IconFontMeta, turns its attributes into glyph keys). fonticon-cookiecutter is a template for a new one, and the packages above are examples, such as fonticon-fontawesome6. To use a font file without writing a package, see addFont.

API

Icons

icon

icon(
    glyph_key: str,
    scale_factor: float = DEFAULT_SCALING_FACTOR,
    color: ValidColor | None = None,
    opacity: float = 1,
    animation: Animation | None = None,
    transform: QTransform | None = None,
    states: dict[str, IconOptionDict | IconOpts]
    | None = None,
) -> QFontIcon

Create a QIcon for glyph_key, with a number of optional settings.

The glyph_key (e.g. 'fa5s.smile') represents a Font-family & style, and a glyph. In most cases, the key should be provided by a plugin in the environment, like:

...but fonts can also be added manually using addFont.

Parameters:

  • glyph_key (str) –

    String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.

  • scale_factor (float, default: DEFAULT_SCALING_FACTOR ) –

    Scale factor (fraction of widget height), When widget icon is painted on widget, it will use font.setPixelSize(round(wdg.height() * scale_factor)). by default 0.875.

  • color (ValidColor, default: None ) –

    Color for the font, by default None. (e.g. The default QColor) Valid color types include QColor, int, str, Qt.GlobalColor, tuple (of integer: RGB[A]) (anything that can be passed to QColor).

  • opacity (float, default: 1 ) –

    Opacity of icon, by default 1

  • animation (Animation, default: None ) –

    Animation for the icon. A subclass of superqt.fonticon.Animation, that provides a concrete animate method. (see "spin" and "pulse" for examples). by default None.

  • transform (QTransform, default: None ) –

    A QTransform to apply when painting the icon, by default None

  • states (dict, default: None ) –

    Provide additional styling for the icon in different states. states must be a mapping of string to dict, where:

    • the key represents a QIcon.State ("on", "off"), a QIcon.Mode ("normal", "active", "selected", "disabled"), or any combination of a state & mode separated by an underscore (e.g. "off_active", "selected_on", etc...).
    • the value is a dict with all of the same key/value meanings listed above as parameters to this function (e.g. glyph_key, color,scale_factor, animation, etc...)

    Missing keys in the state dicts will be taken from the default options, provided by the parameters above.

Returns:

  • QFontIcon –

    A subclass of QIcon. Can be used wherever QIcons are used, such as widget.setIcon()

Examples:

simple example (using the string 'fa5s.smile' assumes the fonticon-fontawesome5 plugin is installed)

>>> btn = QPushButton()
>>> btn.setIcon(icon("fa5s.smile"))

can also directly import from fonticon_fa5

>>> from fonticon_fa5 import FA5S
>>> btn.setIcon(icon(FA5S.smile))

with animation

>>> btn2 = QPushButton()
>>> btn2.setIcon(icon(FA5S.spinner, animation=pulse(btn2)))

complicated example

>>> btn = QPushButton()
>>> btn.setIcon(
...     icon(
...         FA5S.ambulance,
...         color="blue",
...         states={
...             "active": {
...                 "glyph": FA5S.bath,
...                 "color": "red",
...                 "scale_factor": 0.5,
...                 "animation": pulse(btn),
...             },
...             "disabled": {
...                 "color": "green",
...                 "scale_factor": 0.8,
...                 "animation": spin(btn),
...             },
...         },
...     )
... )
>>> btn.setIconSize(QSize(256, 256))
>>> btn.show()

IconOpts

IconOpts(
    glyph_key: str | Unset = _Unset,
    scale_factor: float | Unset = _Unset,
    color: ValidColor | Unset = _Unset,
    opacity: float | Unset = _Unset,
    animation: Animation | Unset | None = _Unset,
    transform: QTransform | Unset | None = _Unset,
)

Options for rendering an icon.

Parameters:

  • glyph_key (str, default: _Unset ) –

    The key of the glyph to use, e.g. 'fa5s.smile', by default None

  • scale_factor (float, default: _Unset ) –

    The scale factor to use, by default None

  • color (ValidColor, default: _Unset ) –

    The color to use, by default None. Colors may be specified as a string, QColor, Qt.GlobalColor, or a 3 or 4-tuple of integers.

  • opacity (float, default: _Unset ) –

    The opacity to use, by default None

  • animation (Animation, default: _Unset ) –

    The animation to use, by default None

Text

setTextIcon

setTextIcon(
    widget: QWidget,
    glyph_key: str,
    size: float | None = None,
) -> None

Set text on a widget to a specific font & glyph.

This is an alternative to setting a QIcon with a pixmap. It may be easier to combine with dynamic stylesheets.

Parameters:

  • widget (QWidget) –

    A widget supporting a setText method.

  • glyph_key (str) –

    String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.

  • size (int, default: None ) –

    Size for QFont. passed to setPixelSize, by default None

font

font(font_prefix: str, size: int | None = None) -> QFont

Create QFont for font_prefix.

Parameters:

  • font_prefix (str) –

    Font_prefix, such as 'fa5s' or 'mdi6', representing a font-family and style.

  • size (int, default: None ) –

    Size for QFont. passed to setPixelSize, by default None

Returns:

  • QFont –

    QFont instance that can be used to add fonticons to widgets.

Fonts

addFont

addFont(
    filepath: str,
    prefix: str,
    charmap: dict[str, str] | None = None,
) -> tuple[str, str] | None

Add OTF/TTF file at filepath to the registry under prefix.

If you'd like to later use a fontkey in the form of prefix.some-name, then charmap must be provided and provide a mapping for all of the glyph names to their unicode numbers. If a charmap is not provided, glyphs must be directly accessed with their unicode as something like key.￿.

Note

in most cases, users will not need this. Instead, they should install a font plugin, like:

Parameters:

  • filepath (str) –

    Path to an OTF or TTF file containing the fonts

  • prefix (str) –

    A prefix that will represent this font file when used for lookup. For example, 'fa5s' for 'Font-Awesome 5 Solid'.

  • charmap (Dict[str, str], default: None ) –

    optional mapping for all of the glyph names to their unicode numbers. See note above.

Returns:

  • (Tuple[str, str], optional) –

    font-family and font-style for the file just registered, or None if something goes wrong.

IconFont

Helper class that provides a standard way to create an IconFont.

Examples:

class FA5S(IconFont):
    __font_file__ = '...'
    some_char = 0xfa42

IconFontMeta

IconFont metaclass.

This updates the value of all class attributes to be prefaced with the class name (lowercase), and makes sure that all values are valid characters.

Examples:

This metaclass turns the following class:

class FA5S(metaclass=IconFontMeta):
    __font_file__ = 'path/to/font.otf'
    some_char = 0xfa42

into this:

class FA5S:
    __font_file__ = path/to/font.otf'
    some_char = 'fa5s.既'

In usage, this means that someone could use icon(FA5S.some_char) (provided that the FA5S class/namespace has already been registered). This makes IDE attribute checking and autocompletion easier.

ENTRY_POINT

ENTRY_POINT = _FIM.ENTRY_POINT

Animations

Animation

Animation(
    parent_widget: QWidget,
    interval: int = 10,
    step: int = 1,
)

Base icon animation class.

animate
animate(painter: QPainter)

Setup and start the timer for the animation.

spin

spin(
    parent_widget: QWidget,
    interval: int = 10,
    step: int = 1,
)

Animation that smoothly spins an icon.

pulse

pulse(parent_widget: QWidget | None = None)

Animation that spins an icon in slower, discrete steps.