What Is the Dear ImGui Docking Branch? Docking and Multi-Viewport Explained

The Dear ImGui docking branch is a dedicated development line in the ocornut/imgui repository that adds window-docking and multi-viewport capabilities, allowing developers to drag panels into dockable layouts and render UI across multiple native OS windows while maintaining a single ImGui context.

Dear ImGui is a bloat-free immediate-mode graphical user interface library for C++. The docking branch extends the master branch with sophisticated layout management features not present in the stable line. According to the source code in ocornut/imgui, this branch introduces the infrastructure for dockable panels and multi-window rendering through extended configuration flags and internal data structures defined in imgui.h and imgui_internal.h.

How to Switch to the Dear ImGui Docking Branch

The docking branch lives alongside the main master branch and is regularly merged to keep features and bug fixes in sync. To access these capabilities, checkout the dedicated branch after cloning the repository:

git checkout docking

This branch is recommended for applications requiring advanced layout features such as persistent docked layouts or multi-window toolchains. The repository maintainers keep this branch stable by syncing it with the latest master updates.

Core Features of the Dear ImGui Docking Branch

Window Docking System

The branch implements a complete window-docking framework that allows you to organize UI panels through an intuitive drag-and-drop interface. Key capabilities include:

• Dragging windows into dockable panels and tab bars
• Splitting and merging dock nodes to create complex, resizable layouts
• Persisting layout configurations across application sessions

This functionality is controlled via the ImGuiConfigFlags_DockingEnable configuration flag, which is defined in imgui.h around line 200.

Multi-Viewport Support

Beyond docking, the branch enables multi-viewport rendering, which allows Dear ImGui windows to break out of the main application window and render as separate native OS windows. These viewports share a single ImGui context while operating as independent native windows. Enable this using ImGuiConfigFlags_ViewportsEnable in the ImGuiIO configuration structure.

Source Code Architecture

The docking implementation spans several key files in the repository, each serving a distinct architectural purpose:

• imgui.h: Contains the public API extensions, including the ImGuiConfigFlags_DockingEnable flag and docking node flags (around line 200).
• imgui_internal.h: Defines internal docking data structures and helper functions under the [SECTION] Docking support comment (around line 28).
• imgui.cpp: Houses the core docking logic, including the DockSpaceOverViewport() function (around line 16132).

Additional configuration options exposed in this branch include io.ConfigDockingWithShift, which restricts docking initiation to when the Shift key is held, and io.ConfigViewports, which activates the multi-viewport system.

Enabling Docking in Your Application

To enable docking capabilities, you must set the appropriate configuration flags after creating your ImGui context but before the main render loop:

// Enable docking and optionally multi-viewport
ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_DockingEnable;   // Enable docking
io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable; // Optional: multi-viewport

Creating a Full-Screen Dock Space

For tool-style applications, you typically want a full-screen dock space that fills the main viewport. The following implementation creates a borderless host window that covers the entire work area and initializes a dock space within it:

void ShowDockSpace()
{
    // Get the main viewport dimensions
    ImGuiViewport* viewport = ImGui::GetMainViewport();
    ImGui::SetNextWindowPos(viewport->WorkPos);
    ImGui::SetNextWindowSize(viewport->WorkSize);
    ImGui::SetNextWindowViewport(viewport->ID);

    // Create borderless window to host the dockspace
    ImGuiWindowFlags flags = ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoCollapse |
                             ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove |
                             ImGuiWindowFlags_NoBringToFrontOnFocus |
                             ImGuiWindowFlags_NoNavFocus | ImGuiWindowFlags_NoBackground;
    
    ImGui::Begin("DockSpace Demo", nullptr, flags);
    
    // Create the dock space using a unique ID
    ImGui::DockSpace(ImGui::GetID("##DockSpace"));
    ImGui::End();
}

This pattern utilizes the DockSpace() function to create a container where other ImGui windows can be docked. For automatic dock space creation over the main viewport without manual window setup, you can call DockSpaceOverViewport() as implemented in imgui.cpp.

Summary

• The Dear ImGui docking branch is a parallel git branch in ocornut/imgui that adds window-docking and multi-viewport capabilities alongside the master branch.
• Key configuration flags include ImGuiConfigFlags_DockingEnable and ImGuiConfigFlags_ViewportsEnable, defined in imgui.h around line 200.
• Core implementation resides in imgui_internal.h (structures around line 28) and imgui.cpp (logic such as DockSpaceOverViewport() around line 16132).
• Enable io.ConfigDockingWithShift to require Shift-key modifier for docking operations.
• The branch is regularly merged with master and recommended for applications requiring complex, persistable UI layouts.

Frequently Asked Questions

What is the difference between the master and docking branches?

The master branch contains the core Dear ImGui immediate-mode GUI functionality. The docking branch extends this with additional APIs for window docking and multi-viewport support. While the master branch focuses on single-window rendering, the docking branch allows windows to be docked into tab bars and rendered across multiple native OS windows. Both branches are kept in sync regularly, so you can switch to docking without losing upstream stability.

How do I enable multi-viewport support?

Multi-viewport support allows ImGui windows to exist as separate native OS windows. To enable this, set the ImGuiConfigFlags_ViewportsEnable flag in your ImGuiIO configuration after initializing the ImGui context:

ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable;

This feature requires platform and renderer backends that support multiple viewports. When enabled, windows can be dragged outside the main application window to create new native windows automatically.

Where is the docking logic implemented in the source code?

The docking implementation is distributed across three primary files. The public API and configuration flags are declared in imgui.h around line 200. Internal data structures and helper functions are defined in imgui_internal.h under the [SECTION] Docking support comment around line 28. The core implementation, including functions like DockSpaceOverViewport(), resides in imgui.cpp around line 16132.

Can I use docking without multi-viewports?

Yes, docking and multi-viewport features are independent. You can enable ImGuiConfigFlags_DockingEnable without setting ImGuiConfigFlags_ViewportsEnable to use dockable panels within a single window. This allows you to create complex docked layouts with splitters and tab bars while keeping all rendering confined to the main application window. Multi-viewport is only required if you need ImGui windows to break out into separate OS windows.

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