QML
← All components

Checkbox

Turn an option on or off, or select multiple independent options from a list.

import Syidax.Core.Checkbox

Supported QML types

TypeDefinition / role
Checkbox field for an independent on/off choice, including an indeterminate state.

Learn by example

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

01 Basic composition

SyCheckbox is a 16 px box with its label (text) beside it that the user checks and unchecks.

Qt capture · image
Basic composition · Default
Default execution
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    property QtObject settings: QtObject {
        id: storyArgs
        property string text: "I agree to the terms"
        property bool checked: false
        property bool indeterminate: false
        property bool disabled: false
        property bool readonly: false
        property bool required: false
        property string message: ""
    }

    

    SyCheckbox {
        text: storyArgs.text
        checked: storyArgs.checked
        indeterminate: storyArgs.indeterminate
        disabled: storyArgs.disabled
        readonly: storyArgs.readonly
        required: storyArgs.required
        message: storyArgs.message
        onCheckedChanged: if (storyArgs.checked !== checked) storyArgs.checked = checked
        onIndeterminateChanged: if (storyArgs.indeterminate !== indeterminate) storyArgs.indeterminate = indeterminate
    }

}

02 disabled · readonly

disabled: true grays the box and the label and makes them inert: no click, no Space, Tab skips the box, the cursor stays an arrow.

Qt capture · image
disabled · readonly · Default
Default execution
QML code
import QtQuick
import Syidax.Core

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

    Column {
        spacing: 8
        SyCheckbox { id: featureTarget0; visible: true; text: "Disabled"; disabled: true }
        SyCheckbox { id: featureTarget1; visible: true; text: "Disabled"; disabled: true; checked: true }
        SyCheckbox { id: featureTarget2; visible: true; text: "Read only"; readonly: true }
        SyCheckbox { id: featureTarget3; visible: true; text: "Read only"; readonly: true; checked: true }
    }
}

03 indeterminate

indeterminate: true draws a dash instead of the check mark — the "some of them" state of a box that stands for a group, such as a Select-all box over rows of which only some are checked.

Qt capture · image
indeterminate · Default
Default execution
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    Column {
        spacing: 8
        SyCheckbox {
            id: all
            text: "Select all"
            checked: a.checked && b.checked && c.checked
            indeterminate: !checked && (a.checked || b.checked || c.checked)
            onCheckedChanged: { a.checked = checked; b.checked = checked; c.checked = checked }
        }
        Column {
            spacing: 8
            leftPadding: 20
            SyCheckbox { id: a; text: "Design"; checked: true }
            SyCheckbox { id: b; text: "Development" }
            SyCheckbox { id: c; text: "QA" }
        }
    }
}

04 changed · focused · blured

The box has three signals.

Qt capture · image
changed · focused · blured · Default
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
    // Focused Gallery routes: keep only the selected API and its prerequisites.
    id: featureStory

    

    Column {
        spacing: 12
        SyCheckbox {
            text: "Subscribe to the newsletter"
            onChanged: (detail) => { if (true) { output.log(("changed: checked %1 · indeterminate %2").arg(detail.checked).arg(detail.indeterminate)) } }
            onFocused: { if (true) { output.log("focused") } }
            onBlured: { if (true) { output.log("blured") } }
        }
        EventLog { id: output }
    }
}

05 toggle · setFocus · checkValidity · …

The box's functions, all shown by the buttons in the demo (a required "I agree" box):

Qt capture · image
toggle · setFocus · checkValidity · … · Default
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: featureStory

    Column {
        spacing: 12
        SyCheckbox { id: terms; text: "I agree to the terms"; required: true }
        Flow {
            width: 560
            spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "terms.toggle()"; variant: "secondary"; size: "small"; onClicked: terms.toggle() }
            SyButton { id: exampleControl2;  visible: true; text: "terms.setFocus()"; variant: "secondary"; size: "small"; onClicked: terms.setFocus() }
            SyButton { id: exampleControl3;  visible: true; text: "terms.checkValidity()"; variant: "secondary"; size: "small"; onClicked: output.log("checkValidity() → " + terms.checkValidity()) }
            SyButton { visible: true; text: "terms.reportValidity()"; variant: "secondary"; size: "small"; onClicked: output.log("reportValidity() → " + terms.reportValidity()) }
            SyButton { visible: true; text: "terms.getValidStatus()"; variant: "secondary"; size: "small"; onClicked: output.log("getValidStatus() → " + JSON.stringify(terms.getValidStatus())) }
            SyButton { visible: true; text: "terms.setCustomError()"; variant: "secondary"; size: "small"; onClicked: terms.setCustomError() }
            SyButton { visible: true; text: "terms.clearCustomError()"; variant: "secondary"; size: "small"; onClicked: terms.clearCustomError() }
        }
        EventLog { id: output }
    }
}

06 Partially selected

Partially selected, configured with indeterminate, checked.

