Standard Ubuntu button. More...

Import Statement: import Ubuntu.Components 1.2


Inherited By:





Detailed Description

See also the Design Guidelines on Buttons.


Column {
    Button {
        text: "Send"
        onClicked: print("clicked text-only Button")
    Button {
        iconName: "compose"
        gradient: UbuntuColors.greyGradient
        onClicked: print("clicked icon-only Button")
    Button {
        iconName: "compose"
        text: "Icon on left"
        iconPosition: "left"
        onClicked: print("clicked text and icon Button")

An Action can be used to specify clicked, iconSource and text. Example:

 Item {
     Action {
         id: action1
         text: "Click me"
         onTriggered: print("action!")
         iconName: "compose"
     Button {
         anchors.centerIn: parent
         action: action1
         color: UbuntuColors.warmGrey

Property Documentation

action : Action

The Action associated with this ActionItem. If action is set, the values of the Action properties are copied to the values of the ActionItem properties.

activeFocusOnPress : bool

The property specifies whether the StyledItem can gain focus on a mouse press/touch or not. When the value is true, the focus will be set on the component when the mouse is pressed over it or touched. However if one of the component's ancestor StyledItem or derived is having the property value false, the focus will not be gained automatically.

In the following example the TextField will stay focused when clicked on the red rectangle.

import QtQuick 2.4
import Ubuntu.Components 1.2
Column {
    width: units.gu(50)
    height: units.gu(100)
    StyledItem {
        objectName: "passiveScope"
        width: parent.width
        height: units.gu(30)
        Rectangle {
            anchors.fill: parent
            color: "red"
            StyledItem {
                objectName: "activeScope"
                activeFocusOnPress: true
                anchors.fill: parent
    TextField {
        id: input
        text: "The input stays focus even if red box is clicked"
    Component.onCompleted: input.forceActiveFocus()
    Connections {
        target: window
        onActiveFocusItemChanged: console.debug("focus on", window.activeFocusItem)

The default value is false.

This QML property was introduced in Ubuntu.Components 1.1.

color : color

The background color of the button.

See also gradient.

font : font

The font used for the button's text.

gradient : Gradient

The gradient used to fill the background of the button.

Standard Ubuntu gradients are defined in UbuntuColors.

If both a gradient and a color are specified, the gradient will be used.

See also color.

hovered : bool

True if the mouse cursor hovers over the button's mouse area.

iconName : string

The icon associated with the actionItem in the suru icon theme. Default value: action.iconName.

Note: The complete list of icons available in Ubuntu is not published yet. For now please refer to the folders where the icon themes are installed:

  • Ubuntu Touch: /usr/share/icons/suru
  • Ubuntu Desktop: /usr/share/icons/ubuntu-mono-dark

These 2 separate icon themes will be merged soon.

If both iconSource and iconName are defined, iconName will be ignored.

iconPosition : string

The position of the icon relative to the text. Options are "left" and "right". The default value is "left".

If only text or only an icon is defined, this property is ignored and the text or icon is centered horizontally and vertically in the button.

Currently this is a string value. We are waiting for support for enums: https://bugreports.qt-project.org/browse/QTBUG-14861

iconSource : url

The image associated with the actionItem. Default value: action.iconSource.

This is the URL of any image file If both iconSource and iconName are defined, iconName will be ignored.

pressed : bool

True if the user presses a mouse button in the button's mouse area.

strokeColor : color

If set to a color, the button has a stroke border instead of a filled shape.

This QML property was introduced in Ubuntu.Components 1.1.

style : Component

Component instantiated immediately and placed below everything else.

text : string

The title of the actionItem. Default value: action.text

Signal Documentation


This handler is called when there is a mouse click on the button and the button is not disabled. If action is defined, the action will be triggered.


This handler is called when there is a long press.

triggered(var value)

Called when the actionItem is triggered.

Method Documentation

trigger( value)

Trigger this action item if it is enabled.