QT QUICK · C++ · PYTHON

One design language.
Native applications.

Build desktop interfaces with QML components, shared tokens and practical examples you can run yourself.

Get started Explore components →

QML Core is a separate product. C++ and Python hosts share the same QML screens.

Syidax QML workbench running in the native application — A real Qt Quick application, built with Syidax Core.

QML CORE

Components

Search components

56 of 56 components

START WITH A WORKING APP

From download to your first window

C++ · CMake

Unzip the SDK and use a Qt kit compatible with the plugin edition.

cmake -S examples/cmake-app -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=C:/Qt/6.12.0/msvc2022_64 -DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded -DCMAKE_POLICY_DEFAULT_CMP0141=NEW
cmake --build build
build/syidax-example --license your.license.json --example workbench

Python · PySide6

Use the pure QML edition. Select your binding explicitly.

python -m venv .venv
.venv/Scripts/python -m pip install -r examples/python-app/requirements-pyside6.txt
.venv/Scripts/python examples/python-app/main.py --binding pyside6 --license your.license.json --example records

Run with --diagnose --json to check your Qt version, import path, fonts, runtime and license. No license token is printed.

The Gallery evaluation app is available now. Paid SDK sales and downloads are coming soon. The installation examples above preview the SDK workflow.

Tested Windows configurations

Native window and example smoke checks cover the versions below. Qt 6.8 is a source minimum, not a promise of tested support for every Qt release. Gallery uses software rendering.

Two complete application examples

Step-by-step captures from the running Windows applications. Play, pause and inspect each state.

Workbench: mark a task done, save changes and see release progress update.

Record Manager: preserve a failed save, retry, search and confirm before deleting.

See the components in context

TRY IT YOURSELF

The native Gallery

Browse examples, inspect properties and switch between light and dark themes in a Windows application. The Gallery is for evaluation; commercial SDK access is separate.

Download Gallery · Windows x64

Download QML examples and sample assets

QML Core

$24.99 / month

$249.99 / year per developer

Same regular unit price as Chart. The same price applies to first purchases, additional seats and renewals.

Documentation, runnable examples and diagnostics are included. Individual technical support, onboarding and SLAs are not provided.

View purchase and license terms →

Troubleshooting

Module not found

The --qml path must contain the Syidax folder. Python uses qml-pure. Run from the unzipped SDK, independently of the source repository.

License is inactive or frozen

Download your QML Core certificate and pass it with --license. Web Core, Chart and Grid certificates do not activate QML. Monthly use ends at expiry. Annual licenses retain only releases covered by their update period.

Qt or plugin mismatch

Check the Qt version and architecture used to build plugins. Do not mix Python Qt bindings. qml-pure removes the compiled plugin ABI dependency.

PDF or icons missing

PDF requires the optional QtQuick.Pdf module. Other Core components remain usable without it. For icon packs and resource paths, read SDK docs/ICON-PACKS.md.

Save failure or corrupt settings

Examples write only to their application-data folder. Check permissions and disk space. Invalid JSON is backed up before reset. A failed save preserves your draft.

← All components

Tree Select

Choose values from a hierarchical dropdown, such as a category or an organizational unit.

import Syidax.Core.TreeSelect

Supported QML types

Type	Definition / role
	Form field selecting one or more values from a popup tree.

Previews are images of native Qt runs. Use the buttons below each image to view a result.

01 Basic composition

SyTreeSelect is a form field whose list is a tree: nodes is the same model SyTree draws ([{ value, label, children, expanded, … }]).

Basic composition · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: false
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: false
        property bool line: false
        property bool required: false
        property bool disabled: false
        property bool readonly: false
        property bool loading: false
        property int maxTagCount: 0
        property bool appendParent: false
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

02 changed

Compare the configuration and result of changed.

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [ { value: "apple", label: "Apple" }, { value: "pear", label: "Pear" } ] },
        { value: "veg", label: "Vegetables", children: [ { value: "kale", label: "Kale" } ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: "Category"
            checkable: true; expandable: true; clearable: true
            onChanged: (detail) => output.log(("changed: %1 (valid %2)").arg(detail.selectedItem.map((i) => i.label).join(", ")).arg(detail.isValid))
            nodes: story.nodes
        }
        EventLog { id: output }
    }
}

03 setValue · clearValue · open · close · reportValidity

Compare the configuration and result of setValue · clearValue · open · close · reportValidity.

