QuickShell

Inputs

Core Concepts

shell.qml entry point

//@ pragma Env QSG_RENDER_LOOP=threaded

import "modules"
import "services"
import Quickshell

ShellRoot {
    Background {}
    Bar {}
    Notifications {}
    Shortcuts {}
    BatteryMonitor {}
}

ShellRoot is the root element. Child elements are typically Scope-based modules or window types.

PanelWindow — anchored bar/panel

import Quickshell
import QtQuick

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 30

    Text {
        anchors.centerIn: parent
        text: "hello world"
        color: "white"
    }
}

Multi-monitor with Variants

Spawn one instance per screen. Instances appear/disappear automatically as monitors connect/disconnect.

import Quickshell

Variants {
    model: Quickshell.screens

    PanelWindow {
        required property ShellScreen modelData
        screen: modelData

        anchors { top: true; left: true; right: true }
        implicitHeight: 30
    }
}

Singleton — global shared service

Add pragma Singleton to a capitalized .qml file. Access it by filename from anywhere in the config. The root element must be Singleton {}, not QtObject or Item.

// services/Audio.qml
pragma Singleton

import Quickshell
import Quickshell.Services.Pipewire

Singleton {
    id: root

    readonly property PwNode sink: Pipewire.defaultAudioSink
    readonly property bool muted: !!sink?.audio?.muted
    readonly property real volume: sink?.audio?.volume ?? 0

    function setVolume(newVolume: real): void {
        if (sink?.ready && sink?.audio)
            sink.audio.volume = Math.max(0, Math.min(1.0, newVolume));
    }
}

Scope — non-singleton module

Use Scope (not Singleton) for modules that don't need global access, or that are instantiated per context (e.g., keyboard shortcuts, battery watchers). Scope participates in the reload graph but is not globally addressable.

// modules/BatteryMonitor.qml
import Quickshell
import Quickshell.Services.UPower
import QtQuick

Scope {
    Connections {
        target: UPower

        function onOnBatteryChanged(): void {
            if (UPower.onBattery)
                console.log("Charger unplugged")
        }
    }

    Timer {
        id: hibernateTimer
        interval: 5000
        onTriggered: Quickshell.execDetached(["systemctl", "hibernate"])
    }
}

pragma ComponentBehavior: Bound

Always add this pragma when a file uses component definitions or signal handlers inside nested components. Without it, inner component blocks cannot reliably access outer id references or required properties.

pragma Singleton
pragma ComponentBehavior: Bound

import Quickshell
import QtQuick

Singleton {
    id: root

    component Notif: QtObject {
        required property string summary
        // Can safely reference `root` here because of ComponentBehavior: Bound
        function close(): void {
            root.list = root.list.filter(n => n !== this);
            destroy();
        }
    }
}

Typed Functions and Properties

QuickShell uses QML 6 — always annotate function parameters and return types:

function setVolume(newVolume: real): void { ... }
function getStreamVolume(stream: PwNode): real { return stream?.audio?.volume ?? 0 }
function getStreamName(stream: PwNode): string { return stream?.name ?? "Unknown" }
function isDndEnabled(): bool { return props.dnd }
function cycleWorkspace(direction: string): void { ... }

Typed property declarations:

readonly property PwNode sink: Pipewire.defaultAudioSink
readonly property list<PwNode> sinks: nodes.sinks
property list<Notif> list: []
readonly property HyprlandMonitor focusedMonitor: Hyprland.focusedMonitor

Null Safety

Use ?. (optional chaining) and ?? (null coalescing) freely — they are idiomatic in QuickShell code:

readonly property bool muted: !!sink?.audio?.muted      // double-! coerces to bool
readonly property real volume: sink?.audio?.volume ?? 0
readonly property string layout: keyboard?.activeKeymap ?? "Unknown"
readonly property int activeWsId: focusedWorkspace?.id ?? 1

Connections

