SortFilterProxyModel QML Type

Provides sorting and filtering capabilities for a QAbstractItemModel. More...

Import Statement: import QtQml.Models
Since: Qt 6.10
Status: Preliminary

This type is under development and is subject to change.

Properties

Methods

Detailed Description

SortFilterProxyModel inherits from QAbstractProxyModel, which handles the transformation of source indexes into proxy indexes. Sorting and filtering are controlled via the sorters and filters properties, which determine the order of execution as specified in QML. This order can be overridden using the priority property available for each sorter. By default, all sorters share the same priority.

SortFilterProxyModel enables users to sort and filter a QAbstractItemModel. The item views such as TableView or TreeView can utilize this proxy model to display filtered content.

Note: Currently, SortFilterProxyModel supports only QAbstractItemModel as the source model.

The snippet below shows the configuration of sorters and filters in the QML SortFilterProxyModel:

ProcessModel { id: processModel }

SortFilterProxyModel {
    id: sfpm
    model: processModel
    sorters: [
        RoleSorter: {
            roleName: "user"
            priority: 0
        },
        RoleSorter: {
            roleName: "pid"
            priority: 1
        }
    ]
    filters: [
        FunctionFilter: {
            component RoleData: QtObject { property qreal cpuUsage }
            function filter(data: RoleData) : bool {
                return (data.cpuUsage > 90)
            }
        }
    ]
}

The SortFilterProxyModel dynamically sorts and filters data whenever there is a change to the data in the source model and can be disabled through the dynamicSortFilter property.

The sorters RoleSorter, ValueSorter and StringSorter can be configured in SortFilterProxyModel. Each sorter can be configured with a specific column index through column property. If a column index is not specified, the sorting will be applied to the column index 0 of the model by default. The execution order of the sorter can be modified through the priority property. This is particularly useful when performing hierarchical sorting, such as sorting data in the first column and then applying sorting to subsequent columns.

To disable a specific sorter, enabled can be set to false.

The sorter priority can also be overridden by setting the primary sorter through the method call setPrimarySorter. This would be helpful in the case where the view wants to sort the data of any specific column by clicking on the column header such as in TableView, when there are other sorters also configured for the model.

The filter ValueFilter and FunctionFilter can be configured in SortFilterProxyModel. Each filter can be set with the column property, similar to the sorter, to filter data in a specific column. If no column is specified, then the filter will be applied to all the column indexes in the model. To reduce the overhead of unwanted checks during filtering, it's recommended to specify the column index.

To disable a specific filter, enabled can be set to false.

ListModel {
    id: listModel
    ListElement { name: "Adan"; age: 25; department: "Process"; pid: 209711; country: "Norway" }
    ListElement { name: "Hannah"; age: 48; department: "HR"; pid: 154916; country: "Germany" }
    ListElement { name: "Divina"; age: 63; department: "Marketing"; pid: 158038; country: "Spain" }
    ListElement { name: "Rohith"; age: 35; department: "Process"; pid: 202582; country: "India" }
    ListElement { name: "Latesha"; age: 23; department: "Quality"; pid: 232582; country: "UK" }
}

SortFilterProxyModel {
    id: ageFilterModel
    model: listModel
    filters: [
        FunctionFilter {
            roleData: QtObject { property int age }
            function filter(data: QtObject) : bool {
                return data.age > 30
            }
        }
    ]
    sorters: [
        RoleSorter { roleName: "department" }
    ]
}

ListView {
    anchors.fill: parent
    clip: true
    model: sfpm
    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1
        Text {
            text: name
            anchors.centerIn: parent
        }
    }
}

Note: This API is considered tech preview and may change or be removed in future versions of Qt.

Property Documentation

autoAcceptChildRows : bool

This property will not filter out children of accepted rows. The behavior is similar to that of autoAcceptChildRows in QSortFilterProxyModel.

The default value is false.


dynamicSortFilter : bool

This property holds whether the proxy model is dynamically sorted and filtered whenever the contents of the source model change.

The default value is true.


filters : list<Filter>

This property holds the list of filters for the SortFilterProxyModel. If no priority is set, the SortFilterProxyModel applies a filter in the order as specified in the list.


model : var

This property allows to set source model for the sort filter proxy model.


recursiveFiltering : bool

This property allows all the configured filters to be applied recursively on children. The behavior is similar to that of recursiveFilteringEnabled in QSortFilterProxyModel.

The default value is false.


sorters : list<Sorter>

This property holds the list of sorters for the SortFilterProxyModel. If no priority is set, the SortFilterProxyModel applies a sorter in the order as specified in the list.


Method Documentation

invalidate()

This method invalidates the model by reevaluating the configured filters and sorters on the source model data.


invalidateSorter()

This method force the sort filter proxy model to reevaluate the configured sorters against the data. It can used in the case where dynamic sorting was disabled through property dynamicSortFilter


setPrimarySorter(sorter)

This method allows to set the primary sorter in the sort filter proxy model. The primary sorter will be evaluated before all other sorters configured as part of sorter property. If not configured or passed null, the sorter with higher priority shall be considered as the primary sorter.


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.