import QtQuick
import Quickshell

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 30
    Text { anchors.centerIn: parent; text: "hello" }
}

import QtQuick
import Quickshell

Variants {
    model: Quickshell.screens
    delegate: Component {
        PanelWindow {
            required property var modelData
            screen: modelData
            anchors { top: true; left: true; right: true }
            implicitHeight: 30
        }
    }
}

npm test

---
name: quickshell
license: LGPL-3.0
description: "Use for building, reviewing, or debugging Quickshell desktop components and qs IPC. Not general QML or compositor config."
---

# Quickshell

## Start with the installed version

**Do not write Quickshell APIs from memory.**
Quickshell changes between releases, especially service modules.

1. Run `qs --version`.
2. Read the matching official guide and type pages under `https://quickshell.org/docs/v<version>/`.
3. When local and web versions may differ, inspect the installed `*.qmltypes` files under `/usr/lib/qt6/qml/Quickshell/` or the platform's equivalent QML import path.
4. Cross-check a nearby official example before using a service or compositor-specific API.

Use [`references/getting-fresh-docs.md`](references/getting-fresh-docs.md) for the lookup procedure.
If cloning upstream examples is necessary, use the `git_clone_safe` tool with the repository URL and an isolated destination.
It is a tool, not a shell command.

## Model

A Quickshell entry file has one QML root object.
There is no rule that it must be `ShellRoot` or `Scope`.
A single `PanelWindow` and a per-screen `Variants` object are both valid roots.
`ShellRoot` is optional and provides inline shell settings.
`Scope` groups non-visual reloadable objects.

```qml
import QtQuick
import Quickshell

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 30
    Text { anchors.centerIn: parent; text: "hello" }
}
```

For one instance per screen:

```qml
import QtQuick
import Quickshell

Variants {
    model: Quickshell.screens
    delegate: Component {
        PanelWindow {
            required property var modelData
            screen: modelData
            anchors { top: true; left: true; right: true }
            implicitHeight: 30
        }
    }
}
```

Use:

- `PanelWindow` for anchored panels and layer-shell surfaces.
- `FloatingWindow` for ordinary desktop windows.
- `PopupWindow` for a popup anchored to another Quickshell window.
- `ShellRoot` when the entry needs multiple child objects or inline shell settings.
- `Scope` when non-visual objects need a common reload scope.

`WlrLayershell` is an attached object on `PanelWindow`, not on `FloatingWindow`.
See [`references/windowing.md`](references/windowing.md).

## QML rules that matter here

- Keep state reactive with property bindings.
- Implicit size flows from child to parent; actual size flows from parent to child.
- Do not use `childrenRect` as a generic container sizing shortcut because it commonly creates binding loops.
- For a service-backed `Slider`, bind `value` to service state and write user movement in `onMoved`.
  Do not replace the binding with imperative synchronization handlers.
- Use `Connections` for signals from a changing external object.
- Use `PwObjectTracker` when the matching installed PipeWire docs require tracking an object.

See [`references/patterns.md`](references/patterns.md) for the small set of retained patterns.

## Services and privileged components

For notifications, PipeWire, MPRIS, PAM, greetd, Polkit, Bluetooth, networking, and system tray APIs,
read the installed-version type page before coding.
Do not advertise a notification capability unless the implementation actually provides it.
Do not improvise PAM, greetd, or Polkit conversations.
Use the official installed-version example and keep prompts separate from user responses.

See [`references/services.md`](references/services.md).

## Tooling: follow upstream first

Read the installed version's [official tooling recommendations](https://quickshell.org/docs/v0.3.1/guide/install-setup/#language-server) before diagnosing a linter or inventing metadata.
Upstream recommends `qmlls` and an empty `.qmlls.ini` beside the entry point.
Quickshell generates the machine-specific configuration; gitignore it and do not hand-maintain its paths.
Use the matching Qt major version for both `qmlls` and `qmllint`.
On Arch, `/usr/lib/qt6/bin/qmllint` is Qt6; the bare `qmllint` command may be Qt5.

Upstream explicitly documents that `PanelWindow` cannot be resolved by the language server.
Its runtime backend registration is not fully represented in static metadata; see [issue #543](https://github.com/quickshell-mirror/quickshell/issues/543).
This is not evidence that valid panel QML or typed IPC functions are broken.
Capture complete stdout/stderr from a minimal reproduction with the correct Qt tool before attributing a failure.
Do not fabricate type metadata, remove typing, or disable additional warning categories to obtain a pass.
Keep project-approved lint policy and verify actual loading in a nested compositor.

## Validation

Separate these evidence levels:

1. **Static:** `qmllint` resolves supported imports and QML structure.
2. **Load:** Quickshell loads the configuration without diagnostics.
3. **Interaction:** input, IPC, timers, hotplug, and service events behave correctly.
4. **Visual:** placement, sizing, clipping, color, typography, and animation are accepted on target displays.

A static or offscreen load check proves neither interaction nor visual correctness.
Do not claim UI validation without observing and exercising the mapped surfaces.

**Never test desktop components against the user's real desktop session by default.**
A test instance can claim D-Bus names, notification ownership, layer-shell surfaces, session-lock protocols, or authentication agents.
Use a nested compositor plus isolated runtime, D-Bus, and service state for runtime checks.
Offscreen validation is limited to parsing or loading and must be reported as such.
Never run live authentication or lockscreen tests without an explicit isolated test plan.

Run helper tests from this skill directory:

```sh
npm test
```

## References

- [`references/getting-fresh-docs.md`](references/getting-fresh-docs.md)
- [`references/patterns.md`](references/patterns.md)
- [`references/windowing.md`](references/windowing.md)
- [`references/services.md`](references/services.md)
- [`references/resources.md`](references/resources.md)
- [`references/packaging.md`](references/packaging.md)
- [`examples/`](examples/)
- `qml` skill for QML language and layout details