marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/layouts.md
View on GitHub<!-- source: https://wiki.hypr.land/configuring/layouts -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
# Hyprland Layouts Reference
---
weight: 10
title: Dwindle layout
---
Dwindle is a BSPWM-like layout, where every window on a workspace is a member of a binary tree.
<video width="1024" height="566" autoplay muted loop>
<source src="https://dl.hypr.land/wiki/demo_dwindle.mp4" type="video/mp4">
</video>
## Quirks
Dwindle splits are NOT PERMANENT.
The split is determined dynamically with the W/H ratio of the parent node.
If W > H, it's side-by-side.
If H > W, it's top-and-bottom.
You can make them permanent by enabling `preserve_split`.
## Config
Category: `dwindle`
| Name | Description | Type | Default | Limits |
| --- | --- | --- | --- | --- |
| force_split | 0 - split follows mouse, 1 - always split to the left (new = left or top), 2 - always split to the right (new = right or bottom) | int | `0` | [0 - 2] |
| preserve_split | If enabled, the split (side/top) will not change regardless of what happens to the container | bool | `false` | |
| smart_split | If enabled, allows a more precise control over the window split direction based on the cursor's position. The window is conceptually divided into four triangles, and cursor's triangle determines the split direction. This feature also turns on `preserve_split` | bool | `false` | |
| smart_resizing | If enabled, resizing direction will be determined by the mouse's position on the window (nearest to which corner). Otherwise, it is based on the window's tiling position | bool | `true` | |
| permanent_direction_override | If enabled, makes the preselect direction persist until either this mode is turned off, another direction is specified, or a non-direction is specified (anything other than `l`, `r`, `u`/`t`, `d`/`b`) | bool | `false` | |
| split_width_multiplier | Specifies the auto-split width multiplier. Multiplying window size is useful on widescreen monitors where window W > H even after several splits | float | `1.0` | [0.1 - 3.0] |
| use_active_for_splits | Whether to prefer the active window or the mouse position for splits | bool | `true` | |
| default_split_ratio | The default split ratio on window open. 1 means an even 50/50 split | float | `1.0` | [0.1 - 1.9] |
| split_bias | Specifies which window will receive the split ratio. 0 - directional (the top or left window), 1 - the current window | int | `0` | [0 - 1] |
| precise_mouse_move | Dragging and dropping windows will place them more precisely, based on where your mouse is | bool | `false` | |
## Dispatchers
| Dispatcher | Description | Params |
| --- | --- | --- |
| window.pseudo | Toggles the given window's pseudo mode | Left empty/`"active"` for current, or `"window"` for a specific window | |
## Layout messages
<!-- TODO: we should make a petition to rework all layoutmsgs for Lua, current syntax is just AWFUL -->
Dispatcher `hl.dsp.layout()` arguments:
| Param | Description | Args |
| --- | --- | --- |
| movetoroot | Moves the window to the root of the workspace tree. See the note [below](#movetoroot) | window?, "unstable"? |
| preselect | A one-time override for the split direction, valid for the next window to be opened, only works on tiled windows | direction |
| rotatesplit | Rotates the split of the current window by an optionally specified angle. Angle must be a multiple of 90. Positive is clockwise, negative is counter-clockwise | int? = 90 |
| splitratio | Changes the split ratio. See the note [below](#splitratio) | float |
| swapsplit | Swaps the two halves of the split of the current window | None |
| togglesplit | Toggles the split (top/side) of the current window. `preserve_split` must be enabled for toggling to work | None |
### movetoroot
Make the specified window a child of its most immediate root node on the workspace.
If the window is already a direct child of the root node, a warning is produced instead.
The default behavior is "stable" in that the focused window remains on the same side of screen.
Adding `unstable` as the second argument will instead swap the positions of the root node's immediate children (i.e. which side of the screen they're on).
Note that `movetoroot unstable` is *not* valid, but `movetoroot active unstable` is the proper way to achieve this.
### splitratio
`splitratio` uses delta value by default, add `exact` after a value to set it instead.
A positive delta is used by default.
To specify direction, prefix the value with plus (`+`) or minus (`-`) sign.
Values outside of the [0.1 - 1.9] range will be clamped to the nearest limit.
{{% details title="Examples" closed="true" %}}
```lua
-- Use movetoroot on window with "imcool" class
hl.bind("SUPER + A", hl.dsp.layout("movetoroot class:imcool"))
hl.bind("SUPER + A", hl.dsp.layout("togglesplit"))
-- Set split ratio to 1.2
hl.bind("SUPER + A", hl.dsp.layout("splitratio 1.2 exact"))
-- Make split ratio 0.8 after previous dispatch
hl.bind("SUPER + A", hl.dsp.layout("splitratio -0.4"))
```
{{% /details %}}
---
---
weight: 30
title: Master layout
---
The master layout makes one (or more) window(s) be the "master", taking (by default) the left part of the screen, and tiles the rest on the right.
You can change the orientation on a per-workspace basis if you want to use anything other than the default left/right split.
<video width="1024" height="566" autoplay muted loop>
<source src="https://dl.hypr.land/wiki/demo_master.mp4" type="video/mp4">
</video>
## Config
Category: `master`
| Name | Description | Type | Default | Limits |
| --- | --- | --- | --- | --- |
| allow_small_split | Enable adding additional master windows in a horizontal split style | bool | `false` | |
| mfact | The size as a percentage of the master window, for example `mfact = 0.70` would mean 70% of the screen will be the master window, and 30% the slave | float | `0.55` | [0 - 1] |
| new_status | `"master"` - new window becomes master, `"slave"` - new windows are added to slave stack, `"inherit"` - inherit from focused window | string | `"slave"` | |
| new_on_top | Whether a newly open window should be on the top of the stack | bool | `false` | |
| new_on_active | `"before"`, `"after"` - place new window relative to the focused window, `"none"` - place new window according to the value of `new_on_top` | string | `"none"` | |
| orientation | Default placement of the master area | string | `"left"` | `"left"`, `"right"`, `"top"`, `"bottom"`, `"center"` |
| slave_count_for_center_master | When using orientation=center, make the master window centered only when at least this many slave windows are open. (Set 0 to always center master) | int | `2` | [0 - 10] |
| center_master_fallback | Set fallback for center master when slaves are less than `slave_count_for_center_master` | string | `"left"` | `"left"`, `"right"`, `"top"`, `"bottom"` |
| smart_resizing | If enabled, resizing direction will be determined by the mouse's position on the window (nearest to which corner). Otherwise, it is based on the window's tiling position | bool | `true` | |
| drop_at_cursor | When enabled, dragging and dropping windows will put them at the cursor position. Otherwise, when dropped at the stack side, they will go to the top/bottom of the stack depending on new_on_top | bool | `true` | |
| always_keep_position | Whether to keep the master window in its configured position when there are no slave windows | bool | `false` | |
| focus_master_on_close | When enabled, closing a window focuses the master window | bool | `false` | |
## Layout messages
Dispatcher `hl.dsp.layout()` arguments:
| command | description | params |
| --- | --- | --- |
| addmaster | Adds a master to the master side. That will be the active window, if it's not a master, or the first non-master window | none |
| cyclenext | Focuses the next window respecting the layout | either `loop` (allow looping from the bottom of the pile back to master) or `noloop` (force stop at the bottom of the pile, like in DWM). `loop` is the default if left blank. |
| cycleprev | Focuses the previous window respecting the layout | either `loop` (allow looping from master to the bottom of the pile) or `noloop` (force stop at master, like in DWM). `loop` is the default if left blank. |
| focusmaster | Focuses the master window | either `master` (focus stays on master), `auto` (default; focus first non-master window if already on master) or `previous` (remember current window when focusing master, if already on master, focus previous or fallback to `auto`). |
| mfact | Change mfact, the master split ratio | the new split ratio, a relative float delta (e.g., `-0.2`, `+0.2`) or `exact` followed by a value between 0.0 and 1.0 |
| orientationbottom | Sets the orientation for the current workspace to bottom (master area bottom, slave windows to the top, horizontally stacked) | none |
| orientationcenter | Sets the orientation for the current workspace to center (master area center, slave windows alternate to the left and right, vertically stacked) | none |
| orientationcycle | Cycle to the next orientation from the provided list, for the current workspace | allowed values: `left`, `top`, `right`, `bottom`, or `center`. The values have to be separated by a space. If left empty, it will work like `orientationnext` |
| orientationleft | Sets the orientation for the current workspace to left (master area left, slave windows to the right, vertically stacked) | none |
| orientationnext | Cycle to the next orientation for the current workspace (clockwise) | none |
| orientationprev | Cycle to the previous orientation for the current workspace (counter-clockwise) | none |
| orientationright | Sets the orientation for the current workspace to right (master area right, slave windows to the left, vertically stacked) | none |
| orientationtop | Sets the orientation for the current workspace to top (master area top, slave windows to the bottom, horizontally stacked) | none |
| removemaster | Removes a master from the master side. That will be the active window, if it's a master, or the last master window | none |
| rollnext | Rotate the next window in stack to be the master, while keeping the focus on master | none |
| rollprev | Rotate the previous window in stack to be the master, while keeping the focus on master | none |
| swapnext | Swaps the focused window with the next window respecting the layout | either `loop` (allow swapping the bottom of the pile and master) or `noloop` (do not allow it, like in DWM). `loop` is the default if left blank. |
| swapprev | Swaps the focused window with the previous window respecting the layout | either `loop` (allow swapping master and the bottom of the pile) or `noloop` (do not allow it, like in DWM). `loop` is the default if left blank. |
| swapwithmaster | Swaps the current window with master. If the current window is the master, swaps it with the first child | either `master` (new focus is the new master window), `child` (new focus is the new child) or `auto` (which is the default, keeps the focus of the previously focused window). Adding `ignoremaster` will ignore this dispatcher if master is already focused. |
Parameters for the commands are separated by a single space.
> [!NOTE]
> Example usage:
>
> ```lua
> hl.bind(KEYS, hl.dsp.layout("cyclenext"))
> -- behaves like xmonads promote feature (https://hackage.haskell.org/package/xmonad-contrib-0.17.1/docs/XMonad-Actions-Promote.html)
> hl.bind(KEYS, hl.dsp.layout("swapwithmaster master"))
> ```
## Workspace Rules
`layout_opts` rules:
| rule | description | type |
| --- | --- | --- |
| orientation = [o] | Sets the orientation of a workspace. For available orientations, see [orientation](#config) | string |
Example usage:
```lua
hl.workspace_rule({ workspace = "2", layout_opts = { orientation = "top" } })
```
---
---
weight: 20
title: Scrolling layout
---
Scrolling is a layout where windows are positioned on an infinitely growing tape.
<video width="1024" height="566" autoplay muted loop>
<source src="https://dl.hypr.land/wiki/demo_scrolling.mp4" type="video/mp4">
</video>
## Config
Category: `scrolling`
| Name | Description | Type | Default | Limits |
| --- | --- | --- | --- | --- |
| fullscreen_on_one_column | When enabled, a single column on a workspace will always span the entire screen | bool | `true` | |
| column_width | The default width of a column | float | `0.5` | [0.1 - 1.0] |
| focus_fit_method | When a column is focused, what method should be used to bring it into view. 0 - center, 1 - fit, 2 - clamped_center | int | `1` | [0 - 2] |
| follow_focus | Behaviour of the scrolling tape when a window is in focus. 0: Focus doesn't cause tape move. 1: Focus may cause tape move, mouse click always moves the tape. 2: Focus may cause tape move. | int | `1` | [0 - 2] |
| follow_min_visible | When a window is focused, require that at least a given fraction of it is visible for focus to follow. Hard input (e.g., binds, clicks) will always follow | float | `0.4` | [0.0 - 1.0] |
| explicit_column_widths | A comma-separated list of preconfigured widths for `colresize +conf/-conf` | string | `"0.333, 0.5, 0.667, 1.0"` | |
| wrap_focus | When enabled, causes `hl.dsp.layout("focus l/r")` to wrap around at the beginning and end | bool | `true` | |
| wrap_swapcol | When enabled, causes `hl.dsp.layout("swapcol l/r")` to wrap around at the beginning and end | bool | `true` | |
| direction | Direction in which new windows appear and the layout scrolls. `"left"`/`"right"`/`"down"`/`"up"` | string | `"right"` | |
## Workspace rules
| name | description | type |
| --- | --- | --- |
| direction | Same as the `scrolling.direction` config option, but per workspace | string |
For example:
```lua
hl.workspace_rule({ workspace = "2", layout_opts = { direction = "right" } })
```
## Layout messages
Dispatcher `hl.dsp.layout()` arguments:
| Name | Description | Params |
| --- | --- | --- |
| center | Centers the currently focused column | none |
| colresize | Resize the current column, to either a value or by a relative value (e.g., `0.5`, `+0.2`, `-0.2`), or cycle the preconfigured ones with `+conf` or `-conf`. Can also be `all (number)` for resizing all columns to a specific width | relative float/relative `conf` |
| consume | Moves the current window into the previous column | none |
| consume_or_expel | Expel if not alone, consume if alone in a column | `prev` or `next` |
| expel | Moves the current window to its own new column (in the backward direction if window is in the top half of the screen, otherwise in the forward direction) | none |
| fit | Executes a fit operation based on the argument. Available: `active`, `visible`, `all`, `toend`, `tobeg`, `expand`. `expand` will expand the current window to take up the remaining free space on the monitor | fit mode |
| fit_into_view | Fits the currently active column fully into view | none |
| focus | Moves the focus and centers the layout, while also wrapping instead of moving to neighboring monitors | direction |
| inhibit_scroll | Prevents the scrolling view from moving for the currently active workspace. The switch is independent for each workspace | left empty for toggle, or `bool` for explicitly enabling/disabling
| move | Move the layout horizontally, by either a relative logical px (`-200`, `+200`) or columns (`+col`, `-col`) | move data |
| promote | Moves a window to its own new column (in the forward direction) | none |
| swapcol | Swaps the current column with its neighbor to the left (`l`) or right (`r`). The swap wraps around (e.g., swapping the first column left moves it to the end) | `l` or `r` |
Example key bindings for your Hyprland config:
```lua
hl.bind(mainMod .. " + period", hl.dsp.layout("move +col"))
hl.bind(mainMod .. " + comma", hl.dsp.layout("swapcol l"))
```
## Convenience functions
- `hl.get_scrolling_offset()`
- `hl.set_scrolling_offset(double)`
Use the LSP (or examine the stubs yourself) for the return values. See [here](../../core#editor-autocompletion) to set up the LSP in your code editor.
## Window rules
With the static rule scrolling_width you can set a starting column width for a window.
```lua
hl.window_rule({ name = "kitty_starting_width", match = { class = "kitty" }, scrolling_width = 0.5})
```
## Layout-Handled Fullscreen
Scrolling has an optional layout-handled fullscreen behavior, which uses its own fullscreen handler.
This custom fullscreen behavior allows you to scroll away from your fullscreen windows without them being un-fullscreened.
You can use it by using `layout_aware = true` (or not specifying `layout_aware` option at all) in your fullscreen dispatches when on a scrolling layout workspace.
It also works with existing window/workspace fullscreen-related selectors.
> [!NOTE]
> When a fullscreen window has focus, the `hl.dsp.focus({ direction })` dispatcher will by default look for other monitors in the specified direction, rather than changing windows on the current monitor.
> If you want to take advantage of the layout-handled ability to scroll away from a fullscreen window, either set `binds.movefocus_cycles_fullscreen = true` to restore the focus dispatcher's window-seeking behavior, or use the scrolling layout's `focus` layout message instead.
Learn more about Fullscreen Handlers [here](../../core/dispatchers#fullscreen-handlers).
---
---
weight: 40
title: Monocle layout
---
Monocle is a layout where windows are always taking up the entire unreserved area of the workspace.
<video width="1024" height="566" autoplay muted loop>
<source src="https://dl.hypr.land/wiki/demo_monocle.mp4" type="video/mp4">
</video>
## Quirks
Due to how layouts work, `hl.dsp.window.cycle_next()` will not work with Monocle.
For cycling monocle windows, either use `hl.dsp.layout("cyclenext")` or `hl.dsp.window.cycle_next({ tiled = true })`.
## Layout messages
Dispatcher `hl.dsp.layout()` arguments:
| name | description | params |
| --- | --- | --- |
| cyclenext | Cycle to the next window | none |
| cycleprev | Cycle to the previous window | none |
---
---
weight: 50
title: Custom layouts
---
You can create custom layouts in the Lua config directly.
For this, define your layout with `hl.layout.register(name, { recalculate, layout_msg? })` then use it as `lua:name`.
A simple example layout:
```lua
hl.layout.register("columns", {
recalculate = function(ctx)
local n = #ctx.targets
if n == 0 then
return
end
for i, target in ipairs(ctx.targets) do
target:place(ctx:column(i, n))
end
end,
})
```
This can then be used as `lua:columns`.
There are some example layouts in the Hyprland repo [here](https://github.com/hyprwm/Hyprland/tree/main/example/layouts).
`ctx` has some convenience functions for you, like `grid_cell`, `column`, `row` and `split`.
It also provides `area` and `targets`, for the work area and target list respectively.
You can get the window from a target by accessing its `.window` field, but please do note that it doesn't always have to be there, and that some layout targets might have multiple, and only expose the "main" one (e.g. group).
> [!NOTE]
> Please prefer `:place()` over `:set_box()` unless necessary.
> `:place()` will calculate the gaps, pseudotiling, reserved space, and more, for you.
> `:set_box()` is only to be used if full manual positioning is absolutely necessary.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |