4 4 Reusable recipes. Each pattern solves a recurring shape of problem. Combine them.
6 +All patterns here are validated against Quickshell **v0.3.0**. When bumping versions, re-check each against the latest `quickshell.org/docs/<version>/guide/` (see `getting-fresh-docs.md`).
6 8 ##
P1. Per-monitor instantiation 22 24 `modelData` is the per-iteration value. Always mark it `required` so qmlls catches missing bindings. `Quickshell.screens` is a `list<ShellScreen>` — each has `name`, `width`, `height`, `scale`. Variants survives monitor hot-plug: when a screen disconnects, its instance is destroyed; when it reconnects, a fresh one is created.
26 +**Source:** [docs/v0.3.0/guide/introduction/ → Reusable components](https://quickshell.org/docs/v0.3.0/guide/introduction/#reusable-components) · [Variants type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Variants) · [ShellScreen type](https://quickshell.org/docs/v0.3.0/types/Quickshell/ShellScreen)
24 28 ##
P2. Live-updating clock 33 37 `SystemClock` is **not** a singleton — you must instantiate it. `clock.date` is a reactive JS `Date`; format it with `Qt.formatTime` / `Qt.formatDate` / `Qt.formatDateTime`. Updates trigger within 50ms of the system clock changing.
39 +**Source:** [SystemClock type](https://quickshell.org/docs/v0.3.0/types/Quickshell/SystemClock) · [quickshell-mirror/quickshell `src/wayland/screencopy/systemclock.*` @ v0.3.0](https://github.com/quickshell-mirror/quickshell/blob/v0.3.0/src/wayland/screencopy/systemclock.cpp) (reference impl)
35 41 ##
P3. Run a shell command, capture output 50 56 `StdioCollector` is a `Property`-like that becomes the full output string after the process closes stdout. **One process, many widgets** — don't spawn per widget (memory + startup cost).
58 +**Source:** [docs/v0.3.0/guide/introduction/ → Running a process](https://quickshell.org/docs/v0.3.0/guide/introduction/#running-a-process) · [Process type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/Process) · [StdioCollector type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/StdioCollector)
52 60 ##
P4. Long-running stream, regex match per line 70 78 `SplitParser` splits on newlines by default; you can override with `split`. Each line fires `onRead(line)`. Use this for any event-stream consumer (Hyprland socket, log tailer, status feed).
80 +**Source:** [SplitParser type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/SplitParser) · [quickshell-examples/focus_following_panel](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/focus_following_panel) (canonical example)
72 82 ##
P5. Bind a service object's state 86 96 The `?.` optional chain is the safe way to read state that might not be present yet (e.g. before the service has connected).
98 +**Source:** [docs/v0.3.0/guide/ → Not "one process per widget"](https://quickshell.org/docs/v0.3.0/guide/faq/#should-i-use-a-process-per-widget) (FAQ) · [Pipewire type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Pipewire/Pipewire) · [PwObjectTracker type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Services.Pipewire/PwObjectTracker)
88 100 ##
P6. React to a service signal 99 111 `Connections` is the idiomatic way to listen to a target's signals. The `target` must be live — wrap with `?.` and use the `target:` binding (not a static `target:` assignment) to make it reactive. The handler name follows `on<SignalName>` convention.
113 +**Source:** [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical Connections + Pipewire example)
101 115 ##
P7. Show a window only when a condition holds 120 134 The window is destroyed when `active` flips to false. Good for rare/expensive UI.
136 +**Source:** [docs/v0.3.0/guide/faq/ → Reduce memory usage](https://quickshell.org/docs/v0.3.0/guide/faq/#reduce-memory-usage) · [LazyLoader type](https://quickshell.org/docs/v0.3.0/types/Quickshell/LazyLoader) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical example)
122 138 ##
P8. Click-through overlay 131 147 The `Region` input mask is the only correct way to make a panel ignore clicks while still rendering. For a window that should be opaque to clicks, leave `mask` unset.
149 +**Source:** [Region type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Region) · [quickshell-examples/activate_linux](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/activate_linux) (`mask: Region {}` example) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (OSD with click-through)
133 151 ##
P9. System icon 144 162 `Quickshell.iconPath` looks up the name in the current icon theme. Three variants: missing icon → purple/black square (default), fallback to a name, or empty string. If the purple square bugs you, use the empty-string overload and `source !== ""` to gate the `IconImage`.
164 +**Source:** [Quickshell.iconPath method](https://quickshell.org/docs/v0.3.0/types/Quickshell/Quickshell#iconPath) · [IconImage type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Widgets/IconImage) · [docs/v0.3.0/guide/faq/ → Get rid of the purple/black icons](https://quickshell.org/docs/v0.3.0/guide/faq/#get-rid-of-the-purpleblack-icons)
146 166 ##
P10. Custom file-bound properties (config-as-code) 158 178 `JsonAdapter` reads a JSON file at startup and exposes its top-level keys as reactive QML properties. Edits to the file are picked up on next reload. Use this for user-tweakable config (theme, layout offsets, monitor list).
180 +**Source:** [JsonAdapter type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/JsonAdapter)
160 182 ##
P11. Multi-file shell 187 209 - `widgets/*.qml` etc. → import with `import qs.widgets as W` (LSP-friendly, v0.2.0+).
188 210 - `import "relative/path"` works but loses LSP coverage; prefer `qs.*`.
212 +**Source:** [docs/v0.3.0/guide/qml-language/ → Implicit imports](https://quickshell.org/docs/v0.3.0/guide/qml-language/#implicit-imports) · [docs/v0.3.0/guide/qml-language/ → Manual imports (qs.*)](https://quickshell.org/docs/v0.3.0/guide/qml-language/#manual-imports)
190 214 ## P12. Version-gate a feature
202 226 `Quickshell.hasVersion` is the API; the `#pragma`-style preprocessor (different syntax) lets you gate by version at parse time. Use these when you want the same shell.qml to work across quickshell releases.
228 +**Source:** [Quickshell.hasVersion method](https://quickshell.org/docs/v0.3.0/types/Quickshell/Quickshell#hasVersion) · [docs/v0.3.0/guide/advanced/ → If/Endif preprocessor](https://quickshell.org/docs/v0.3.0/guide/advanced/#ifendif)
204 230 ##
P13. Reuse state across components 206 232 Put the state in the `Scope` root:
219 245 Components declared inside `Scope` can reach `root.foo` by id. If you find yourself passing the same property into 4+ components, hoist it to `Scope`.
247 +**Source:** [Scope type](https://quickshell.org/docs/v0.3.0/types/Quickshell/Scope) · [quickshell-examples/volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) (canonical Scope example)
221 249 ##
P14. Custom re-usable component file 236 264 Consume from `shell.qml` (auto-imported) or `import qs.widgets as W; W.MyButton { ... }`. Components are just `Item`-like root objects — anything that's a QML object can be a component.
266 +**Source:** [docs/v0.3.0/guide/qml-language/ → Creating types](https://quickshell.org/docs/v0.3.0/guide/qml-language/#creating-types) · [quickshell-examples/wlogout](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/wlogout) (canonical multi-file component example)
238 268 ##
P15. Hide the reload popup 240 270 If you have your own reloader indicator, you can disable the built-in one (v0.3.0+):
251 281 The default reload popup shows on every file save. For noisier iteration, replace it with a smaller indicator or disable via `QuickshellSettings`.
283 +**Source:** [quickshell-examples/reload-popup](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/reload-popup) · [quickshell.org/docs/v0.3.0/guide/advanced/ → Environment (QS_NO_RELOAD_POPUP)](https://quickshell.org/docs/v0.3.0/guide/advanced/#environment)
253 285 ##
P16. Process IPC (call into quickshell from outside) 272 304 Use this for keybind triggers, scripts, and external automation.
306 +**Source:** [IpcHandler type](https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/IpcHandler) · [docs/v0.3.0/guide/faq/ → Open/close windows with commands](https://quickshell.org/docs/v0.3.0/guide/faq/#openclose-windows-with-commands) · [docs/v0.3.0/guide/advanced/ → IPC signal listener (v0.3.0+)](https://quickshell.org/docs/v0.3.0/guide/advanced/#environment)