User Interaction Methods

You can use a set of basic components to add interaction methods to UIs, such as performing actions by using a pointing device or the keyboard, or flicking the visible area of the screen horizontally or vertically. Further, you can use Qt Quick Controls components to inform users about the progress of the application or to gather input from users.

"Qt Quick Controls components in Library"

The following types of controls are available for user interaction:

You can specify values for the properties of components in the Properties view. Some properties are common to all components, whereas some are common to particular types of controls. Some properties are only available for a particular component. The following sections describe the basic interaction methods, the controls, and their properties.

Basic Interaction Methods

Users can interact with applications by using pointing devices or the keyboard. If the content does not fit the visible area of the screen, it can be flicked horizontally or vertically.

Mouse Area

Signals and handlers are used to deliver mouse interactions. Specifically, you can use a Mouse Area component to define JavaScript callbacks (also called signal handlers), which accept mouse events within a defined area.

A mouse area receives events within a defined area. One quick way to define this area is to anchor the mouse area to its parent's area. If the parent is a Rectangle (or any component that is derived from an Item), the mouse area will fill the area defined by the parent's dimensions. Alternatively, you can define an area smaller or larger than the parent. Several controls, such as buttons, contain a mouse area.

A mouse area emits signals in response to different mouse events:

  • canceled()
  • clicked()
  • doubleClicked()
  • entered()
  • exited()
  • positionChanged()
  • pressAndHold()
  • pressed()
  • released()

A more modern way of handling events from all pointing devices, including mouse and touchscreen, is via Qt Quick Input Handlers.

Focus Scope

When a key is pressed or released, a key event is generated and delivered to the focused component. If no component has active focus, the key event is ignored. If the component with active focus accepts the key event, propagation stops. Otherwise the event is sent to the component's parent until the event is accepted, or the root component is reached and the event is ignored.

A component has focus when the Focus property in the Advanced tab is set to true. However, for reusable or imported components, this is not sufficient, and you should use a Focus Scope component.

Within each focus scope, one object may have focus enabled. If more than one component have it enabled, the last component to enable it will have the focus and the others are unset, similarly to when there are no focus scopes.

When a focus scope receives active focus, the contained component with focus set (if any) also gets the active focus. If this component is also a focus scope, both the focus scope and the sub-focused component will have active focus.

The Focus Scope component is not a visual component and therefore the properties of its children need to be exposed to the parent component of the focus scope. Layouts and positioners will use these visual and styling properties to create the layout.

For more information, see Keyboard Focus in Qt Quick.


Flickable places its children on a surface that can be dragged and flicked, causing the view onto the child components to scroll. This behavior forms the basis of components that are designed to show large numbers of child components, such as List View and Grid View. For more information, see List and Grid Views.

In traditional user interfaces, views can be scrolled using standard controls, such as scroll bars and arrow buttons. In some situations, it is also possible to drag the view directly by pressing and holding a mouse button while moving the cursor. In touch-based user interfaces, this dragging action is often complemented with a flicking action, where scrolling continues after the user has stopped touching the view.

The contents of a flickable component are not automatically clipped. If the component is not used as a full-screen component, consider selecting the Clip check box in the Visibility section.

"Flickable properties"

Users can interact with a flickable component if the Interactive property is set to true. Set it to false to temporarily disable flicking. This enables special interaction with the component's children. For example, you might want to freeze a flickable map while scrolling through a pop-up that is a child of the Flickable.

The Flick direction field determines whether the view can be flicked horizontally or vertically. Select AutoFlickDirection to enable flicking vertically if the content height is not equal to height of the flickable and horizontally if the content width is not equal to the width of the flickable. Select AutoFlickIfNeeded if the content height or width is greater than that of the flickable.

Specify the maximum velocity for flicking the view in pixels per second in the Max. velocity field. Specify the rate at which a flick will decelerate in the Decelerate field.

The Bounds movement property determines whether the flickable will give a feeling that the edges of the view are soft, rather than a hard physical boundary. Select StopAtBounds for custom edge effects where the contents do not follow drags or flicks beyond the bounds of the flickable. Select FollowBoundsBehavior to have the contents follow drags or flicks beyond the bounds of the flickable depending on the value of the Behavior field.

