Snappy Dock

This isn't all good yet so try at your own risk

Showcase (snappy mode)

there is also a boring static mode

Snappy Dock is a small dock for Hyprland.

It has two parts:

• snappydock-d: a C daemon that talks to Hyprland, tracks windows, loads config, and launches apps.
• shell/: a QuickShell/QML frontend that draws the dock, icons, dots, and menus.

The dock is meant to stay simple: quick to build, easy to configure, and easy to debug.

Features

• Shows running Hyprland windows as dock icons.
• Supports pinned apps.
• Left-click focuses a running app or launches a pinned app.
• Right-click opens a menu for focus, launch, pin, unpin, close, float, fullscreen, and move to workspace.
• Includes a launcher button. By default it runs fuzzel.
• Resolves app icons from desktop files and icon themes.
• Reads an INI config file from ~/.config/snappy-dock/config.ini.

Requirements

Runtime:

• Hyprland
• QuickShell 0.3 or newer
• json-c

Build tools:

• meson
• ninja
• A C compiler such as gcc or clang
• json-c development headers

Package names depend on your distro. Common names are:

• Arch: meson, ninja, json-c, gcc
• Debian/Ubuntu: meson, ninja-build, libjson-c-dev, build-essential
• Fedora: meson, ninja-build, json-c-devel, gcc

Build

From the repo root:

meson setup build
meson compile -C build

If build/ already exists, only run:

meson compile -C build

Install

Using Meson

System install, usually to /usr/local:

sudo meson install -C build

This installs:

• snappy-dock wrapper script
• snappydock-d daemon
• QML shell files
• config.ini.example

To uninstall a Meson install:

sudo ninja uninstall -C build

Manual Install (Makefile)

Alternatively, you can build and install using the provided native Makefile:

make
sudo make install

To gracefully uninstall and clean up your system afterwards:

sudo make uninstall

Run

Start the installed dock:

snappy-dock

Restart it after installing changes:

snappy-dock --restart

Useful wrapper commands:

snappy-dock --status
snappy-dock --kill
snappy-dock --config
snappy-dock --help

Run from the source tree without installing:

quickshell -p shell

Configuration

Create your user config:

mkdir -p ~/.config/snappy-dock
cp config/config.ini.example ~/.config/snappy-dock/config.ini

If you are outside the source tree after installing system-wide, copy the installed example instead:

mkdir -p ~/.config/snappy-dock
cp /usr/local/share/snappy-dock/config.ini.example ~/.config/snappy-dock/config.ini

Edit it:

$EDITOR ~/.config/snappy-dock/config.ini

Restart after changing config:

snappy-dock --restart

You do not need to rebuild or reinstall after changing ~/.config/snappy-dock/config.ini. A restart is enough.

You only need to reinstall after changing files in this repo, such as QML, C source, or snappy-dock.sh:

meson compile -C build
sudo meson install -C build
snappy-dock --restart

The daemon watches the config file and can send updates to the shell while running. A restart is still the clearest way to make sure every setting is applied.

See config/config.ini.example for all settings and plain-language notes.

Common config keys:

Key	What it controls
Position	Dock edge: bottom, top, left, or right
Alignment	Placement along the edge: center, start, or end
FullWidth	Whether to stretch the dock window across the whole screen width
Mode	Dock animation mode: static or snappy (macOS-style magnification)
[Icons] IconSize	Icon size in pixels
[Icons] Theme	Qt icon theme name, for example Tela-dracula
[Icons] Fallback	Icon used when a themed app icon is missing
Layer	Wayland layer: background, bottom, top, or overlay
ExclusiveZone	How many pixels are reserved for the dock, or auto to detect the dock height
AutoHide	Whether the dock hides after the pointer leaves
HotspotDelay	Delay (ms) before the dock hides after cursor leaves
LauncherCmd	Command run by the launcher button
LauncherPos	Launcher button position: start, end, or none
LauncherIcon	Icon or text for the launcher (default dots)
LauncherIconSize	Size of the launcher icon (0 for auto)
LauncherHoverBg	Show hover background for the launcher (true/false)
LauncherHoverBgSize	Size of the hover background (0 for auto)
WorkspaceCount	Workspaces shown in the right-click move menu
[Margins]	Extra edge spacing
[Font] Family	Font family used for text (e.g. Sans, FiraCode Nerd Font)
[Font] Weight	Font weight (e.g. Normal, Bold)

Important

Snappy Mode Constraints: When using Mode=snappy, ExclusiveZone=auto does not work reliably due to dynamic geometry changes. You must set ExclusiveZone manually to a fixed pixel value (e.g., 48). It is also highly recommended to use Layer=overlay in snappy mode to prevent the compositor from clipping magnified icons.

Pinned Apps

Pinned apps are stored here:

~/.config/snappy-dock/pinned

The file uses one app class name per line. You normally do not need to edit it by hand. Use the right-click menu on a dock icon and choose pin or unpin.

Example:

firefox
Alacritty
code

If an app does not launch from a pinned icon, check that the class name matches the app desktop file or the window class shown by Hyprland.

Controls

Input	Action
Left-click running app	Focus that app
Left-click pinned app with no running window	Launch it
Right-click icon	Open the app menu
Right-click menu: Pin/Unpin	Add or remove the app from pinned apps
Right-click menu: Move to workspace	Move a window to another workspace

File Layout

daemon/src/               C daemon source
shell/                    QuickShell/QML frontend
config/config.ini.example Example config file
snappy-dock.sh            Installed wrapper script
meson.build               Build and install rules

Troubleshooting

snappy-dock: ERROR: quickshell not found in PATH

Install QuickShell and make sure quickshell is available in your PATH.

snappy-dock: ERROR: snappydock-d not found in PATH

Build and install again:

meson compile -C build
sudo meson install -C build

QuickShell says Failed to load configuration

Run the shell directly to see the QML error:

quickshell -p shell

If you installed the dock, reinstall after changing QML files:

sudo meson install -C build
snappy-dock --restart

Icons are missing

Make sure the app has a .desktop file in one of the normal application directories, such as:

~/.local/share/applications
/usr/share/applications
/usr/local/share/applications

Also check that your icon theme contains the icon named by the desktop file. You can set a theme in ~/.config/snappy-dock/config.ini:

[Icons]
IconSize=48
Theme=Tela-dracula
Fallback=application-x-executable

Restart the dock after changing Theme; QuickShell reads the Qt icon theme when it starts.

The dock does not react to Hyprland

Make sure Snappy Dock is started inside a Hyprland session. The daemon needs Hyprland IPC environment variables such as HYPRLAND_INSTANCE_SIGNATURE.

Roadmap / Future TODOs

• FullWidth Taskbar Integration: Currently FullWidth stretches the dock, but the UI items remain centered. A future update will make FullWidth expand the entire bar into a traditional taskbar layout, automatically adjusting and fitting items along the full length.

License

MIT. See LICENSE.