tonybtw.com

#+TITLE: Quickshell Tutorial - Build Your Own Bar

#+AUTHOR: Tony, btw

#+date: 2025-12-03

#+HUGO_TITLE: Quickshell Tutorial - Build Your Own Bar

#+HUGO_FRONT_MATTER_FORMAT: yaml

#+HUGO_CUSTOM_FRONT_MATTER: :image "/img/quickshell.png" :showTableOfContents true

#+HUGO_BASE_DIR: ~/repos/tonybtw.com

#+HUGO_SECTION: tutorial/quickshell

#+EXPORT_FILE_NAME: index

#+OPTIONS: toc:nil broken-links:mark

#+HUGO_AUTO_SET_HEADLINE_SECTION: nil

#+DESCRIPTION: This is a quick and painless tutorial on how to build a custom status bar using Quickshell, a powerful Qt/QML based shell framework for Wayland.

* Intro

What's up guys, my name is Tony, and today I'm gonna give you a quick and painless introduction to Quickshell.

Quickshell is a full shell framework built on Qt/QML. You can build pretty much any desktop widget you can imagine with it - bars, dashboards, wallpaper managers, screen lock widgets, and more.

We're going to do a basic overview of how to create a bar using Quickshell today. In future tutorials I'll cover creating a wallpaper manager, building a dashboard overlay, and making a screen lock widget. But for now, let's start with the fundamentals by building a functional status bar step by step.

* Install Quickshell

Alright so I'm on NixOS today, but this is going to work on Arch, Gentoo, and other distributions. I'll leave install instructions for all of those below.

