Keybindings

The default binds, how to rebind them, the resize / planes submaps, and how mod "auto" picks Alt or Super.

Every bind is a line in the binds block: "<key pattern>" "<action>". Every bind below is rebindable; nothing here is hard-wired except Escape always exits a submap (it can't be rebound into a trap).

The mod key

mod "auto"

Mod is the modifier every bind references. auto (the default) resolves to Alt when running nested (the host compositor owns Super) and Super on a real session (the DRM backend) — so you don't need a different config for nested vs session. Override it explicitly with mod "alt" or mod "super"; an explicit value always wins. Throughout the docs, Mod means whatever this resolves to.

Key patterns combine modifiers with +: Mod, Shift, Ctrl, Alt, Super, then the key (Return, space, Tab, period, a letter, …). Binds follow the letter the key types, not the physical position — Mod+q on azerty is the key that types q.

Default binds

Rebinding

Drop the lines you want into your binds block. Same pattern as a default = override; new pattern = added. You don't re-list the rest.

binds {
    // override a default: make Mod+Return spawn your launcher instead
    "Mod+Return" "spawn:wofi --show drun"
    // add new ones (these have no default — the action exists, the bind doesn't)
    "Mod+Print" "spawn:grim -g \"$(slurp)\" ~/shot.png"
    "Mod+slash" "jump-to-window"
    "Mod+1" "plane-switch:1"
    "Mod+2" "plane-switch:2"
}

The action string is the same vocabulary atlasctl action accepts — anything bindable is invocable from a script too. Actions that take an argument use a colon: spawn:<cmd>, tag-toggle:<name>, plane-switch:<n>, width-set:<ratio>, mark-jump:<name>. See Configuration and the config reference for the full list.

Submaps

A submap is a modal bind table (Hyprland submaps / i3 modes). A bind with the "submap:<name>" action enters the mode; while it's active its table replaces the normal binds (typically bare keys — no chords), unbound keys are swallowed instead of reaching the focused app, and Escape always exits. The shortcut that entered a submap also exits it (toggle), on top of Escape.

Try the default pan submap: Mod+w, then pan around with bare h/j/k/l, Escape to leave.

No on-screen indicator ships in the compositor, but the atlas-submap waybar module (see Integration) shows the active submap so you never get stuck in one unaware.

The resize submap (Mod+r)

Resize verbs target innermost-first: they resize the closest thing around the focused window that flexes on that axis, falling outward when there isn't one.

While the resize submap is active, the region a resize will affect is outlined on screen (the resize-highlight colour), so the innermost-first target is never a surprise. Steps come from resize { step-px step-share }.

The planes submap (Mod+o)

Your own submaps

Declare a submap and an enter-bind for it. Add oneshot=#true to make it exit after its first action (handy for a "do one thing then get out of the way" mode); the default is sticky.

binds {
    "Mod+g" "submap:groups"
}

submaps {
    groups oneshot=#true {
        "n" "spawn-new-group"
        "l" "group-next"
        "h" "group-prev"
        "Escape" "submap-exit"
    }
}

A note on azerty defaults

The default plane-next / plane-prev binds use Mod+period / Mod+comma. On azerty/fr, , is unshifted (so Mod+comma works) but . needs Shift (so the bare Mod+period keysym never matches). Punctuation keysyms aren't layout-normalized the way letters are. If you're on azerty, rebind these to something that fits your layout — they're one-line changes.