StyleVariation QML Type | Qt Labs StyleKit | Qt 6.11.2
Description: Defines alternative styling for specific controls.

- Qt 6.11
- Qt Labs StyleKit
- QML Types
- StyleVariation
- Qt 6.11.2 Reference Documentation

# StyleVariation QML Type

Defines alternative styling for specific controls. More...

Import Statement: | `import Qt.labs.StyleKit`
Inherits: | AbstractStylableControls

- List of all members, including inherited members

## Properties

- name : string

## Attached Properties

- controlType : int
- variations : list<string>

## Detailed Description

A StyleVariation lets you define alternative styling that can be applied to specific controls in the application (instance variations), or to all descendants of a particular parent control type (type variations). For example, you can give controls in a sidebar a compact appearance, or make buttons inside all toolbars look different from buttons elsewhere.

### Instance Variations

Instance variations are activated by setting the variations attached property on any item in the application — all StyleKit controls that are children or descendants of that item will receive the alternative styling. Variations can also be set at multiple levels of the hierarchy simultaneously; when they conflict, the variation closest to the control takes precedence.

Instance variations are defined in the Style or Theme that they affect:

     Style {
         StyleVariation {
             name: "mini"
             control {
                 padding: 2
                 background.implicitHeight: 15
                 indicator.implicitWidth: 15
                 indicator.implicitHeight: 15
                 handle.implicitWidth: 15
                 handle.implicitHeight: 15
             }
         }

         StyleVariation {
             name: "alert"
             abstractButton.background.color: "red"
         }
     }

And they are applied from the application using the variations attached property:

     GroupBox {
         title: "Mini controls"
         StyleVariation.variations: ["mini"]

         Row {
             spacing: 10
             Button { text: "Save" }
             CheckBox { text: "Option" }
             // This button also has the "alert" variation, in addition to "mini"
             Button {
                 text: "Delete"
                 StyleVariation.variations: ["alert"]
             }
         }
     }

Variation names referred to from the application that are not defined in the active style (or theme) are silently ignored — they act as hints that the style author can choose to implement or leave unhandled.

### Type Variations

Type variations are assigned to the variations property of a specific ControlStyle, without requiring a name. Unlike instance variations — which require the application to explicitly opt in — type variations are applied automatically to all controls of a given type whenever they are descendants of the specified parent control type.

The following snippet shows how to make all Buttons inside a Frame look distinct from buttons elsewhere:

     Style {
         frame {
             variations: StyleVariation {
                 button {
                     text.color: "ghostwhite"
                     background.border.width: 0
                     background.color: "slategrey"
                 }
             }
         }

         groupBox {
             // groupBox falls back to frame. Therefore, if the varations set on a
             // frame is not wanted on a groupBox, just override it and set it back to [].
             variations: []
         }
     }

Because groupBox falls back to frame in the style hierarchy, type variations set on `frame` are automatically inherited by `groupBox` as well. To opt out, reset the variations for the subtype.

### Propagation order

A StyleVariation is local to the Style or Theme where it is defined. A Theme cannot shadow an entire StyleVariation defined in the Style — only individual properties within it can be overridden, just like any other style property.

For example, if both the Style and the active Theme define `frame.variations`, both type variation arrays take effect for a Frame. The resolution order for individual properties is: the Theme's variation properties take precedence over the Theme's direct properties, which take precedence over the Style's variation properties, which take precedence over the Style's direct properties.

The same applies to instance variations. A StyleVariation defined in a Theme takes precedence over the Theme's direct properties. If a StyleVariation with the same name is also defined in the Style, both take effect, following the same resolution order as described above.

In the following snippet, a button with `StyleVariation.variations: ["alert"]` will be red in the light theme and cyan in the dark theme, with a 4-pixel border in both. Because the dark theme overrides `button.background.radius` to be `6`, that property takes precedence over the `background.radius` set in the Style's variation. As a result, the button's radius ends up being `6` in the dark theme, but `0` in the light theme:

     Style {
         button.background.radius: 2
         StyleVariation {
             name: "alert"
             button.background.border.width: 4
             button.background.radius: 0
         }

         light: Theme {
             StyleVariation {
                 name: "alert"
                 button.background.color: "red"
             }
         }

         dark: Theme {
             button.background.radius: 6
             StyleVariation {
                 name: "alert"
                 button.background.color: "cyan"
             }
         }
     }

Note: Types in Qt.labs modules are not guaranteed to remain compatible in future versions.

See also Style, Theme, ControlStyle.variations, and StyleVariation.variations, {StyleKit Property Resolution}.

## Property Documentation

### name : string

The name of this variation.

The name identifies this variation when used as an instance variation.

See also variations and Instance Variations.

## Attached Property Documentation

### StyleVariation.controlType : int

This property identifies the control type of the item it is attached to.

StyleKit uses it to resolve type variations for descendant controls — if a parent item's `controlType` matches a control type that has variations defined in the Style, those variations apply to all descendant controls.

Built-in controls set this property automatically. Custom controls must set it explicitly to participate in type variation resolution.

See also ControlStyle.variations and StyleReader.controlType.

### StyleVariation.variations : list<string>

This property holds the list of instance variations to activate for a Control, and its descendant controls.

If multiple variations in the list sets the same property, the first one in the list takes precedence.

If variations are set on both a parent item and a descendant control, both sets apply, with the control's own variations taking precedence over those inherited from the parent.

     GroupBox {
         title: "Mini controls"
         StyleVariation.variations: ["mini"]

         Row {
             spacing: 10
             Button { text: "Save" }
             CheckBox { text: "Option" }
             // This button also has the "alert" variation, in addition to "mini"
             Button {
                 text: "Delete"
                 StyleVariation.variations: ["alert"]
             }
         }
     }

See also name.