Repository navigation
Tiling and Window Switcher
Two window-management features that the shell adds on top of Hyprland: a Tiling Assistant that snaps windows into zones like KDE's or Windows' snap layouts (by dragging with Super held, or from the keyboard), and an Alt + Tab window switcher with search, live previews and a "peek". Both are configured in Settings → Windows and Settings → Tiling; the first is off by default, the second on.
Hyprland tiles by itself (dwindle/master). The assistant is for the times you'd rather have floating windows placed exactly where a layout says: it floats the window, gives it the zone's precise geometry (with your gaps and border width taken into account) and remembers the size and position it had before so it can restore them when you drag it out again.
-
Settings → Tiling → Tiling assistant → Enable (
tiling.enable; off by default). - Hold Super and drag a window (left mouse, or middle mouse to move; right mouse to resize): coloured zones appear over the monitor under the cursor; drop it on one.
- Or use the keyboard: Super + Alt + ← / → / ↑ / ↓ moves the focused window to the next zone in that direction, and untiles it when it's already against that side of the screen. Super + Alt + Tab (and + Shift) cycles the focused monitor's layout, with a strip showing the layout names.
The assistant needs the shell's Hyprland binds (they report your Super+drag gestures to the shell). If Hyprland has no binding for it the page tells you, and re-running the installer with
--hypr(Installer and CLI) installs the config. Only Super + drag is detected: dragging by a window's own title bar fires no Hyprland bind, and guessing it from the window's motion was dropped because nothing reports the mouse button coming back up.
tiling.mode decides (Settings → Tiling → What happens on drop):
| Mode | Behaviour |
|---|---|
| Quick-tile (default) | Float the window and set the zone's exact geometry |
| Preview only | Draw the overlay but never touch the window; the keyboard quick-tile and neighbour resizing do nothing |
| Hybrid | Quick-tile windows that are already floating; preview-only for the ones Hyprland is tiling |
Dragging a tiled window back out restores its original size and float state (restoreOnUntile, on). Turning Tile by dragging off (dragQuickTile) leaves the keyboard as the only way in and lets a grabbed window go exactly where you put it; Show zones when a window drag starts (showOnDragStart) turns the overlay off for drags; Quick-tile with Super + Alt + arrows (keyboardQuickTile) turns the keyboard off.
A layout is a list of rectangles written as fractions (0–1) of the monitor's usable area — the screen minus the bar and gaps. Built-in presets (tiling.defaultPreset, default kde):
| Preset | Zones |
|---|---|
kde |
Left half, top-right quarter, bottom-right quarter |
halves |
Two columns |
thirds |
Three columns |
sidebars |
Narrow · wide centre · narrow (25/50/25 %) |
quarters |
2 × 2 grid |
sixths |
3 × 2 grid |
custom |
Zones you draw in the page's zone editor (TilingZoneEditor) |
Every monitor can have its own layout (tiling.monitors: { name, preset, gapsOverride, zones[] }), picked in the page's Monitor and Layout controls with a live preview. Zones may overlap (the page shows overlaps hatched — the cursor decides which one a window lands in). Changing the layout leaves windows where they are; the next quick-tile snaps one into the nearest zone of the new layout.
By default the zones use Hyprland's own gaps_out / gaps_in (tiling.gaps.followHyprland, on) so tiled windows sit where real ones would. Turn it off to use your own screen-edge and between-zones values (8 / 4 px), optionally overridden per monitor.
Resizing a tiled window past its zone pulls the divider it shares with its neighbours instead of overlapping them (tiling.coResize.enable, on; edgeTolerancePx 8 decides how near a shared edge counts). Two optional switches hand a whole workspace over: Tile the whole workspace when one window is tiled (adoptWorkspace, off — every other window is floated and given a zone) and the reverse, Untile the whole workspace when one window is untiled (releaseWorkspace, off). Dragged dividers last until the shell restarts and are dropped when the layout changes; only windows the assistant placed take part.
Zone and hovered-zone opacity (28 % / 55 %), corner radius, fade, labels on zones, how long the zones flash after a keyboard quick-tile (500 ms), how long the layout-name strip stays (1.4 s), and a stack indicator: zones holding more than one window keep a thin outline and a count while nothing is dragged (otherwise a second window just covers the first).
scripts/hyprland/drag_monitor.py watches Hyprland and reports the gesture; the assistant refreshes the monitor list at the start of each gesture so a bar that changed side or height doesn't leave zones laid out against stale space. The advanced options (tiling.detection.*) are the tolerance for deciding a window has left Hyprland's placement (2 px), the sampling rate between drags (5 Hz, just to keep a pre-drag geometry worth restoring) and the polling rate during one (90 Hz).
| Keys | Action |
|---|---|
| Alt + Tab / Alt + Shift + Tab | Open and move to the next / previous window (most recently used first); release Alt to switch |
| Alt + ` (the key above Tab) | Switch only between this app's windows |
| ← → ↑ ↓, Home / End, Tab | Move the selection (the panel's columns use Up/Down; the island's single row uses Left/Right) |
| 1 – 9 | Jump to that window while nothing is typed |
| Delete | Close the selected window |
| Type (with Alt held) | Search windows by title or app; letters filter the list |
| Enter / click | Switch; Esc cancels or clears the search |
- A quick tap is silent. Within 150 ms of Alt + Tab no UI is shown at all: releasing Alt switches to the previous window, so a rapid back-and-forth never flashes anything.
-
Search. With a search typed, releasing Alt keeps the switcher open so you can carry on with Alt up (the key hints say "Let go of Alt — keep typing"). Optionally Alt + letter from anywhere opens it already searching (
searchAnywhere, off) — letters your own Hyprland config binds with Alt are left alone. -
Peek. Hold a selection still for
peekDelayMs(600 ms;0never peeks) and the screen shows that window where it really is — a countdown fills in meanwhile — and a release while peeking switches with the compositor's animations off so the workspace doesn't slide in behind it. Peek at the whole workspace (peekWholeWorkspace, off) shows its other windows too and keeps the bar visible. -
Two faces. With the Dynamic Island on, the island becomes the switcher (a cover flow); otherwise a floating panel of thumbnails opens on the focused monitor. Both read the same state; the choice is frozen at open. Live thumbnails:
showThumbnails. One-line key reminder:showKeyHints. -
Which windows: Every workspace (
includeOtherWorkspaces, on — special workspaces too) or only what's on screen; This monitor only (currentMonitorOnly, off).
The switcher never takes keyboard focus (that would pull it away from the window you're switching from on every tap and could lose the Alt release). Instead the shell binds the keys at runtime and enters a Hyprland submap in the same compositor call as Alt + Tab; the Alt release is decided inside the compositor (nothing typed → switch; something typed → move to a typing submap), and Esc/Enter leave the submap there, so a shell that dies mid-switch can never strand your keyboard — and a shell that starts finds and undoes anything one before it left behind. Because the binds are put on at runtime, your own Alt + Tab bind wins: the page warns "Alt+Tab is already bound in your Hyprland config, so the switcher stays off" (same for Alt + `, which leaves just same-app switching off).
The Windows page also holds the window frame (gaps between windows and around the screen, border width — 0 is Borderless — and the active-border colour: primary, secondary, tertiary, primary container or surface), transparency & blur (shell panels Solid / Automatic / Custom; compositor blur Live / Wallpaper only / Off — "wallpaper only" blurs once and reuses it, keeping glass without the cost of re-blurring every animation; app windows Per app or all Opaque; blur size, threshold and advanced passes/noise/vibrancy), and window animations (Off, Scale from 20 % or Slide from the nearest or a chosen edge, with duration), which can be saved to ~/.config/hypr/custom/general.lua with a backup. The lower-level Hyprland options live in Hyprland Settings.
| Piece | Role |
|---|---|
services/TilingAssistant.qml |
Gesture state, zone resolution, drop, quick-tile, layout cycle, co-resize |
modules/common/functions/tiling.js |
Zone maths, presets, gap handling |
modules/ii/tilingAssistant/ |
TilingOverlay, ZoneIndicator, LayoutHint, TilingStackBadges
|
scripts/hyprland/drag_monitor.py |
The drag detector |
modules/settings/configs/TilingConfig.qml, TilingZoneEditor.qml
|
Settings and zone editor |
services/WindowSwitcher.qml, windowSwitcher/WindowSwitcherLogic.js
|
Switcher state, ordering, search, submap binds |
modules/common/panels/windowSwitcher/ |
Floating panel, peek, hints |
modules/ii/dynamicIsland/widgets/IslandWindowSwitcher.qml |
Island face |
modules/settings/configs/WindowsConfig.qml |
Windows page |
Global shortcuts named by the tiling binds: tilingDragMove, tilingDragResize, tilingTile<Direction>, tilingLayoutCycle / tilingLayoutCyclePrev.