Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

ContextMenu QML Type

The ContextMenu attached type provides a way to open a context menu in a platform-appropriate manner. More...

Import Statement: import QtQuick.Controls
Since: Qt 6.9

Properties

Signals

Detailed Description

ContextMenu can be attached to any item in order to show a context menu upon a platform-specific event, such as a right click or the context menu key.

Pane {
    anchors.fill: parent

    ContextMenu.menu: Menu {
        MenuItem {
            text: qsTr("Eat Tomato")
            onTriggered: { /* ... */ }
        }
        MenuItem {
            text: qsTr("Throw Tomato")
            onTriggered: { /* ... */ }
        }
        MenuItem {
            text: qsTr("Squash Tomato")
            onTriggered: { /* ... */ }
        }
    }
}

Sharing context menus

It's possible to share a Menu amongst several attached context menu objects. This allows reusing a single Menu when the items that need context menus have data in common. For example:

pragma ComponentBehavior: Bound

import QtQuick
import QtQuick.Controls.Basic
import QtQuick.Templates as T

ApplicationWindow {
    width: 600
    height: 400
    visible: true

    component Tomato: Label {
        id: tomato
        objectName: text
        horizontalAlignment: Label.AlignHCenter
        verticalAlignment: Label.AlignVCenter
        width: Math.max(200, contentWidth * 1.5, contentWidth * 1.5)
        height: width
        color: skinColor

        function eat() { print("Ate " + text) }
        function ditch() { print("Threw " + text) }
        function squash() { print("Squashed " + text) }

        property color skinColor: "tomato"

        background: Rectangle {
            color: tomato.skinColor
            radius: width / 2
        }

        ContextMenu.menu: contextMenu
    }

    Menu {
        id: contextMenu

        readonly property Tomato triggerItem: parent as Tomato
        readonly property string triggerItemText: triggerItem?.text ?? ""

        MenuItem {
            text: qsTr("Eat %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.eat()
        }
        MenuItem {
            text: qsTr("Throw %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.ditch()
        }
        MenuItem {
            text: qsTr("Squash %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.squash()
        }
    }

    Row {
        anchors.centerIn: parent

        Tomato {
            text: qsTr("tomato")
        }

        Tomato {
            text: qsTr("really ripe tomato")
            skinColor: "maroon"
        }
    }
}

Performance

ContextMenu lazily creates its Menu only when it's requested. If it wasn't for this optimization, the Menu would be created when the containing component is being loaded, which is typically at application startup.

It is recommended not to give the Menu assigned to ContextMenu's menu property an id when it's defined where it's assigned. Doing so prevents this optimization. For example:

Pane {
    anchors.fill: parent

    ContextMenu.menu: Menu {
        // This prevents lazy creation of the Menu.
        id: myMenu

        // ...
    }
}

The example in the Sharing context menus section works because the Menu is defined separately from its assignment.

Interaction with other menus

If a Menu is opened via e.g. a TapHandler or other means, ContextMenu will not open at the same time. This allows legacy applications that were written before ContextMenu was introduced to continue working as expected.

Native menu support

ContextMenu is backed by a native menu on iOS.

Note: if you assign your own menu, you must set popupType to Popup.Native to ensure native menu support.

Property Documentation

This property holds the context menu that will be opened. It can be set to any Menu object.

Note: The Menu assigned to this property cannot be given an id. See Sharing context menus for more information.

Signal Documentation

requested(point position)

This signal is emitted when a context menu is requested.

If it was requested by a right mouse button click, position gives the position of the click relative to the parent.

The example below shows how to programmatically open a context menu:

Button {
    id: button
    text: qsTr("Click me!")
    ContextMenu.onRequested: position => {
        const menu = buttonMenu.createObject(button)
        menu.popup(position)
    }
}

Component {
    id: buttonMenu
    Menu {
        MenuItem { text: qsTr("Open") }
    }
}

If no menu is set, but this signal is connected, the context menu event will be accepted and will not propagate.

Note: The corresponding handler is onRequested.

See also QContextMenuEvent::pos().

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