[[https://quickshell.org/docs/v0.2.1/types/][Quickshell Documentation]]

*** NixOS

#+begin_src nix

{

  environment.systemPackages = with pkgs; [

    quickshell

  ];

}

#+end_src

*** Arch Linux

#+begin_src sh

yay -S quickshell-git

#+end_src

*** Gentoo

For Gentoo, you'll need to compile from source:

#+begin_src sh

git clone https://github.com/outfoxxed/quickshell

cd quickshell

# Follow the build instructions in their README

#+end_src

* Running Examples

You can run any of these examples with:

#+begin_src sh

qs -p ~/.config/testshell/01-hello.qml

#+end_src

Just swap out the filename as we go through each one.

* 01 - Hello World

Quickshell has excellent documentation, and we're going to be following that today. Let's start with the absolute basics - just getting something on screen.

#+begin_src qml

import Quickshell

import QtQuick

FloatingWindow {

    visible: true

    width: 200

    height: 100

    Text {

        anchors.centerIn: parent

        text: "Hello, Quickshell!"

        color: "#0db9d7"

        font.pixelSize: 18

    }

}

#+end_src

So what's going on here?

Every Quickshell config starts with imports. We're pulling in =Quickshell= for the core stuff and =QtQuick= for basic UI elements like =Text= and =Rectangle=.

We're using =FloatingWindow= as our root element. This is just a regular floating window - it doesn't dock to any edges or reserve any screen space. We're setting it to 200x100 pixels and making it visible.

The =Text= element is pretty self-explanatory. The =anchors.centerIn: parent= bit is QML's layout system - it just centers the text inside its parent container.

* 02 - Empty Bar

Alright, let's turn this into an actual bar that docks to the top of your screen.

#+begin_src qml

import Quickshell

import Quickshell.Wayland

import QtQuick

PanelWindow {

    anchors.top: true

    anchors.left: true

    anchors.right: true

    implicitHeight: 30

    color: "#1a1b26"

    Text {

        anchors.centerIn: parent

        text: "My First Bar"

        color: "#a9b1d6"

        font.pixelSize: 14

    }

}

#+end_src

The big change here is we're using =PanelWindow= as our root element instead of =FloatingWindow=. This is a Wayland-specific thing (hence the new import), and it lets us dock the window to screen edges.

Setting =anchors.top=, =anchors.left=, and =anchors.right= to =true= tells it to stick to the top edge and span the full width. The =implicitHeight: 30= gives us a 30 pixel tall bar.

Unlike a floating window, a =PanelWindow= actually reserves space - your other windows won't overlap with it.

* 03 - Workspaces

So we are on Hyprland today, lets add quickshell to our Hyprland config.

Now let's add some actual functionality - workspace indicators that show which workspace you're on and let you click to switch.

#+begin_src qml

import Quickshell

import Quickshell.Wayland

import Quickshell.Hyprland

import QtQuick

import QtQuick.Layouts

PanelWindow {

    anchors.top: true

    anchors.left: true

    anchors.right: true

    implicitHeight: 30

    color: "#1a1b26"

    RowLayout {

        anchors.fill: parent

        anchors.margins: 8

        Repeater {

            model: 9

            Text {

                property var ws: Hyprland.workspaces.values.find(w => w.id === index + 1)

                property bool isActive: Hyprland.focusedWorkspace?.id === (index + 1)

                text: index + 1

                color: isActive ? "#0db9d7" : (ws ? "#7aa2f7" : "#444b6a")

                font { pixelSize: 14; bold: true }

                MouseArea {

                    anchors.fill: parent

                    onClicked: Hyprland.dispatch("workspace " + (index + 1))

                }

            }

        }

        Item { Layout.fillWidth: true }

    }

}

#+end_src

Okay, there's a lot more going on here. Let me break it down.

We're importing =Quickshell.Hyprland= which gives us access to Hyprland's IPC.

=QtQuick.Layouts= gives us =RowLayout=, which arranges its children horizontally. Way easier than manually positioning everything.

The =Repeater= is super useful - it takes a model (in this case, just the number 9) and creates that many copies of whatever's inside it. Each copy gets an =index= variable (0-8).

For each workspace number, we're looking up the actual workspace from the window manager with =Hyprland.workspaces.values.find()=. This gives us live data - when workspaces change, the bar updates automatically. We also check if it's the active workspace using =Hyprland.focusedWorkspace=.

The color logic is straightforward: cyan if it's the active workspace, blue if it exists but isn't active, and muted gray if there's no windows on that workspace.

The =MouseArea= makes the whole thing clickable, and =Hyprland.dispatch()= sends commands to Hyprland. So clicking on "3" runs =workspace 3=.

That =Item { Layout.fillWidth: true }= at the end is just a spacer - it pushes everything to the left.

* 04 - System Stats

Now let's add some system stats. This is where things get interesting because we need to run shell commands and parse their output.

** Theme Properties

Instead of hardcoding colors everywhere, we define them once on the PanelWindow. Now you can reference =root.colBg= anywhere in your config, and if you want to change your color scheme, you only have to do it in one place.

#+begin_src qml

PanelWindow {

    id: root

    property color colBg: "#1a1b26"

    property color colFg: "#a9b1d6"

    property color colMuted: "#444b6a"

    property color colCyan: "#0db9d7"

    property color colBlue: "#7aa2f7"

    property color colYellow: "#e0af68"

    property string fontFamily: "JetBrainsMono Nerd Font"

    property int fontSize: 14

}

#+end_src

** Running Shell Commands

This is how you run external commands and capture their output. We import =Quickshell.Io= which gives us the =Process= type.

#+begin_src qml

Process {

    id: cpuProc

    command: ["sh", "-c", "head -1 /proc/stat"]

    stdout: SplitParser {

        onRead: data => {

            if (!data) return

            var p = data.trim().split(/\s+/)

            var idle = parseInt(p[4]) + parseInt(p[5])

            var total = p.slice(1, 8).reduce((a, b) => a + parseInt(b), 0)

            if (lastCpuTotal > 0) {

                cpuUsage = Math.round(100 * (1 - (idle - lastCpuIdle) / (total - lastCpuTotal)))

            }

            lastCpuTotal = total

            lastCpuIdle = idle

        }

    }

    Component.onCompleted: running = true

}

#+end_src

The =command= is an array - first element is the program, rest are arguments. The =SplitParser= attached to =stdout= calls =onRead= for each line of output. Setting =running = true= triggers the process to run.

** Timers

To update the CPU usage periodically, we use a =Timer=. This one fires every 2 seconds and re-runs the CPU process.

#+begin_src qml

Timer {

    interval: 2000        // Every 2 seconds

    running: true         // Start immediately

    repeat: true          // Keep going forever

    onTriggered: cpuProc.running = true

}

#+end_src

* 05 - Adding Widgets

Let's expand our bar with a clock and memory usage. This builds on the same patterns - more =Process= calls and =Timer= elements.

** Memory Widget

#+begin_src qml

// Add to your system data properties

property int memUsage: 0

// Memory process

Process {

    id: memProc

    command: ["sh", "-c", "free | grep Mem"]

    stdout: SplitParser {

        onRead: data => {

            if (!data) return

            var parts = data.trim().split(/\s+/)

            var total = parseInt(parts[1]) || 1

            var used = parseInt(parts[2]) || 0

            memUsage = Math.round(100 * used / total)

        }

    }

    Component.onCompleted: running = true

}

// Update your timer to run both processes

Timer {

    interval: 2000

    running: true

    repeat: true

    onTriggered: {

        cpuProc.running = true

        memProc.running = true

    }

}

#+end_src

** Clock

The clock is just a =Text= element with its own timer. Every second it updates the text with the current time.

#+begin_src qml

Text {

    id: clock

    text: Qt.formatDateTime(new Date(), "ddd, MMM dd - HH:mm")

    Timer {

        interval: 1000

        running: true

        repeat: true

        onTriggered: clock.text = Qt.formatDateTime(new Date(), "ddd, MMM dd - HH:mm")

    }

}

#+end_src

** Adding Dividers

To visually separate widgets, you can use simple =Rectangle= elements:

#+begin_src qml

Rectangle { width: 1; height: 16; color: root.colMuted }

#+end_src

* Complete Bar Example

Here's the final bar with workspaces, CPU, memory, and a clock all together:

#+begin_src qml

import Quickshell

import Quickshell.Wayland

import Quickshell.Io

import Quickshell.Hyprland

import QtQuick

import QtQuick.Layouts

PanelWindow {

    id: root

    // Theme

    property color colBg: "#1a1b26"

    property color colFg: "#a9b1d6"

    property color colMuted: "#444b6a"

    property color colCyan: "#0db9d7"

    property color colBlue: "#7aa2f7"

    property color colYellow: "#e0af68"

    property string fontFamily: "JetBrainsMono Nerd Font"

    property int fontSize: 14

    // System data

    property int cpuUsage: 0

    property int memUsage: 0

    property var lastCpuIdle: 0

    property var lastCpuTotal: 0

    // Processes and timers here...

    anchors.top: true

    anchors.left: true

    anchors.right: true

    implicitHeight: 30

    color: root.colBg

    RowLayout {

        anchors.fill: parent

        anchors.margins: 8

        spacing: 8

        // Workspaces

        Repeater {

            model: 9

            Text {

                property var ws: Hyprland.workspaces.values.find(w => w.id === index + 1)

                property bool isActive: Hyprland.focusedWorkspace?.id === (index + 1)

                text: index + 1

                color: isActive ? root.colCyan : (ws ? root.colBlue : root.colMuted)

                font { family: root.fontFamily; pixelSize: root.fontSize; bold: true }

                MouseArea {

                    anchors.fill: parent

                    onClicked: Hyprland.dispatch("workspace " + (index + 1))

                }

            }

        }

        Item { Layout.fillWidth: true }

        // CPU

        Text {

            text: "CPU: " + cpuUsage + "%"

            color: root.colYellow

            font { family: root.fontFamily; pixelSize: root.fontSize; bold: true }

        }

        Rectangle { width: 1; height: 16; color: root.colMuted }

        // Memory

        Text {

            text: "Mem: " + memUsage + "%"

            color: root.colCyan

            font { family: root.fontFamily; pixelSize: root.fontSize; bold: true }

        }

        Rectangle { width: 1; height: 16; color: root.colMuted }

        // Clock

        Text {

            id: clock

            color: root.colBlue

            font { family: root.fontFamily; pixelSize: root.fontSize; bold: true }

            text: Qt.formatDateTime(new Date(), "ddd, MMM dd - HH:mm")

            Timer {

                interval: 1000

                running: true

                repeat: true

                onTriggered: clock.text = Qt.formatDateTime(new Date(), "ddd, MMM dd - HH:mm")

            }

        }

    }

}

#+end_src

* Key Concepts Summary

| Concept       | Description                                           |

|---------------+-------------------------------------------------------|

| FloatingWindow | A regular floating window, doesn't dock              |

| PanelWindow   | Docks to screen edges, reserves space                 |

| RowLayout     | Arranges children horizontally                        |

| Repeater      | Creates multiple copies of a component                |

| Process       | Runs shell commands and captures output               |

| Timer         | Triggers actions at intervals                         |

| MouseArea     | Makes elements clickable                              |

| anchors       | QML's layout system for positioning                   |

| property      | Declare custom variables on components                |

* Next Steps

That's the core of it. Quickshell can do way more than just bars though - you can build:

- Wallpaper managers with smooth transitions

- Dashboard overlays with system stats

- Screen lock widgets

- Notification centers

- Application launchers

Check out the Quickshell documentation for more advanced features and the full API reference.

* Final Thoughts

Thanks so much for checking out this tutorial. If you got value from it, and you want to find more tutorials like this, check out

my youtube channel here: [[https://youtube.com/@tony-btw][YouTube]], or my website here: [[https://www.tonybtw.com][tony,btw]]

You can support me here: [[https://ko-fi.com/tonybtw][kofi]]