qt-qml-review
Review QML code for correctness, performance, and idiom using qmllint and Qt6 best practices.
SKILL.mddocs/skills/qt-qml-review/SKILL.md
GitHubWhen to use
You are auditing existing .qml files for defects, binding loops, performance regressions, and non-idiomatic patterns before merge. Reach here when the goal is judging code someone else (or you) already wrote.
Not for: authoring new QML from scratch (use qt-qml) or writing QDoc API documentation (use qt-qml-docs).
Method
- Run
qmllintfirst and triage by warning category. Decision point: if it reports unqualified access, fix by adding anid(orthis.) rather than suppressing the warning. - Hunt binding loops. Decision point: if a property's binding depends transitively on itself (e.g.
widthbound to a child sized byparent.width), break the cycle by anchoring to a fixed dimension or introducing an intermediate constant. - Check layout discipline. Decision point: if an item sets both
anchorsandLayout.*attached properties, that's a conflict — inside aLayout, useLayout.*; outside, useanchors. - Assess binding cost. Decision point: if a binding runs heavy JavaScript or is re-evaluated on every frame, move the work to C++ or precompute; keep binding expressions small and pure.
- Flag type hygiene. Decision point: if a property is
varwhere a concrete type fits, recommend the typed form so the engine can optimize and qmllint can check it. - Review dynamic objects and images. Decision point: if objects are created with
Qt.createObject/Component.createObject, confirm each has a matchingdestroy(); ifImageshows a large asset, requiresourceSizeto cap decode memory. - Enforce style with
qmlformatand confirmpragma ComponentBehavior: Boundon delegate-bearing components.
Example
// BEFORE — flagged by qmllint
Rectangle {
width: childText.width + 20 // unqualified: childText resolved via scope
Text { id: childText; text: "hi" }
Image { source: "big.png" } // full-res decode into memory
}
// AFTER
Rectangle {
id: box
width: label.width + 20 // qualified via id
Text { id: label; text: "hi" }
Image {
source: "big.png"
sourceSize.width: 128 // caps decoded size
sourceSize.height: 128
}
}
qmllint MyComponent.qml
qmllint --qmljsdebugger noop MyComponent.qml # attach JS debugger transport
qmlformat -i MyComponent.qml # in-place style fix
Pitfalls
- Unqualified property access. Resolving names through the scope chain is slow and fragile; qmllint flags it — fix with an
idorthis., never by ignoring. - Binding loops. qmllint reports "Binding loop detected"; a runtime loop silently stops updating. Break the dependency cycle, don't add a timer hack.
- anchors + Layout mixing. Setting
anchorson a child of aLayoutis ignored/undefined; pick one positioning system per parent. - JavaScript-heavy bindings. Complex JS in a binding re-runs on every dependency change and blocks the GUI thread; push logic to C++ or cache.
- var instead of typed.
property vardisables engine optimizations and type checks; preferint/real/string/concrete types. - Loader overuse. Every
Loaderadds indirection and a separate context; don't wrap trivial static content in one. - Leaked dynamic objects. Objects from
createObjectwithoutdestroy()accumulate; property injection into created objects hides their real interface — pass an explicit model/props instead. - Item vs Rectangle. Using
Rectanglepurely as a container adds a needless render node; useItemwhen you don't need fill/border.
Output format
QML Review: <file>
qmllint: <N warnings> (<categories>)
Findings
- [correctness] <file>:<line> — <issue> → <fix>
- [performance] <file>:<line> — <issue> → <fix>
- [idiom] <file>:<line> — <issue> → <fix>
Verdict: <block | approve-with-nits | approve>
Reference
- qmllint: the static QML analyzer shipped with Qt 6; warning categories include
unqualified(unqualified access),deprecated,import(unresolved imports),compiler, and binding-loop detection. Categories are tunable via--<category>flags or a.qmllint.ini/pragma. - --qmljsdebugger:
qmllint --qmljsdebugger <spec>enables the QML/JS debugger transport for tooling integration. - Unqualified access fix: add an
idto the referenced object and qualify (box.width), or usethis.inside the same object. - Binding loops: reported as "Binding loop detected for property"; occur when a binding transitively depends on itself. Break via fixed sizing or intermediate properties.
- Layout vs anchors: inside
RowLayout/ColumnLayout/GridLayout(fromQtQuick.Layouts) useLayout.fillWidth,Layout.preferredWidth, etc.; outside a Layout useanchors. Do not mix on the same item. - Typed properties: prefer
int,real,bool,string,color, or concrete QML/registered types overvarfor engine optimization and lint coverage. - Image.sourceSize: sets the decoded pixel dimensions, capping texture/decode memory regardless of display size; essential for large assets.
- Item vs Rectangle:
Itemis the base visual with no rendering;Rectangleadds a fill/border render node — useItemfor pure containers. - pragma ComponentBehavior: Bound (Qt 6.5+): required-idiom for delegates capturing outer ids; qmllint warns when captured context is ambiguous without it.
- qmlformat: the official formatter;
qmlformat -i <file>rewrites in place to canonical style. Enforce in CI alongside qmllint. - Dynamic objects: objects from
Component.createObject/Qt.createQmlObjectmust be released withdestroy(); prefer passing properties at creation over post-hoc property injection.