This page documents Dear ImGui's configuration and customization systems, covering how to adapt the library's behavior, appearance, and features to your application's needs. Configuration happens at two distinct levels: compile-time through preprocessor definitions and runtime through configuration structures.
Dear ImGui provides a layered configuration system that allows customization at different stages of integration:
Sources: imgui.cpp1-103 imgui.h388-405 imconfig.h1-148
Dear ImGui uses a multi-level configuration system to allow flexible customization without modifying library files:
| Configuration Method | Priority | Use Case | File Modified |
|---|---|---|---|
IMGUI_USER_CONFIG define | Highest | Project-wide customization | Your custom file |
imconfig.h (local copy) | Medium | Per-project modifications | imconfig.h in your tree |
| Project preprocessor defines | Varies | Build-specific options | Build system |
| Default configuration | Lowest | Standard behavior | Built-in defaults |
Recommended Approach: Use #define IMGUI_USER_CONFIG "my_imgui_config.h" in your build system rather than modifying imconfig.h directly. This keeps library files pristine and facilitates updates.
Sources: imgui.h63-68 imconfig.h1-14 imgui.cpp241-258
Warning: Dear ImGui relies heavily on assertions to catch programming errors. Disabling them is strongly discouraged during development.
Sources: imconfig.h17-21 imgui.h94-97
| Define | Effect | Use Case |
|---|---|---|
IMGUI_DISABLE | Disables entire library | Conditional compilation |
IMGUI_DISABLE_DEMO_WINDOWS | Removes demo/style editor | Shipping builds |
IMGUI_DISABLE_DEBUG_TOOLS | Removes metrics/debugger | Shipping builds |
IMGUI_DISABLE_OBSOLETE_FUNCTIONS | Enforces modern API | Code modernization |
IMGUI_DISABLE_DEFAULT_FONT | Removes embedded fonts (~23 KB) | Custom font workflows |
IMGUI_DISABLE_SSE | Disables SSE optimizations | ARM/compatibility |
Example workflow for shipping builds:
Sources: imconfig.h31-53 imgui_internal.h62-74
Sources: imconfig.h40-51
Sources: imconfig.h69-115 imgui.h291-316 imgui.cpp230-234
Note: FreeType generally produces higher quality glyphs with better hinting, especially for small text. See Font System for details.
Sources: imconfig.h85-101 misc/freetype/imgui_freetype.h8-11 imgui_internal.h126-130
The ImGuiIO structure is the primary runtime configuration interface, accessed via ImGui::GetIO():
Sources: imgui.h2253-2561 imgui.cpp1213-1309
Set via io.ConfigFlags to control core behavior:
| Flag | Effect | Default |
|---|---|---|
ImGuiConfigFlags_NavEnableKeyboard | Enable keyboard navigation | Disabled |
ImGuiConfigFlags_NavEnableGamepad | Enable gamepad navigation | Disabled |
ImGuiConfigFlags_NavEnableSetMousePos | Instruct backend to move OS mouse cursor | Disabled |
ImGuiConfigFlags_NavNoCaptureKeyboard | Don't set io.WantCaptureKeyboard flag | Disabled |
ImGuiConfigFlags_NoMouse | Disable mouse input entirely | Disabled |
ImGuiConfigFlags_NoMouseCursorChange | Don't change mouse cursor shape | Disabled |
ImGuiConfigFlags_NoKeyboard | Disable keyboard input entirely | Disabled |
ImGuiConfigFlags_IsSRGB | Enable sRGB-aware rendering | Disabled |
ImGuiConfigFlags_IsTouchScreen | Touch input available | Disabled |
Example initialization:
Sources: imgui.h1849-1881 imgui.cpp1213-1227
Set by backend implementations to declare capabilities via io.BackendFlags:
| Flag | Meaning | Set By |
|---|---|---|
ImGuiBackendFlags_HasGamepad | Backend can provide gamepad input | Platform backend |
ImGuiBackendFlags_HasMouseCursors | Backend can honor GetMouseCursor() | Platform backend |
ImGuiBackendFlags_HasSetMousePos | Backend can reposition OS mouse | Platform backend |
ImGuiBackendFlags_RendererHasVtxOffset | Renderer supports ImDrawCmd::VtxOffset | Renderer backend |
ImGuiBackendFlags_RendererHasTextures | Renderer supports texture management | Renderer backend |
Note: Applications should not set these flags directly; they are managed by backend implementations.
Sources: imgui.h1888-1904 imgui.cpp330-335
The ImGuiIO structure provides numerous Config* fields for fine-tuning behavior:
Common configuration example:
Sources: imgui.h2302-2390 imgui.cpp1213-1309
ImGuiIO provides callback hooks for platform integration:
| Callback | Purpose | Set By |
|---|---|---|
GetClipboardTextFn | Read clipboard text | Application/Platform backend |
SetClipboardTextFn | Write clipboard text | Application/Platform backend |
ClipboardUserData | User data for clipboard callbacks | Application |
PlatformSetImeDataFn | Set IME composition position | Platform backend |
PlatformLocaleDecimalPoint | Locale decimal point character | Platform backend |
Example callback setup (typically done by backends):
Sources: imgui.h2448-2462 imgui.cpp1280-1287
The ImGuiStyle structure controls all visual appearance aspects, accessed via ImGui::GetStyle():
Sources: imgui.h2003-2115 imgui.cpp1310-1439
Dear ImGui defines 58 color slots (ImGuiCol_ enum) for complete visual customization:
| Color Category | Key Colors | Usage |
|---|---|---|
| Text | ImGuiCol_Text, ImGuiCol_TextDisabled | All text rendering |
| Windows | ImGuiCol_WindowBg, ImGuiCol_ChildBg, ImGuiCol_PopupBg | Window backgrounds |
| Borders | ImGuiCol_Border, ImGuiCol_BorderShadow | Window/widget borders |
| Frames | ImGuiCol_FrameBg, ImGuiCol_FrameBgHovered, ImGuiCol_FrameBgActive | Input widgets |
| Title Bar | ImGuiCol_TitleBg, ImGuiCol_TitleBgActive, ImGuiCol_TitleBgCollapsed | Window titles |
| Scrollbar | ImGuiCol_ScrollbarBg, ImGuiCol_ScrollbarGrab, ImGuiCol_ScrollbarGrabHovered, ImGuiCol_ScrollbarGrabActive | Scrollbars |
| Widgets | ImGuiCol_Button, ImGuiCol_CheckMark, ImGuiCol_SliderGrab | Interactive elements |
| Tables | ImGuiCol_TableHeaderBg, ImGuiCol_TableBorderStrong, ImGuiCol_TableRowBg | Table styling |
| Tabs | ImGuiCol_Tab, ImGuiCol_TabSelected, ImGuiCol_TabDimmed | Tab bars |
Accessing and modifying colors:
Sources: imgui.h1438-1517 imgui.cpp1310-1439 imgui_draw.cpp187-280
Dear ImGui provides three built-in color themes accessible via convenience functions:
| Function | Theme | Characteristics |
|---|---|---|
ImGui::StyleColorsDark() | Dark (Default) | Dark backgrounds, blue accents |
ImGui::StyleColorsLight() | Light | Light backgrounds, darker accents |
ImGui::StyleColorsClassic() | Classic | Original ImGui appearance |
Usage:
Implementation locations:
ImGui::StyleColorsDark() at imgui_draw.cpp187-280ImGui::StyleColorsLight() at imgui_draw.cpp282-376ImGui::StyleColorsClassic() at imgui_draw.cpp378-472Sources: imgui.h787-789 imgui_draw.cpp187-472
For temporary style changes, use the style stack system:
Available style variables (ImGuiStyleVar_ enum):
WindowPadding, FramePadding, ItemSpacing, ItemInnerSpacing, IndentSpacingScrollbarSize, GrabMinSize, WindowMinSizeWindowBorderSize, ChildBorderSize, PopupBorderSize, FrameBorderSizeWindowRounding, ChildRounding, FrameRounding, PopupRounding, ScrollbarRounding, GrabRounding, TabRoundingWindowTitleAlign, ButtonTextAlign, SelectableTextAlignAlpha, DisabledAlpha, CellPadding, SeparatorTextPaddingSources: imgui.h1636-1676 imgui.cpp8800-8868
DPI-aware setup example:
Note: As of version 1.92, the font and scaling system has been significantly redesigned. See Font System for complete details on modern scaling approaches.
Sources: imgui.h2121-2139 imgui.cpp1440-1488 imgui.cpp462-492
Override memory allocation functions before creating any ImGui contexts:
Important: Allocator functions must be set before any Dear ImGui contexts are created and apply globally to all contexts in the same memory space.
Sources: imgui.h813-815 imgui.cpp1170-1189
When using the FreeType font backend, you can specify separate allocators for FreeType operations:
Use case: Redirecting FreeType allocations to a separate memory heap for better memory tracking or allocation performance.
Sources: misc/freetype/imgui_freetype.h70-71 misc/freetype/imgui_freetype.cpp89-96
By default, ImTextureID is a 64-bit value (ImU64), but you can customize it:
Note: If you customize ImTextureID, you must implement == and != operators if it's a struct/class type.
Sources: imgui.h323-346 imgui.cpp337-340
Use with the Item Picker tool (Metrics/Debugger->Tools->Item Picker) to break into code at widget creation.
Sources: imconfig.h129-132 imgui_internal.h310-324
Enable specific debug log categories:
View logs via ImGui::ShowDebugLogWindow().
Sources: imgui_internal.h244-254 imgui.cpp11897-12055
Highlights widgets with conflicting IDs, helping debug the ID stack system.
Sources: imconfig.h134-136 imgui.h2383-2384
Proper initialization sequence for maximum compatibility:
Sources: imgui.cpp277-315 imgui.h388-396
When using Dear ImGui across DLL boundaries (not recommended but sometimes necessary):
Sources: imgui.h390-391 imgui.cpp67-70
Example configuration presets for common scenarios:
Sources: imgui.cpp132-198 imgui.h2302-2390
| Flag | Effect | Notes |
|---|---|---|
ImGuiConfigFlags_None | Default state | No flags set |
ImGuiConfigFlags_NavEnableKeyboard | Master keyboard navigation enable | Set to use Tab/Arrow keys |
ImGuiConfigFlags_NavEnableGamepad | Master gamepad navigation enable | Requires backend support |
ImGuiConfigFlags_NavEnableSetMousePos | Request backend to move OS cursor | For gamepad cursor emulation |
ImGuiConfigFlags_NavNoCaptureKeyboard | Disable io.WantCaptureKeyboard flag | Let app handle all keys |
ImGuiConfigFlags_NoMouse | Instruct ImGui to clear mouse state | Mouse input ignored |
ImGuiConfigFlags_NoMouseCursorChange | Instruct backend to not alter cursor | Keep OS cursor unchanged |
ImGuiConfigFlags_NoKeyboard | Instruct ImGui to clear keyboard state | Keyboard input ignored |
ImGuiConfigFlags_IsSRGB | Application uses sRGB framebuffer | For color correction |
ImGuiConfigFlags_IsTouchScreen | Touch input available | Enables touch-specific behavior |
Sources: imgui.h1849-1881
| Variable | Type | Default | Description |
|---|---|---|---|
Alpha | float | 1.0 | Global alpha multiplier |
DisabledAlpha | float | 0.6 | Alpha multiplier when disabled |
WindowPadding | ImVec2 | 8,8 | Padding inside windows |
WindowRounding | float | 0.0 | Window corner radius (0 = square) |
WindowBorderSize | float | 1.0 | Window border thickness |
WindowMinSize | ImVec2 | 32,32 | Minimum resizable window size |
FramePadding | ImVec2 | 4,3 | Padding inside framed widgets |
FrameRounding | float | 0.0 | Widget corner radius |
FrameBorderSize | float | 0.0 | Widget border thickness |
ItemSpacing | ImVec2 | 8,4 | Horizontal, vertical spacing between items |
ItemInnerSpacing | ImVec2 | 4,4 | Spacing within compound widgets |
IndentSpacing | float | 21.0 | TreeNode indentation width |
ScrollbarSize | float | 14.0 | Scrollbar width/height |
ScrollbarRounding | float | 9.0 | Scrollbar corner radius |
GrabMinSize | float | 12.0 | Minimum slider/scrollbar grab size |
GrabRounding | float | 0.0 | Slider/scrollbar grab corner radius |
TabRounding | float | 4.0 | Tab corner radius |
Sources: imgui.h2003-2115 imgui.cpp1310-1439
Dear ImGui's configuration system provides comprehensive control over library behavior and appearance through:
imconfig.h and preprocessor defines for structural decisions (feature enabling/disabling, type customization)ImGuiIO for behavioral settings (input handling, navigation, callbacks)ImGuiStyle for all appearance aspects (colors, sizes, spacing, rounding)The recommended approach is:
IMGUI_USER_CONFIG for compile-time customization instead of modifying imconfig.hImGuiIO during initialization before the first NewFrame()ImGuiStyle once during initialization or allow runtime theme switchingPushStyleVar/PushStyleColor) for temporary modificationsFor platform-specific concerns, see Backend System. For font configuration, see Font System.
Refresh this wiki