Contents

StyleKit Features Overview

This page gives a brief introduction to the main features of StyleKit. For a complete reference of all available types and properties, see the QML Types page.

Creating a Style

A Style is a QML object that describes the visual appearance of all Qt Quick Controls in your application — button, slider, checkBox, and so on. Each has its own group in the style where you can set properties such as colors, sizes, radii, and shadows for the visual parts that make up the control.

The control group is special, since it acts as a fallback for all the other control groups. If you leave out some of the properties for a slider, for example, they will be read from control instead. Properties not set in slider or control fall back further to the fallback style which is a complete style similar to the Basic Style. This means you don't necessarily need to style all the available controls, only the ones you want to customize — the fallback system takes care of styling the rest:

 // PlainStyle.qml

 Style {
     control {
         // control does not map to an actual Qt Quick Control, but is a shared
         // fallback for all other controls. Use it to define styling that is
         // common to all of them. Unset properties fall back to Style.fallbackStyle.
         padding: 6
         text.color: "white"
         background {
             radius: 4
             border.color: "gray"
         }
         indicator {
             implicitWidth: 20
             implicitHeight: 20
             border.width: 1
             radius: 3
         }
         handle {
             implicitWidth: 20
             implicitHeight: 20
             radius: 10
         }
     }

     slider {
         // slider defines the styling for a Qt Quick Slider.
         // Unset properties fall back to control.
         handle.color: "white"
         indicator {
             implicitWidth: Style.Stretch
             implicitHeight: 6
             color: "steelblue"
             foreground.color: "skyblue"
         }
     }

     abstractButton {
         // abstractButton does not map to an actual Qt Quick Control, but
         // is a shared fallback for button-like controls, such as button,
         // radioButton, checkBox). Use it to define styling that is common
         // to all of them. Unset properties fall back to control.
         background.shadow {
             opacity: 0.6
             verticalOffset: 2
             horizontalOffset: 2
             color: "gray"
         }
     }

     button {
         // button defines the styling for a Qt Quick Button.
         // Unset properties fall back to abstractButton.
         background {
             implicitWidth: 120
             color: "lightsteelblue"
             gradient: Gradient {
                 GradientStop { position: 0.0; color: Qt.alpha("black", 0.0)}
                 GradientStop { position: 1.0; color: Qt.alpha("black", 0.2)}
             }
         }
     }

     // Controls left undefined — such as radioButton, checkBox, or
     // switchControl — fall back to their immediate base type, which in
     // this style will be either abstractButton or control directly.
 }

Activating a Style

To activate the style, assign it to StyleKit.style on the root ApplicationWindow. All controls in the application then pick it up automatically:

 // Main.qml

 import QtQuick
 import Qt.labs.StyleKit

 ApplicationWindow {
     id: app
     width: 1024
     height: 800
     visible: true

     // Assign the style to be used
     StyleKit.style: PlainStyle {}

     // Controls are used as normal
     Column {
         anchors.fill: parent
         anchors.margins: 10
         spacing: 10

         Button {
             text: "Button"
         }

         Slider {
             width: 200
         }
     }
 }

Control States

Controls change appearance depending on user interaction — a button looks different when hovered, pressed, or disabled. StyleKit lets you express this in the style by placing the state name in front of the affected properties, to give them alternative values when the control is in that state.

States can be nested, and a more specific combination (e.g. hovered.checked) takes precedence over its individual components:

 button {
     text.color: "aliceblue"
     background.color: "cornflowerblue"
     pressed.background.color: "deepskyblue"
     hovered.background.color: "lightskyblue"
     focused.background.color: "lightsteelblue"
     checked.background.color: "royalblue"
     highlighted.background.color: "lightblue"
     disabled {
         background.color: "lightgray"
         background.border.color: "darkgray"
     }

     // Nested states, such as hovered.checked in this case, takes
     // precedence over both hovered and checked:
     hovered.checked.background.color: "steelblue"
 }

State Transitions

State changes can be animated by setting the transition property on a control style. A StyleAnimation provides a convenient way to animate groups of related style properties, such as all background or indicator colors, but you can use standard QML animations such as ColorAnimation and NumberAnimation as well:

 comboBox {
     background.color: "lightgray"
     hovered.background.color: "plum"

     indicator.color: "white"
     hovered.indicator.color: "pink"
     hovered.indicator.border.width: 4

     transition: Transition {
         StyleAnimation {
             animateBackgroundColors: true
             animateIndicatorColors: true
             animateIndicatorBorder: true
             easing.type: Easing.OutQuad
             duration: 500
         }
     }
 }

Theming

