Skip to content

QIconifyIcon

A QIcon with one of the SVG icons of Iconify: over 450,000 icons, from more than 260 open source icon sets. Find an icon at https://icon-sets.iconify.design, and create it with its key, in the form "prefix:name": QIconifyIcon("bi:bell"). (For a comparison with font icons, see Icons.)

Requires pyconify

Icons are downloaded with pyconify, which you can install with the iconify extra:

pip install "superqt[iconify]"

Example

QIconifyIcon QIconifyIcon
from qtpy.QtCore import QSize
from qtpy.QtWidgets import QApplication, QPushButton

from superqt import QIconifyIcon

app = QApplication([])

btn = QPushButton()
btn.setIcon(QIconifyIcon("fluent-emoji-flat:alarm-clock"))
btn.setIconSize(QSize(60, 60))
btn.show()

app.exec()

Colors, rotation, and states

Single-color icons can be colored, and any icon can be flipped or rotated:

button.setIcon(QIconifyIcon("bi:bell-fill", color="red", rotate=90))
QIconifyIcon QIconifyIcon

Without a color, single-color icons are black, whatever the widget's palette. For a dark theme, pass a color, for example one from the palette:

color = button.palette().color(QPalette.ColorRole.ButtonText).name()
button.setIcon(QIconifyIcon("bi:bell", color=color))
QIconifyIcon QIconifyIcon

addKey adds icons for other states and modes of the same QIcon. For example, a different icon when a checkable button is checked:

icon = QIconifyIcon("bi:bell", color="gray")
icon.addKey("bi:bell-fill", color="orange", state=QIcon.State.On)
button.setCheckable(True)
button.setIcon(icon)
QIconifyIcon QIconifyIcon

How icons are fetched

The first time an icon is used, pyconify downloads it from the Iconify API (api.iconify.design), and saves it in a cache on disk, where later sessions find it.

  • The download happens when the QIconifyIcon is created, in the thread that creates it, which waits for it (with a timeout of 2 seconds).
  • The first icon of each session also asks the API when the icon sets last changed, so that cached icons that are out of date are downloaded again.
  • Without network access, cached icons still load. An icon that isn't cached causes a warning, and is replaced by a question mark icon.
  • pyconify.get_cache_directory() returns the location of the cache. To use another directory, set the PYCONIFY_CACHE environment variable to it (or to 0, to turn the cache off) before superqt.iconify (or pyconify) is imported.

Using icons offline, or in an app

To make sure that an app's icons are available without network access, ship them in a cache directory:

  1. Fill a directory with the icons: create each of them once (for example, by running the app), with PYCONIFY_CACHE set to that directory.
  2. Ship the directory with the app, and set PYCONIFY_CACHE to it before importing superqt.iconify:

    import os
    from pathlib import Path
    
    os.environ["PYCONIFY_CACHE"] = str(Path(__file__).parent / "icon_cache")
    
    from superqt import QIconifyIcon
    

The icons are then loaded from the directory. With network access, an icon whose set has changed since is downloaded again, into the same directory (so it should be writable).

Licenses

Each icon set has its own license. Most are permissive (such as MIT or Apache 2.0), but many require attribution (CC BY 4.0), and a few are GPL. The license of a set is shown on its page at https://icon-sets.iconify.design, and returned by pyconify.collections().

API

QIconifyIcon

QIconifyIcon(
    *key: str,
    color: str | None = None,
    flip: Flip | None = None,
    rotate: Rotation | None = None,
    dir: str | None = None,
)

QIcon backed by an iconify icon.

Iconify includes over 450,000 icons from 260+ icon sets, including Bootstrap, Font Awesome, Material Design, and many more.

Search available icons at https://icon-sets.iconify.design Once you find one you like, use the key in the format "prefix:name" to create an icon: QIconifyIcon("bi:bell").

This class is a thin wrapper around the pyconify svg_path function. It pulls SVGs from iconify, creates a temporary SVG file and uses it as the source for a QIcon. SVGs are cached to disk, and persist across sessions (until pyconify.clear_cache() is called).

Parameters are the same as QIconifyIcon.addKey, which can be used to add additional icons for various modes and states to the same QIcon.

Parameters:

  • *key (str, default: () ) –

    Icon set prefix and name. May be passed as a single string in the format "prefix:name" or as two separate strings: 'prefix', 'name'.

  • color (str, default: None ) –

    Icon color. If not provided, the icon will appear black (the icon fill color will be set to the string "currentColor").

  • flip (str, default: None ) –

    Flip icon. Must be one of "horizontal", "vertical", "horizontal,vertical"

  • rotate (str | int, default: None ) –

    Rotate icon. Must be one of 0, 90, 180, 270, or 0, 1, 2, 3 (equivalent to 0, 90, 180, 270, respectively)

  • dir (str, default: None ) –

    If 'dir' is not None, the file will be created in that directory, otherwise a default directory is used.

Examples:

>>> from qtpy.QtWidgets import QPushButton
>>> from superqt import QIconifyIcon
>>> btn = QPushButton()
>>> icon = QIconifyIcon("bi:alarm-fill", color="red", rotate=90)
>>> btn.setIcon(icon)

addKey

addKey(
    *key: str,
    color: str | None = None,
    flip: Flip | None = None,
    rotate: Rotation | None = None,
    dir: str | None = None,
    size: QSize | None = None,
    mode: Mode = Normal,
    state: State = Off,
) -> QIconifyIcon

Add an icon to this QIcon.

This is a variant of QIcon.addFile that uses an iconify icon keys and arguments instead of a file path.

Parameters:

  • *key (str, default: () ) –

    Icon set prefix and name. May be passed as a single string in the format "prefix:name" or as two separate strings: 'prefix', 'name'.

  • color (str, default: None ) –

    Icon color. If not provided, the icon will appear black (the icon fill color will be set to the string "currentColor").

  • flip (str, default: None ) –

    Flip icon. Must be one of "horizontal", "vertical", "horizontal,vertical"

  • rotate (str | int, default: None ) –

    Rotate icon. Must be one of 0, 90, 180, 270, or 0, 1, 2, 3 (equivalent to 0, 90, 180, 270, respectively)

  • dir (str, default: None ) –

    If 'dir' is not None, the file will be created in that directory, otherwise a default directory is used.

  • size (QSize, default: None ) –

    Size specified for the icon, passed to QIcon.addFile.

  • mode (Mode, default: Normal ) –

    Mode specified for the icon, passed to QIcon.addFile.

  • state (State, default: Off ) –

    State specified for the icon, passed to QIcon.addFile.

Returns:

  • QIconifyIcon –

    This QIconifyIcon instance, for chaining.