Form layouts

Kirigami.FormLayout components make it easy to create forms that follow the Human Interface Guidelines. They are ideal for settings dialogs and for large groups of related controls and input fields.

With enough space, form layouts take up two columns. The left column holds the labels of the form's child components, and the right column holds the components themselves. In narrower windows (or on mobile), forms become a single vertical column, with each label placed above its component.

#Simple form

Kirigami.FormLayout components are used much like Qt Quick Layouts such as ColumnLayout or RowLayout. The child components are arranged automatically according to the space available to the form layout.

Children of a Kirigami.FormLayout have an attached property named Kirigami.FormData.label, which sets the label shown for that child.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    pageStack.initialPage: Kirigami.Page {

        Kirigami.FormLayout {
            anchors.fill: parent

            Controls.TextField {
                Kirigami.FormData.label: "TextField 1:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 2:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 3:"
            }
        }
    }
}

#Sections and separators

Form layouts can also be divided into sections. To start a section, set a child component's Kirigami.FormData.isSection to true. This gives the component some extra margin at the top to mark the start of the new section.

Kirigami.Separator components are best suited for starting new sections. A separator draws a thin horizontal line marking the end of a section. If you'd rather not have a line between sections, use a plain QML Item instead. You could also set Kirigami.FormData.isSection on any other component, but this isn't recommended.

On a component whose Kirigami.FormData.isSection is true, the text of its Kirigami.FormData.label is shown as the section's header text. This doesn't work well with every component, hence the recommendation to use Kirigami.Separator or Item components where you want header text.

The header text is larger than the normal label text and gives users a clear visual cue of what the section is about.

Kirigami.FormLayout {
    anchors.fill: parent

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
    Kirigami.Separator {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "New Section!"
    }
    ColumnLayout {
        Kirigami.FormData.label: "Radio buttons"
        Controls.RadioButton {
            text: "Radio 1"
            checked: true
        }
        Controls.RadioButton {
            text: "Radio 2"
        }
        Controls.RadioButton {
            text: "Radio 3"
        }
    }
    Item {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "Another Section! (lineless though)"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 4:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
}

#Forcing a desktop or mobile layout

If you want your form layout to look the same whatever the application's environment, use the wideMode property of Kirigami.FormLayout:

• When true, the form layout uses a desktop-optimized wide (two-column) layout.
• When false, the form layout uses a mobile layout (single column).

Kirigami.FormLayout {
    anchors.fill: parent
    wideMode: false

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
}

#Aligning your labels

Sometimes you want a label for a component with more than one line, or for a list of components. You do this by setting Kirigami.FormData.label on a ColumnLayout, as you may have noticed in Sections and separators. By default the label is placed in the vertical center of the layout, which isn't always what you want. You can change this with Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: Qt.AlignTop

        Controls.Label {
            text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
            elide: Text.ElideLeft
        }
    }
}

Setting the label alignment is particularly useful for components, or lists of components, whose size you don't know in advance. For example, you can align the label to the top only when the text needs more than one line, with a JavaScript ternary operator:

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: labelText.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

        Controls.Label {
            id: labelText
            text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
            elide: Text.ElideLeft
        }
    }
}