StyleKit has built-in support for light and dark themes through the light and dark properties on a Style. Similar to a Style, a Theme lets you define the style each control should have when that theme is active. Properties that are not set in a theme will fall back to be read from the style:

 Style {
     light: Theme {
         applicationWindow.background.color: "gainsboro"
         control.text.color: "#202020"
         control.background.color: "#f0f0f0"
         control.background.border.color: "#d0d0d0"
         button.hovered.background.color: "#4a90d9"
         radioButton.indicator.foreground.color: "#d0d0d0"
     }

     dark: Theme {
         applicationWindow.background.color: "#2b2b2b"
         control.text.color: "#e0e0e0"
         control.background.color: "#404040"
         control.background.border.color: "#606060"
         button.hovered.background.color: "#6ab0f9"
         radioButton.indicator.foreground.color: "#606060"
     }
 }

Custom Themes

Beyond light and dark, you can define any number of additional themes using CustomTheme. Each CustomTheme has a name and holds a Theme object with the same structure as the built-in themes:

 Style {
     CustomTheme {
         name: "HighContrast"
         theme: Theme {
             control.background.color: "white"
             control.background.border.color: "black"
             control.background.border.width: 2
         }
     }

     CustomTheme {
         name: "Sepia"
         theme: Theme {
             control.text.color: "#5b4636"
             control.background.color: "#f4ecd8"
             control.background.border.color: "#c8b99a"
             applicationWindow.background.color: "#efe6d0"
         }
     }
 }

To switch themes at runtime, set Style.themeName from a QML file in your application to the name of the desired theme. The Style.themeNames property lists all available theme names, which makes it straightforward to populate a selector control:

 ComboBox {
     model: StyleKit.style.themeNames
     onCurrentTextChanged: StyleKit.style.themeName = currentText
 }

To activate a theme at application start-up, set themeName when assigning the style:

 ApplicationWindow {
     width: 1024
     height: 800
     visible: true

     StyleKit.style: MyStyleKitStyle {
         themeName: "HighContrast"
     }
 }

Style Variations

A StyleVariation lets you define alternative styling for parts of the application. This is useful when you need to style controls differently when they are children of, for example, a ToolBar or a GroupBox, or if you want to implement style hints that the application can optionally apply to some of the controls.

There are two types of style variations: type variations and instance variations.

Type Variations

A type variation contains alternative styling for controls that are children (or descendants) of another control type. This means that if a StyleVariation contains styling for a button, and it's added to the variations property of a frame, StyleKit will style all Buttons that are children of Frames in the application accordingly:

 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: []
     }
 }

Instance Variations

Named StyleVariations can be applied to individual controls in the application using the StyleVariation.variations attached property. When applied, the control itself, and all its descendants, will receive the alternative styling. This is different from a type variation, which affects all controls of a certain type, such as all Frames. Instance variations will only affect the control instance (and the descendants) on which they're attached:

 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"
     }
 }

Apply them to controls in your application:

 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"]
         }
     }
 }

Custom Controls

If your application includes custom controls that are not part of Qt Quick Controls, you can still integrate them with StyleKit. Just add a CustomControl for each of them and style them the same way you style the built-in controls:

 // MyStyle.qml

 Style {
     id: style
     readonly property int myControlType: 0
     CustomControl {
         controlType: style.myControlType
         background {
             implicitWidth: 120
             implicitHeight: 30
             radius: 0
         }
         hovered.background.color: "lightslategray"
         pressed.background.color: "skyblue"
     }
 }

In the control's implementation, use a StyleReader with the matching controlType to read back the style properties. The correct property values are resolved by taking Themes, StyleVariations, fallback types, and property propagation into account. For a style reader to do this, it needs to know the state of your control. Therefore bind your control's state to the relevant StyleReader properties such as hovered and pressed. Each time there is a state change, any affected style properties will be updated, causing your control to repaint:

 // Main.qml

 component MyControl : Rectangle {
     StyleReader {
         id: styleReader
         controlType: StyleKit.style.myControlType
         hovered: hoverHandler.hovered
         pressed: tapHandler.pressed
         palette: app.palette
     }

     HoverHandler { id: hoverHandler }
     TapHandler { id: tapHandler }

     implicitWidth: styleReader.background.implicitWidth
     implicitHeight: styleReader.background.implicitHeight
     color: styleReader.background.color
     radius: styleReader.background.radius

     Text {
         font: styleReader.font
         anchors.centerIn: parent
         text: "ok"
     }
 }

Custom Delegates

Each visual part of a control — background, handle, indicator, etc — is rendered by a delegate. By default StyleKit uses StyledItem for rendering, but you can replace it entirely with you own QML component.

