Integration guide

Overview

Integrating Dear ImGui into an existing application typically involves:

Adding the core Dear ImGui files to your project
Choosing and integrating platform and renderer backends
Initializing Dear ImGui in your application startup
Calling Dear ImGui functions in your main loop
Rendering the Dear ImGui draw data

Most integrations take less than an hour when using existing backends. Custom backends require more time but are straightforward to implement.

Core files

The core Dear ImGui library is self-contained in these files (from the repository root):

imgui.cpp          // Main implementation
imgui.h            // Public API
imgui_draw.cpp     // Rendering
imgui_tables.cpp   // Tables functionality
imgui_widgets.cpp  // Widget implementations

No build process required - just add these files to your existing project and compile them.

Choosing backends

Dear ImGui needs two types of backends:

Platform backends

Handle windowing, input (mouse/keyboard/gamepad), and OS features:

imgui_impl_glfw.cpp - GLFW (cross-platform, recommended)
imgui_impl_sdl2.cpp / imgui_impl_sdl3.cpp - SDL2/SDL3 (cross-platform)
imgui_impl_win32.cpp - Win32 native API (Windows only)
imgui_impl_osx.mm - macOS native API
imgui_impl_android.cpp - Android native
imgui_impl_glut.cpp - GLUT/FreeGLUT (legacy, not recommended)

Renderer backends

Handle texture creation and rendering Dear ImGui draw commands:

imgui_impl_opengl3.cpp - OpenGL 3/4, OpenGL ES 2/3, WebGL
imgui_impl_opengl2.cpp - OpenGL 2 (legacy fixed pipeline)
imgui_impl_dx11.cpp - DirectX 11
imgui_impl_dx12.cpp - DirectX 12
imgui_impl_dx9.cpp - DirectX 9
imgui_impl_vulkan.cpp - Vulkan
imgui_impl_metal.mm - Metal (macOS/iOS)
imgui_impl_wgpu.cpp - WebGPU
imgui_impl_sdlrenderer3.cpp - SDL_Renderer

Recommended combos
All backends

Platform	Renderer	Use case
GLFW	OpenGL3	Desktop cross-platform
SDL3	OpenGL3	Games, cross-platform
SDL3	Vulkan	Modern graphics
Win32	DX11	Windows native
Win32	DX12	Windows, modern graphics

Integration steps

Add files to your project

Copy the core files and your chosen backends:

# Core library
imgui/imgui.cpp
imgui/imgui_draw.cpp
imgui/imgui_tables.cpp
imgui/imgui_widgets.cpp
imgui/imgui_demo.cpp

# Backends (example: GLFW + OpenGL3)
imgui/backends/imgui_impl_glfw.cpp
imgui/backends/imgui_impl_opengl3.cpp

Add these files to your build system (CMake, Make, Visual Studio project, etc.).

Include headers

In your application code:

#include "imgui.h"
#include "imgui_impl_glfw.h"   // Your platform backend
#include "imgui_impl_opengl3.h" // Your renderer backend

Initialize at startup

After creating your window and graphics context:

// Setup Dear ImGui context
IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();

// Optional: enable keyboard/gamepad controls
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;

// Setup style
ImGui::StyleColorsDark();
// or: ImGui::StyleColorsLight();
// or: ImGui::StyleColorsClassic();

// Setup Platform/Renderer backends
ImGui_ImplGlfw_InitForOpenGL(window, true);
ImGui_ImplOpenGL3_Init("#version 130");

Per-frame updates

At the start of your frame, before UI code:

// Poll events (platform-specific)
glfwPollEvents();

// Start the Dear ImGui frame
ImGui_ImplOpenGL3_NewFrame();
ImGui_ImplGlfw_NewFrame();
ImGui::NewFrame();

Submit UI code

Anywhere in your main loop after NewFrame():

// Your UI code here
ImGui::Begin("Debug Window");
ImGui::Text("FPS: %.1f", ImGui::GetIO().Framerate);
ImGui::End();

