Skip to content
ArchEclipse

Common pages

↑↓to navigate↵to openescto close
Configuration
On this page

Configuration

Configuration

How the Hyprland Lua modules, custom overrides, Quickshell settings and startup scripts fit together.

ArchEclipse has two configuration layers:

  1. Hyprland — Lua modules in ~/.config/hypr, loaded by hyprland.lua.
  2. Quickshell — runtime settings in ~/.cache/quickshell/settings/settings.json, edited through the in-shell Settings tab.

Some things live in both. A Hyprland slider in Settings writes a machine-local Lua module and pushes it to Hyprland; the shell's own appearance is stored in the JSON settings file.

Configuration paths#

PathContents
~/.config/hypr/hyprland.luaEntry point: XDG environment, module loading, custom modules
~/.config/hypr/config/*.luaTracked base configuration, one file per section
~/.config/hypr/config/custom/*.luaMachine-local overrides, loaded last
~/.config/hypr/config/defaults/*.luaTemplates copied into custom/ by the installer
~/.config/hypr/config/scripts/Hyprland-side Lua helpers (bar restart, brightness, drag, RC)
~/.config/hypr/scripts/Bash capture scripts (screenshot.sh, screenrecord.sh)
~/.config/hypr/maintenance/Python installer, updater and their components
~/.config/quickshell/archeclipse/Shell source: shell.qml, services, widgets, theme
~/.cache/quickshell/settings/settings.jsonPersisted shell settings
~/.cache/coloreclipse/colors.scssPalette generated from the wallpaper
~/.config/wallpapers/Wallpaper categories, custom images and Wallhaven downloads

Load order#

hyprland.lua first sets the session environment, then requires the base modules in this order:

lua
animations, scripts, bind, decoration, device, env, exec,
general, gesture, input, layerrule, layouts, misc,
monitor, windowrule, workspace

After that, every *.lua file in ~/.config/hypr/config/custom/ is loaded in sorted order. Because custom modules run last, they can override a value set by a base module. They cannot undo the effect of a function that already ran unless Hyprland exposes a matching API.

The base list lives in hyprland.lua. Adding a new base section means creating config/<name>.lua and adding it to that list. Host-specific changes belong in custom/.

What the base config sets#

These are the tracked defaults. The Settings panel can change several of them at runtime, and custom modules take precedence.

AreaDefault
Layoutdwindle, force_split = 2, preserve_split = true
Gapsgaps_in = 4, gaps_out = 12
Bordersborder_size = 0 (active/inactive border colors are inert at 0)
Roundingrounding = 12
Opacityactive_opacity = 0.85, inactive_opacity = 0.85
Blurenabled, size = 4, passes = 4, popups enabled
Shadowsdisabled (shadow.enabled = false)
Monitorone fallback rule: output = "", mode = "highres", position = "auto", scale = 1
Keyboardkb_rules = "evdev", kb_model = "pc105", kb_options = "grp:alt_shift_toggle"
Touchpadnatural scroll, tap-to-click, scroll_factor = 0.1, no disable-while-typing
Gestures3-finger horizontal = workspaces, 3-finger up = special, 4-finger up = fullscreen, 4-finger left/right = float
Misclogo and splash disabled, DPMS wake on input, swallow disabled
Animationsenabled, shared ease curve, phi * 2 interval

Making changes#

Prefer config/custom/#

Create a new Lua file in ~/.config/hypr/config/custom/, for example:

lua
-- ~/.config/hypr/config/custom/decoration_gaps.lua
hl.config({
    general = {
        gaps_in = 6,
        gaps_out = 16,
    },
})

Custom modules are outside the tracked base configuration, so they survive the installer's copy-if-missing step. The updater still resets the whole checkout, but custom/ is gitignored and left alone.

Do not rely on load order#

Custom files load alphabetically, not in dependency order. Keep each file self-contained: repeat the table path you are changing instead of assuming another module set it first.

Apply and validate#

bash
hyprctl reload
hyprctl configerrors

You can syntax-check the Lua before reloading:

bash
luac -p ~/.config/hypr/hyprland.lua ~/.config/hypr/config/*.lua

config/defaults/ contains {{ PLACEHOLDER }} templates for the installer and is not valid Lua; do not lint that directory as-is.

Settings that are not in Hyprland#

The Quickshell layer reads its own settings file and does not read the Hyprland Lua modules. Examples:

  • bar orientation, opacity, radius, padding and font size;
  • panel widths and hot-zone sizes;
  • shell animation speed and island motion style;
  • screenshot and recording options;
  • notification DND and lock grace period.

Those are documented in Settings.

Startup applications#

~/.config/hypr/config/exec.lua registers a single hl.on("hyprland.start", ...) handler for the wallpaper daemon, bar, polkit agent, theme applier and tray applets. The installer adds config/custom/browser.lua and config/custom/discord_client.lua, which start the selected browser and chat client and place their windows.

Quickshell configuration#

The shell is not compiled and has no build step. It is pure QML plus helper scripts. Its runtime state lives in services/QML singletons and is exposed through qs IPC:

bash
qs -p ~/.config/quickshell/archeclipse ipc call bar toggleBar HDMI-A-1

Shell modules are declared in qmldir files. Adding a new QML file requires registering it there; adding a documentation page does not. See Widgets and Bar.