equisdots · hyprland

Hyprland compositor configuration for the equisdots desktop: modular Lua config, palette-driven theming and system scripts.

Content

Previews · Quick Install · Features · Customization · Quick Reference · Structure · Documentation · Related Repos

---

Previews

previews

Captures served from the website previews page (hotlinked; no images are stored in this repository).

The desktop

_{The full desktop -- equisdots doctor, the timex TUI and btop over an interactive scene.}

_{Tiling and panels -- Hyprland tiling with btop, the widgets panel and the settings editor at once.}

_{Scenes and monitors -- a scene wallpaper reacting to the palette, with the system monitor and terminal UI on top.}

Shell and settings

_{Bar islands -- workspaces, clock and status islands: palette-tinted, blur-aware and position-independent.}

_{Bar -- master switch, position, zones and modules, configured live in the settings panel.}

_{Bar position -- move the bar to any edge; the preview reflects position and zones.}

_{Timex -- weather provider, city, forecast layout and calendar popup options.}

_{Monitors -- resolution, refresh rate, VRR, bit depth, HDR and mirroring per output.}

_{Glass and blur -- translucency for popups, menus and the bar; blur comes from a Hyprland layer rule.}

_{Widgets panel -- the floating hub: palettes, settings and desktop widgets one tap away.}

_{App launcher -- fuzzy search over installed applications with instant launch.}

gifs previews

Clips served from the website previews page (hotlinked; no files are stored in this repository).

Desktop tour · v1

Desktop tour · v2

---

Quick Install

The official installer of the whole stack is equisdots/dots (./dots install).

Standalone (this repo only):

git clone https://github.com/equisdots/hyprland.git
cd hyprland
chmod +x install.sh
./install.sh

Options: --dotfiles-only (config only), --nvidia-only (NVIDIA setup only).

The installer detects your distro and GPU, installs packages (Hyprland, kitty, rofi, and more), backs up existing configs, deploys the dotfiles, optionally configures NVIDIA Optimus and installs the SDDM theme, and installs kitty / Neovim from their own repos (`xscriptor-colors/terminal`, `xscriptor-colors/nvim`). Kitty, starship and Neovim then follow the palette through equisdots/theme-sync. The Quickshell shell, the palettes and the engines come from the org repos through equisdots/dots: the installer runs dots install for you (fetching it on demand), so a single ./install.sh leaves a complete desktop.

---

Features

• Lua Config -- Hyprland 0.55+ hyprland.lua modular config (env, colors, keybinds, animations, rules, autostart) driven by the active palette.
• 12-Palette Theming -- dock/palettes drive the bar (equisdots/shell), window borders, kitty, starship, VS Code (color + icons) and Neovim in real time via theme-sync (equisdots/theme-sync).
• System Scripts -- Session helpers: scale menu, monitor manager, GPU modes, idle modes, lock, reload and the monthly updater.
• NVIDIA Optimus -- GPU mode switching (integrated/hybrid/nvidia) via keybind or Rofi.
• Multi-Monitor -- Auto-detection at max refresh rate (Lua wildcard), Rofi-based position/resolution/refresh rate manager.
• Static SDDM Login -- minimal black/white greeter from equisdots/login (no palette sync, no runtime sudo); window borders and the lock follow the palette instead.
• Screen Recording -- GPU capture with separate desktop/mic audio channels.

The Quickshell UI (bar, popups, panels, editor, lock) lives in equisdots/shell.

---

Customization

SUPER + W wallpaper picker · SUPER + SHIFT + S / SUPER + SHIFT + D settings panel and bar editor (equisdots/shell)

See Hyprland Config for file structure and Quick Reference for all keybinds.

---

Quick Reference

SUPER + Return Terminal · SUPER + D Apps · SUPER + W Wallpaper · SUPER + S Calendar · SUPER + Space Float · SUPER + L Lock · Print Screenshot · SUPER + Escape Exit

See full keybinding table.

---

Structure

hyprland/
  install.sh                  Automated installer (installs kitty/nvim from their repos)
  uninstall.sh                Config removal
  config/hypr/                Hyprland Lua configs (hyprland.lua + modules,
                              hypridle.conf)
  config/rofi/                Launcher themes
  config/dunst/               Notification daemon
  config/cava/                Audio visualizer
  config/pam.d/               PAM service for the quickshell lock screen
  scripts/                    Shell scripts and daemons (reload.sh, lock.sh)

---

Documentation

• Installation -- Full install, uninstall, and post-install guide
• Quick Reference -- All keybindings and scripts at a glance
• Scripts -- All shell scripts and daemons
• Hyprland Configuration -- Modular config structure and dynamic reload
• Screenshots & Recording -- Capture system with virtual audio
• Neovim Configuration -- Editor setup from `xscriptor-colors/nvim` (palettes from the shell panel)
• Multi-Monitor Setup -- Display configuration guide
• GPU Mode Switching -- NVIDIA Optimus control

License · Code of Conduct · Roadmap · Changelog · Security

Local checks

No CI: run the checks locally before pushing.

scripts/check.sh

• luac -p over every config/**/*.lua module.
• bash -n over every shell script (shellcheck, advisory, when installed).

Related Repos

• Shell - Quickshell UI (bar, popups, panels, editor, lock)
• Palettes - base16 palette data + schema
• theme-sync - cross-app theming engine
• davincix - wallpaper engine kernel
• dots - meta installer and updater
• timex - time, weather and calendar engine
• login - static SDDM greeter
• Terminal - Kitty + Starship synchronized dotfiles
• Nvim - synchronized dotfiles
• VSCode - synchronized dotfiles
• XFetch - terminal tool shown in the previews