// Optional: show demo for learning
ImGui::ShowDemoWindow();

Render Dear ImGui

At the end of your frame, after your rendering:

// Finalize Dear ImGui frame
ImGui::Render();

// Render your application
glClear(GL_COLOR_BUFFER_BIT);
RenderYourApplication();

// Render Dear ImGui on top
ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());

// Swap buffers
glfwSwapBuffers(window);

Cleanup at shutdown

Before destroying your window:

ImGui_ImplOpenGL3_Shutdown();
ImGui_ImplGlfw_Shutdown();
ImGui::DestroyContext();

Platform-specific examples

GLFW + OpenGL3
SDL2 + OpenGL3
Win32 + DirectX11
Win32 + DirectX12

// Initialization
GLFWwindow* window = glfwCreateWindow(1280, 720, "App", NULL, NULL);
glfwMakeContextCurrent(window);

IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGui_ImplGlfw_InitForOpenGL(window, true);
ImGui_ImplOpenGL3_Init("#version 130");

// Main loop
while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    
    ImGui_ImplOpenGL3_NewFrame();
    ImGui_ImplGlfw_NewFrame();
    ImGui::NewFrame();
    
    // Your UI code
    
    ImGui::Render();
    int display_w, display_h;
    glfwGetFramebufferSize(window, &display_w, &display_h);
    glViewport(0, 0, display_w, display_h);
    glClearColor(0.1f, 0.1f, 0.1f, 1.0f);
    glClear(GL_COLOR_BUFFER_BIT);
    ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
    
    glfwSwapBuffers(window);
}

// Cleanup
ImGui_ImplOpenGL3_Shutdown();
ImGui_ImplGlfw_Shutdown();
ImGui::DestroyContext();

// Initialization
SDL_Init(SDL_INIT_VIDEO | SDL_INIT_GAMECONTROLLER);
SDL_Window* window = SDL_CreateWindow("App", SDL_WINDOWPOS_CENTERED,
    SDL_WINDOWPOS_CENTERED, 1280, 720, SDL_WINDOW_OPENGL);
SDL_GLContext gl_context = SDL_GL_CreateContext(window);
SDL_GL_MakeCurrent(window, gl_context);
SDL_GL_SetSwapInterval(1);

IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGui_ImplSDL2_InitForOpenGL(window, gl_context);
ImGui_ImplOpenGL3_Init("#version 130");

// Main loop
bool done = false;
while (!done) {
    SDL_Event event;
    while (SDL_PollEvent(&event)) {
        ImGui_ImplSDL2_ProcessEvent(&event);
        if (event.type == SDL_QUIT)
            done = true;
    }
    
    ImGui_ImplOpenGL3_NewFrame();
    ImGui_ImplSDL2_NewFrame();
    ImGui::NewFrame();
    
    // Your UI code
    
    ImGui::Render();
    glViewport(0, 0, (int)io.DisplaySize.x, (int)io.DisplaySize.y);
    glClearColor(0.1f, 0.1f, 0.1f, 1.0f);
    glClear(GL_COLOR_BUFFER_BIT);
    ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
    SDL_GL_SwapWindow(window);
}

// Cleanup
ImGui_ImplOpenGL3_Shutdown();
ImGui_ImplSDL2_Shutdown();
ImGui::DestroyContext();

// After creating D3D11 device and window
IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGui_ImplWin32_Init(hwnd);
ImGui_ImplDX11_Init(g_pd3dDevice, g_pd3dDeviceContext);

// Main loop
MSG msg;
while (msg.message != WM_QUIT) {
    if (::PeekMessage(&msg, NULL, 0U, 0U, PM_REMOVE)) {
        ::TranslateMessage(&msg);
        ::DispatchMessage(&msg);
        continue;
    }
    
    ImGui_ImplDX11_NewFrame();
    ImGui_ImplWin32_NewFrame();
    ImGui::NewFrame();
    
    // Your UI code
    
    ImGui::Render();
    const float clear_color[4] = { 0.1f, 0.1f, 0.1f, 1.0f };
    g_pd3dDeviceContext->ClearRenderTargetView(g_mainRenderTargetView, clear_color);
    ImGui_ImplDX11_RenderDrawData(ImGui::GetDrawData());
    g_pSwapChain->Present(1, 0);
}