setValue · clearValue · open · close · reportValidity · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.

    id: story
    readonly property var nodes: [
        { value: "fruit", label: "Fruit", children: [ { value: "apple", label: "Apple" }, { value: "pear", label: "Pear" } ] },
        { value: "veg", label: "Vegetables", children: [ { value: "kale", label: "Kale" } ] }
    ]

    Column {
        spacing: 24
        Item {
            width: 560; height: 310
            SyTreeSelect {
                x: 24; y: 24
 id: picker; width: 260; label: "Category"; checkable: true; expandable: true; required: true; nodes: story.nodes }
        }
        Flow {
            objectName: "exampleCommands"

            width: 520
            spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "picker.setValue([\"apple\", \"kale\"])"; variant: "secondary"; size: "small"; onClicked: picker.setValue(["apple", "kale"]) }
            SyButton { id: exampleControl2;  visible: true; text: "picker.clearValue()"; variant: "secondary"; size: "small"; onClicked: picker.clearValue() }
            SyButton { visible: true; text: "picker.open()"; variant: "secondary"; size: "small"; onClicked: picker.open() }
            SyButton { id: exampleControl3;  visible: true; text: "picker.close()"; variant: "secondary"; size: "small"; onClicked: picker.close() }
            SyButton { id: exampleControl4;  visible: true; text: "console.log(picker.reportValidity())"; variant: "secondary"; size: "small"; onClicked: output.log(picker.reportValidity()) }
        }
        Text {
            text: "picker.value === " + JSON.stringify(picker.value) + "   picker.isOpen === " + picker.isOpen
            font.family: Theme.monoFontFamily
            font.pixelSize: 12
            color: Theme.semantic.textSubtle
        }
        EventLog { id: output }
    }
}

04 Select multiple nodes

Select multiple nodes, configured with checkable, expandAll.

Select multiple nodes · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: true
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: true
        property bool line: false
        property bool required: false
        property bool disabled: false
        property bool readonly: false
        property bool loading: false
        property int maxTagCount: 0
        property bool appendParent: false
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

05 Read-only selection

Read-only selection, configured with readonly.

Read-only selection · Result — Qt capture · image

Default execution

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: false
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: false
        property bool line: false
        property bool required: false
        property bool disabled: false
        property bool readonly: true
        property bool loading: false
        property int maxTagCount: 0
        property bool appendParent: false
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect {
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

06 Loading nodes

Loading nodes, configured with loading.

Loading nodes · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: false
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: false
        property bool line: false
        property bool required: false
        property bool disabled: false
        property bool readonly: false
        property bool loading: true
        property int maxTagCount: 0
        property bool appendParent: false
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

07 Include parent nodes

Include parent nodes, configured with checkable, appendParent.

Include parent nodes · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: true
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: false
        property bool line: false
        property bool required: false
        property bool disabled: false
        property bool readonly: false
        property bool loading: false
        property int maxTagCount: 0
        property bool appendParent: true
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

08 Hierarchy connectors

Hierarchy connectors, configured with line, expandAll.

Hierarchy connectors · Opened — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "Interact with the controls to see event results."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "Category"
        property string placeholder: "Pick a category"
        property bool checkable: false
        property bool clearable: true
        property bool expandable: true
        property bool expandAll: true
        property bool line: true
        property bool required: false
        property bool disabled: false
        property bool readonly: false
        property bool loading: false
        property int maxTagCount: 0
        property bool appendParent: false
    }

    readonly property var nodes: [
        { value: "fruit", label: "Fruit", expanded: true, children: [
            { value: "apple", label: "Apple" },
            { value: "pear", label: "Pear" }
        ] },
        { value: "veg", label: "Vegetables", children: [
            { value: "kale", label: "Kale" },
            { value: "leek", label: "Leek" }
        ] }
    ]

    Column {
        spacing: 12
        SyTreeSelect { id: exampleControl1; 
            width: 260
            label: storyArgs.label
            placeholder: storyArgs.placeholder
            checkable: storyArgs.checkable
            clearable: storyArgs.clearable
            expandable: storyArgs.expandable
            expandAll: storyArgs.expandAll
            line: storyArgs.line
            required: storyArgs.required
            disabled: storyArgs.disabled
            readonly: storyArgs.readonly
            loading: storyArgs.loading
            maxTagCount: storyArgs.maxTagCount
            appendParent: storyArgs.appendParent
            nodes: story.nodes
            onChanged: (detail) => output.log(detail.selectedItem.map((i) => i.label).join(", "))
        }
        EventLog { id: output }
    }

}

09 Required field and reset

Compare the untouched field, validation error and reset result.