Qt capture · image
Partially selected · Result
Default execution
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    property QtObject settings: QtObject {
        id: storyArgs
        property string text: "I agree to the terms"
        property bool checked: false
        property bool indeterminate: true
        property bool disabled: false
        property bool readonly: false
        property bool required: false
        property string message: ""
    }

    

    SyCheckbox {
        text: storyArgs.text
        checked: storyArgs.checked
        indeterminate: storyArgs.indeterminate
        disabled: storyArgs.disabled
        readonly: storyArgs.readonly
        required: storyArgs.required
        message: storyArgs.message
        onCheckedChanged: if (storyArgs.checked !== checked) storyArgs.checked = checked
        onIndeterminateChanged: if (storyArgs.indeterminate !== indeterminate) storyArgs.indeterminate = indeterminate
    }

}

07 Required field and reset

Compare the untouched field, validation error and reset result.

Qt capture · image
Required field and reset · Untouched
QML code
import QtQuick
import Syidax.Core

Column {
    width: 440; spacing: 12
    SyCheckbox {
        id: field; width: parent.width; name: "selection"; required: true
        text: "Required selection"
        
        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 }
}

08 Custom error

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

Qt capture · image
Custom error · Untouched
QML code
import QtQuick
import Syidax.Core

Column {
    width: 440; spacing: 12
    SyCheckbox {
        id: field; width: parent.width; name: "selection"; required: true
        text: "Required selection"
        checked: true
        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 69

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

Properties

ItemBehavior / conditions
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.
The shared field properties (name, label, required, disabled, message, error, touched, submitted, customError, validStatus, valid, invalid, showTitle, ready) are described on the Form page; the ones below are the checkbox's own or have checkbox-specific meaning.

Properties

PropertyTypeDefaultDescription
boolfalseThe state. Flipped by clicks, Space and toggle(); every change emits changed.
boolfalseDraws the dash (the "some of them" look) on top of the state. The next click checks the box and clears it. No changed on its own.
string""The label beside the box; clicking it toggles too.
Item…—Default property: items declared inside go after the label text, 4 px apart, centered.
string"on"What the owning SyForm submits under name while checked.
var (read-only)—value while checked, null otherwise — what SyForm.values() stores.
string""Key in the owning SyForm's values().
boolfalseUnchecked → valueMissing.
boolfalseInert and grayed; not a Tab stop; always valid; not submitted.
boolfalseFocusable but unchangeable; always valid; still submitted.
string""Hover text: shown as a SyTooltip when the pointer rests on the checkbox.
string""Helper line under the row
string""custom error copy for the required check.
string""Inherited title line above the row; normally left empty.
string"medium"Inherited; has no effect on the checkbox.
bool (read-only)—The box has active focus
bool (read-only)—the pointer is over the row (false while disabled).
string (read-only)—unchecked · checked · indeterminate.
string (read-only)—enabled · hover · focus · readonly · disabled.

Methods

MethodDescription
The click: indeterminate → checked, otherwise flip checked. Ignored while disabled or readonly.
Give the box keyboard focus / take it away (focused / blured fire; the blur sets touched).
Give the box keyboard focus / take it away (focused / blured fire; the blur sets touched).
true unless a required box is unchecked (or a custom error is set). Silent.
Same verdict, and the error line shows from now on.
"" · valueMissing · custom.
"" · valueMissing · custom.
Force / lift the custom status; the error shows at once.
Force / lift the custom status; the error shows at once.
Restores checked (to initialChecked, the value the control was created with) and value, and clears the touched, reported and custom flags.

Signals

SignalArgumentsWhen
detail: { value: bool, isValid: bool, checked: bool, indeterminate: bool } — value is the new checkedchecked changed after load, by the user or from code. Not for the initial value, not when only indeterminate changes.
trueThe box gained active focus.
falseThe box lost focus; touched is set first.

Behavior

ItemBehavior / conditions
The state. Flipped by clicks, Space and toggle(); every change emits changed.
The click: indeterminate → checked, otherwise flip checked. Ignored while disabled or readonly.
checked changed after load, by the user or from code. Not for the initial value, not when only indeterminate changes.
Draws the dash (the "some of them" look) on top of the state. The next click checks the box and clears it. No changed on its own.
value while checked, null otherwise — what SyForm.values() stores.
What the owning SyForm submits under name while checked.
Key in the owning SyForm's values().
Unchecked → valueMissing.
required makes an unchecked box valueMissing; the error line under the row ("This field is required", or error) appears once the box was left (touched) or reported (submitted).
required makes an unchecked box valueMissing; the error line under the row ("This field is required", or error) appears once the box was left (touched) or reported (submitted).
required makes an unchecked box valueMissing; the error line under the row ("This field is required", or error) appears once the box was left (touched) or reported (submitted).
Inert and grayed; not a Tab stop; always valid; not submitted.
Focusable but unchangeable; always valid; still submitted.
Tab stops on the box unless it is disabled (a read-only box is still a Tab stop); Space toggles; Enter does nothing. The focus ring is drawn around the box while it has focus and is not disabled. The hand cursor shows while the box is interactive, the arrow while disabled or read-only.
disabled grays the box and the label, blocks every interaction and the Tab stop, and the box is skipped by SyForm.values().
Tones: disabled > readonly > focus > hover > enabled, each in the current mode.
Tones: disabled > readonly > focus > hover > enabled, each in the current mode.
The box gained active focus.
The box lost focus; touched is set first.
Inherited; has no effect on the checkbox.
Inherited title line above the row; normally left empty.
The label beside the box; clicking it toggles too.
Colors come from Theme.checkbox by mode and state and follow Theme.scheme.