| name | quickshell-popup-menu |
| description | Use when creating anchored popup menus, flyouts, tooltip-like panels, or transient menu surfaces in Quickshell. |
| source_examples | ["examples/quickshell/standalone/popup-menu-panel.qml"] |
| source_docs | ["https://quickshell.org/docs/v0.3.0/types/Quickshell/PopupWindow/","https://doc.qt.io/qt-6/qml-qtquick-mousearea.html"] |
Quickshell Popup Menu
When to use
Use this for anchored menus, flyouts, tooltips, quick settings, inventory menus, or context panels attached to a shell widget.
Steps
- Create the owner as a
PanelWindow and put PopupWindow inside that owner scope.
- Set
anchor.window: <panel id>.
- Position with
anchor.rect.x and anchor.rect.y; avoid deprecated relativeX, relativeY, and parentWindow.
- Bind
visible to explicit menu state, but remember the popup is shown only when both visible and the anchor are valid.
- Use
grabFocus: true if outside click should close/dismiss the popup.
- Give each row/control a
MouseArea with hover feedback and validator markers.
Safety baseline
- Keep work in the project sandbox unless explicitly asked to edit source.
- Do not write to
~/.config/quickshell.
- Do not launch a live persistent widget from a skill; generate/static-review first.
- Keep KDE/Wayland examples free of
hyprctl and FloatingWindow.
Verification
PopupWindow has anchor.window and anchor.rect coordinates.- Toggle button and popup rows have explicit hitboxes.
- No popup writes to live Quickshell config.