Required field and reset · Untouched — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Column {
    width: 440; spacing: 12
    SyTreeSelect {
        id: field; width: parent.width; name: "selection"; required: true
        label: "Required selection"; nodes: [{value: "design", label: "Design"}, {value: "dev", label: "Development"}]
        
        error: "Complete this field before continuing."
    }
    Row {
        spacing: 8
        SyButton { id: check; text: "Validate"; onClicked: field.reportValidity() }
        SyButton { id: reset; text: "Reset"; onClicked: field.reset() }
    }
    Text { text: "Status: " + (field.invalid ? "Invalid" : "Ready"); color: Theme.semantic.textDefault }
}

10 Custom error

Show an application-specific error, then reset the field.

Custom error · Untouched — Qt capture · image

QML code

import QtQuick
import Syidax.Core

Column {
    width: 440; spacing: 12
    SyTreeSelect {
        id: field; width: parent.width; name: "selection"; required: true
        label: "Required selection"; nodes: [{value: "design", label: "Design"}, {value: "dev", label: "Development"}]
        
        error: "This selection is currently unavailable. Choose another."
    }
    Row {
        spacing: 8
        SyButton { id: check; text: "Show error"; onClicked: field.setCustomError() }
        SyButton { id: reset; text: "Reset"; onClicked: field.reset() }
    }
    Text { text: "Status: " + (field.invalid ? "Invalid" : "Ready"); color: Theme.semantic.textDefault }
}

API 84

Hover or select an item for its QML example and copy button.

Properties

Type	Default	Description
list	`[]`	The tree model `[{ value, label, children, expanded, checked, disabled, icon, … }]` (as `SyTree`). Mirrors the tree's state after every change.
bool	`false`	Check boxes pick several nodes, shown as tags. Changing it clears the selection.
bool	`false`	An × that empties the selection while something is selected (not while disabled / readonly).
var	`""`	Re-apply it with `setValue(defaultValue)`.
string	`""`	Shown while nothing is selected and nothing typed.
string	`"default"`	`default` · `error` — `error` forces the error border.
bool	`false`	Carets on parents; otherwise every level shows.
bool	`false`	Opens every parent.
bool	`false`	Guide lines between levels.
bool	`false`	A spinner instead of the tree.
int	`0`	Tags shown before the rest fold into "+n"; `0` shows all.
real	`0`	A fixed row width (`0` = natural).
bool	`false`	The tree sits permanently under the box instead of a popup.
bool	`false`	Readable, nothing opens; always valid.
list	`[]`	`[{ value, label }]` — the pick, or the topmost checked nodes.
string	`""`	The filter text typed in the box.
string or list (read-only binding)	—	The picked value or, when checkable, the list of values.
read-only	—	The values of `selectedItem`
read-only	—	the first label.
bool (read-only)	—	The popup is open (always true with `appendParent`).
SyTree (read-only)	—	The inner tree, for `expandNode()`, `collapseNode()`, `findNode()`, …
bool (read-only)	—	Focus or open popup
bool (read-only)	—	pointer over the box.
string	`""`	The frame's title, form key, helper text and custom error copy.
string	`""`	The frame's title, form key, helper text and custom error copy.
string	`""`	The frame's title, form key, helper text and custom error copy.
string	`""`	The frame's title, form key, helper text and custom error copy.
string	`"medium"`	`small` · `medium` · `large` — box height 24 / 32 / 40 px.
bool	`false`	Dimmed and inert, always valid
bool	`false`	nothing selected is `valueMissing`.
read-only	—	Validity: `""` · `valueMissing` · `custom`; `invalid` once touched or reported.
read-only	—	Validity: `""` · `valueMissing` · `custom`; `invalid` once touched or reported.
read-only	—	Validity: `""` · `valueMissing` · `custom`; `invalid` once touched or reported.
real	`240`	The width when the app sets none.

Methods