Connections is the primary way to react to signals on external objects. Use the function onXxx() syntax (not the old onXxx: property syntax):

Connections {
    target: Hyprland

    function onRawEvent(event: HyprlandEvent): void {
        if (event.name === "configreloaded")
            root.reload();
        else if (["openwindow", "closewindow"].includes(event.name))
            Hyprland.refreshToplevels();
    }
}

Connections {
    target: UPower.displayDevice

    function onPercentageChanged(): void {
        const p = UPower.displayDevice.percentage * 100;
        if (p <= 10) console.warn("Battery critical:", p);
    }
}

Multiple Connections blocks in one file are fine and common.

Readonly Properties with Complex Expressions

Use JS array methods directly in readonly property bindings:

// Partition Pipewire nodes into sinks, sources, and streams
readonly property var nodes: Pipewire.nodes.values.reduce((acc, node) => {
    if (!node.isStream) {
        if (node.isSink) acc.sinks.push(node);
        else if (node.audio) acc.sources.push(node);
    } else if (node.audio) {
        acc.streams.push(node);
    }
    return acc;
}, { sinks: [], sources: [], streams: [] })

readonly property list<PwNode> sinks: nodes.sinks

// Find active network access point
readonly property AccessPoint active: networks.find(n => n.active) ?? null

// Filter only open special workspaces
readonly property var openSpecials: workspaces.values
    .filter(w => w.name.startsWith("special:") && w.lastIpcObject.windows > 0)

Inline Components

Define reusable local types inside a file using component. Requires pragma ComponentBehavior: Bound.

pragma Singleton
pragma ComponentBehavior: Bound

import Quickshell
import Quickshell.Services.Notifications
import QtQuick

Singleton {
    id: root

    property list<Notif> list: []
    readonly property list<Notif> popups: list.filter(n => n.popup)

    component Notif: QtObject {
        property bool popup
        property bool closed
        property string summary
        property string body
        property int urgency
        property var locks: new Set()

        function close(): void {
            closed = true;
            if (locks.size === 0) {
                root.list = root.list.filter(n => n !== this);
                destroy();
            }
        }
    }

    Component { id: notifComp; Notif {} }

    NotificationServer {
        onNotification: notif => {
            const obj = notifComp.createObject(root, {
                summary: notif.summary,
                body: notif.body,
                popup: true
            });
            root.list = [obj, ...root.list];
        }
    }
}

IpcHandler — CLI control

Expose functions to external tools via qs ipc call <target> <function> [args...]. Return types matter: use string, bool, real, or void.

IpcHandler {
    target: "audio"

    function getVolume(): real { return Audio.volume }
    function setVolume(v: real): void { Audio.setVolume(v) }
    function toggleMute(): void {
        if (Audio.sink?.audio)
            Audio.sink.audio.muted = !Audio.sink.audio.muted;
    }
}

IpcHandler {
    target: "notifs"

    function isDndEnabled(): bool { return props.dnd }
    function toggleDnd(): void { props.dnd = !props.dnd }
    function clear(): void {
        for (const n of root.list.slice()) n.close();
    }
    function listActive(): string {
        return root.notClosed.map(n => n.summary).join("\n");
    }
}

Call from the terminal:

qs ipc call audio setVolume 0.5
qs ipc call notifs toggleDnd
qs ipc call notifs isDndEnabled
qs ipc call hypr listSpecialWorkspaces

PersistentProperties

Survives config reload. Use reloadableId (not reloadSource) to key the storage.

PersistentProperties {
    id: props
    reloadableId: "notifs"

    property bool dnd
    property string lastWorkspace: ""
}

Access like any object: props.dnd, props.lastWorkspace = "special:scratch".

FileView — reading and writing files

FileView {
    path: `${Quickshell.configDir}/state/notifs.json`

    onLoaded: {
        const data = JSON.parse(text());
        for (const item of data)
            root.list.push(notifComp.createObject(root, item));
    }

    onLoadFailed: err => {
        if (err === FileViewError.FileNotFound)
            setText("[]");   // initialize empty file
    }
}

