Dear ImGui Basic Widgets: Complete Guide to UI Controls

Dear ImGui provides a comprehensive set of basic widgets—including buttons, checkboxes, sliders, input fields, color editors, and layout elements—all declared in imgui.h and implemented in imgui_widgets.cpp for immediate-mode GUI development.

Dear ImGui is a bloat-free, immediate-mode graphical user interface library designed for creating debug tools and content creation applications. The widget API, maintained in the ocornut/imgui repository, offers lightweight, stateless UI primitives that return interaction status directly to your application code each frame without requiring persistent widget objects.

Button Widgets

Dear ImGui offers three distinct button variants for different interaction needs. The standard Button (ImGui::Button()) is declared at line 635 in imgui.h and returns true when clicked during the current frame. For compact layouts, SmallButton (line 636) removes vertical frame padding to sit inline with text. InvisibleButton (line 637) provides hit-testing capabilities without any visual representation, useful for custom drawing or overlay interactions. ImageButton (line 657) combines texture display with click handling, requiring a valid ImTextureID from your renderer.

Selection and Toggle Controls

Binary and mutually-exclusive selections are handled through several specialized widgets. Checkbox (line 639) binds directly to a bool pointer, while CheckboxFlags (lines 640-641) manipulates individual bits within an integer flag mask. RadioButton (lines 642-643) supports both boolean and integer-based mutually-exclusive selection patterns, typically used for mode switching or category selection.

Numeric Input Widgets

Dear ImGui provides multiple approaches to numeric data entry. DragFloat and DragInt (line 680) implement click-and-drag modifiers that change values while the mouse moves, offering fine-grained control without visible slider chrome. SliderFloat and SliderInt (line 699) display classic horizontal sliders with visible grab bars for intuitive range-limited selection. VSliderFloat and VSliderInt (line 710) provide vertical orientations for space-constrained layouts. InputFloat and InputInt (around line 950) offer direct text entry with optional clamping to specified ranges.

Text and List Widgets

Text input and selection lists are handled by several high-level primitives. InputText (around line 880) provides editable single-line and multi-line text fields with buffer management. Combo (around line 860) implements dropdown selection from string arrays. ListBox (around line 880) renders scrollable selection lists, while Selectable (around line 900) creates individual items that work with both single and multi-selection paradigms, commonly used within tables or custom list implementations.

Color and Visualization Widgets

Color manipulation and data visualization widgets include ColorEdit4 (line 739) and ColorPicker for RGBA value selection with optional alpha channels. Image (around line 650) displays textures without interaction, distinct from ImageButton. ProgressBar (around line 1080) renders simple floating-point progress indicators. PlotLines and PlotHistogram (around line 1100) provide lightweight data visualization for quick debugging graphs without external plotting dependencies.

Hierarchy and Layout Widgets

Structural organization relies on TreeNode (around line 920) for expandable hierarchical sections and CollapsingHeader (around line 940) as a convenience wrapper for collapsible content panels. MenuItem (around line 960) creates entries for menu bars and popup menus. Separator (around line 970) and Spacing provide visual dividers and empty space for layout structure. Text, TextColored, and TextWrapped (around line 1000) handle non-interactive label rendering with various formatting options.

Implementation Architecture

All basic widgets share a common implementation foundation in imgui_widgets.cpp, where low-level behaviors like ButtonBehavior, SliderBehavior, and DragBehavior reside. The public API declarations live in imgui.h, while internal helpers and flag definitions are found in imgui_internal.h (including the generic button function at line 3746). State management follows an immediate-mode design: widgets generate unique ImGuiID values based on label strings or explicit IDs to track hover, active, and focus states across frames without maintaining persistent widget objects. The imgui.cpp file handles core engine logic including ID generation and input processing through the ImGuiIO structure, while imgui_demo.cpp provides comprehensive usage examples for every widget.

Practical Usage Examples

The following patterns demonstrate typical widget usage within an ImGui::Begin/End block:

// Button interactions
if (ImGui::Button("Press Me")) {
    // Executes on click
}
ImGui::SameLine();
ImGui::SmallButton("Inline Compact");

// Boolean toggles
static bool show_window = false;
ImGui::Checkbox("Show Window", &show_window);

// Bit flag manipulation
static int flags = 0;
ImGui::CheckboxFlags("Enable Feature A", &flags, 1 << 0);
ImGui::CheckboxFlags("Enable Feature B", &flags, 1 << 1);

// Mutually exclusive selection
static int mode = 0;
ImGui::RadioButton("Mode 0", &mode, 0);
ImGui::RadioButton("Mode 1", &mode, 1);

// Numeric inputs with constraints
static float speed = 1.0f;
ImGui::DragFloat("Speed", &speed, 0.1f, 0.0f, 10.0f);

static int value = 50;
ImGui::SliderInt("Value", &value, 0, 100);

// Text entry
static char buffer[64] = "";
ImGui::InputText("Label", buffer, IM_ARRAYSIZE(buffer));

// Color selection
static ImVec4 color = ImVec4(0.45f, 0.55f, 0.60f, 1.00f);
ImGui::ColorEdit4("Background", (float*)&color);

// Dropdown selection
static int item = 0;
const char* items[] = { "Apple", "Banana", "Cherry" };
ImGui::Combo("Fruit", &item, items, IM_ARRAYSIZE(items));

// Hierarchical layout
if (ImGui::TreeNode("Advanced Settings")) {
    ImGui::Text("Configuration options");
    ImGui::TreePop();
}
ImGui::CollapsingHeader("Static Header");

Summary

• Dear ImGui provides over 20 basic widgets covering buttons, inputs, selections, colors, and layout elements in a single-header API (imgui.h).
• Implementation resides in imgui_widgets.cpp with low-level behaviors like ButtonBehavior and SliderBehavior defined in imgui_internal.h.
• Immediate-mode architecture eliminates persistent widget objects; state is stored in application variables and identified via unique ImGuiID hashes.
• Numeric inputs offer three paradigms: direct text entry (InputFloat), click-and-drag (DragFloat), and visual sliders (SliderFloat).
• Extensibility is supported through invisible buttons, selectable items, and low-level behavior functions for building custom widgets.

Frequently Asked Questions

What is the difference between DragFloat and SliderFloat in Dear ImGui?

DragFloat (line 680 in imgui.h) modifies values through click-and-drag mouse movement without displaying a grab bar, making it ideal for precise adjustments in limited space. SliderFloat (line 699) renders a visible horizontal track with a draggable grab handle, providing better visual feedback for range-limited values but requiring more horizontal screen real estate.

How does Dear ImGui track widget state without persistent objects?

Dear ImGui uses an immediate-mode design where widgets generate unique ImGuiID values based on their label strings or explicit ID stacks. These IDs index into internal hash tables (managed in imgui.cpp) that track hover, active, and focus states across frames. The application maintains the actual data (bools, ints, floats), while the library tracks transient interaction state.

Where are the widget implementations located in the source code?

Public API declarations for all basic widgets are in imgui.h, while the actual drawing and interaction logic lives in imgui_widgets.cpp. Low-level behavior helpers like ButtonBehavior and SliderBehavior are declared in imgui_internal.h (e.g., line 3746 for button behavior). Reference implementations demonstrating all widgets appear in imgui_demo.cpp.

Can I create custom widgets using Dear ImGui's basic primitives?

Yes. Developers can compose custom widgets by combining low-level primitives like InvisibleButton for hit detection, or by utilizing internal behavior functions from imgui_internal.h such as ButtonBehavior, DragBehavior, and SliderBehavior. The library's design encourages extending functionality through these composable building blocks rather than inheritance or subclassing.

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