Quickshell shell
The Quickshell UI of equisdots: bar engines, panels, settings editor, desktop widgets and IPC.
The shell in equisdots/shell is a Quickshell application that provides the bar, popups, panels, the settings editor, the desktop widgets and the lock screen. It is written in QML with a small JavaScript layer for pure logic.
It is compositor-neutral: core/Compositor.qml selects a backend at
runtime (Hyprland by default, niri when XDG_CURRENT_DESKTOP
contains niri or NIRI_SOCKET is set). Widgets never branch on the
compositor; they consume the same adapter surface. Under niri the shared shell
is completed by the niri-shell overlay (see
Architecture).
It is also plugin-driven: generic hosts mount enabled plugins, their panels, bar modules and complete bars without knowing plugin ids. Nyx, timex, screenshots and the keybind editor are the first surfaces; see Plugins and extensions.
Shell.qml is the main entry: it mounts the master window, the bar, the
floating layer and the desktop widgets. Lock.qml is the alternate entry for
the PAM session lock (WlSessionLock), launched by lock.sh; both import the
same core/ services.
Architecture
Shell.qml
core/ services and contracts (no visuals)
Config.qml settings.json: rawSettings + setSetting/updateJsonBulk
WindowRegistry.js widget layout + position math
Personalization.js option tables; EditorNav.js panel pages
Theme, Cava, SysData, WidgetSync, compositors/, scripts/watchers/
ui/
Main.qml master window, widget stack, morph, IPC handler
PluginHosts.qml generic mount point for plugin hosts and complete bars
bar/ host, zones engine, modules, popups
plugins/ dynamic plugin settings pages (p_<id>)
panels/ clipboard, wallpaper, file search, system and tools
widgets/ floating desktop widgets and their redactor
The widget call chain is always the same:
keybind -> qs_manager.sh -> qs ipc call main handleCommand "toggle <widget>" -> ui/Main.qml -> WindowRegistry.getLayout() -> StackView.replace.
settings.json is the single source of truth. Panels write through
Config.setSetting(key, value) and watch the file so external edits (xturing,
manual JSON edits) apply live.
The bar
The bar host (ui/bar/Bar.qml) runs a single zones engine on any screen edge
(top, bottom, left, right). Islands are grouped into data-driven zones
(start, center, end) with module drag and drop, per-zone backgrounds and
unify mode. settings.json -> bar.enabled is the master switch: off unmaps
every bar window and releases the reserved edge, live. Complete bars can also
ship as plugins (provides.bar.provider) and coexist on their own switches.
The core bar shares the palette and 18 modules: help, search, settings, update,
recording, time, date, media, workspaces, tray, keyboard, wifi, bluetooth,
sysmon, volume, battery, weather and focus. weather and focus ship disabled
so upgrades never change a layout on their own. Modules may be supplied by
plugins (provides.bar.modules.<id>): the recording indicator, weather and
sysmon are the first cases, and the core slot keeps the layout and user config.
Customizing the bar and its modules
Every module in ui/bar/modules/ is one island pill built on the shared
ModulePill component: it declares what to show, and the pill handles the
background, border, hover scale, entrance animation and clicks. The zone always
injects the same seven properties — bar, colors, zoneReady, slotIndex,
effectiveBorderWidth, effectiveBorderColor and unified — and ModulePill
adds the orientation helpers plus the normalized per-module config.
Per-module values live under bar.modules.<id> and every field is optional:
| Field | Meaning |
|---|---|
icon |
Glyph override (help, search, settings, update, keyboard, wifi, bluetooth, volume, battery, weather, focus, recording). |
color |
Content color: a colors.* role name or a #hex string. |
fill |
Island fill: default / on / off. |
accent |
Accent role override (for example green), turning the island into an accent island. |
size |
Font pixel size override (0 keeps the module default). |
effect / cursor |
Per-module view effect (typewriter on the clock) and its blinking cursor. |
The workspaces module has its own bar-wide options: workspacesMarker
(number, dot, letter, custom) and workspacesMarkerText. Built-in
defaults give battery, settings, search, time and help their
palette fill, and every module has a built-in accent role that follows the
active palette.
Key options under bar in settings.json:
{
"bar": {
"enabled": true,
"position": "top",
"palette": "x",
"thickness": 48,
"edgeGap": 8,
"pillBg": true,
"barBg": false,
"dragModules": true,
"zones": [
{ "id": "start", "align": "start",
"modules": [ { "id": "help", "enabled": true } ] }
]
}
}
The Bar Editor (Theme and Bar groups) exposes the same keys visually; see the
pages listed below. Colors always come from the active palette through
ui/bar/Colors.qml.
Widgets and panels
All popups dispatch through qs_manager.sh. Main shortcuts:
| Shortcut | Widget |
|---|---|
SUPER + D |
App launcher |
SUPER + C / V / B / N |
Clipboard / volume / battery / network |
SUPER + S / Z |
Calendar (timex) / display scale |
SUPER + M / SUPER + P |
Music / idle |
SUPER + W |
Wallpaper picker (davinci) |
SUPER + I / SUPER + U |
System monitor / updater |
SUPER + Y / SUPER + O |
Quick notes / RSS reader |
SUPER + ' |
File search |
SUPER + SHIFT + S / D |
Settings panel (bar editor) |
SUPER + SHIFT + M |
Plugins panel |
SUPER + SHIFT + W |
Desktop widget redactor |
SUPER + SHIFT + P |
Palette widget |
The settings panel is data-driven from core/EditorNav.js with groups Shell,
Bar, Theme, Behavior, Widgets, System and Plugins. Collapse state and page order
persist under settings.editor. The Plugins group lists installed plugins,
their master switches and one configuration page per plugin that ships
settings.page. The notification system has its own options
(settings.notifications), and shadows, glass and mascots are configured from
the Theme group.
Windows, shadows and glass
Shell.qml mounts ui/Main.qml (master window, widget stack, morph, IPC),
ui/bar/Bar.qml (the bar host), ui/Floating.qml (notifications and
OSD-like surfaces), ui/PluginHosts.qml (generic plugin hosts, including the
Nyx island; see Nyx mascot island), ui/widgets/Widgets.qml (one
widget loader per screen) and the screenshots plugin overlay; Lock.qml is the
alternate PAM session-lock entry.
Neither Hyprland nor niri decorates layer-shell surfaces, so popup shadows are
drawn in QML by Main.qml and follow the animated box (position, size, morph and
fade). Configure them under settings.json -> shadows (enabled, blur,
spread, offsetX, offsetY, opacity, radius; scaled by the UI scale)
from Theme -> Shadows; settings.json -> glass (enabled, opacity) makes
the shell backgrounds translucent so the compositor backdrop blur shows
through (on Hyprland via a layer rule; on niri only surfaces that request
ext-background-effect are blurred). The bar draws its own shadows from the
same config.
Desktop widgets
Press SUPER + SHIFT + W to open the redactor on the current monitor. The
real widget windows are hidden while editing, and every change is persisted
automatically about 300 ms after the last edit.
Five types with variants: Clock (digital, analog, minimal), Music, Weather (reads the timex cache), Visualizer (shared cava instance) and Image (from the wallpaper folder). Layouts are stored per monitor:
~/.local/state/quickshell/widgets/<monitor>/layout.json
Each layout entry stores the variant, position, size, rotation, opacity and, for Image widgets, the chosen file; the picker browses the wallpaper folder. Widgets render above the wallpaper and below windows, on every monitor, with grid and edge snapping, rotation, opacity and resize handles. Palette changes recolor them instantly.
IPC
~/.config/hypr/scripts/qs_manager.sh toggle volume
~/.config/hypr/scripts/qs_manager.sh close
~/.config/hypr/scripts/qs_manager.sh 3 # switch to workspace 3
~/.config/hypr/scripts/qs_manager.sh 3 move # move the window there
~/.config/hypr/scripts/qs_manager.sh prev
~/.config/hypr/scripts/qs_manager.sh next
qs ipc call main handleCommand "toggle calendar"
qs ipc call main forceReload
Widget names are the WindowRegistry.js keys (bar-editor, calendar,
volume, and so on).
Development
There is no CI; each repository ships a local check:
scripts/check.sh # qmllint over every .qml + node --check over JS modules
Reload while developing with qs ipc call main forceReload, or run a copied
config (quickshell -p /tmp/qstest/Shell.qml) to see QML errors in the
foreground. QML Process calls scripts directly, so copied scripts must stay
executable, and glyphs must exist in the Hack Nerd Font.
Related pages
- Theming and palettes for
Colors.qmland palettes. - Wallpapers for the picker and davinci.
- Architecture and repositories for the install layout.