Skip to content

Configuration

David edited this page Nov 9, 2026 · 2 revisions

Keybindings

setup() in your Hyprland Lua config takes these options:

dofile(path).setup({
  mod = "SUPER",
  key = "Tab",
  closeKey = "Q",
  appKey = "grave",
  overviewKey = "F3",
  timeout = 30000,
})
  • mod: the modifier you hold in the switcher, one of SUPER, ALT or CTRL
  • key: the key that opens the switcher and moves forward. Adding Shift moves back
  • closeKey: closes the selected window while the switcher is open, or false for no key
  • appKey: opens the switcher with only the windows of the focused app, or false for no key. It is a key name for your layout, such as masculine on a Spanish keyboard
  • overviewKey: opens and closes the overview, such as SUPER + F3, or false for no key
  • timeout: milliseconds after which an open switcher cancels itself

Options

hyprglance reads ~/.config/hyprglance/config.json and applies changes as soon as the file is saved. Every key is optional, and a key you remove goes back to its default. If the folder did not exist when hyprglance started, restart it once.

These are the defaults:

{
  "scope": "output",
  "appScope": "all",
  "order": "recent",
  "includeCurrent": true,
  "thumbnailWidth": 240,
  "minThumbnailWidth": 140,
  "showTitles": true,
  "fontFamily": "",
  "fontSize": 13,
  "radius": 16,
  "showDelay": 50,
  "theme": "~/.config/stylix/palette.json",
  "overview": {
    "scope": "workspace",
    "layout": "real",
    "monitors": "all",
    "workspaces": true,
    "showEmpty": "drag",
    "backdrop": 0.55,
    "undim": true,
    "drag": true,
    "dropPreview": true,
    "maxThumbnail": 640,
    "workspaceWidth": 160,
    "workspaceKeys": { "1": 1, "2": 2, "3": 3, "4": 4, "5": 5, "6": 6, "7": 7, "8": 8, "9": 9, "0": 10 },
    "margin": 48,
    "gap": 24,
    "animation": 200
  }
}

With Home Manager, set them through programs.hyprglance.settings, which writes this file:

programs.hyprglance.settings.overview.monitors = "focused";

Switcher

  • scope: which windows appear. output for the focused monitor, workspace for the focused workspace, or all
  • appScope: which windows appear with appKey. all for every workspace and monitor, or scope to follow scope
  • order: recent for most recently used first, or workspace to group them by workspace number
  • includeCurrent: whether the focused window appears
  • thumbnailWidth: preview width in pixels
  • minThumbnailWidth: when previews would get narrower than this, the strip wraps onto another row
  • showDelay: milliseconds Super has to stay held before the strip appears, so a quick tap switches without flashing it. 0 shows it at once

Overview

  • scope: workspace for the windows on each monitor's current workspace, or output for every window on that monitor
  • layout: real keeps the windows arranged as they are on screen, grid lays them out in a grid. real only applies with scope set to workspace, and falls back to a grid when windows overlap
  • monitors: all opens on every monitor, focused only on the current one
  • workspaces: shows or hides the workspace row
  • showEmpty: when empty workspaces appear in the row. drag while you drag a window, always, or never. If a monitor shows no empty workspace while you drag, a + card takes the window to a new one
  • backdrop: how opaque the veil over your desktop is, from 0 to 1
  • undim: turns off decoration:dim_inactive while the overview is open, so previews are not greyed out, and restores it afterwards
  • drag: lets you drag windows onto a workspace or another monitor
  • dropPreview: shows where the window will land while you drag. It is an estimate, and only works with the dwindle layout
  • maxThumbnail: maximum width of a preview in pixels
  • workspaceWidth: width of each workspace miniature in pixels
  • workspaceKeys: which workspace each number key goes to. Change it if Super + N does not go to workspace N in your config
  • margin, gap: outer margin and space between windows in pixels
  • animation: milliseconds windows take to travel between their place on screen and the overview. 0 turns it off

Appearance

  • showTitles: shows or hides window titles
  • fontFamily: empty uses the system sans-serif
  • fontSize: text size in pixels
  • radius: corner radius in pixels
  • theme: path to a base16 scheme in JSON, such as the palette.json that Stylix writes. Without one, hyprglance uses Catppuccin Mocha

Clone this wiki locally