Scrollable pages and list views

Scrollable pages are useful when combined with vertical components or dynamic components such as List Views.

Kirigami.ScrollablePage

A Kirigami.ScrollablePagearrow-up-right is a page that holds scrollable content, such as a ListViewarrow-up-right. Scrolling, as well as scrolling indicators, are automatically managed.

Kirigami.ScrollablePage {
    id: root
    //The rectangle will automatically be scrollable
    Rectangle {
        width: root.width
        height: 99999
    }
}

In almost every other way, a scrollable page is the same as a normal page.

circle-exclamation

ListView in a ScrollablePage

When the direct children of a Kirigami.ScrollablePagearrow-up-right extend vertically beyond the size of the page itself, a scrollbar appears at the right edge of the page and the page will be scrollable.

Two scrollable pages, both containing a ListView with custom contents (screenshot of NeoChat)

Often you have more than one child in your Kirigami.ScrollablePagearrow-up-right, and positioning items can be tricky—especially in combination with a ListViewarrow-up-right.

  • For non-visual components, having them inside the ListViewarrow-up-right component won't change the visuals of the page, so we can move them inside the scope of the list view. Same for elements anchored to the center of the page, such as placeholder messages for empty list views.

  • For other items, it might make sense to move them to the header or footer of the Kirigami.ScrollablePagearrow-up-right. This is often the case for search bars.

PlaceholderMessage

It is possible to add a Kirigami.PlaceholderMessagearrow-up-right with some instructions in case the list view is empty.

Search in the ListView

A search field is often added to a Kirigami.ScrollablePagearrow-up-right to filter the ListViewarrow-up-right. This can be done by changing the default titleDelegatearrow-up-right to use a Kirigami.SearchFieldarrow-up-right instead.

circle-info

Hint

You can use KSortFilterProxyModelarrow-up-right from KItemModelarrow-up-right to easily add filtering capability directly in QML without any need for C++ code.

Pull to refresh

Another function provided by this component is a "pull-to-refresh" action. To use this, activate it as follows:

By pulling down, you can also activate a special mode with a larger top margin which makes single-handed use of the application easier.

Last updated