In the Press delay field, specify the time in milliseconds to delay delivering a press to children of a flickable. This can be useful when reacting to a press before a flicking action has undesirable effects. If the flickable is dragged or flicked before the delay times out, the press event will not be delivered. If the button is released within the timeout, both the press and release will be delivered.

Note: For nested flickables with press delay set, the press delay of outer flickables is overridden by the innermost flickable. If the drag exceeds the platform drag threshold, the press event will be delivered regardless of this property.

The Pixel aligned property sets the alignment of Content X and Content Y to pixels (true) or subpixels (false). Enable it to optimize for still content or moving content with high constrast edges, such as one-pixel-wide lines, text, or vector graphics. Disable this property when optimizing for animation quality.

If Synchronous drag is set to true, then when the mouse or touchpoint moves far enough to begin dragging the content, the content will jump, so that the content pixel which was under the cursor or touchpoint when pressed remains under that point. The default is false, which provides a smoother experience (no jump) at the cost of losing some of the drag distance at the beginning.

The Content size field specifies the dimensions of the surface controlled by a flickable. Typically, set the values of the W and H fields to the combined size of the components placed in the flickable. You can set additional margins around the content in the Margins field.

The Origin field specifies the origin of the content. It refers to the top-left position of the content regardless of layout direction. Usually, the X and Y values are set to 0. However, a List View and Grid View may have an arbitrary origin due to delegate size variation, or component insertion or removal outside the visible region.

General Control Properties

You can set control properties in the Properties view.

"Control section in Properties"

The Enabled check box indicates whether the control is enabled.

The value of the Focus policy field determines whether the control accepts focus by tabbing, clicking, and using the mouse wheel.

Select the Hover and Wheel check boxes to enable the control to accept mouse events. The hover value is propagated to all child components, unless it has been explicitly set for them.

Note: Take care when enabling wheel events for controls within scrollable components, such as Flickable, because the control will consume the events, and therefore interrupt scrolling of the flickable.

Spacing is useful for controls that have multiple or repetitive building blocks. For example, some styles use spacing to determine the distance between the text and indicator of a Check Box. Spacing is not enforced by the controls, so each style may interpret it differently, and some may ignore it altogether.

Button Controls

Qt Quick Controls offer a selection of button-like controls for specific use cases. The following sections contain guidelines for choosing the button most suitable for a use case and discuss the values you can set for button properties in the Properties view.

"Button controls in Form Editor"

Recommendations for buttons that contain text:

  • Keep labels short and concise.
  • Use the default font unless you have UI guidelines specifying otherwise.
  • If the text is localized, consider how a longer text affects the layout.

For more information about setting text properties, see Fonts and Padding.

The properties that are shared by all button controls are described in:


Button can be pushed or clicked by users. Typically, buttons are used to perform an action or to answer a question. For example, OK, Apply, Cancel, Close, Yes, No, and Help.

The button text should be a verb describing the action, or a noun matching the title of the popup that will be opened.

Don't use a button to set state, because a Switch is more suitable for that purpose.

Select the Highlighted check box to draw the users' attention towards a button. Highlighting a button has no effect on keyboard interaction.

"Highlighted button"

A flat button typically does not draw a background unless it is pressed or checked. To create a flat button, select the Flat check box.

"Flat button"

Delay Button

Delay Button incorporates a delay before triggering an action. This delay prevents accidental presses.

Use delay buttons in touch user interfaces and for actions that must be triggered with care.

You can set the delay in milliseconds in the Delay field.

Check Box

Check Box presents an option button that can be toggled on (checked) or off (unchecked). Check boxes are typically used to select one or more options from a set of options. For larger sets of options, such as those in a list, consider using Check Delegate instead.

Use check boxes to build multi-selection option lists where any number of options can be selected, including none, but the options are not mutually exclusive.

Use a single check box for a yes/no choice, such as when users have to accept the terms of service agreement in a dialog. For a single yes/no choice, you can also use a Switch. If users are choosing between options, use a check box. If they are choosing between actions to be taken, a switch is recommended.

The value of the Checked property determines the state of the check box. However, in addition to the checked and unchecked states, a check box has a third state: partially checked.

Select the Tri-state check box to enable the check box to cycle between checked, partially checked, and unchecked states when users toggle it by using touch, mouse, or keyboard.

When options can be grouped, you can use a partially checked check box to represent the whole group. Select PartiallyChecked in the Check state field to indicate that users selected some sub-components in the group but not all of them.