// Cleanup
ImGui_ImplDX11_Shutdown();
ImGui_ImplWin32_Shutdown();
ImGui::DestroyContext();

// After creating D3D12 device and command queue
IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGui_ImplWin32_Init(hwnd);
ImGui_ImplDX12_Init(g_pd3dDevice, NUM_FRAMES_IN_FLIGHT,
    DXGI_FORMAT_R8G8B8A8_UNORM, g_pd3dSrvDescHeap,
    g_pd3dSrvDescHeap->GetCPUDescriptorHandleForHeapStart(),
    g_pd3dSrvDescHeap->GetGPUDescriptorHandleForHeapStart());

// Main loop - similar to DX11 but with command lists
// See examples/example_win32_directx12/ for full code

// Cleanup
ImGui_ImplDX12_Shutdown();
ImGui_ImplWin32_Shutdown();
ImGui::DestroyContext();

Handling input

Dear ImGui needs to know when to capture input. Use these flags:

ImGuiIO& io = ImGui::GetIO();

// Check if Dear ImGui wants keyboard input
if (!io.WantCaptureKeyboard) {
    // Pass keyboard events to your application
}

// Check if Dear ImGui wants mouse input
if (!io.WantCaptureMouse) {
    // Pass mouse events to your application
}

// Check if Dear ImGui wants text input
if (!io.WantTextInput) {
    // Your application logic
}

Important: When io.WantCaptureMouse is true, don’t dispatch mouse input to your application. Similarly for keyboard. This prevents UI interactions from “falling through” to your application.

Configuration options

Set these flags on ImGuiIO after creating the context:

ImGuiIO& io = ImGui::GetIO();

// Enable keyboard navigation
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;

// Enable gamepad navigation
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;

// Enable docking (docking branch only)
io.ConfigFlags |= ImGuiConfigFlags_DockingEnable;

// Enable multi-viewport / platform windows (docking branch only)
io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable;

// Disable .ini file save/load
io.IniFilename = NULL;

// Set custom .ini path
io.IniFilename = "my_app.ini";

Loading fonts

Dear ImGui embeds a default font, but you can load custom fonts:

ImGuiIO& io = ImGui::GetIO();

// Add default font at different size
io.Fonts->AddFontDefault();

// Load TTF font from file
ImFont* font = io.Fonts->AddFontFromFileTTF("fonts/Roboto-Regular.ttf", 16.0f);

// Load with custom glyph ranges (for international text)
ImFontConfig config;
config.MergeMode = true;
io.Fonts->AddFontFromFileTTF("fonts/DroidSans.ttf", 16.0f, &config,
    io.Fonts->GetGlyphRangesJapanese());

// Use the font
ImGui::PushFont(font);
ImGui::Text("Custom font text");
ImGui::PopFont();

Load fonts before the first frame. After adding fonts, they’re automatically uploaded to the GPU by the renderer backend.

Integration with game engines

Unreal Engine

Use the ImGui for Unreal Engine plugin.

Unity

Use Dear ImGui for Unity package.

Custom engines

For custom engines with their own abstraction layers:

Start with standard backends

Use imgui_impl_glfw.cpp + your graphics API backend to get running quickly.

Evaluate if custom backend needed

In most cases, standard backends work fine even with engine abstractions.

Write custom backend if necessary

See the Backends documentation for implementation details.

Build system integration

CMake
Makefile
Visual Studio

set(IMGUI_DIR ${CMAKE_CURRENT_SOURCE_DIR}/imgui)

