Skip to main content

​
Getting Help

For first-time users having issues compiling, linking, running, or loading fonts:
Post in Discussions for compilation/setup issues. Use Issues for bugs, feature requests, and building a knowledge database.

​
Integration Issues

​
Little Squares Instead of Text

Your renderer backend is not using the font texture correctly or it hasn’t been uploaded to the GPU. Symptoms:
  • Text appears as white rectangles
  • All characters show as empty squares
Common causes:
Before v1.92: Did you modify the font atlas after ImGui_ImplXXX_NewFrame()?The texture atlas may be too large for your graphics API. This happens with many fonts or large glyph ranges.Solutions:
  • Reduce oversampling: font_config.OversampleH = 1
  • Load fewer glyph ranges
  • Set io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight
Since v1.92 with updated backends: This should be rare. Please report if it happens.
If using a custom backend:
  • Verify texture is uploaded to GPU
  • Check that shaders and rendering states are correct
  • Ensure texture is bound during rendering
  • Use a graphics debugger like RenderDoc
  • Compare your code to existing backends

​
Clipping Issues

Symptoms:
  • Elements disappear when moving windows
  • UI clips incorrectly at window boundaries
  • Widgets render outside expected bounds
Cause: Mishandling clipping rectangles in render function.
Dear ImGui clipping rectangles are defined as (x1=left, y1=top, x2=right, y2=bottom) NOT as (x1, y1, width, height).
Solution: 
// Correct clipping implementation (from DirectX11 backend)
ImVec2 clip_off = draw_data->DisplayPos;
ImVec2 clip_min(pcmd->ClipRect.x - clip_off.x, pcmd->ClipRect.y - clip_off.y);
ImVec2 clip_max(pcmd->ClipRect.z - clip_off.x, pcmd->ClipRect.w - clip_off.y);

if (clip_max.x <= clip_min.x || clip_max.y <= clip_min.y)
    continue;

// Apply scissor/clipping rectangle
const D3D11_RECT r = { (LONG)clip_min.x, (LONG)clip_min.y, (LONG)clip_max.x, (LONG)clip_max.y };
ctx->RSSetScissorRects(1, &r);
Refer to rendering backends in the backends/ folder for correct implementations.

​
Widget Not Reacting to Clicks

Most common mistake: Using the same ID for multiple widgets.
Dear ImGui needs unique IDs for interactive widgets. IDs are built from:
  • Window name
  • Widget labels
  • ID stack (PushID/PopID)
Wrong:
ImGui::DragFloat2("My value", &objects[0]->pos.x);
ImGui::DragFloat2("My value", &objects[1]->pos.x);  // ERROR: Same ID!
ImGui::DragFloat2("My value", &objects[2]->pos.x);  // ERROR: Same ID!
Correct - Using ## suffix:
ImGui::DragFloat2("My value##1", &objects[0]->pos.x);
ImGui::DragFloat2("My value##2", &objects[1]->pos.x);
ImGui::DragFloat2("My value##3", &objects[2]->pos.x);
Correct - Using PushID:
for (int n = 0; n < 3; n++) {
    ImGui::PushID(n);
    ImGui::DragFloat2("My value", &objects[n]->pos.x);
    ImGui::PopID();
}
Use Demo > Tools > ID Stack Tool or call ImGui::ShowIDStackToolWindow() to debug ID issues.

​
Input Handling

​
When to Dispatch Input to ImGui vs Application

Use the io.WantCaptureMouse and io.WantCaptureKeyboard flags: 
void MyLowLevelMouseButtonHandler(int button, bool down)
{
    ImGuiIO& io = ImGui::GetIO();
    
    // (1) ALWAYS forward mouse data to ImGui
    io.AddMouseButtonEvent(button, down);
    
    // (2) ONLY forward to your app if ImGui doesn't want it
    if (!io.WantCaptureMouse)
        my_game->HandleMouseData(button, down);
}
Always pass mouse/keyboard inputs to Dear ImGui, regardless of WantCapture flags. ImGui needs input to detect clicks in empty areas to unfocus windows.
Available flags:
  • io.WantCaptureMouse - ImGui wants mouse input (hovering window, etc.)
  • io.WantCaptureKeyboard - ImGui wants keyboard input (typing in InputText, etc.)
  • io.WantTextInput - Notify OS to show on-screen keyboard (mobile/console)

​
Keyboard/Gamepad Navigation

Enable navigation in configuration: 
ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;  // Enable keyboard navigation
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;   // Enable gamepad navigation
See USING GAMEPAD/KEYBOARD NAVIGATION CONTROLS section in imgui.cpp for details.

​
Font Issues

​
Missing Glyphs

Since v1.92 with updated backend: Specifying glyph ranges is unnecessary! Missing glyph issues should be rare.
Pre-1.92 or without updated backend: If you see squares for non-ASCII characters, you need to load fonts with explicit glyph ranges: 
ImGuiIO& io = ImGui::GetIO();

// Load Japanese font with Japanese glyph ranges
io.Fonts->AddFontFromFileTTF(
    "NotoSansCJKjp-Medium.otf",
    20.0f,
    nullptr,
    io.Fonts->GetGlyphRangesJapanese()
);

