- Qt 6.9
- Qt Quick Controls
- Icons in Qt Quick Controls
- Qt 6.9.2 Reference Documentation

Focus Management ◦ Styling and Customizing

# Icons in Qt Quick Controls

Qt Quick Controls comes with support for icons since Qt 5.10. This means, Buttons, item delegates, and menu items are now capable of presenting an icon in addition to a text label.

## Using Icons

AbstractButton and Action provide the following properties through which icons can be set:

- `icon.name`
- `icon.source`
- `icon.width`
- `icon.height`
- `icon.color`
- `icon.cache`

Theme icons are referenced by a name, and regular icons by a source URL. Both `icon.name` and `icon.source` can be set to ensure that an icon will always be found. If the icon is found in the theme, it will always be used; even if `icon.source` is also set. If the icon is not found in the theme, `icon.source` will be used instead.

     Button {
         icon.name: "edit-cut"
         icon.source: "images/cut.png"
     }

Each Qt Quick Controls 2 style requests a default icon size and color according to their guidelines, but it is possible to override these by setting the `icon.width`, `icon.height`, and `icon.color` properties.

The image that is loaded by an icon whose `width` and `height` are not set depends on the type of icon in use. For theme icons, the closest available size will be chosen. For regular icons, the behavior is the same as the sourceSize property of Image.

The icon color is specified by default so that it matches the text color in different states. In order to use an icon with the original colors, set the color to `"transparent"`.

     Button {
         icon.color: "transparent"
         icon.source: "images/logo.png"
     }

For buttons, the display property can be used to control how the icon and text are displayed within the button.

The `icon.cache` property controls whether or not the icon image is cached. For more information, see cache.

## Icon Themes

Compliant icon themes must follow the freedesktop icon theme specification, which can be obtained here: http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html.

Traditionally, only Linux and UNIX support icon themes on the platform level, but it is possible to bundle a compliant icon theme in an application to use themed icons on any platform.

The default icon theme search paths depend on the platform. On Linux and UNIX, the search path will use the `XDG_DATA_DIRS` environment variable if available. All platforms have the resource directory `:/icons` as a fallback. Custom icon theme search paths can be set with QIcon::setThemeSearchPaths().

The following example bundles an icon theme called mytheme into the application's resources using Qt's resource system.

     <RCC>
         <qresource prefix="/">
             <file>icons/mytheme/index.theme</file>
             <file>icons/mytheme/32x32/myicon.png</file>
             <file>icons/mytheme/32x32@2/myicon.png</file>
         </qresource>
     </RCC>

The `index.theme` file describes the general attributes of the icon theme, and lists the available theme icon directories:

     [Icon Theme]
     Name=mytheme
     Comment=My Icon Theme

     Directories=32x32,32x32@2

     [32x32]
     Size=32
     Type=Fixed

     [32x32@2]
     Size=32
     Scale=2
     Type=Fixed

In order to use the bundled icon theme, an application should call QIcon::setThemeName() before loading the main QML file:

     #include <QGuiApplication>
     #include <QQmlApplicationEngine>
     #include <QIcon>

     int main(int argc, char *argv[])
     {
         QGuiApplication app(argc, argv);

         QIcon::setThemeName("mytheme"); // <--

         QQmlApplicationEngine engine;
         engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
         return app.exec();
     }

Now it is possible to use named icons from the bundled icon theme without having to specify any fallback source:

     Button {
         icon.name: "myicon"
     }

The Gallery example and Wearable Demo provide complete runnable applications with a bundled icon theme.

Focus Management ◦ Styling and Customizing