The checkable options are often listed vertically.

The check box label should be a statement that the check mark makes true and that the absence of a check mark makes false. Therefore, the check box label should not contain a negative statement.

Radio Button

Radio Button is an option button that can be toggled on (checked) or off (unchecked). Radio buttons are typically used to select one option from a set of options. Selecting an option automatically clears the previous selection.

If there are only two mutually exclusive options, combine them into a single Check Box or a Switch.

Radio Delegate is similar to radio button, except that it is typically used in views.

Recommendations for radio buttons:

  • Limit the label text to one line.
  • Ensure that a sensible default option is checked.
  • List radio button options vertically.
  • Keep the list short.
  • In order to avoid confusion, do not put two groups of radio buttons next to each other.


Switch is an option button that can be dragged or toggled on (checked) or off (unchecked). Switches are typically used to select between two states: on or off. For larger sets of options, such as those in a list, consider using Switch Delegate instead.

Use a switch for binary operations that take effect immediately after the switch is toggled. For example, use a switch to turn WiFi on or off.

Round Button

Round Button is a clickable control that starts an action, or opens or closes a popup. A round button with a square image icon or one-letter font icon is circular. A circular round button takes less space than a normal button, and can also be used as a floating action button.

A round button has the same properties as a Button.

Displaying Text and Icons

A button can contain text, an icon, or both. Specify the button text in the Text field. The value of the Display field determines whether only text or an icon is displayed, or when both are visible, whether the text is placed beside the icon or under it.

"General button properties"

Checking Buttons

A checkable button toggles between checked (on) and unchecked (off) when users click on it or press the space bar while the button has active focus. Select the Checkable check box to make a button checkable. To make the button checked, select the Checked check box.

Buttons that belong to the same parent component can be mutually exclusive. Users can click a button to check it, and the previous selection is cleared. Users cannot uncheck the currently checked button by clicking it. Instead, they must click another button in the group to set the new checked button for that group.

Radio buttons and tab buttons are mutually exclusive by default. To make other types of buttons mutually exclusive, select the Exclusive check box.

If the buttons don't belong to the same parent, checking and unchecking buttons does not affect the other buttons in the group.

Button Signals

A button emits the clicked() signal when it is activated by users. Connect to this signal to perform the button's action. Buttons provide the following additional signals: canceled(), doubleClicked(), pressed(), released(), and pressAndHold() for long presses.

Select the Auto-repeat check box to repeat the pressed(), released(), and clicked() signals while the button is pressed and held down. The pressAndHold() signal will not be emitted.


Qt Quick Controls offer a selection of indicator-like controls, such as busy indicator, page indicator, and progress bar, for specific use cases. The following sections contain guidelines for choosing the indicator most suitable for a use case.

"Indicator types"

Busy Indicator

Busy Indicator indicates that an operation is in progress, and that the UI has to wait for the operation to complete.

A busy indicator is similar to an indeterminate Progress Bar. Both can be used to indicate background activity. The main difference is visual and that a progress bar can also present a concrete amount of progress (when it can be determined). Due to the visual difference, busy indicators and indeterminate progress bars fit in different places in UIs.

Select the Running check box to make the busy indicator visible.

Typical places for a busy indicator are:

  • In the corner of a Tool Bar
  • As an overlay on top of a Page
  • On the side of an Item Delegate

Page Indicator

Page Indicator is used to indicate the currently active page in a container of multiple pages. Specify the number of pages in the Count field. Select the current page in the Current field.

Progress Bar

Progress Bar indicates the progress of an operation. You can specify the initial value in the Value field, but it should be updated regularly. Specify the range in the From and To fields, which can both contain any value.

"Progress Bar properties"

Select the Indeterminate check box when unable to determine the size of the item being downloaded, or if the download progress might get interrupted due to a network failure.

The indeterminate mode is similar to a Busy Indicator in that both can be used to indicate background activity. Due to their visual differences, indeterminate progress bars and busy indicators fit in different places in UIs.

Typical places for an indeterminate progress bar are:

  • At the bottom of a Tool Bar
  • Inline within the content of a Page
  • In an Item Delegate to show the progress of a particular item


