- Qt 6.9
- Qt Quick Controls
- QML Types
- TextField
- Qt 6.9.3 Reference Documentation

# TextField QML Type

Single-line text input field. More...

Import Statement: | `import QtQuick.Controls`
Inherits: | TextInput

- List of all members, including inherited members

## Properties

- background : Item
- bottomInset : real `(since QtQuick.Controls 2.5 (Qt 5.12))`
- focusReason : enumeration
- hoverEnabled : bool `(since QtQuick.Controls 2.1 (Qt 5.8))`
- hovered : bool `(since QtQuick.Controls 2.1 (Qt 5.8))`
- implicitBackgroundHeight : real `(since QtQuick.Controls 2.5 (Qt 5.12))`
- implicitBackgroundWidth : real `(since QtQuick.Controls 2.5 (Qt 5.12))`
- leftInset : real `(since QtQuick.Controls 2.5 (Qt 5.12))`
- placeholderText : string
- placeholderTextColor : color `(since QtQuick.Controls 2.5 (Qt 5.12))`
- rightInset : real `(since QtQuick.Controls 2.5 (Qt 5.12))`
- topInset : real `(since QtQuick.Controls 2.5 (Qt 5.12))`

## Signals

- pressAndHold(MouseEvent event)
- pressed(MouseEvent event) `(since QtQuick.Controls 2.1 (Qt 5.8))`
- released(MouseEvent event) `(since QtQuick.Controls 2.1 (Qt 5.8))`

## Detailed Description

TextField is a single line text editor. TextField extends TextInput with a placeholder text functionality, and adds decoration.

| A text field in its normal state.
| A text field that has active focus.
| A text field that is disabled.

     TextField {
         placeholderText: qsTr("Enter name")
     }

See also TextArea, Customizing TextField, and Input Controls.

## Property Documentation

background : Item

This property holds the background item.

Note: If the background item has no explicit size specified, it automatically follows the control's size. In most cases, there is no need to specify width or height for a background item.

Note: Most controls use the implicit size of the background item to calculate the implicit size of the control itself. If you replace the background item with a custom one, you should also consider providing a sensible implicit size for it (unless it is an item like Image which has its own implicit size).

See also Customizing TextField.

bottomInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the bottom inset for the background.

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

See also Control Layout and topInset.

focusReason : enumeration

This property holds the reason of the last focus change.

Note: This property does not indicate whether the item has active focus, but the reason why the item either gained or lost focus.

Constant | Description
--- | ---
`Qt.MouseFocusReason` | A mouse action occurred.
`Qt.TabFocusReason` | The Tab key was pressed.
`Qt.BacktabFocusReason` | A Backtab occurred. The input for this may include the Shift or Control keys; e.g. Shift+Tab.
`Qt.ActiveWindowFocusReason` | The window system made this window either active or inactive.
`Qt.PopupFocusReason` | The application opened/closed a pop-up that grabbed/released the keyboard focus.
`Qt.ShortcutFocusReason` | The user typed a label's buddy shortcut
`Qt.MenuBarFocusReason` | The menu bar took focus.
`Qt.OtherFocusReason` | Another reason, usually application-specific.

Note: Prefer QtQuick.Controls::Control::focusReason to this property.

hoverEnabled : bool `[since QtQuick.Controls 2.1 (Qt 5.8)]`

This property determines whether the text field accepts hover events. The default value is `false`.

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

See also hovered.

hovered : bool `[read-only, since QtQuick.Controls 2.1 (Qt 5.8)]`

This property holds whether the text field is hovered.

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

See also hoverEnabled.

implicitBackgroundHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the implicit background height.

The value is equal to `background ? background.implicitHeight : 0`.

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

See also implicitBackgroundWidth.

implicitBackgroundWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the implicit background width.

The value is equal to `background ? background.implicitWidth : 0`.

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

See also implicitBackgroundHeight.

leftInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the left inset for the background.

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

See also Control Layout and rightInset.

placeholderText : string

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

placeholderTextColor : color `[since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the color of placeholderText.

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

See also placeholderText.

rightInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the right inset for the background.

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

See also Control Layout and leftInset.

topInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

This property holds the top inset for the background.

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

See also Control Layout and bottomInset.

## Signal Documentation

pressAndHold(MouseEvent event)

This signal is emitted when there is a long press (the delay depends on the platform plugin). The event parameter provides information about the press, including the x and y coordinates of the press, and which button is pressed.

Note: The corresponding handler is `onPressAndHold`.

See also pressed and released.

`[since QtQuick.Controls 2.1 (Qt 5.8)]` pressed(MouseEvent event)

This signal is emitted when the text field is pressed by the user. The event parameter provides information about the press, including the x and y coordinates of the press, and which button is pressed.

Note: The corresponding handler is `onPressed`.

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

See also released and pressAndHold.

`[since QtQuick.Controls 2.1 (Qt 5.8)]` released(MouseEvent event)

This signal is emitted when the text field is released by the user. The event parameter provides information about the release, including the x and y coordinates of the press, and which button is pressed.

Note: The corresponding handler is `onReleased`.

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

See also pressed and pressAndHold.