Hyprland Layout Algorithms: Dwindle vs Master Tiling Implementation

Hyprland implements two primary tiling layout algorithms—Dwindle (binary-tree recursive splitting) and Master (primary-stack arrangement)—through the ITiledAlgorithm interface in src/layout/algorithm/, enabling dynamic per-workspace configuration via hyprctl or hyprland.conf.

The hyprwm/Hyprland compositor provides a modular window management system where layout algorithms dictate how windows tile on screen. These algorithms inherit from a common interface defined in src/layout/algorithm/Algorithm.hpp, allowing instant switching between binary-tree layouts and master-stack arrangements without restarting the compositor.

How Hyprland Layout Algorithms Work

Hyprland’s layout system centers around the ITiledAlgorithm interface defined in src/layout/algorithm/Algorithm.hpp. All tiling algorithms must implement this interface to participate in window management.

Core interface methods include:

• applyLayout(CSpace* pSpace) – Computes positioning geometry for each window in the workspace.
• handleWindowAdd – Updates internal data structures when a new window joins the workspace.
• handleWindowRemove – Cleans up internal references when a window closes.
• requestResize – Processes user-initiated resize operations within the tiling constraints.

The LayoutManager (src/layout/LayoutManager.cpp) maintains algorithm instances and assigns the appropriate ITiledAlgorithm implementation to each workspace based on configuration. Switching layouts at runtime swaps the algorithm object while preserving the current window ordering.

The Dwindle Layout Algorithm

Dwindle implements a binary-tree tiling approach where screen space recursively splits with each new window. The algorithm alternates between horizontal and vertical splits, placing the newest window as the deepest leaf in the tree structure.

Key implementation details in src/layout/algorithm/tiled/dwindle/DwindleAlgorithm.cpp:

• The CDwindleAlgorithm class inherits from ITiledAlgorithm.
• Each window addition triggers a recursive split of the currently focused node.
• Splits alternate direction (horizontal, then vertical, then horizontal) to maintain balanced proportions.
• Geometry calculations respect gaps, borders, and reserved screen areas.

This layout suits users preferring classic i3-style tiling where each window occupies a distinct pane, automatically maintaining reasonable aspect ratios as the window count increases.

The Master Layout Algorithm

Master implements a primary-stack (master-stack) paradigm where one or more master windows occupy a large dedicated area while remaining windows stack in a secondary column. Users can dynamically adjust the master area ratio using keybinds.

Key implementation details in src/layout/algorithm/tiled/master/MasterAlgorithm.cpp:

• The CMasterAlgorithm class manages separate master and stack window lists.
• applyLayout positions master windows according to configured split ratios (typically master-slave proportions).
• Stack windows divide the remaining space vertically.
• Methods like requestResize adjust the master area width/height based on user interaction.

This layout excels for workflows centered on a primary application (terminal, editor, browser) with auxiliary windows (chat, file manager, documentation) stacked beside it.

Other Layout Options

While Dwindle and Master serve as the primary tiling strategies, Hyprland includes additional algorithms:

• Monocle (CMonocleAlgorithm in src/layout/algorithm/tiled/monocle/MonocleAlgorithm.cpp): Full-screen tiling where only one window displays at a time while maintaining workspace window ordering for quick cycling.
• Floating (CDefaultFloatingAlgorithm in src/layout/algorithm/floating/default/DefaultFloatingAlgorithm.cpp): The default non-tiling layout allowing free window positioning, used for dialog boxes and explicitly floated windows.

Configuring Layout Algorithms

Users assign layouts per workspace in hyprland.conf or dynamically via hyprctl.

Static configuration in hyprland.conf:

# Use Dwindle as the default tiling layout

workspace = 1, Dwindle
workspace = 2, Master
workspace = 3, Monocle

Runtime switching via hyprctl:

# Switch workspace 1 to Master layout

hyprctl keyword workspace:1,layout master

# Switch workspace 2 to Dwindle layout

hyprctl keyword workspace:2,layout dwindle

Plugin developers can programmatically set layouts using the LayoutManager API:

#include <hyprland/src/layout/LayoutManager.hpp>
#include <hyprland/src/state/WorkspaceState.hpp>

void setWorkspaceToDwindle(const int wsID) {
    auto* pWS = g_pLayoutManager->getWorkspaceByID(wsID);
    if (!pWS) return;

    // Directly assign the Dwindle algorithm instance
    pWS->setLayoutAlg(g_pLayoutManager->getAlgorithm("dwindle"));
    pWS->recalculateLayout(); // trigger an immediate layout refresh
}

Summary

• Dwindle (CDwindleAlgorithm) creates a binary tree of windows with alternating horizontal and vertical splits, ideal for balanced multi-window workflows.
• Master (CMasterAlgorithm) implements a primary-stack layout with configurable master area sizing, optimized for focus-driven workflows.
• Both algorithms inherit from ITiledAlgorithm defined in src/layout/algorithm/Algorithm.hpp and implement applyLayout, handleWindowAdd, and requestResize.
• The LayoutManager (src/layout/LayoutManager.cpp) handles per-workspace algorithm assignment and runtime switching.
• Configuration occurs through hyprland.conf workspace rules or hyprctl commands for immediate changes.

Frequently Asked Questions

How do I switch between Dwindle and Master layouts dynamically?

Use the hyprctl command to change a workspace's layout at runtime. For example, hyprctl keyword workspace:1,layout master switches workspace 1 to Master mode immediately without restarting Hyprland. The LayoutManager swaps the algorithm instance while preserving window order.

What interface do all Hyprland layout algorithms implement?

All tiling algorithms implement ITiledAlgorithm from src/layout/algorithm/Algorithm.hpp. This interface requires methods like applyLayout(CSpace* pSpace) for geometry calculation, handleWindowAdd for window insertion, and requestResize for user resize handling. Floating algorithms implement the separate IFloatingAlgorithm interface.

Where is the Dwindle algorithm implemented in the source code?

The binary-tree Dwindle logic resides in src/layout/algorithm/tiled/dwindle/DwindleAlgorithm.cpp within the CDwindleAlgorithm class. This file contains the recursive splitting logic that alternates split directions as windows are added to the workspace.

Can I set different layouts for different workspaces in Hyprland?

Yes. Add workspace-specific rules to hyprland.conf using the syntax workspace = ID, LayoutName. For example, workspace = 1, Dwindle and workspace = 2, Master configure workspace 1 to use binary-tree tiling while workspace 2 uses the master-stack arrangement.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}