8 -Toolkit for building desktop components in QML (QtQuick). Not a WM, not a DE — runs alongside your compositor and owns a few Wayland surfaces (panels, popups, OSDs, lockscreens, etc.). Hot-reloads on save.
8 +Toolkit for building desktop components in QML (QtQuick). Not a WM, not a DE — runs alongside your compositor and owns a few Wayland surfaces (panels, popups, OSDs, lockscreens, greeters, polkit agent, system tray, etc.). Hot-reloads on save.
18 18 └── Connections { target: SomeService; function onXxx() {...} }
21 -- A **shell** is a `shell.qml` file inside a named config dir.
22 -- The **root** is `ShellRoot` (passive container) or `Scope` (container with shared state + services).
23 -- **Windows** are children of the root. Three kinds: `PanelWindow` (anchored to screen edge/corner, reserves space), `FloatingWindow` (free desktop window), `PopupWindow` (auto-positioned over a parent).
24 -- **Variants** instantiates a component per item in a model — the canonical pattern for one-bar-per-monitor.
25 -- **Reactive bindings** do the work. You don't write update logic; you write expressions whose dependencies re-evaluate.
21 +- **Root:** `ShellRoot` (passive) or `Scope` (shared state + services).
22 +- **Windows:** `PanelWindow` (anchored, reserves space), `FloatingWindow` (free), `PopupWindow` (auto-positioned over a parent).
23 +- **`Variants`** instantiates a delegate per model item — the canonical pattern for one-bar-per-monitor.
24 +- **Reactive bindings** do the work. Write expressions; dependencies re-evaluate.
27 -## File layout (user config)
30 -$XDG_CONFIG_HOME/quickshell/<
name>/ # usually ~/.config/quickshell/<
name>/
31 -├── shell.qml # entry point; root must be ShellRoot or Scope
32 -├── .qmlls.ini # touch to enable LSP; managed by quickshell (gitignore)
33 -├── Bar.qml # implicitly importable from shell.qml (PascalCase)
35 -│ ├── Clock.qml # import via qs.widgets.Clock (qs.*, since v0.2.0)
29 +$XDG_CONFIG_HOME/quickshell/<
name>/ # usually ~/.config/quickshell/<
name>/
30 +├── shell.qml # entry; root must be ShellRoot or Scope
31 +├── .qmlls.ini # touch to enable LSP; gitignore
32 +├── Bar.qml # implicit import (PascalCase, same dir)
33 +└── widgets/Clock.qml # import via: import qs.widgets as W
40 -- Multiple named configs live side by side; pick with `qs -c <name>`.
41 -- `qs -p /path/to/shell.qml` runs an arbitrary file.
42 -- A `shell.qml` directly inside `~/.config/quickshell/` shadows all named configs.
36 +Named configs coexist; pick with `qs -c <name>`. Run arbitrary file: `qs -p /path/to/shell.qml`. A bare `~/.config/quickshell/shell.qml` shadows named configs.
44 -## Minimal bar (one focused monitor)
41 +import QtQuick; import Quickshell
51 43 anchors { top: true; left: true; right: true }
57 -## Per-monitor bar (the canonical shape)
49 +## Per-monitor (canonical)
52 +import QtQuick; import Quickshell
64 54 model: Quickshell.screens
65 55 delegate: Component {
69 59 anchors { top: true; left: true; right: true }
71 - Text { anchors.centerIn: parent; text: "bar" }
77 -`Quickshell.screens` is the monitor list; each element is a `ShellScreen` with `name`, `width`, `height`, `scale`.
79 -## Sizing (the rule that breaks everyone once)
66 +## Sizing (the rule that breaks everyone)
81 68 > **Implicit size flows child → parent. Actual size flows parent → child.**
83 -- Children set `implicitWidth`/`implicitHeight` (what they want).
84 -- Containers/`PanelWindow` set `width`/`height` (what they get).
85 -- `childrenRect` is the wrong tool for containers (creates binding loop). Use anchors or `MarginWrapperManager`/`WrapperItem`.
86 -- An `Item` with no implicit size is 0×0 — invisible. Quickshell warns about this on first show.
70 +`childrenRect` is wrong for containers (binding loop). Use anchors or `MarginWrapperManager`/`WrapperItem`. An `Item` with no implicit size is 0×0 — invisible.
92 - property int count: 0
93 - Timer { running: true; interval: 1000; repeat: true; onTriggered: count++ }
94 - width: 100 + count // re-evaluates every time count changes
76 +| Run a command, capture stdout | `Process { command: ["..."]; running: true; stdout: StdioCollector { onStreamFinished: x.text = this.text } }` |
77 +| Stream line-by-line | `Process { ...; stdout: SplitParser { onRead: line => ... } }` |
78 +| Bind service state | `PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }` then read `?.audio.volume` |
79 +| React to signal | `Connections { target: X?.audio; function onVolumeChanged() {...} }` |
80 +| Conditional window (memory-aware) | `LazyLoader { active: show; PanelWindow {...} }` |
81 +| Click-through | `PanelWindow { color: "transparent"; mask: Region {} }` |
82 +| System icon | `IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }` |
83 +| Path relative to this QML file | `Qt.resolvedUrl("foo.png")` |
84 +| Shell cache / data / state | `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` |
85 +| Env var | `Quickshell.env("VAR")` |
86 +| External callable | `IpcHandler { target: "mybar"; function toggle(): void {...} }` → `qs ipc call mybar toggle` |
87 +| Version-gate | `Loader { active: Quickshell.hasVersion("0.3.0"); sourceComponent: ... }` |
98 -`property <type> <name>: <expr>` declares a reactive property. Any binding to it (including inside other components) re-runs when dependencies change.
103 -import QtQuick // Rectangle, Text, Item, Timer, etc.
104 -import QtQuick.Layouts // RowLayout, ColumnLayout, GridLayout
105 -import QtQuick.Controls // Button, Slider, Label (Material/Universal styling)
106 -import Quickshell // PanelWindow, FloatingWindow, PopupWindow, Scope, ShellRoot, Quickshell.* helpers
107 -import Quickshell.Io // Process, StdioCollector, SplitParser, Socket, FileView, IpcHandler
108 -import Quickshell.Wayland // Toplevel, ToplevelManager, WlSessionLock, WlrLayershell
109 -import Quickshell.Services.Pipewire // Pipewire, PwObjectTracker, PwNode, PwNodeLinkTracker
110 -import Quickshell.Services.Mpris // Mpris (media player)
111 -import Quickshell.Services.Notifications
112 -import Quickshell.Services.SystemTray
113 -import Quickshell.Services.UPower // battery
114 -import Quickshell.Services.Bluetooth
115 -import Quickshell.Services.Polkit
116 -import Quickshell.Widgets // IconImage, WrapperRectangle, MarginWrapperManager, ClippingWrapperRectangle
117 -import qs.widgets as W // your own modules, v0.2.0+; LSP-friendly
118 -import qs // the shell root dir
121 -Neighbor `.qml` files starting with **uppercase** are implicitly importable from `shell.qml`. Use `qs.*` for subfolders — much better LSP coverage than relative path imports.
126 -// One-shot command, capture all stdout as a string
130 - stdout: StdioCollector { onStreamFinished: someText.text = this.text }
133 -// Long-running stream, line by line
135 - command: ["some-listener"]
137 - stdout: SplitParser {
138 - onRead: line => console.log("got:", line)
143 -`StdioCollector` accumulates then fires `streamFinished`. `SplitParser` fires `onRead` per line. **One process, many widgets** — don't spawn one `Process` per widget (FAQ).
145 -##
Binding to a service's state 147 -Most Quickshell services expose singletons with reactive state. To read a property, you must keep the service "looking" at the object or the binding dies:
150 -import Quickshell.Services.Pipewire
152 -// Force Pipewire to keep tracking the default sink
153 -PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
154 -Text { text: `vol: ${(Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100 | 0}%` }
157 -Same pattern for `Mpris.players`, `UPower.devices`, `Bluetooth.adapters`, etc. The tracker + `?.` optional chain is idiomatic.
162 -// Property change handler (auto-generated signal)
163 -onVolumeChanged: console.log("vol =", volume)
167 -onClicked: doThing()
169 -// Connections to a target's signals
171 - target: Pipewire.defaultAudioSink?.audio
172 - function onVolumeChanged() { ... }
175 -// One-shot at creation
176 -Component.onCompleted: console.log("ready")
179 -##
Conditional UI (memory-aware) 182 -// Cheap, always in memory; just hides
183 -Item { visible: shouldShow; ... }
185 -// Frees memory when not active (rebuilds on toggle)
186 -LazyLoader { active: shouldShow; PanelWindow { ... } }
189 -`LazyLoader` for non-Item roots (`PanelWindow` etc.); `Loader` for `Item`-derived trees. The `visible` toggle is fine for always-shown panels; `LazyLoader` is the answer for OSDs/drawers that appear and disappear.
195 - color: "transparent"
196 - mask: Region {} // empty click region — clicks pass through
200 -`Region` is the only correct way to make a window ignore input while still rendering. Use it for OSDs and decorative overlays.
205 -import Quickshell.Widgets
206 -IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }
209 -`Quickshell.iconPath(name)` resolves a system icon theme name. Three overloads: missing icon → purple/black square, fallback, or empty string. Use the fallback/empty overload if the square bothers you.
213 -- `Qt.resolvedUrl("foo.png")` → path relative to the current QML file.
214 -- `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` → XDG cache/data/state for this shell.
215 -- `Quickshell.env("VAR")` → env var lookup.
220 92 touch ~/.config/quickshell/<name>/.qmlls.ini
223 -Quickshell will overwrite it with a managed config (gitignore it). qmlls gives completions for Quickshell types. **Without `.qmlls.ini`, all Quickshell symbols are unresolved in your editor.**
95 +Quickshell manages the file content; gitignore it. Without it, every Quickshell symbol is unresolved in your editor.
227 -API breaks between minor versions. Use `Quickshell.hasVersion("0.3.0")` and the preprocessor (`pragma …`) to version-gate. Pin your distro's quickshell package; track master only if you want to live on the edge.
231 -- `references/types.md` — quick lookup table of every Quickshell type
232 -- `references/patterns.md` — reusable recipes (timers, process I/O, signals, monitor-per-instance, conditional load)
233 -- `references/services.md` — pipewire, mpris, notifications, system tray, upower, bluetooth, greetd, polkit
234 -- `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock
235 -- `references/resources.md` — icons, paths, env, system paths
236 -- `references/getting-fresh-docs.md` — how to read the current docs (don't memorize; look up)
237 -- `examples/` — minimal, runnable prototypes; copy/adapt
99 +API breaks happen between minor versions. Pin the distro package; track master only if you want the edge. Use `Quickshell.hasVersion()` + the preprocessor to version-gate.
239 101 ##
When NOT to use 241 -- You want a preconfigured desktop → use [Caelestia](https://github.com/caelestia-dots/shell) or [Illogical-Impulse](https://github.com/end-4/dots-hyprland) instead.
242 -- You want a one-line status bar → use Waybar. Quickshell is programming, not config.
243 -- You target Windows/macOS → Quickshell is Linux/BSD only.
244 -- You're on X11 with no wlroots compat → Hyprland/Sway/i3/Niri are the supported targets; X11 is best-effort.
103 +- Preconfigured desktop → Caelestia / Illogical-Impulse.
104 +- One-line status bar → Waybar. Quickshell is programming.
105 +- Windows / macOS → Linux + BSD only.
106 +- X11 with no wlroots compat → prefer Hyprland/Sway/i3/Niri.
110 +- `references/types.md` — curated type index
111 +- `references/patterns.md` — 16 reusable recipes (P1–P16)
112 +- `references/services.md` — pipewire, mpris, notifications, tray, upower, bluetooth, greetd, polkit
113 +- `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock / WlrLayershell
114 +- `references/resources.md` — paths, icons, env, IPC, persistence
115 +- `references/getting-fresh-docs.md` — how to read current docs
116 +- `examples/` — 6 minimal, runnable prototypes