- Qt 6.12
- Qt Quick Controls
- QML Types
- SearchField
- Qt 6.12.0 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
  - clearIndicator.hovered : bool
  - clearIndicator.implicitIndicatorHeight : real
  - clearIndicator.implicitIndicatorWidth : real
  - clearIndicator.indicator : Item
  - clearIndicator.pressed : bool
- currentIndex : int
- cursorPosition : int `(since 6.12)`
- delegate : Component
- delegateModel : model
- highlightedIndex : int
- live : bool
- placeholderText : string `(since 6.12)`
- popup : Popup
- searchIndicator
  - searchIndicator.hovered : bool
  - searchIndicator.implicitIndicatorHeight : real
  - searchIndicator.implicitIndicatorWidth : real
  - searchIndicator.indicator : Item
  - searchIndicator.pressed : bool
- selectTextByMouse : bool `(since 6.12)`
- selectedText : string `(since 6.12)`
- selectionEnd : int `(since 6.12)`
- selectionStart : int `(since 6.12)`
- suggestionCount : int
- suggestionModel : model
- text : string
- textRole : string

## Signals

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

## Methods

- void deselect() `(since 6.12)`
- void select(int start, int end) `(since 6.12)`
- void selectAll() `(since 6.12)`
- void selectWord() `(since 6.12)`

## 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's Indicators

SearchField provides two optional embedded indicator buttons: searchIndicator and clearIndicator.

These are not indicators in the sense of BusyIndicator or ProgressBar. Instead, they are interactive controls embedded into the field (similar to the up/down buttons in SpinBox). Pressing searchIndicator triggers searchButtonPressed, and pressing clearIndicator triggers clearButtonPressed.

In addition to exposing the actions, the indicator buttons provide interaction state (pressed/hovered/focused, etc.) that can be used by styles.

### Customizing indicator content

The searchIndicator and clearIndicator properties are read-only. Customization is supported through their internal properties.

In particular, the button's visual content is provided by its `indicator` item, which is writable. This allows the default content to be replaced or removed entirely.

For example, to remove both indicator icons:

     SearchField {
         searchIndicator.indicator: null
         clearIndicator.indicator: null
     }

This is a supported customization scenario. Different SearchField variants may omit one of the buttons (for example, providing only a search button) or replace the indicator content with an alternative item (for example, a microphone icon to trigger speech input).

## 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
         sourceModel: fruitModel
         sorters: [
             RoleSorter {
                 roleName: "name"
             }
         ]
         filters: [
             FunctionFilter {
                 property var regExp: new RegExp(fruitSearch.text, "i")
                 onRegExpChanged: invalidate()
                 function filter(name: string): bool {
                     return regExp.test(name);
                 }
             }
         ]
     }

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

See also searchIndicator, clearIndicator, searchButtonPressed, and clearButtonPressed.

## Property Documentation

### clearIndicator group

### clearIndicator.hovered : bool

### clearIndicator.implicitIndicatorHeight : real

### clearIndicator.implicitIndicatorWidth : real

### clearIndicator.indicator : Item

### clearIndicator.pressed : bool

This grouped property holds the clearIndicator indicator item and its associated properties.

This property holds the clear indicator. Pressing it triggers clearButtonPressed.

It is exposed so that styles and applications can customize it through its internal properties (for example, replacing or removing the `clearIndicator` via `clearIndicator.indicator`, or reacting to interaction state such as pressed and hovered).

See also SearchField's Indicators.

### 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.

### cursorPosition : int `[since 6.12]`

The position of the cursor in the text field. The cursor is positioned between characters.

Note: The characters in this case refer to the string of QChar objects, therefore 16-bit Unicode characters, and the position is considered an index into this string. This does not necessarily correspond to individual graphemes in the writing system, as a single grapheme may be represented by multiple Unicode characters, such as in the case of surrogate pairs, linguistic ligatures or diacritics.

This property was introduced in Qt 6.12.

### 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()
         }
     }

Since Qt 6.11, SearchField does not take ownership of the delegate.

### 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().

### placeholderText : string `[since 6.12]`

This property holds the hint that is displayed in the SearchField before the user enters text.

This property was introduced in Qt 6.12.

### popup : Popup

This property holds the popup.

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

     onSpecialEvent: searchField.popup.close()

### searchIndicator group

### searchIndicator.hovered : bool

### searchIndicator.implicitIndicatorHeight : real

### searchIndicator.implicitIndicatorWidth : real

### searchIndicator.indicator : Item

### searchIndicator.pressed : bool

This grouped property holds the searchIndicator indicator item and its associated properties.

This property holds the search indicator. Pressing it triggers searchButtonPressed.

It is exposed so that styles and applications can customize it through its internal properties (for example, replacing or removing the `searchIndicator` via `searchIndicator.indicator`, or reacting to interaction state such as pressed and hovered).

See also SearchField's Indicators.

### selectTextByMouse : bool `[since 6.12]`

This property holds whether the text can be selected with the mouse.

The default value is `true`.

This property was introduced in Qt 6.12.

### selectedText : string `[read-only, since 6.12]`

This read-only property holds the currently selected text.

This property was introduced in Qt 6.12.

### selectionEnd : int `[read-only, since 6.12]`

The cursor position after the last character in the current selection.

This property is read-only. To change the selection, use select(start, end), selectAll(), or selectWord().

This property was introduced in Qt 6.12.

See also selectionStart, cursorPosition, and selectedText.

### selectionStart : int `[read-only, since 6.12]`

The cursor position before the first character in the current selection.

This property is read-only. To change the selection, use select(start, end), selectAll(), or selectWord().

This property was introduced in Qt 6.12.

See also selectionEnd, cursorPosition, and selectedText.

### 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 clearButtonPressed()

This signal is emitted when the clear button is pressed.

Note: The corresponding handler is `onClearButtonPressed`.

See also searchButtonPressed().

### 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 searchButtonPressed()

This signal is emitted when the search button is pressed.

Note: The corresponding handler is `onSearchButtonPressed`.

See also clearButtonPressed().

### 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().

## Method Documentation

### `[since 6.12]` void deselect()

Removes the active text selection.

This method was introduced in Qt 6.12.

See also selectedText, selectionStart, and selectionEnd.

### `[since 6.12]` void select(int start, int end)

Causes the text from start to end to be selected.

If either start or end is out of range, the selection is not changed.

After calling this, selectionStart will become the lesser and selectionEnd will become the greater (regardless of the order passed to this method).

This method was introduced in Qt 6.12.

See also selectionStart and selectionEnd.

### `[since 6.12]` void selectAll()

Selects all text in the text field of the control.

This method was introduced in Qt 6.12.

### `[since 6.12]` void selectWord()

Causes the word closest to the current cursor position to be selected.

This method was introduced in Qt 6.12.

See also cursorPosition and selectedText.