The component needs to define two required properties that StyleKit populates automatically:

  • delegateStyle — the DelegateStyle that carries the resolved style properties (color, radius, implicit size, etc.)
  • control — the Qt Quick Control the delegate belongs to

You then assign the component to the delegate property of the visual part that you want to affect:

 // import QtQuick.Templates as T

 slider {
     handle.delegate: Rectangle {
         id: handle
         required property DelegateStyle delegateStyle
         required property T.Slider control
         implicitWidth: delegateStyle.implicitWidth
         implicitHeight: delegateStyle.implicitHeight
         radius: delegateStyle.radius
         color: delegateStyle.color
         Text {
             anchors.centerIn: parent
             text: handle.control.value.toFixed(0)
         }
     }
 }

Overlay and Underlay

If you only want to augment the default rendering rather than replace it completely, use StyledItem as the root of your delegate. Any children you add to StyledItem are drawn on top of (overlay) the default rendering:

 Style {
     component Star : Shape {
         id: star
         property color color
         ShapePath {
             fillColor: star.color
             scale: Qt.size(star.width, star.height)
             PathMove { x: 0.50; y: 0.00 }
             PathLine { x: 0.59; y: 0.35 }
             PathLine { x: 0.97; y: 0.35 }
             PathLine { x: 0.66; y: 0.57 }
             PathLine { x: 0.78; y: 0.91 }
             PathLine { x: 0.50; y: 0.70 }
             PathLine { x: 0.22; y: 0.91 }
             PathLine { x: 0.34; y: 0.57 }
             PathLine { x: 0.03; y: 0.35 }
             PathLine { x: 0.41; y: 0.35 }
             PathLine { x: 0.50; y: 0.00 }
         }
     }

     button {
         background.delegate: StyledItem {
             width: parent.width
             height: parent.height
             // Draw a star on top the default rendering
             Star {
                 anchors.fill: parent
                 color: "gold"
             }
         }
     }
 }

To draw something underneath the default rendering instead, make your delegate an Item, place the extra content first, and embed a StyledItem as a child to render the default appearance on top:

 Style {
     component Star : Shape {
         id: star
         property color color
         ShapePath {
             fillColor: star.color
             scale: Qt.size(star.width, star.height)
             PathMove { x: 0.50; y: 0.00 }
             PathLine { x: 0.59; y: 0.35 }
             PathLine { x: 0.97; y: 0.35 }
             PathLine { x: 0.66; y: 0.57 }
             PathLine { x: 0.78; y: 0.91 }
             PathLine { x: 0.50; y: 0.70 }
             PathLine { x: 0.22; y: 0.91 }
             PathLine { x: 0.34; y: 0.57 }
             PathLine { x: 0.03; y: 0.35 }
             PathLine { x: 0.41; y: 0.35 }
             PathLine { x: 0.50; y: 0.00 }
         }
     }

     slider.handle.delegate: Item {
         // Since the root item is not a StyledItem, the following
         // required properties must be defined explicitly:
         required property DelegateStyle delegateStyle
         required property QtObject control

         implicitWidth: delegateStyle.implicitWidth
         implicitHeight: delegateStyle.implicitHeight
         width: parent.width
         height: parent.height
         scale: delegateStyle.scale
         rotation: delegateStyle.rotation
         visible: delegateStyle.visible

         // Draw a star underneath the default handle delegate
         Star {
             width: parent.width * 2
             height: parent.height * 2
             anchors.centerIn: parent
             color: "gold"
         }

         StyledItem {
             // Forward delegateStyle into StyledItem. StyledItem doesn't
             // use 'control' for anything, so it can be omitted.
             delegateStyle: parent.delegateStyle
         }
     }
 }

Custom Data

Custom delegates sometimes need additional styling properties that go beyond the built-in ones — for example to style child items that StyleKit knows nothing about. The data property makes this possible. It can hold any QtObject, so it can carry whatever information your delegate needs.

Like all the other style properties, data participates in style property resolution — the delegate always receives the object that matches the current control state, active theme, and style variations. Unlike the built-in properties, data is propagated as a whole — individual properties inside the object do not propagate separately:

 component OverlayData : QtObject {
     property color overlayColor
 }

 toolButton {
     background.delegate: StyledItem {
         id: custom
         Text {
             color: custom.delegateStyle.data.overlayColor
             font.pixelSize: 30
             text: "シ"
         }
     }
     background.data: OverlayData {
         overlayColor: "sandybrown"
     }
     hovered.background.data: OverlayData {
         overlayColor: "magenta"
     }
 }

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.