Qt Quick Controls offers a set of selector-like controls, such as sliders, dial, sping box, combo box, and tumbler, for specific use cases. The following sections contain guidelines for choosing the selector most suitable for a use case.

"Selector types"

Slider and Dial

Slider is used to select a value by sliding a handle along a track, whereas Range Slider is used to select a range specified by two values, by sliding each handle along a track.

Dial is similar to a traditional dial knob that is found on devices such as stereos or industrial equipment. It allows users to specify a value within a range.

In the From and To fields, set the range of the slider or dial. Set the value of the slide handle or dial in the Value field. For a range slider, set the initial positions of the first and second handles in the First value and Second value fields.

"Range slider properties"

In the Snap mode field, set how the slider handles or dial behave with regards to the value of the Step size field. By default, they do not snap to step size, but you can set them to snap to it either while being dragged or after being released.

You can set slider orientation to horizontal or vertical in the Orientation field.

Select the Live check box to provide live updates of the value properties.

Modify the Touch drag threshold to determine the threshold at which a touch drag event will be initiated.

For more information, watch the following video:

A dial supports circular, horizontal, and vertical input modes. For applications where fast input is important, the circular input mode is useful, as clicking the dial will move it directly to that position. For applications where precise input is important, the horizontal and vertical input modes are recommended, as these allow small adjustments to be made relative to where the dial is clicked. These modes are also better for dials where large jumps in values could be unsafe, such as a dial that controls audio volume. Set the input mode in the Input mode field.

"Dial properties"

Spin Box

"Spin Box"

Spin box enables users to choose an integer value by clicking the up or down indicator buttons, or by pressing up or down on the keyboard. Select the Editable check box to enable users to enter a text value in the input field.

The other spin box properties are similar to those of a dial.

Combo Box

Combo Box is a combined button and popup list. It provides a means of presenting a list of options to users in a way that takes up the minimum amount of screen space.

A combo box is used to select a value from a static multiple-line drop-down list. Users cannot add new values, and only one option can be selected.

Combo box values are provided by a data model. The data model is usually a JavaScript array, a ListModel, or an integer, but other types of data models are also supported.

Select the Editable check box to auto-complete combo box text based on what is available in the model.

"Combo box properties"

When using models that have multiple named roles, specify the role of the Display text property in the Text role field. To use a role of the model item that corresponds to the text role, enter valueRole in the field.

The Current property is the index of the current item in the combo box. The default value is -1 when the combo box is empty, and 0 otherwise.

A flat combo box does not draw a background unless it is interacted with, which makes it blend into the UI. Use flat combo boxes on a toolbar, for example, to match the flat look of tool buttons. To create a flat combo box, select the Flat check box.

Recommendations for combo boxes:

  • If the number of values very large, consider applying a filter.
  • If the number of values is small, consider using Radio Button, so that users can see all options at the same time.
  • Set a default value, which should be the value that you expect to be chosen most often.


Tumbler allows users to select an option from a spinnable wheel of items. It is useful when there are too many options to use, for example, a Radio Button, and too few options to require the use of an editable Spin Box. It is convenient in that it requires no keyboard usage and wraps around at each end when there are a large number of items.

Specify the number of visible options in the Visible count field. Select the index of the current option in the Current field.

"Tumbler properties"

To enable wrapping, select the Wrap check box.

Tab Bar

Tab Bar provides a tab-based navigation model, where users can switch between different views or subtasks. A tab bar is commonly used as a header or footer of an ApplicationWindow. Select the toolbar position in the Position field.

Typically, a tab bar contains a static set of Tab Button controls that are defined as its children. The Current field shows the index of the current tab button. The default value is -1 when the tab bar is empty, and 0 otherwise.

"Tab Bar properties"

You can specify content size in the Content width and Content height fields.

If the total width of the buttons exceeds the available width of the tab bar, it automatically becomes flickable.

Tool Bar

Tool Bar contains application-wide and context-sensitive actions and controls, such as navigation buttons and search fields. A toolbar is commonly used as a header or footer of an ApplicationWindow. Select the toolbar position in the Position field.

"Tool Bar properties"

Tool Button is nearly identical to Button, but it has a graphical appearance that makes it more suitable for insertion into a toolbar.

A toolbar does not provide a layout of its own, but requires you to position its contents, for instance by creating a RowLayout. If the toolbar contains only one item, it will resize to fit the implicit item size. This makes a toolbar particularly suitable for use together with layouts. However, you can specify content size in the Content width and Content height fields.