add_library(imgui STATIC
    ${IMGUI_DIR}/imgui.cpp
    ${IMGUI_DIR}/imgui_draw.cpp
    ${IMGUI_DIR}/imgui_tables.cpp
    ${IMGUI_DIR}/imgui_widgets.cpp
    ${IMGUI_DIR}/imgui_demo.cpp
    ${IMGUI_DIR}/backends/imgui_impl_glfw.cpp
    ${IMGUI_DIR}/backends/imgui_impl_opengl3.cpp
)

target_include_directories(imgui PUBLIC ${IMGUI_DIR} ${IMGUI_DIR}/backends)
target_link_libraries(imgui PUBLIC glfw OpenGL::GL)

# Link to your executable
target_link_libraries(your_app PRIVATE imgui)

IMGUI_DIR = imgui
SOURCES = main.cpp
SOURCES += $(IMGUI_DIR)/imgui.cpp $(IMGUI_DIR)/imgui_draw.cpp
SOURCES += $(IMGUI_DIR)/imgui_tables.cpp $(IMGUI_DIR)/imgui_widgets.cpp
SOURCES += $(IMGUI_DIR)/imgui_demo.cpp
SOURCES += $(IMGUI_DIR)/backends/imgui_impl_glfw.cpp
SOURCES += $(IMGUI_DIR)/backends/imgui_impl_opengl3.cpp

CXXFLAGS = -std=c++11 -I$(IMGUI_DIR) -I$(IMGUI_DIR)/backends
LIBS = -lglfw -lGL -ldl

$(CXX) $(CXXFLAGS) $(SOURCES) -o app $(LIBS)

Add all .cpp files to your project
Right-click project → Properties → C/C++ → General
Add to Additional Include Directories:
- $(ProjectDir)imgui
- $(ProjectDir)imgui\backends
Link required libraries (opengl32.lib, etc.)

Common issues

Nothing renders / blank screen

Verify you’re calling ImGui_ImplXXX_NewFrame() for both backends
Verify you’re calling ImGui::NewFrame() before UI code
Verify you’re calling ImGui::Render() before RenderDrawData()
Check that your viewport/scissor state is correct
Try calling ImGui::ShowDemoWindow() to test

Widgets show squares instead of text

Font atlas texture wasn’t uploaded to GPU. The renderer backend should handle this automatically after the first frame.

Clipping issues / disappearing elements

Your renderer may not be handling scissor rectangles correctly. Check that you’re applying the scissor rect from ImDrawCmd.

Input not working

Verify platform backend NewFrame() is called before ImGui::NewFrame()
For SDL, ensure you’re calling ImGui_ImplSDL2_ProcessEvent(&event)
For Win32, ensure your WndProc calls ImGui_ImplWin32_WndProcHandler()

Crashes or asserts

Run IMGUI_CHECKVERSION() at startup
Ensure you’re not mixing Debug/Release builds
Check that all required backends are initialized
Verify you’re not calling UI code before NewFrame()

Next steps

API reference

Explore all available widgets and functions

Examples

See complete example applications

Custom backends

Learn to write your own platform/renderer backend

FAQ

Find answers to common questions

Getting Started

Core Concepts

Widgets

Advanced Features

Backends

Styling

Guides

Overview

Core files

Choosing backends

Platform backends

Renderer backends

Integration steps

Platform-specific examples

Handling input

Configuration options

Loading fonts

Integration with game engines

Unreal Engine

Unity

Custom engines

Build system integration

Common issues

Next steps

API reference

Examples

Custom backends

FAQ

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Widgets

Advanced Features

Backends

Styling

Guides

​Overview

​Core files

​Choosing backends

​Platform backends

​Renderer backends

​Integration steps

​Platform-specific examples

​Handling input

​Configuration options

​Loading fonts

​Integration with game engines

​Unreal Engine

​Unity

​Custom engines

​Build system integration

​Common issues

​Next steps

API reference

Examples

Custom backends

FAQ

Build docs developers (and LLMs) love

Overview

Core files

Choosing backends

Platform backends

Renderer backends

Integration steps

Platform-specific examples

Handling input

Configuration options

Loading fonts

Integration with game engines

Unreal Engine

Unity

Custom engines

Build system integration

Common issues

Next steps