Method	Description
	Picks from code — a value or a list. Checkable: unchecks all, checks these (subtrees follow). Single: the first found node. Unknown values are ignored. No signal.
	Empties the selection and the search text, marks touched, emits `changed`. Ignored while disabled / readonly.
	Opens the popup (marks touched; ignored while disabled, readonly or `appendParent`)
	closes it.
	Gives the search box keyboard focus
	takes it away and closes the popup.
	Whether the status is `""`, silently
	the same and reveals the error line.
	`""`, `"valueMissing"` or `"custom"`.
	Forces the `custom` status
	clears it.
	Restores `defaultValue` (the tree's checks follow) and clears the touched / submitted / custom flags. No signal.

Signals

Signal	Arguments	When
	`detail: { selectedItem, isValid }`	The user picked a node, checked or unchecked one (also through a tag's ×), or cleared. Not for `defaultValue`, `setValue()` or `reset()`.
	`detail: { selectedItem, isValid }`	The box gained / lost focus (focus marks the field touched).
	`detail: { selectedItem, isValid }`	The box gained / lost focus (focus marks the field touched).

Behavior

Item	Behavior / conditions
	The tree model `[{ value, label, children, expanded, checked, disabled, icon, … }]` (as `SyTree`). Mirrors the tree's state after every change.
	The picked value or, when checkable, the list of values.
	`nodes` is the `SyTree` model: a list of `{ value, label, children, expanded, checked, disabled, icon, … }`; `value` must be unique in the tree. without `checkable` the rows are clickable: a click selects the node, writes `selectedItem = [{ value, label }]`, shows its label in the box, clears the search text, emits `changed` and closes the popup.
	`nodes` is the `SyTree` model: a list of `{ value, label, children, expanded, checked, disabled, icon, … }`; `value` must be unique in the tree.
	`nodes` is the `SyTree` model: a list of `{ value, label, children, expanded, checked, disabled, icon, … }`; `value` must be unique in the tree. `disabled`: dimmed box, no interaction, no clear ×, always valid.
	Carets on parents; otherwise every level shows.
	Opens every parent.
	Guide lines between levels.
	A fixed row width (`0` = natural).
	Check boxes pick several nodes, shown as tags. Changing it clears the selection.
	`[{ value, label }]` — the pick, or the topmost checked nodes.
	The user picked a node, checked or unchecked one (also through a tag's ×), or cleared. Not for `defaultValue`, `setValue()` or `reset()`.
	Tags shown before the rest fold into "+n"; `0` shows all.
	The selection applied at creation and whenever it changes: a value, `"a,b"` or a list. Re-apply it with `setValue(defaultValue)`.
	Picks from code — a value or a list. Checkable: unchecks all, checks these (subtrees follow). Single: the first found node. Unknown values are ignored. No signal.
	Restores `defaultValue` (the tree's checks follow) and clears the touched / submitted / custom flags. No signal.
	The filter text typed in the box.
	under the box, as wide as it, at most 300 px tall (scrolls beyond), opened by a click on the box, by typing, by ArrowDown or `open()`; closed by Escape, a press outside, a single-mode pick or `close()`. With `appendParent` the tree is drawn inside the field right under the box, framed, and `open()` / `close()` do nothing. `readonly`: readable, nothing opens or types, the tags lose their ×, `clearValue()` / `open()` are ignored, always valid. The field counts as touched as soon as the box gains focus (or on a pick, a clear, `open()`), so a required empty field shows its error line right after it is focused — earlier than the other fields, which wait for a blur.
	under the box, as wide as it, at most 300 px tall (scrolls beyond), opened by a click on the box, by typing, by ArrowDown or `open()`; closed by Escape, a press outside, a single-mode pick or `close()`. With `appendParent` the tree is drawn inside the field right under the box, framed, and `open()` / `close()` do nothing.
	The popup is open (always true with `appendParent`).
	The tree sits permanently under the box instead of a popup.
	A spinner instead of the tree.
	Readable, nothing opens; always valid.
	Empties the selection and the search text, marks touched, emits `changed`. Ignored while disabled / readonly.
	`default` · `error` — `error` forces the error border.
	`status: "error"` forces the error border.
	`hasFocus` is true while the box has focus or the popup is open.
	`required` with nothing selected → `valueMissing`; `setCustomError()` → `custom`; disabled or readonly → `""`.
	`required` with nothing selected → `valueMissing`; `setCustomError()` → `custom`; disabled or readonly → `""`.
	`name` keys the field in `SyForm.values()`: the value, or the list of values when checkable.
	`name` keys the field in `SyForm.values()`: the value, or the list of values when checkable.
	`small` · `medium` · `large` — box height 24 / 32 / 40 px.
	The width when the app sets none.
	the box is `size` high (24 / 32 / 40 px) and grows with the tag rows; the width is `preferredWidth` 240 unless the app sets `width`.

Keyboard

Item	Behavior / conditions
	Keyboard: Tab and Shift+Tab enter and leave the field. Hidden and disabled fields are skipped. Escape closes an open picker before continuing. Textarea uses Tab for focus navigation, including inside a modal; it does not insert indentation.

One design language.Native applications.

Components

From download to your first window

C++ · CMake

Python · PySide6

Tested Windows configurations

Two complete application examples

See the components in context

The native Gallery

QML Core

Troubleshooting

Tree Select

Supported QML types

Learn by example

01 Basic composition

02 changed

03 setValue · clearValue · open · close · reportValidity

04 Select multiple nodes

05 Read-only selection

06 Loading nodes

07 Include parent nodes

08 Hierarchy connectors

09 Required field and reset

10 Custom error

Properties

Methods

Signals

Behavior

Keyboard

One design language.
Native applications.