| name | quickshell-panel-window |
| description | Use when creating or modifying Quickshell shell surfaces such as corner cards, bars, HUD panels, or anchored desktop widgets. |
| source_examples | ["examples/quickshell/standalone/panel-corner-card.qml"] |
| source_docs | ["https://quickshell.org/docs/v0.3.0/types/Quickshell/PanelWindow/","https://git.outfoxxed.me/quickshell/quickshell-examples.git"] |
Quickshell PanelWindow
When to use
Use this before building any standalone Quickshell widget surface: corner cards, bars, passive overlays, HUD panels, and shell-contained menus.
Steps
- Start with
ShellRoot { PanelWindow { ... } } for a standalone artifact.
- Set only the anchors needed for the intended geometry. Example: top-right card uses
anchors.top: true and anchors.right: true.
- Put offsets in
margins for those anchored edges only.
- Set
color: "transparent" on PanelWindow and draw visible background/border in child Rectangle or frame components.
- Use
implicitWidth / implicitHeight for content-sized widgets.
- For non-reserving overlays/cards use
exclusionMode: ExclusionMode.Ignore or exclusiveZone: 0.
- Use
mask: Region {} only for passive click-through OSDs. Never use it on an interactive widget.
- If multi-monitor output is needed later, wrap
PanelWindow in Variants { model: Quickshell.screens }, but keep the first sandbox single-surface unless the task asks for monitors.
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
- Generated QML contains
PanelWindow.
- Generated QML does not contain
FloatingWindow.
- Generated QML does not contain
hyprctl.
- Anchors and margins match the requested screen edge.
- Interactive widgets do not use an empty
Region {} mask.
