Features

Everything below is available when the kwin-tiling module is enabled on a host. The checklist is the quick reference; the sections explain how each part works in practice.

At a glance

• Layouts — MasterStack, Stacked, Scrolling, Centered, and Grid; pick a default per monitor, cycle at runtime
• Gaps — adjustable space between tiles and around screen edges; per-monitor overrides with reset
• Window rules — float or ignore windows by app class or title; utilities, dialogs, and transients auto-float
• Keyboard — focus in four directions, toggle float, promote to master, toggle master pin, focus last window, move within layout, move across monitors, adjust master width/count
• Mouse — drag windows to swap or insert; drag dividers to resize master ratio and per-window heights inside a column
• Settings KCM — enable layouts, gaps, master ratio/count, borderless-when-tiled, and per-monitor overrides (layout, gaps, and sizing) in System Settings → Window Management → Tiling; changes apply live
• Autotile — new windows tile automatically; moving between desktops or monitors reflows and follows focus
• Persistence — master ratio, master count, and layout choices survive restarts via kwinrc
• Smart gaps — gaps collapse to zero when only one window is on screen
• Master pin — lock a window to the master slot per output/desktop until unpinned
• Focus last — toggle back to the previously active window (Meta+U)
• Borderless when tiled — optional setting to hide window decorations while tiled
• Resize axis gating — split updates only apply to the axis actually dragged
• Retile — Meta+Shift+R rebuilds the active screen’s layout when tiles and windows drift out of sync
• Packaging — vendored source + small hooks patch over stock KWin; ships as a Nix flake module/overlay

Layouts

Five layout engines place windows on each monitor and virtual desktop. You pick a default in the KCM, cycle at runtime, or override per monitor.

MasterStack

The classic tiling layout: one or more master windows on the left (or right, depending on configuration) and a stack of remaining windows on the other side. Good for a primary app plus several smaller ones alongside it.

• Set how many master windows you want (master count)
• Adjust the master column width with keyboard shortcuts or by dragging the divider
• Resize individual window heights inside either column by dragging horizontal splitters

Stacked

All windows share one full-width column, stacked vertically. Every window gets the same width; you control height per window. Simple and predictable when you mostly work in one column.

Scrolling

A horizontal strip of columns — similar to PaperWM or niri’s scrolling model. The viewport scrolls to show the active column. New windows open in new columns; you can resize column widths and move windows between columns. This is a minimal first implementation: consume/expel, center column, and column-width cycling have keyboard defaults — see Usage & Shortcuts and Roadmap for polish still planned.

Centered

The active (master) window sits in the centre. Remaining windows split into left and right stack columns. Useful when you want the focused window front and centre.

Grid

Windows fill a smoothly scaling grid (1, 2, 4, 6, 9, … cells as more windows open). Grid is opt-in — it is not in the default EnabledLayouts list because it is newer and less battle-tested than the other layouts. Enable it in the KCM or add Grid to EnabledLayouts in kwinrc.

Per-monitor overrides

Each output can use a different default layout, gap values, master width, master count, and scrolling column width. The KCM shows whether a monitor uses global defaults or has its own overrides, with a button to reset per-monitor customisations.

Gaps and spacing

Gaps control empty space around and between tiles:

• Between tiles — uniform gap between adjacent windows
• Screen edges — separate margins on left, right, top, and bottom
• Per-monitor — override gap values for individual outputs

When only one window is visible in a layout, gaps automatically collapse to zero (smart gaps) so you get full use of the screen.

Window rules

Not every window should tile. Rules decide what happens when a window opens:

• Float — keep a window (or an entire app class) floating above the tiled layer. Toggle per-window with Meta+W or set a permanent class rule from the window context menu.
• Ignore — exclude windows from tiling entirely (matched by app class or window title).
• Auto-float — utility windows, dialogs, and transient pop-ups float automatically so they don’t break your layout.

Rules are stored in kwinrc and evaluated when windows are added.

Keyboard control

All shortcuts are standard KWin actions — rebind them in System Settings → Shortcuts → KWin. Defaults:

Action	Default
Focus left / right / up / down	Meta+Arrow keys
Toggle floating	Meta+W
Promote to master	Meta+Shift+Space
Move window prev / next in layout	Meta+Shift+Left/Right
Move window to left / right monitor	Meta+Shift+Ctrl+Left/Right
Increase / decrease master width	Meta+Ctrl+L / Meta+Ctrl+H
Increase / decrease master count	Meta+Ctrl+. / Meta+Ctrl+,

Cycle layout, zoom, flip master, gaps, reset sizes, and scrolling column actions have defaults (Meta+Shift+… and Meta+Ctrl+0). Direct layout switches (MasterStack, Stacked, etc.) stay unbound — use cycle or bind them in Settings. See Usage & Shortcuts for the full table and mouse interactions.

Mouse control

• Drag a window onto another — swap their positions in the layout
• Drag onto empty space — insert the window there (master side vs stack side depends on where you drop)
• Drag the master/stack divider — change the master column width; the value is saved to kwinrc
• Drag horizontal borders inside a column — resize individual window heights; works in MasterStack, Stacked, and Scrolling

Dragging a window only a few pixels and releasing in the same spot won’t leave behind a ghost tile — the controller cancels the move and cleans up empty leaves.

Settings panel (KCM)

System Settings → Window Management → Tiling exposes:

• Global enable/disable
• Which layouts are available and which is the default
• Master width (ratio) and master count
• Gap values (between tiles and per-edge margins)
• Per-monitor overrides for layout and gaps

Changes take effect immediately — no logout required. The KCM writes to the [Tiling] group in ~/.config/kwinrc. Master ratio and count adjusted via keyboard or mouse are also persisted automatically.

Autotile and focus

When tiling is enabled:

• New windows are placed into the active layout for their monitor and desktop
• Moving a window to another desktop or monitor removes it from the old layout, retiles on the new one, and moves focus with it
• Floating windows stay above tiled ones when FloatAbove is enabled

Implementation highlights

• Master count — control how many windows sit in the master area (keyboard, KCM, and persistence)
• Per-window height weights — resize heights inside a column with both keyboard and mouse
• Live KCM — gap, master ratio, and master count changes apply without restarting the session
• Cross-monitor robustness — moving windows between outputs no longer leaves phantom tiles; empty leaves are pruned after structural changes
• Clean packaging — vendored source plus a small patch over stock KWin, shipped as a Nix flake module

How it fits together

At runtime a TilingController listens for windows opening, closing, moving between desktops or monitors, and interactive drag/resize events. For each monitor and virtual desktop it picks a layout engine (MasterStack, Stacked, etc.) that calculates where each window should sit.

The engines set relative positions on KWin’s tile tree; KWin’s own tile machinery handles the actual window geometry, gap application, and rendering. This is why patching upstream KWin works — we add layout logic on top of infrastructure that already exists.

For what’s still planned, see Roadmap.