3 +description: Use when building Wayland desktop components with Quickshell (status bars, widgets, OSDs, lockscreens, Greetd login, Polkit agent, app launchers) on Hyprland/Sway/i3/Niri. Triggers on "quickshell", "qs shell", "qml bar", "qtquick panel", "make me a bar/widget/lockscreen with quickshell", "add a module to my quickshell config".
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.
14 +└── ShellRoot (or Scope)
15 + ├── Variants { model: Quickshell.screens; delegate: Component { PanelWindow {...} } }
16 + ├── FloatingWindow {...}
17 + ├── PopupWindow {...}
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.
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)
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.
44 +##
Minimal bar (one focused monitor) 51 + anchors { top: true; left: true; right: true }
53 + Text { anchors.centerIn: parent; text: "hello" }
57 +##
Per-monitor bar (the canonical shape) 64 + model: Quickshell.screens
65 + delegate: Component {
67 + required property var modelData
69 + 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) 81 +> **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.
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
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 +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.**
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
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.