Patterns

Choosing controls

Which control to use for which kind of question, and how to explain a setting without cluttering the page.

A form with five rows: a switch for Night light, a checkbox for restoring windows on startup, two radio buttons for what clicking files does, a combo box for language, and a slider with a number box for volumeA form with five rows: a switch for Night light, a checkbox for restoring windows on startup, two radio buttons for what clicking files does, a combo box for language, and a slider with a number box for volume
Five kinds of question, five controls. All are ordinary Qt Quick Controls in a form layout.
Show the QML for this example
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as QQC2
import org.kde.kirigami as Kirigami

Item {
    implicitWidth: Kirigami.Units.gridUnit * 28
    implicitHeight: form.implicitHeight

    Kirigami.FormLayout {
        id: form
        anchors.fill: parent

        QQC2.Switch {
            Kirigami.FormData.label: "Night light:"
            checked: true
        }

        QQC2.CheckBox {
            Kirigami.FormData.label: "On startup:"
            text: "Restore open windows"
            checked: true
        }

        ColumnLayout {
            Kirigami.FormData.label: "Clicking files:"
            Kirigami.FormData.buddyFor: firstRadio
            spacing: Kirigami.Units.smallSpacing

            QQC2.RadioButton {
                id: firstRadio
                text: "Opens them"
            }
            QQC2.RadioButton {
                text: "Selects them"
                checked: true
            }
        }

        QQC2.ComboBox {
            Kirigami.FormData.label: "Language:"
            model: ["English", "Deutsch", "Español", "Français", "日本語"]
        }

        RowLayout {
            Kirigami.FormData.label: "Volume:"
            Kirigami.FormData.buddyFor: volume
            spacing: Kirigami.Units.smallSpacing

            QQC2.Slider {
                id: volume
                from: 0
                to: 100
                value: 65
            }
            QQC2.SpinBox {
                from: 0
                to: 100
                value: volume.value
            }
        }
    }
}

The right control for the question

The user is… Use Notes
Turning something on or off, effective at once QQC2.Switch Flipping it is the action; there is no Apply.
Turning something on or off, otherwise QQC2.CheckBox Also the right choice for ticking items in a list.
Picking one of two or three options QQC2.RadioButton All options stay visible. Keep their texts short.
Picking one of up to about ten QQC2.ComboBox
Picking one of more than ten A scrollable list A long drop-down is hard to scan and to scroll.
Setting a rough amount quickly QQC2.Slider Volume, brightness, zoom.
Setting an exact number QQC2.SpinBox
Both rough and exact A slider followed by a spin box As in the last row of the picture.
Typing text A text field
Picking a file or folder FileDialog from QtQuick.Dialogs Never build your own file picker.

Buttons

Where Use
On a toolbar QQC2.ToolButton, or better, actions
Floating over content, one main action QQC2.RoundButton, icon only
Everywhere else QQC2.Button

A button that opens a menu shows a small downward arrow. A button whose action needs more input before anything happens ends its label with an ellipsis: “Save As…”.

Rules that apply to all of them

☑ Mute notifications
Do

Keep the label fixed and let the control show the state.

Mute → Unmute
Don’t

Change a control’s label or icon when it is switched. Nobody can tell whether the text names the state or the action.

  • Order options logically: smallest to largest, most to least common. When there is no natural order, sort alphabetically.
  • Use web-style links only for web addresses. An underlined link opens something in the browser. Do not use one to move around inside your app; that is what buttons and list items are for.
  • Check text as it is typed. If the input is not valid, say why in an inline message and disable the confirm button until it is.
  • Apply settings at once. A changed setting should take effect immediately, without asking for a restart.

Explaining a control

Good labels need no explanation. When one is needed anyway, choose the lightest form that works:

Two settings. Under the first checkbox is a small grey sentence of explanation. Next to the second checkbox is a small round i button.Two settings. Under the first checkbox is a small grey sentence of explanation. Next to the second checkbox is a small round i button.
Top: one sentence under the control. Bottom: a help button for an explanation too long to show all the time.
Show the QML for this example
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as QQC2
import org.kde.kirigami as Kirigami

Item {
    implicitWidth: Kirigami.Units.gridUnit * 28
    implicitHeight: form.implicitHeight

    Kirigami.FormLayout {
        id: form
        anchors.fill: parent

        // Short help: one sentence right under the control.
        QQC2.CheckBox {
            Kirigami.FormData.label: "Updates:"
            text: "Install automatically"
            checked: true
        }
        QQC2.Label {
            text: "Updates are installed the next time the system restarts."
            font: Kirigami.Theme.smallFont
            opacity: 0.75
        }

        Item {
            Kirigami.FormData.isSection: true
        }

        // Longer help: a help button that opens a popup.
        RowLayout {
            Kirigami.FormData.label: "Privacy:"
            spacing: Kirigami.Units.smallSpacing

            QQC2.CheckBox {
                text: "Share usage statistics"
            }
            Kirigami.ContextualHelpButton {
                toolTipText: "Anonymous numbers such as how often the app is opened. No file names or personal data are sent."
            }
        }
    }
}
The explanation is… Use
One short sentence about one control A label directly under the control
One or two sentences about the whole page Text at the top of the page
Longer, and only some people need it Kirigami.ContextualHelpButton beside the control
Much longer A “Details” or “Show More” section, or a separate page
RowLayout {
    Kirigami.FormData.label: "Privacy:"

    QQC2.CheckBox {
        text: "Share usage statistics"
    }
    Kirigami.ContextualHelpButton {
        toolTipText: "Anonymous numbers such as how often the app is opened."
    }
}

Where this comes from

This page restates the upstream KDE documentation in plainer words and adds pictures. When the two disagree, upstream wins.