ComboBox QML Type

This property holds whether the combo box contains acceptable text in the editable text field.

If a validator has been set, the value is true only if the current text is acceptable to the validator as a final string (not as an intermediate string).

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also validator and accepted.

This property holds the number of items in the combo box.

This property holds the index of the current item in the combo box.

The default value is -1 when count is 0, and 0 otherwise.

See also activated(), currentText, and highlightedIndex.

This property holds the text of the current item in the combo box.

See also currentIndex, displayText, textRole, and editText.

This property holds the value of the current item in the combo box.

For an example of how to use this property, see ComboBox Model Roles.

This property was introduced in QtQuick.Controls 2.14 (Qt 5.14).

See also currentIndex, currentText, and valueRole.

This property holds a delegate that presents an item in the combo box 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: comboBox.popup.close()
    }
}

See also ItemDelegate and Customizing ComboBox.

This property holds the text that is displayed on the combo box button.

By default, the display text presents the current selection. That is, it follows the text of the current item. However, the default display text can be overridden with a custom value.

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

See also currentText and textRole.

This property holds whether the combo box button is visually down.

Unless explicitly set, this property is true when either pressed or popup.visible is true. To return to the default value, set this property to undefined.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also pressed and popup.

This property holds the text in the text field of an editable combo box.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also editable, currentText, and displayText.

This property holds whether the combo box is editable.

The default value is false.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also validator.

This property holds whether the combo box button is flat.

A flat combo box button does not draw a background unless it is interacted with. In comparison to normal combo boxes, flat combo boxes provide looks that make them stand out less from the rest of the UI. For instance, when placing a combo box into a tool bar, it may be desirable to make the combo box flat so it matches better with the flat looks of tool buttons.

The default value is false.

This property was introduced in QtQuick.Controls 2.1 (Qt 5.8).

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

When a highlighted item is activated, the popup is closed, currentIndex is set to highlightedIndex, and the value of this property is reset to -1, as there is no longer a highlighted item.

See also highlighted() and currentIndex.

This property controls how the implicitContentWidth of the ComboBox is calculated.

When the width of a ComboBox is not large enough to display text, that text is elided. Depending on which parts of the text are elided, this can make selecting an item difficult for the end user. An efficient way of ensuring that a ComboBox is wide enough to avoid text being elided is to set a width that is known to be large enough:

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

However, it is often not possible to know whether or not a hard-coded value will be large enough, as the size of text depends on many factors, such as font family, font size, translations, and so on.

implicitContentWidthPolicy provides an easy way to control how the implicitContentWidth is calculated, which in turn affects the implicitWidth of the ComboBox and ensures that text will not be elided.

The available values are:

The default value is ContentItemImplicitWidth.

As this property only affects the implicitWidth of the ComboBox, setting an explicit width can still result in eliding.

This property was introduced in QtQuick.Controls 6.0 (Qt 6.0).

This property holds the implicit indicator height.

The value is equal to indicator ? indicator.implicitHeight : 0.

This is typically used, together with implicitContentHeight and implicitBackgroundHeight, to calculate the implicitHeight.

This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

See also implicitIndicatorWidth.

This property holds the implicit indicator width.

The value is equal to indicator ? indicator.implicitWidth : 0.

This is typically used, together with implicitContentWidth and implicitBackgroundWidth, to calculate the implicitWidth.

This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).

See also implicitIndicatorHeight.

This property holds the drop indicator item.

See also Customizing ComboBox.

This property holds whether an editable combo box has partial text input from an input method.

While it is composing, an input method may rely on mouse or key events from the combo box to edit or commit the partial text. This property can be used to determine when to disable event handlers that may interfere with the correct operation of an input method.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

Provides hints to the input method about the expected content of the combo box and how it should operate.

The default value is Qt.ImhNoPredictiveText.

The value is a bit-wise combination of flags or Qt.ImhNone if no hints are set.

Flags that alter behavior are:

• Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords.
• Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
• Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
• Qt.ImhPreferNumbers - Numbers are preferred (but not required).
• Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
• Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
• Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
• Qt.ImhDate - The text editor functions as a date field.
• Qt.ImhTime - The text editor functions as a time field.

Flags that restrict input (exclusive flags) are:

• Qt.ImhDigitsOnly - Only digits are allowed.
• Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
• Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
• Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
• Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
• Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
• Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

Masks:

• Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

This property holds the model providing data for the combo box.

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

See also textRole and Data Models.

This property holds the popup.

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

onSpecialEvent: comboBox.popup.close()

See also Customizing ComboBox.

This property holds whether the combo box button is physically pressed. A button can be pressed by either touch or key events.

See also down.

This property holds whether the text field for an editable ComboBox can be selected with the mouse.

The default value is false.

This property was introduced in QtQuick.Controls 2.15 (Qt 5.15).

This property holds the model role used for populating the combo box.

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

See also model, currentText, displayText, and ComboBox Model Roles.

This property holds an input text validator for an editable combo box.

When a validator is set, the text field will only accept input which leaves the text property in an intermediate state. The accepted signal will only be emitted if the text is in an acceptable state when the Return or Enter key is pressed.

The currently supported validators are IntValidator, DoubleValidator, and RegularExpressionValidator. An example of using validators is shown below, which allows input of integers between 0 and 10 into the text field:

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also acceptableInput, accepted, and editable.

This property holds the model role used for storing the value associated with each item in the model.

For an example of how to use this property, see ComboBox Model Roles.

This property was introduced in QtQuick.Controls 2.14 (Qt 5.14).

See also model and currentValue.

This signal is emitted when the Return or Enter key is pressed on an editable combo box.

You can handle this signal in order to add the newly entered item to the model, for example:

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Before the signal is emitted, a check is done to see if the string exists in the model. If it does, currentIndex will be set to its index, and currentText to the string itself.

After the signal has been emitted, and if the first check failed (that is, the item did not exist), another check will be done to see if the item was added by the signal handler. If it was, the currentIndex and currentText are updated accordingly. Otherwise, they will be set to -1 and "", respectively.

This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

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), or while the popup is closed and the combo box is navigated via keyboard, causing the currentIndex to change. The currentIndex property is set to index.

See also currentIndex.

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.

See also highlightedIndex.

Decrements the current index of the combo box, or the highlighted index if the popup list is visible.

See also currentIndex and highlightedIndex.

Returns the index of the specified text, or -1 if no match is found.

The way the search is performed is defined by the specified match flags. By default, combo box performs case sensitive exact matching (Qt.MatchExactly). All other match types are case-insensitive unless the Qt.MatchCaseSensitive flag is also specified.

For example:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

See also textRole.

Increments the current index of the combo box, or the highlighted index if the popup list is visible.

See also currentIndex and highlightedIndex.

Returns the index of the specified value, or -1 if no match is found.

For an example of how to use this method, see ComboBox Model Roles.

This method was introduced in QtQuick.Controls 2.14 (Qt 5.14).

See also find(), currentValue, currentIndex, valueRole, and valueAt.

Selects all the text in the editable text field of the combo box.

This method was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also editText.

Returns the text for the specified index, or an empty string if the index is out of bounds.

For example:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

See also textRole.

Returns the value at position index in the combo box.

This method was introduced in QtQuick.Controls 2.14 (Qt 5.14).

See also indexOfValue.