# How Omarchy Integrates with Hyprland: Window Gaps, Monitor Focus, and Reload Guards

> Learn how Omarchy integrates with Hyprland using Lua modules for reload guards, dynamic window gaps, and monitor focus. Enhance your tiling window manager experience.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Omarchy extends Hyprland through Lua modules that implement reload guards to prevent stale state, dynamic window gap toggles, and monitor-aware event handlers that synchronize widgets across displays.**

Omarchy is an open-source desktop environment that deeply integrates with the Hyprland compositor through custom Lua scripting. When you configure **Omarchy to integrate with Hyprland**, it injects bootstrap logic, toggle commands, and event listeners directly into Hyprland's configuration lifecycle. This integration enables real-time gap adjustments, intelligent module reloading, and responsive monitor focus tracking without requiring session restarts.

## Reload Guard Mechanism

The **reload guard** ensures that Omarchy's Lua modules are freshly loaded when Hyprland reloads its configuration, while preserving third-party modules. This prevents stale state from persisting across `hyprctl reload` commands.

### Selective Module Clearing

In [`default/hypr/bootstrap.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bootstrap.lua), Omarchy defines a set of module prefixes that identify its own code. The `should_reload_module` function checks if a loaded module matches any of these prefixes before clearing it from `package.loaded`.

```lua
-- https://github.com/omacom/omarchy/blob/quattro/default/hypr/bootstrap.lua#L4-L18
local reload_prefixes = {
  "default.hypr",
  "hypr",
  "omarchy.current.theme",
}

local function should_reload_module(module)
  for _, prefix in ipairs(reload_prefixes) do
    if module == prefix or module:sub(1, #prefix + 1) == prefix .. "." then
      return true
    end
  end
  return false
end

```

When Hyprland reloads, the bootstrap iterates over `package.loaded`, removes matching modules by setting them to `nil`, and leaves external dependencies intact.

### Package Path Reconstruction

After clearing stale modules, the bootstrap reconstructs `package.path` to prioritize user-specific configuration directories over system defaults. This ensures that modifications in `~/.config/` or `~/.local/state/` take precedence immediately.

```lua
-- https://github.com/omacom/omarchy/blob/quattro/default/hypr/bootstrap.lua#L31-L39
package.path = home .. "/.local/state/?.lua;" ..
               home .. "/.config/?.lua;" ..
               (os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/?.lua;" ..
               package.path

```

## Window Gaps Toggle System

Omarchy exposes a **window gaps toggle** that switches between default spacing and zero-gap layouts without requiring a configuration reload.

### Command Registration and Keybindings

The toggle command `omarchy-hyprland-window-gaps-toggle` is registered in two locations. First, in `default/omarchy/omarchy-menu.jsonc` as a UI menu entry:

```json
// https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L98
"trigger.toggle.window-gaps": {"icon":"","label":"Window Gaps","action":"omarchy-hyprland-window-gaps-toggle"}

```

Second, in [`default/hypr/bindings/utilities.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bindings/utilities.lua) as a keyboard shortcut:

```lua
-- https://github.com/omacom/omarchy/blob/quattro/default/hypr/bindings/utilities.lua#L20
o.bind("SUPER + SHIFT + BACKSPACE", "Toggle window gaps", "omarchy-hyprland-window-gaps-toggle")

```

### Gap State Implementation

The actual toggle logic resides in [`default/hypr/toggles/window-no-gaps.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/toggles/window-no-gaps.lua). This script reads the current `gaps_in` and `gaps_out` values from Hyprland's live configuration, swaps them between default values (typically `gaps_in = 5`, `gaps_out = 10`) and zero gaps (`gaps_in = 0`, `gaps_out = 0`), and applies the changes immediately via Hyprland's dispatch system. No session restart is required for the changes to take effect.

## Monitor Focus Event Handling

To maintain UI consistency across multiple displays, Omarchy listens to Hyprland's `monitor.focused` events and recalculates widget geometries dynamically.

### Event Listener Registration

In [`default/hypr/qconsole.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/qconsole.lua), Omarchy registers a callback function named `fit` to handle monitor focus changes:

```lua
-- https://github.com/omacom/omarchy/blob/quattro/default/hypr/qconsole.lua#L27-L33
hl.on("monitor.focused", fit)

```

Hyprland emits this event whenever the active monitor changes, such as when using `CTRL + ALT + TAB` to cycle displays.

### Dynamic UI Synchronization

The `fit` function updates the geometry of screen-aware components including the **qconsole** overlay, dynamic notification widgets, and the "focus-app" launcher. By reacting to focus events in real-time, Omarchy ensures that all positioned UI elements align correctly with the current monitor's dimensions and offset.

## Practical Configuration Examples

### Custom Monitor Focus Handler

You can extend the monitor focus behavior by creating a custom handler in your user configuration:

```lua
-- ~/.config/hypr/custom-focus.lua
local hl = require("omarchy.helpers")

local function my_focus_handler(info)
  -- info contains monitor id, geometry, etc.
  print("Monitor focused:", info.name, info.geometry)
  hl.dispatch(hl.dsp.notify({title="Monitor", body=info.name}))
end

hl.on("monitor.focused", my_focus_handler)

```

### Manual Gap Toggle from Command Line

Execute the toggle directly without using the keybinding:

```bash
omarchy-hyprland-window-gaps-toggle

```

### Forcing a Clean Reload

When you need to reload Hyprland configuration while ensuring Omarchy clears its internal state:

```bash
hyprctl reload

```

The bootstrap script automatically detects the reload and clears Omarchy-specific modules from `package.loaded` before reinitializing.

## Summary

- **Reload Guard**: The [`default/hypr/bootstrap.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bootstrap.lua) script filters `package.loaded` using prefix matching (`default.hypr`, `hypr`, `omarchy.current.theme`) to clear only Omarchy modules during configuration reloads.
- **Window Gaps**: The `omarchy-hyprland-window-gaps-toggle` command, bound to `SUPER + SHIFT + BACKSPACE` in [`default/hypr/bindings/utilities.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bindings/utilities.lua), switches gap values between default and zero without restarting Hyprland.
- **Monitor Focus**: The `fit` function in [`default/hypr/qconsole.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/qconsole.lua) handles `monitor.focused` events to keep widgets synchronized with the active display geometry.
- **Module Path**: Omarchy reconstructs `package.path` to prioritize user directories (`~/.local/state`, `~/.config`) over system paths (`$OMARCHY_PATH`).

## Frequently Asked Questions

### How does Omarchy prevent stale Lua modules when Hyprland reloads?

Omarchy implements a reload guard in [`default/hypr/bootstrap.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bootstrap.lua) that iterates through `package.loaded` and removes modules matching specific prefixes (`default.hypr`, `hypr`, `omarchy.current.theme`). This selective clearing ensures that Omarchy's code refreshes on `hyprctl reload` while third-party Lua modules remain cached and unaffected.

### What is the default keybinding to toggle window gaps in Omarchy?

The default keybinding is `SUPER + SHIFT + BACKSPACE`, defined in [`default/hypr/bindings/utilities.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bindings/utilities.lua). This triggers the `omarchy-hyprland-window-gaps-toggle` command, which switches between configured gap values and zero gaps in [`default/hypr/toggles/window-no-gaps.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/toggles/window-no-gaps.lua) without requiring a configuration reload.

### How does Omarchy handle monitor switching in Hyprland?

Omarchy registers an event listener in [`default/hypr/qconsole.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/qconsole.lua) using `hl.on("monitor.focused", fit)`. When Hyprland emits a focus event (triggered by display switching), the `fit` function recalculates widget positions for the **qconsole** overlay, notification system, and focus-app launcher to match the new monitor's geometry.

### Where is the Hyprland bootstrap entry point located in Omarchy?

The bootstrap script is located at [`default/hypr/bootstrap.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/bootstrap.lua) within the Omarchy repository. This file is typically sourced from the user's `~/.config/hypr/hyprland.lua` (or the system-wide default) and handles module prefix filtering, package path reconstruction, and initial library loading for the Hyprland session.