Patterns

Showing collections

Lists, grids, tables and tabs all show many things at once. Which one fits depends on what the things are.

List, grid or table?

The items are… Use Built with
Mostly text: names, messages, settings A list ListView and list items
Mostly visual: photos, covers, apps A grid, or cards GridView, Kirigami.CardsLayout
Records with three or more fields worth comparing A table TableView

If you are tempted to make a table with two columns, make a list with a title and a subtitle instead.

A list of four network connections, each with an icon, a name and a smaller status line; the first is highlightedA list of four network connections, each with an icon, a name and a smaller status line; the first is highlighted
Two fields per item fit a list comfortably: one as the title, one as the subtitle.
Show the QML for this example
import QtQuick
import QtQuick.Controls as QQC2
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

// Two lines per item: a title and a quieter subtitle.
QQC2.ScrollView {
    width: Kirigami.Units.gridUnit * 20
    height: Kirigami.Units.gridUnit * 11

    Kirigami.Theme.colorSet: Kirigami.Theme.View
    Kirigami.Theme.inherit: false
    background: Rectangle {
        color: Kirigami.Theme.backgroundColor
    }

    ListView {
        currentIndex: 0

        model: ListModel {
            ListElement { name: "Home Wi-Fi"; detail: "Connected, excellent signal"; glyph: "network-wireless" }
            ListElement { name: "Office"; detail: "Saved, out of range"; glyph: "network-wireless" }
            ListElement { name: "Wired connection"; detail: "Cable unplugged"; glyph: "network-wired" }
            ListElement { name: "Work VPN"; detail: "Not connected"; glyph: "network-vpn" }
        }

        delegate: KD.SubtitleDelegate {
            required property string name
            required property string detail
            required property string glyph

            width: ListView.view.width
            text: name
            subtitle: detail
            icon.name: glyph
            highlighted: ListView.isCurrentItem
        }
    }
}

Avoid trees

Tree views, with rows that expand into indented child rows, are hard to use with touch and easy to get lost in. Prefer a list with section headers, a list that pushes a new page, or collapsible sections.

Making lists easy to scan

  • Make the selected or active item stand out. The highlight colour marks the current row; bold text marks the item that is in use, such as the connected network or the playing track.
  • Vary the icons, or leave them out. A column of identical icons tells nobody anything.
  • Striped rows help the eye in wide lists and tables. Turn them on with Kirigami.Theme.useAlternateBackgroundColor: true on the view; do not paint them yourself.
  • Group long lists under section headers.

Adding and removing items

A list of three accounts under a header bar reading Accounts, with an Add Account button at its right endA list of three accounts under a header bar reading Accounts, with an Add Account button at its right end
The button that adds to this list lives in the list’s own header.
Show the QML for this example
import QtQuick
import QtQuick.Controls as QQC2
import org.kde.kirigami as Kirigami

// Controls for the list itself sit in a header that belongs to the list.
QQC2.ScrollView {
    width: Kirigami.Units.gridUnit * 20
    height: Kirigami.Units.gridUnit * 10

    Kirigami.Theme.colorSet: Kirigami.Theme.View
    Kirigami.Theme.inherit: false
    background: Rectangle {
        color: Kirigami.Theme.backgroundColor
    }

    ListView {
        currentIndex: -1
        model: ["Konqi", "Katie", "Kandalf"]

        headerPositioning: ListView.OverlayHeader
        header: Kirigami.InlineViewHeader {
            width: ListView.view.width
            text: "Accounts"
            actions: [
                Kirigami.Action {
                    text: "Add Account"
                    icon.name: "list-add"
                }
            ]
        }

        delegate: QQC2.ItemDelegate {
            required property string modelData

            width: ListView.view.width
            text: modelData
            icon.name: "user"
        }
    }
}
  • Controls that add to a list belong to the list. Put them in a Kirigami.InlineViewHeader at the top of the view, not far away in the window’s toolbar.
  • Controls that act on one row go on that row, at its trailing end, as icon-only buttons. Keep them always visible; a button that appears only on hover does not exist for touch users. Use at most two per row, and preferably none or one.
  • Removing should be easy to undo. See Feedback and status.

Tabs

There are two kinds of tabs and they should not be confused.

Kind What the tabs are Component Placement
Navigation tabs The fixed places of your app Kirigami.NavigationTabBar Above content on desktop, below on phones
Document tabs Things the user opened: web pages, files, chats QQC2.TabBar Above the content, full width

Document tabs can be closed and reordered by the user, so each needs a close button. Hide the tab bar when only one tab is open.

Tabs do not scale. As a way to split one view into sections they stop working beyond four or five tabs on a desktop, and two on a phone. If you have more, use a list that leads to pages.

Showing extra detail

The detail is… Show it…
Large enough to fill the window On a new page
Read-only and possibly long In an overlay sheet
A question or a small form In a dialog

Anything that floats over the content needs a visible edge, so it does not melt into the background in dark colour schemes. Kirigami’s own sheets, dialogs and cards have one.

Where this comes from

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