- Qt 6.11
- Qt Labs StyleKit
- QML Types
- ControlStateStyle
- Qt 6.11.1 Reference Documentation

# ControlStateStyle QML Type

Describes the style of a control in a given state. More...

Import Statement: | `import Qt.labs.StyleKit`
Inherits: | ControlStyleProperties
Inherited By: | ControlStyle and CustomControl

- List of all members, including inherited members

## Properties

- checked : ControlStateStyle
- disabled : ControlStateStyle
- focused : ControlStateStyle
- highlighted : ControlStateStyle
- hovered : ControlStateStyle
- pressed : ControlStateStyle
- vertical : ControlStateStyle

## Detailed Description

ControlStateStyle describes the style of a control in a particular state. A ControlStyle inherits ControlStateStyle, since it represents the normal state — properties set directly on a ControlStyle describe how the control looks when no other state is active. State-specific overrides are then set through nested states such as pressed, hovered, and checked.

Nested states are not mutually exclusive. Multiple states can be active at the same time — for example, a button can be both hovered and pressed simultaneously. When several states are active, all matching state overrides are applied. If the same property is set in multiple active states, conflicts are resolved using the following priority order: pressed, hovered, highlighted, focused, checked, vertical. So for example `pressed.background.color` wins over `checked.background.color` if the control is both pressed and checked.

The disabled state is an exception: a disabled control cannot be interacted with, so the pressed, hovered, highlighted, and focused states will not apply. However, disabled can still be combined with states like checked and vertical.

The more deeply nested a state is, the more qualified it is. For example, `hovered.pressed.background.color` takes precedence over `hovered.background.color` when both hovered and pressed are active. The nesting order does not matter: `hovered.pressed` and `pressed.hovered` are equivalent. However, if both forms are used at the same time, which one wins is undefined.

Deeper nesting of states can also be used to resolve conflicts. If the same property is set in both hovered and checked, the priority order means the hovered value wins. If you would rather have the checked value win, or use an altogether different value in that situation, you can override the property in `hovered.checked`, which then takes precedence over both.

The following snippet shows how to style a button differently depending on its state:

     button {
         text.color: "white"
         background.color: "cornflowerblue"

         pressed.background.color: "cadetblue"
         hovered.background.color: "dodgerblue"
         highlighted.background.color: "lightblue"
         focused.background.color: "lightskyblue"
         checked.background.color: "darkseagreen"
         disabled.background.color: "gray"

         // hovered.checked takes precedence over both hovered and checked
         hovered.checked.background.color: "mediumseagreen"

         hovered.checked {
             // Nested states are grouped properties, so you can use the compact
             // per-property form above, or structure them hierarchically for
             // better readability. Both forms are functionally equivalent.
             pressed {
                 // hovered.checked.pressed takes precedence over hovered.checked
                 background {
                     color: "mediumaquamarine"
                     scale: 0.95
                 }
                 text {
                     bold: true
                 }
             }
         }
     }

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

See also ControlStyle, DelegateStyle, and FallbackStyle Reference.

## Property Documentation

### checked : ControlStateStyle

Style overrides applied when the control is checked.

See also pressed, hovered, highlighted, focused, vertical, disabled, and StyleReader.checked.

### disabled : ControlStateStyle

Style overrides applied when the control is disabled.

A disabled control cannot be interacted with, so pressed, hovered, highlighted, and focused will not be applied at the same time as disabled.

See also pressed, hovered, highlighted, focused, checked, vertical, and StyleReader.enabled.

### focused : ControlStateStyle

Style overrides applied when the control is focused.

See also pressed, hovered, highlighted, checked, vertical, disabled, and StyleReader.focused.

### highlighted : ControlStateStyle

Style overrides applied when the control is highlighted.

See also pressed, hovered, focused, checked, vertical, disabled, and StyleReader.highlighted.

### hovered : ControlStateStyle

Style overrides applied when the control is hovered.

See also pressed, highlighted, focused, checked, vertical, disabled, and StyleReader.hovered.

### pressed : ControlStateStyle

Style overrides applied when the control is pressed.

See also hovered, highlighted, focused, checked, vertical, disabled, and StyleReader.pressed.

### vertical : ControlStateStyle

Style overrides applied when the control is vertical (for example, a vertical Slider or ScrollBar).

See also pressed, hovered, highlighted, focused, checked, disabled, and StyleReader.vertical.