setText() writes back to the file. Use JsonAdapter for typed JSON access.

Process — running commands

import Quickshell.Io

// One-shot: collect full output
Process {
    id: dateProc
    command: ["date", "+%H:%M"]   // always an array, never a plain string
    running: true

    stdout: StdioCollector {
        onStreamFinished: root.timeText = text.trim()
    }
}

// Streaming: line-by-line output
Process {
    command: ["nmcli", "monitor"]
    running: true

    stdout: SplitParser {
        onRead: line => root.handleNmcliLine(line)
    }
}

Periodic refresh:

Timer {
    interval: 60000; repeat: true; running: true
    onTriggered: dateProc.running = true
}

LazyLoader — conditional/deferred components

LazyLoader {
    id: dialogLoader
    active: false   // set true to load, false to unload and destroy

    FloatingWindow {
        // only created when dialogLoader.active = true
    }
}

Utility Functions

// Fire-and-forget (no stdout capture):
Quickshell.execDetached(["systemctl", "hibernate"])
Quickshell.execDetached(["notify-send", "Hello"])

// Read environment variable:
Quickshell.env("XKB_RULES_PATH") || "/usr/share/X11/xkb/rules/base.lst"

// Deferred execution (next event loop tick):
Qt.callLater(() => { root.initialize() })
Qt.callLater(() => { root.sync() }, 100)   // with ms delay

Import Structure

Three tiers — always in this order:

// 1. Local project imports
import "modules"
import qs.services
import qs.config

// 2. Framework/plugin imports (if any)
import Caelestia.Services

// 3. Quickshell + Qt imports
import Quickshell
import Quickshell.Hyprland
import Quickshell.Io
import Quickshell.Services.Pipewire
import QtQuick
import QtQuick.Layouts

Module Reference

Quickshell (core)

Quickshell.Io

Quickshell.Hyprland

Refresh methods: Hyprland.refreshWorkspaces(), Hyprland.refreshMonitors(), Hyprland.refreshToplevels(), Hyprland.dispatch(request).

Quickshell.Wayland

Quickshell.Services.Mpris

Quickshell.Services.Notifications

Quickshell.Services.SystemTray

Quickshell.Services.Pipewire

Quickshell.Services.UPower

Quickshell.Widgets

Workflow

Step 1: Pick the right root type

Step 2: Map goal to modules

Step 3: Write the QML

• Add pragma ComponentBehavior: Bound whenever the file uses component definitions
• Annotate all function parameters and return types
• Use ?. and ?? for nullable Quickshell model objects
• Use Connections { target: X; function onY() {} } for all signal reactions
• Extract shared state to pragma Singleton files (capitalized names, Singleton {} root)
• Use PersistentProperties with reloadableId for state that must survive --reload
• Add PwObjectTracker { objects: [...] } when holding Pipewire node references

Step 4: Reload and test

quickshell --reload
quickshell -p shell.qml

Step 5: Debug

• QML errors print to stderr — always run from a terminal
• console.log(...) / console.warn(...) for runtime values
• qs ipc call <target> <fn> to exercise IpcHandler functions live

Validation

• pragma ComponentBehavior: Bound present in files that define component types
• All function parameters and return types annotated
• ?. / ?? used on all nullable Quickshell model properties
• Multi-monitor widgets wrapped in Variants { model: Quickshell.screens }
• Singleton {} used as root in singleton files (not QtObject or Item)
• PersistentProperties uses reloadableId (not reloadSource)
• Process.command is a string array
• PwObjectTracker present when retaining Pipewire node references
• quickshell --reload shows no parse errors

Common Pitfalls

More Info

• Type reference: https://quickshell.org/docs/v0.2.1/types/
• Usage guide: https://quickshell.org/docs/v0.2.1/guide/
• Examples: https://github.com/outfoxxed/quickshell-examples