Tool Separator is used to visually distinguish between groups of items on a toolbar by separating them with a line. It can be used in horizontal or vertical toolbars by setting the value of the Orientation field.

Styling Controls

The UI controls can be styled. Form Editor reads the preferred style from a configuration file (qtquickcontrols2.conf). To change the style, select another style from the list on the main toolbar. This enables you to check how your UI looks when using the available styles.

"Style menu on the toolbar"

For an example of defining your own style and using it in the Design mode, see Qt Quick Controls 2 - Flat Style.

For more information about how to customize a particular control, see Customization Reference.

History of Qt Quick Controls

In Qt 4, ready-made Qt Quick 1 Components were provided for creating UIs with a native look and feel for a particular target platform. In Qt 5.1, Qt Quick Controls, Dialogs, and Layouts were added for creating classic desktop-style user interfaces using Qt Quick 2.1. The Qt Quick Controls Styles could be used to customize Qt Quick Controls.

Since Qt 5.7, Qt Quick Controls 2 replace Qt Quick Controls 1 and Qt Labs Controls. They provide lightweight components for creating performant user interfaces for devices.

Qt Quick Controls 2 work in conjunction with Qt Quick and Qt Quick Layouts.

The Qt Creator project wizards create Qt Quick applications that use Qt Quick 2 types or Qt Quick Controls 2 types.

Even if you use Qt Quick Controls 2, you can still write cross-platform applications, by using different sets of QML files for each platform.

Some ready-made controls, such as a gauge, dial, status indicator, and tumbler, are provided by the Qt Quick Extras module.

Summary of User Interaction Methods

The following table lists the components that you can use to add interaction methods to UIs. The Location column contains the module where you can find the component in Library > Components. The MCU column indicates which components are supported on MCUs.

Busy IndicatorQt Quick ControlsIndicates activity while content is being loaded.
ButtonQt Quick ControlsA push button that you can associate with an action.
Check BoxQt Quick ControlsAn option button that can be toggled on (checked) or off (unchecked).
Check DelegateQt Quick ControlsAn item delegate that can be toggled on (checked) or off (unchecked).
Combo BoxQt Quick ControlsA combined button and popup list that is populated by using a data model.
Delay ButtonQt Quick ControlsAn option button that is triggered when held down long enough.
DialQt Quick ControlsA circular dial that is rotated to set a value.
FlickableDefault Components - BasicItems can be flicked horizontally or vertically.
Focus ScopeDefault Components - BasicAssists in keyboard focus handling when building reusable QML components.
Mouse AreaDefault Components - BasicEnables simple mouse handling.
Page IndicatorQt Quick ControlsIndicates the indicate the currently active page in a container of multiple pages.
Progress BarQt Quick ControlsIndicates the progress of an operation.
Radio ButtonQt Quick ControlsAn option button that can be switched on (checked) or off (unchecked).
Radio DelegateQt Quick ControlsAn item delegate that can be toggled on (checked) or off (unchecked).
Range SliderQt Quick ControlsEnables users to select a range of values by sliding two handles along a track.
Round ButtonQt Quick ControlsA push button with rounded corners that you can associate with an action.
SliderQt Quick ControlsEnables users to select a value by sliding a handle along a track.
Spin BoxQt Quick ControlsEnables users to specify a value by clicking the up or down buttons, by pressing up or down on the keyboard, or by entering a value in the box.
SwitchQt Quick ControlsAn option button that can be toggled on or off.
Switch DelegateQt Quick ControlsAn item delegate with a switch indicator that can be toggled on or off.
Tab BarQt Quick ControlsEnables users to switch between different views or subtasks.
Tab ButtonQt Quick ControlsA button that is functionally similar to Button, but provides a look that is more suitable for a Tab Bar.
Tool BarQt Quick ControlsA container of application-wide and context sensitive actions and controls, such as navigation buttons and search fields.
Tool ButtonQt Quick ControlsA button that is functionally similar to Button, but provides a look that is more suitable for a Tool Bar.
Tool SeparatorQt Quick ControlsSeparates a group of items from adjacent items on a Tool Bar.
TumblerQt Quick ControlsA spinnable wheel of items that can be selected.

© 2021 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.