- Qt 6.12
- Qt Quick Controls
- Styling Qt Quick Controls
- Qt 6.12.0 Reference Documentation

Icons ◦ Basic Style

# Styling Qt Quick Controls

## Available Styles

Qt Quick Controls comes with a selection of styles.

### Basic Style

The Basic Style is a simple and light-weight all-round style that offers the maximum performance for Qt Quick Controls.

### Fusion Style

The light theme of the Fusion style. | The dark theme of the Fusion style.

The Fusion Style is a platform-agnostic style that offers a desktop-oriented look and feel for Qt Quick Controls.

### Imagine Style

The Imagine Style is based on image assets. The style comes with a default set of images which can easily be changed by providing a directory with images using a predefined naming convention.

### macOS Style

The light theme of the macOS style. | The dark theme of the macOS style.

The macOS Style is a native-looking style for macOS.

Note: this style is only available for applications running on macOS.

### iOS Style

The light theme of the iOS style. | The dark theme of the iOS style.

The iOS Style is a native-looking style for iOS based on image assets.

Note: this style is only available for applications running on iOS.

### Material Style

The light theme of the Material style. | The dark theme of the Material style.

The Material Style offers an appealing design based on the Google Material Design Guidelines, but requires more system resources than the Basic style.

### Universal Style

The light theme of the Universal style. | The dark theme of the Universal style.

The Universal Style offers an appealing design based on the Microsoft Universal Design Guidelines, but requires more system resources than the Basic style.

### Windows Style

The Windows Style is a native-looking style for Windows.

Note: this style is only available for applications running on Windows.

### FluentWinUI3 Style

The light theme of the FluentWinUI3 style. | The dark theme of the FluentWinUI3 style.

The FluentWinUI3 Style is a modern, native-looking style designed for platforms running Windows 11 and above, which follows the Fluent UI and the WinUI 3 design guidelines. The FluentWinUI3 can be run on all supported platforms.

## Using Styles in Qt Quick Controls

### Default Styles

If no style is explicitly set, a default style will be used. The style that is used depends on the operating system:

- Android: Material Style
- iOS: iOS Style
- Linux: Fusion Style
- macOS: macOS Style
- Windows: Windows Style

For all other operating systems, the Basic Style is used.

### Compile-Time Style Selection

Compile-time style selection is a way of specifying a style to use by directly or indirectly importing it in QML. Since it is selected at compile time, you cannot change the style at run time if you use compile-time style selection.

The most convenient way to use comile-time style selection is to import the QtQuick.Controls.Native style. `QtQuick.Controls.Native` in turn imports the default style for the target platform. If you import `QtQuick.Controls.Native`, you should not import any specific other styles, nor the (run-time selected) `QtQuick.Controls` module. `QtQuick.Controls.Native` imports the platform-default style for you and that style handles its fallback. You can't have more than one top-level style at the same time. For example:

     // Refrain from importing QtQuick.Controls or specific styles.
     import QtQuick.Controls.Native

     ApplicationWindow {
         // ...
     }

However, you can also import one specific style at compile time, disregarding the platform defaults. For example, to import the Material style:

     // The style must be imported before any other QtQuick.Controls imports
     // in order for run-time style selection API like QQuickStyle::name() to
     // work.
     import QtQuick.Controls.Material

     ApplicationWindow {
         // ...
     }

Notice that `QtQuick.Controls` (which is responsible for run-time style selection) is not imported. The fallback style is specified by the qmldir of the style:

     module QtQuick.Controls.Material
     # ...
     import QtQuick.Controls.Basic auto

The benefit of compile-time style selection is that the QML compiler knows which specific style is in use and can generate C++ code for bindings.

Another benefit is that the `QtQuick.Controls` plugin is not used and therefore does not need to be deployed with the application.

Explicit imports are also necessary if your application is built statically.

A disadvantage of compile-time style selection is that one executable cannot support multiple styles, as each style requires its own.

See Mixing Style Selection for information about mixing compile-time and run-time style selection.

### Run-Time Style Selection

Run-time style selection is a way of specifying a style to use by importing `QtQuick.Controls`:

     import QtQuick.Controls

