SearchField QML Type | Qt Quick Controls | Qt 6.10.3
Description: A specialized input field designed to use for search functionality.

- Qt 6.10
- Qt Quick Controls
- QML Types
- SearchField
- Qt 6.10.3 Reference Documentation

# SearchField QML Type

A specialized input field designed to use for search functionality. More...

Import Statement: | `import QtQuick.Controls`
Since: | Qt 6.10
Inherits: | Control

- List of all members, including inherited members

## Properties

- clearIndicator : real
- currentIndex : int
- delegate : Component
- delegateModel : model
- highlightedIndex : int
- live : bool
- popup : Popup
- searchIndicator : real
- suggestionCount : int
- suggestionModel : model
- text : string
- textRole : string

## Signals

- void accepted()
- void activated(int index)
- void highlighted(int index)
- void searchTriggered()
- void textEdited()

## Detailed Description

SearchField is a specialized input field designed to use for search functionality. The control includes a text field, search and clear icons, and a popup that displays suggestions or search results.

Note: The iOS style does not provide a built-in popup for SearchField in order to preserve the native look and feel. If a popup is still wanted, it has to be defined by the user.

## SearchField Model Roles

SearchField is able to visualize standard data models that provide the `modelData` role:

- models that have only one role
- models that do not have named roles (JavaScript array, integer)

When using models that have multiple named roles, SearchField must be configured to use a specific text role for its text and delegate instances.

     ListModel {
         id : fruitModel
         ListElement { name: "Apple"; color: "green" }
         ListElement { name: "Cherry"; color: "red" }
         ListElement { name: "Banana"; color: "yellow" }
         ListElement { name: "Orange"; color: "orange" }
         ListElement { name: "WaterMelon"; color: "pink" }
     }

     SortFilterProxyModel {
         id: fruitFilter
         model: fruitModel
         sorters: [
             RoleSorter {
                 roleName: "name"
             }
         ]
         filters: [
             FunctionFilter {
                 component CustomData: QtObject { property string name }
                 property var regExp: new RegExp(fruitSearch.text, "i")
                 onRegExpChanged: invalidate()
                 function filter(data: CustomData): bool {
                     return regExp.test(data.name);
                 }
             }
         ]
     }

     SearchField {
         id: fruitSearch
         suggestionModel: fruitFilter
         textRole: "name"
         anchors.horizontalCenter: parent.horizontalCenter
     }

## Property Documentation

clearIndicator : real `[read-only]`

This property holds the clear indicator.

currentIndex : int

This property holds the index of the currently selected suggestion in the popup list.

Its value is `-1` when no suggestion is selected.

currentIndex is not modified automatically when the model changes or when the user types or edits text. It is updated only when the user explicitly selects a suggestion, either by clicking an item in the popup, or by pressing Enter on a highlighted item.

currentIndex can be set; for example, to display the first item in the model at startup. Before doing so, ensure that the model is not empty:

     SearchField {
         id: searchField
         suggestionModel: ListModel {
             ListElement { value: "123,456" }
         }
         textRole: "value"

         Component.onCompleted: {
             if (suggestionModel.count > 0) {
                text = suggestionModel.get(0).value
                currentIndex = 0
            }
         }
     }

See also activated(), text, and highlightedIndex.

delegate : Component

This property holds a delegate that presents an item in the search field popup.

It is recommended to use ItemDelegate (or any other AbstractButton derivatives) as the delegate. This ensures that the interaction works as expected, and the popup will automatically close when appropriate. When other types are used as the delegate, the popup must be closed manually. For example, if MouseArea is used:

     delegate: Rectangle {
         // ...
         MouseArea {
             // ...
             onClicked: searchField.popup.close()
         }
     }

delegateModel : model `[read-only]`

This property holds the model that provides delegate instances for the search field.

It is typically assigned to a ListView in the contentItem of the popup.

highlightedIndex : int `[read-only]`

This property holds the index of the currently highlighted item in the popup list.

When the highlighted item is activated, the popup closes, currentIndex is updated to match `highlightedIndex`, and this property is reset to `-1`, indicating that no item is currently highlighted.

See also highlighted() and currentIndex.

live : bool

This property holds a boolean value that determines whether the search is triggered on every text edit.

When set to `true`, the searchTriggered() signal is emitted on each text change, allowing you to respond to every keystroke. When set to `false`, the searchTriggered() is only emitted when the user presses the Enter or Return key.

See also searchTriggered().

popup : Popup

This property holds the popup.

The popup can be opened or closed manually, if necessary:

     onSpecialEvent: searchField.popup.close()

searchIndicator : real `[read-only]`

This property holds the search indicator.

suggestionCount : int `[read-only]`

This property holds the number of suggestions to display from the suggestion model.

suggestionModel : model

This property holds the data model used to display search suggestions in the popup menu.

     SearchField {
         textRole: "age"
         suggestionModel: ListModel {
             ListElement { name: "Karen"; age: "66" }
             ListElement { name: "Jim"; age: "32" }
             ListElement { name: "Pamela"; age: "28" }
         }
     }

See also textRole.

text : string

This property holds the current input text in the search field.

Text is bound to the user input, triggering suggestion updates or search logic.

See also searchTriggered() and textEdited().

textRole : string

This property holds the model role used to display items in the suggestion model shown in the popup list.

When the model has multiple roles, `textRole` can be set to determine which role should be displayed.

## Signal Documentation

void accepted()

This signal is emitted when the user confirms their input by pressing the Enter or Return key.

This signal is typically used to trigger a search or action based on the final text input, and it indicates the user's intention to complete or submit the query.

Note: The corresponding handler is `onAccepted`.

See also searchTriggered().

void activated(int index)

This signal is emitted when the item at index is activated by the user.

An item is activated when it is selected while the popup is open, causing the popup to close (and currentIndex to change). The currentIndex property is set to index.

Note: The corresponding handler is `onActivated`.

See also currentIndex.

void highlighted(int index)

This signal is emitted when the item at index in the popup list is highlighted by the user.

The highlighted signal is only emitted when the popup is open and an item is highlighted, but not necessarily activated.

Note: The corresponding handler is `onHighlighted`.

See also highlightedIndex.

void searchTriggered()

This signal is emitted when a search action is initiated.

It occurs in two cases: 1. When the Enter or Return key is pressed, it will be emitted together with accepted() signal 2. When the text is edited and if the live property is set to `true`, this signal will be emitted.

This signal is ideal for initiating searches both on-demand and in real-time as the user types, depending on the desired interaction model.

Note: The corresponding handler is `onSearchTriggered`.

See also accepted() and textEdited().

void textEdited()

This signal is emitted every time the user modifies the text in the search field, typically with each keystroke.

Note: The corresponding handler is `onTextEdited`.

See also searchTriggered().