​
Font Loading Fails

Symptom: Assert “Could not load font file!” Cause: Incorrect filename or wrong working directory.
Remember: In C/C++, backslashes must be escaped:
// WRONG
io.Fonts->AddFontFromFileTTF("MyFiles\MyFont.ttf", 20.0f);

// CORRECT
io.Fonts->AddFontFromFileTTF("MyFiles\\MyFont.ttf", 20.0f);

// ALSO CORRECT (forward slashes work on Windows)
io.Fonts->AddFontFromFileTTF("MyFiles/MyFont.ttf", 20.0f);
Working directory: Make sure your IDE runs your executable from the correct directory.In Visual Studio: Project Properties > Debugging > Working Directory

​
UTF-8 Encoding Issues

Symptom: Non-ASCII characters display incorrectly Cause: Source code not encoded as UTF-8
Use the built-in encoding viewer:
ImGui::DebugTextEncoding(u8"こんにちは");  // Correct
ImGui::DebugTextEncoding("こんにちは");    // May be incorrect
Or use Metrics/Debugger > Tools > UTF-8 Encoding viewer
Use u8 prefix (C++11):
ImGui::Text(u8"こんにちは");  // Always UTF-8
Visual Studio compiler flags:
  • Add /utf-8 command-line flag
  • Or use #pragma execution_character_set("utf-8")
C++20 note: u8"" returns const char8_t*, requiring cast:
ImGui::Text((const char*)u8"こんにちは");
Disable this with /Zc:char8_t- (MSVC) or -fno-char8_t (Clang/GCC).

​
Display Issues

​
DPI Scaling

Symptom: Blurry text on high-DPI displays Cause: Application not marked as DPI-aware
You must inform Windows that your app is DPI-aware:SDL2:
SDL_CreateWindow("App", x, y, w, h, SDL_WINDOW_ALLOW_HIGHDPI);
::SetProcessDPIAware();
SDL3:
SDL_CreateWindow("App", w, h, SDL_WINDOW_HIGH_PIXEL_DENSITY);
GLFW: AutomaticOther Windows projects:
#include "imgui_impl_win32.h"
ImGui_ImplWin32_EnableDpiAwareness();
Or use an application manifest.
Since v1.92:
ImGuiStyle& style = ImGui::GetStyle();
style.FontScaleDpi = 2.0f;  // Scale fonts for high-DPI

​
Layout Issues

Overlapping widgets: 
// Use SameLine() for horizontal layout
ImGui::Button("Button 1");
ImGui::SameLine();
ImGui::Button("Button 2");

// Adjust spacing
ImGui::SameLine(0.0f, 20.0f);  // 20 pixels spacing
Widgets not visible: 
// Reserve space with Dummy or check window size
if (ImGui::GetContentRegionAvail().x < 200) {
    // Not enough space
}

​
Debug Tools

​
Metrics/Debugger Window

ImGui::ShowMetricsWindow();
Displays:
  • Window information
  • Draw command details
  • Font atlas visualization
  • Internal state

​
Demo Window

ImGui::ShowDemoWindow();
The demo is the best learning resource. Study its code in imgui_demo.cpp.

​
ID Stack Tool

ImGui::ShowIDStackToolWindow();
Debug ID conflicts by hovering over widgets to see their ID path.

​
Style Editor

ImGui::ShowStyleEditor();
Live-edit all style properties.

​
Performance Issues

  • Minimize window count
  • Use less rounded corners
  • Reduce anti-aliasing
  • Batch similar items
  • Don’t call ImGui::Begin() for collapsed windows
  • Use ImGuiWindowFlags_NoBackground when appropriate
  • Reduce transparency
  • Simplify layouts
  • Reduce texture atlas size
  • Lower oversampling
  • Disable anti-aliasing on low-end hardware
  • Reduce window count
See Performance Guide for detailed optimization.

​
Platform-Specific Issues

​
Windows

Visual Studio: Set project type to “Windows Application” instead of “Console Application”Or use:
#pragma comment(linker, "/SUBSYSTEM:windows /ENTRY:mainCRTStartup")
Make sure you’re linking against:
  • Graphics API libraries (OpenGL32.lib, d3d11.lib, etc.)
  • Platform libraries (user32.lib, gdi32.lib, etc.)
  • ImGui .cpp files are compiled and linked

​
Linux

Use glad, glew, or gl3w. Make sure loader is initialized before ImGui_ImplOpenGL3_Init().
gladLoadGL();  // or glewInit(), etc.
ImGui_ImplOpenGL3_Init("#version 130");

​
macOS

Handle display scale properly:
float scale = [[window backingScaleFactor] floatValue];
Since v1.92: macOS pixel/backing scale is automatically handled.

​
Web (Emscripten)

Required flags:
-s USE_WEBGL2=1
-s FULL_ES3=1
-s WASM=1

​
Common Misconceptions

Don’t check if mouse is hovering a window manually. Use io.WantCaptureMouse instead.
Don’t skip calling ImGui::Begin() even if it returns false. Always call matching ImGui::End().
Don’t modify ImGuiStyle mid-frame. Use PushStyleVar/PushStyleColor or modify between frames.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us