The `QtQuick.Controls` plugin will import the style that was set at runtime via one of the following approaches:

- QQuickStyle::setStyle()
- The `-style` command line argument
- The QT_QUICK_CONTROLS_STYLE environment variable
- The qtquickcontrols2.conf configuration file

The priority of these approaches follows the order they are listed, from highest to lowest. That is, using `QQuickStyle` to set the style will always take priority over using the command line argument, for example.

Similarly, the fallback style can be set via one of the following methods:

- QQuickStyle::setFallbackStyle()
- The QT_QUICK_CONTROLS_FALLBACK_STYLE environment variable
- The qtquickcontrols2.conf configuration file

Note: you can only dynamically choose the fallback style if it hasn't been chosen statically in the main style's qmldir file.

The benefit of run-time style selection is that a single application binary can support multiple styles, meaning that the end user can choose which style to run the application with.

A disadvantage of this approach is that QML compiler can't know which specific style is in use and therefore cannot generate C++ code for bindings on properties of Qt Quick Controls types. This does not affect the QML compiler's abilities to generate C++ for bindings on types from other modules.

See Mixing Style Selection for information about mixing run-time and compile-time style selection.

### Style-specific APIs

Several styles expose APIs specific to that style, for example the Material Style attached object or the Universal Style attached object. These style-specific APIs are only available when their style is actually selected, directly or indirectly, using either compile-time or run-time style selection.

### Mixing Style Selection

It is recommended to only use either compile-time or run-time style selection in your application. However, if your application loads third party QML code, for example, it may not be possible to control which imports are used. If you do mix the two approaches, be aware of the following limitations:

- Compile-time style selection overrides run-time style selection.
- The style that you want to use should always be explicitly imported before any other Controls import. If you don't do this, theming (such as fonts and palettes) will not behave as expected. The first explicitly imported style is also what QQuickStyle::name() will report.
- The last explicitly imported style is what will actually be used. For example, if you import `QtQuick.Controls` first and then `QtQuick.Controls.Material`, the Material style's Button.qml will be used when a Button is created. Due to the previous point about theming, it is for this reason that you should never explicitly import two different styles in the same application.
- If you intend to use compile-time style selection but load code that imports `QtQuick.Controls`, be aware that calling QQuickStyle::name() before a style has been explicitly imported will cause the platform default to be reported. If you can't avoid this, set the style to match the compile-time one beforehand via QQuickStyle::setStyle() or one of the other ways listed in Run-Time Style Selection.

#### Using QQuickStyle in C++

QQuickStyle provides C++ API for configuring a specific style. The following example runs a Qt Quick Controls application with the Material style:

     QQuickStyle::setStyle("Material");

See the detailed description of QQuickStyle for more details.

#### Command line argument

Passing a `-style` command line argument is the convenient way to test different styles. It takes precedence over the other methods listed below. The following example runs a Qt Quick Controls application with the Material style:

     ./app -style Material

#### Environment variable

Setting the `QT_QUICK_CONTROLS_STYLE` environment variable can be used to set a system-wide style preference. It takes precedence over the configuration file mentioned below. The following example runs a Qt Quick Controls application with the Universal style:

     QT_QUICK_CONTROLS_STYLE=Universal ./app

See Supported Environment Variables in Qt Quick Controls for the full list of supported environment variables.

#### Configuration file

Qt Quick Controls support a special configuration file, `:/qtquickcontrols2.conf`, that is built into an application's resources.

The configuration file can specify the preferred style (may be overridden by either of the methods described earlier) and certain style-specific attributes. The following example specifies that the preferred style is the Material style.

     [Controls]
     Style=Material

See Qt Quick Controls Configuration File for more details about the configuration file.

## Related Information

- Basic Style
- Fusion Style
- Imagine Style
- Material Style
- Universal Style
- FluentWinUI3 Style
- Customizing Qt Quick Controls
- Using File Selectors with Qt Quick Controls
- Deploying Qt Quick Controls Applications
- Qt Quick Controls Configuration File
- Supported Environment Variables in Qt Quick Controls

Icons ◦ Basic Style