3 +description: Use when writing or editing QML/QtQuick code — property bindings, components, signals, models, anchors, layouts, JavaScript integration. Triggers on "qml", "qtquick", "qt qml", "qml binding", "qml signal", "qml component", "qml layout", "qt property binding". Does NOT cover Quickshell-specific types (see the quickshell skill for that).
8 +QML (Qt Modeling Language) is the declarative UI language for QtQuick. You build a tree of objects; properties propagate reactively. The language is small — the depth is in the standard library (`QtQuick`, `QtQuick.Controls`, `QtQuick.Layouts`, `QtQuick.Window`, …).
10 +This skill is **pure QML** — no Quickshell, no Qt-specific compositor types. For Quickshell desktop shells, layer-shell, or Wayland IPC, see the `quickshell` skill.
16 +import QtQuick.Controls
19 + // root object: a window with an attached contentItem + header + footer
20 + width: 400; height: 300; visible: true
22 + // properties flow top-down via bindings
26 + // child objects fill the tree
28 + anchors.fill: parent
29 + Text { text: "Hello" }
30 + Button { text: "Click" }
35 +- **Tree of objects** — each `{...}` is an object; nested objects are children.
36 +- **Property bindings** — `width: parent.width / 2` is an expression; it re-evaluates when `parent.width` changes.
37 +- **Signals** — objects emit them; you connect with `on<Signal>` handlers.
38 +- **JavaScript** — inline expressions and full functions; QML is JS-aware.
43 +import QtQuick // Item, Rectangle, Text, Image, MouseArea, Timer, …
44 +import QtQuick.Window // Window, ApplicationWindow
45 +import QtQuick.Controls // Button, TextField, Label, Slider, TabBar, …
46 +import QtQuick.Layouts // RowLayout, ColumnLayout, GridLayout, StackLayout
47 +import QtQuick.Dialogs // FileDialog, MessageDialog
48 +import Qt.labs.platform 1.1 // native menu/standardPaths (labs; pin a version)
49 +import "myfile.js" as MyJs // JS file as a namespace
50 +import "subfolder" as Sub // relative-path folder import
53 +Module imports `<Module> [Major.Minor] [as <Namespace>]`. Relative imports use a path. Always pin a major.minor for stability.
55 +##
Defining a property 59 + property int count: 0 // int, default 0
60 + property string name: "x" // string
61 + property real ratio: 0.5 // float (QML's `real` = double)
62 + property bool enabled: true
63 + property var things: [1, "x", true] // var = untyped (rarely needed)
64 + property color tint: "red" // color string → QColor
65 + property url img: "https://example.com" // URL
66 + property MyType other // reference to another object
67 + property point p: Qt.point(0, 0) // x, y
68 + property size s: Qt.size(100, 50) // w, h
69 + property rect r: Qt.rect(0, 0, 100, 50) // x, y, w, h
70 + property date d: new Date()
71 + property list<int> nums: [1, 2, 3] // QML list
72 + property var fn: (x) => x * 2 // function
75 + readonly property int ro: 5 // bind-once-style; can't be assigned
76 + default property Item content // default property (used when object is the value)
77 + required property var modelData // forces the user to set it
78 + property int reset: count > 0 ? 0 : 0 // always re-evaluates if count changes
82 +- `readonly` — can be assigned in initial binding only.
83 +- `default` — this is the property an object child becomes the value of (e.g. `Item { Rectangle {...} }` is shorthand for `Item { default: Rectangle {...} }`).
84 +- `required` — the user of this type must set this; `qmllint` enforces.
89 +property int count: 0
90 +Timer { running: true; interval: 1000; repeat: true; onTriggered: count++ }
93 + width: count * 10 // re-evaluates every time `count` changes
94 + visible: count > 0 // reactively hides when count is 0
98 +**This is the key insight.** You don't write update code. You write expressions; QML tracks dependencies and re-evaluates.
104 + signal activated(string from) // declare a signal
105 + signal toggled() // no args
107 + property int level: 0
109 + onActivated: (from) => console.log("from:", from) // handler
110 + onLevelChanged: console.log("now", level) // auto-signal for property changes
112 + Component.onCompleted: console.log("ready") // one-shot at creation
113 + Component.onDestruction: console.log("destroyed")
116 + anchors.fill: parent
117 + onClicked: parent.activated("click")
122 +Every property has an auto-generated `on<Property>Changed` signal. To listen to another object's signals, use `Connections { target: x; function on<Signal>() { ... } }`.
128 + function square(x: int): int { return x * x }
129 + function notify(msg: string): void { console.log(msg) }
130 + property var add: (a, b) => a + b
134 +Use `void` return for non-returning functions. Functions are JavaScript, with QML value-type semantics (e.g. `point` is passed by value).
136 +##
Inline components 140 + component Labeled: Row {
141 + property string text
142 + Text { text: parent.text }
145 + Labeled { text: "first" }
146 + Labeled { text: "second" }
150 +`component Name: Type { ... }` defines a type locally. Use this to avoid making a separate file for one-shot types.
152 +##
Custom types in their own file 155 +// MyButton.qml (PascalCase, in the same dir as the consumer)
157 +import QtQuick.Controls
159 + property string iconName: ""
160 + icon.name: iconName
164 +Neighbor `.qml` files with PascalCase names are auto-imported in the same directory. For subfolders, use relative imports or `qmldir` files.
170 + anchors.fill: parent // fill parent
171 + anchors.centerIn: parent // center inside parent
172 + anchors.left: parent.left // left edge to parent's left
173 + anchors.top: parent.top; anchors.bottom: parent.bottom // stretch top-bottom
175 + width: 100; height: 50 // set actual size
176 + implicitWidth: 100; implicitHeight: 50 // desired size (used by containers)
180 +**The cardinal rule:** implicit size flows child → parent; actual size flows parent → child. Setting actual size on a child that a container will manage is a bug — the container will overwrite it. Setting implicit size on a container is correct.
182 +##
Layouts (the easy way) 184 +`import QtQuick.Layouts`
187 +RowLayout { // horizontal
189 + Item { Layout.fillWidth: true } // spacer
190 + Text { text: "right" }
193 +ColumnLayout { spacing: 8 } // vertical
194 +GridLayout { columns: 3 } // grid
195 +StackLayout { } // stack (only one visible)
198 +`Layout.fillWidth: true` (and friends) make the child stretch. `Layout.preferredWidth: 100` sets the size before stretching.
205 + ListElement { name: "Alice"; age: 30 }
206 + ListElement { name: "Bob"; age: 25 }
211 + delegate: Text { text: name } // `name` is auto-injected from the model role
215 +Other models: `Repeater` (inline, no scroll), `ListView` (scrollable, recycles), `GridView`, `TableView`, `PathView`. For dynamic data, use `ObjectModel` or a custom C++ `QAbstractListModel`.
217 +##
Component composition 222 + default property Item body // accepts one Item as the "body"
224 + Rectangle { anchors.fill: parent; color: "lightblue" }
233 + Text { text: "first" }
234 + Text { text: "second" }
239 +Default properties make component composition clean — the consumer doesn't have to use `body: Column {...}`, they can just put the column inside.
241 +##
When NOT to use QML 243 +- C++ hot paths or large data transformations — use C++ with a QObject model exposed to QML.
244 +- Async I/O — QML has promises (`Qt.callLater`) but Node.js / Python is usually cleaner.
245 +- Complex business logic — write the logic in C++ or Python, expose the result as a property.
249 +- `references/syntax.md` — imports, properties, bindings in depth
250 +- `references/components.md` — defining custom types, inline components, default properties
251 +- `references/layouts.md` — anchors, layouts, the implicit/actual size rule
252 +- `references/models.md` — Repeater, ListView, ObjectModel, custom C++ models
253 +- `references/signals.md` — signal declaration, handlers, Connections
254 +- `references/javascript.md` — JS in QML, function calls, lambdas
255 +- `references/common-pitfalls.md` — `childrenRect` loops, zero-size Items, binding fights
256 +- `examples/` — 7 minimal, runnable QML prototypes (no Quickshell, no Qt-specific compositor types)
260 +- **`quickshell` skill** — for using QML inside a Quickshell shell, layer-shell panels, IPC, and the Quickshell-specific types.
261 +- Qt docs: <https://doc.qt.io/qt-6/qml-tutorial.html>, <https://doc.qt.io/qt-6/qtqml-index.html>