dear-imgui-reflect

Reflection-based UI helpers for dear-imgui-rs: automatically generate Dear ImGui widgets for your Rust structs and enums, inspired by the C++ ImReflect library.

This crate exposes:

• ImGuiValue – per-type editing widgets (low-level hook, similar to ImInput<T>).
• ImGuiReflect – derive-based struct/enum editor that walks fields and dispatches to ImGuiValue.
• ReflectSettings / MemberSettings – ImSettings-style configuration for numeric widgets, containers, tuples, maps, and more.

It is designed to integrate directly with dear-imgui-rs and the rest of this workspace.

Links

• Core ImGui bindings: https://crates.io/crates/dear-imgui-rs
• Examples (native): examples/reflect_demo.rs
• ImReflect (C++ reference library): https://github.com/Sven-vh/ImReflect

Compatibility

The optional glam and mint features track the same workspace versions as other crates in this repository.

See also: docs/COMPATIBILITY.md for the full workspace matrix.

Cargo Integration

Add the crate alongside dear-imgui-rs:

[dependencies]
dear-imgui-rs = "0.8"
dear-imgui-reflect = "0.8"

Optional math interop:

[dependencies]
dear-imgui-rs = "0.8"
dear-imgui-reflect = { version = "0.8", features = ["glam", "mint"] }
glam = "0.29" # or workspace version
mint = "0.5"

By default the derive feature is enabled so you can use #[derive(ImGuiReflect)].

Basic Usage

Define a struct and derive ImGuiReflect:

use dear_imgui_reflect as reflect;
use reflect::ImGuiReflect;

#[derive(ImGuiReflect, Default)]
struct GameSettings {
    #[imgui(name = "Volume", slider, min = 0, max = 100)]
    volume: i32,
    sensitivity: f32,
    fullscreen: bool,
}

In your Dear ImGui frame, call reflect::input or the Ui extension:

use dear_imgui_reflect as reflect;
use reflect::ImGuiReflectExt;
use reflect::imgui::*; // re-export of dear-imgui-rs

fn frame(ui: &Ui, settings: &mut GameSettings) {
    ui.window("Settings").build(|| {
        // Free function (ImReflect-style)
        reflect::input(ui, "Game Settings", settings);

        // Or via Ui extension:
        // ui.input_reflect("Game Settings", settings);
    });
}

Enums (C-like, no payload) can also derive ImGuiReflect and are rendered as combos or radios:

use dear_imgui_reflect::ImGuiReflect;

#[derive(ImGuiReflect)]
enum Quality {
    #[imgui(name = "Low (Fast)")]
    Low,
    Medium,
    High,
}

#[derive(ImGuiReflect)]
#[imgui(enum_style = "radio")] // "combo" (default) or "radio"
enum RenderMode {
    Forward,
    Deferred,
    PathTracing,
}

Features Overview

• Derive-based struct/enum editing
  • #[derive(ImGuiReflect)] for named-field structs and C-like enums.
  • Field attributes for labels, skipping, numeric behavior, text widgets, tuples, and more.
• Numeric widgets (input / drag / slider)
  • Per-field attributes: as_input, as_drag, slider, slider_default_range.
  • Range and steps: min, max, step, step_fast, speed.
  • Slider/drag flags: log, wrap_around, clamp, always_clamp, no_input, no_round_to_format, clamp_on_input, clamp_zero_range, no_speed_tweaks.
  • Formatting helpers: format = "...", hex, percentage, scientific, prefix = "...", suffix = "...".
  • Type-level defaults via ReflectSettings::numerics_*.
  • Numeric presets via NumericTypeSettings helpers such as with_float, with_hex, slider_0_to_1, slider_minus1_to_1, drag_with_speed, and percentage_slider_0_to_1.
• Booleans
  • Styles: checkbox (default), button, radio, dropdown.
  • Per-field attributes: bool_style = "checkbox|button|radio|dropdown", true_text, false_text.
• Text
  • Single-line String / ImString with hint and min_width.
  • Multiline with multiline, optional lines, and auto_resize.
  • read_only for non-editable text.
  • display_only for text labels without an input box (layout only).
• Containers & optionals
  • Option<T> – checkbox toggles presence; nested editor for Some(T).
  • Vec<T> – insertable/removable/reorderable with tree-node dropdown.
  • Fixed arrays [T; N] (for T: ImGuiValue, currently tuned for small N).
  • Maps: HashMap<String, V, S> and BTreeMap<String, V> with inline key+value editors, add/remove, optional table layout.
• Tuples
  • Fixed tuples (A, B), (A, B, C), … up to higher arity (up to 8 elements in the current implementation).
  • Global and per-member layout control: line vs grid, columns, dropdown, min width.
  • Per-element overrides via MemberSettings paths like "tuple_field[0]".
• Pointers & math types
  • Box<T> forwards to T: ImGuiReflect.
  • Rc<T> / Arc<T> editable only when unique; otherwise rendered read-only.
  • Optional glam and mint support (Vec2/3/4, mint::Vector2/3/4<f32>) via input_float2/3/4.
• ImSettings-style configuration
  • Global ReflectSettings with helpers:
    • vec(), arrays(), maps(), tuples(), bools().
    • numerics_i32(), numerics_f32(), numerics_u32(), numerics_f64().
  • Per-member overrides via ReflectSettings::for_member::<T>("field_name").
  • Snapshot scope helper: with_settings_scope(|| { ... }).

Field Attributes Cheat Sheet

These attributes are placed on struct fields inside a #[derive(ImGuiReflect)] type:

#[derive(ImGuiReflect)]
struct Example {
    // General
    #[imgui(skip)]
    ignored: i32,

    #[imgui(name = "Custom Label")]
    renamed: i32,

    #[imgui(read_only)]
    read_only_value: i32,

    // Numeric widgets
    #[imgui(as_input, step = 1, step_fast = 10)]
    counter: i32,

    #[imgui(as_drag, speed = 0.1, min = 0.0, max = 10.0, log, always_clamp)]
    drag_value: f32,

    #[imgui(slider, min = 0, max = 100, clamp, no_input)]
    slider_value: i32,

    #[imgui(slider, slider_default_range)]
    slider_half_range: f32,

    #[imgui(as_input, hex)]
    hex_display: i32,

    #[imgui(as_drag, percentage, speed = 0.5)]
    percent_display: f32,

    // Bool styles
    #[imgui(bool_style = "button", true_text = "On", false_text = "Off")]
    power: bool,

    #[imgui(bool_style = "dropdown", true_text = "Enabled", false_text = "Disabled")]
    dropdown_toggle: bool,

    // Text
    #[imgui(hint = "Window title", min_width = 200.0)]
    title: String,

    #[imgui(multiline, lines = 3, auto_resize)]
    description: String,

    #[imgui(display_only)]
    status: String,

    // Tuples
    #[imgui(tuple_render = "grid", tuple_columns = 4, tuple_min_width = 80.0)]
    color: (f32, f32, f32, f32),
}

Containers & Maps

Option, Vec, Arrays

use dear_imgui_reflect::ImGuiReflect;

#[derive(ImGuiReflect, Default)]
struct Containers {
    extra_gain: Option<f32>,
    samples: Vec<i32>,
    offset: [f32; 3],
}

• Option<T>: a checkbox toggles Some(T) / None; when set to Some, a default T::default() is created and edited inline.
• Vec<T>: supports insertion (+), removal (-), and drag-to-reorder handles by default.
• Arrays [T; N] (for supported T) use similar layout, with optional reordering.

You can change the default behavior globally:

use dear_imgui_reflect as reflect;

reflect::with_settings(|s| {
    // All Vec<T> become reorder-only by default
    *s.vec_mut() = reflect::VecSettings::reorder_only();

    // Arrays cannot be reordered
    *s.arrays_mut() = reflect::ArraySettings::fixed_order();
});

Or override on a single member using MemberSettings:

use dear_imgui_reflect as reflect;

#[derive(reflect::ImGuiReflect, Default)]
struct ContainerSettingsDemo {
    full_vec: Vec<i32>,
    reorder_only_vec: Vec<i32>,
    fixed_no_reorder: [i32; 3],
}

fn configure_member_settings() {
    reflect::with_settings(|settings| {
        // Make one vector reorder-only
        settings
            .for_member::<ContainerSettingsDemo>("reorder_only_vec")
            .vec_reorder_only();

        // Disable reordering for a single array
        settings
            .for_member::<ContainerSettingsDemo>("fixed_no_reorder")
            .arrays_fixed_order();
    });
}

String-keyed Maps

dear-imgui-reflect supports:

• HashMap<String, V, S>
• BTreeMap<String, V>

Example:

use dear_imgui_reflect::ImGuiReflect;
use std::collections::{BTreeMap, HashMap};

#[derive(ImGuiReflect, Default)]
struct MapDemo {
    hash: HashMap<String, i32>,
    btree: BTreeMap<String, f32>,
}

Runtime behavior:

• The header shows label [len].
• New entries are added via a + button, opening a popup to edit both key and value before insertion.
• Existing entries can be renamed by editing the key; the underlying map is updated.
• Right-clicking a row shows Remove item (when allowed); right-clicking the header shows Clear all.
• Optional table layout via MapSettings::use_table.

You can create const-maps (no insert/remove) globally or per member:

use dear_imgui_reflect as reflect;

#[derive(reflect::ImGuiReflect, Default)]
struct ConstMapDemo {
    items: std::collections::HashMap<String, i32>,
}

fn configure_maps() {
    reflect::with_settings(|settings| {
        // Treat all maps as const-maps by default
        *settings.maps_mut() = reflect::MapSettings::const_map();

        // Or just one field:
        settings
            .for_member::<ConstMapDemo>("items")
            .maps_const();
    });
}

Tuples & Per-Element Settings

Tuples are rendered as small groups of widgets. You can choose line or grid layout and override per-element behavior using MemberSettings.

use dear_imgui_reflect as reflect;
use reflect::ImGuiReflect;

#[derive(ImGuiReflect, Default)]
struct TupleDemo {
    // Defaults to line layout, labels inferred from field name and index
    pair_int_float: (i32, f32),

    // Grid layout with 3 columns
    #[imgui(tuple_render = "grid", tuple_columns = 3)]
    triple_mixed: (bool, i32, f32),

    // Dropdown + line layout
    #[imgui(tuple_render = "line", tuple_dropdown)]
    quad_tuple: (i32, i32, i32, i32),
}

Per-element numeric overrides use member paths of the form "field_name[index]":

use dear_imgui_reflect as reflect;
use reflect::{NumericRange, NumericTypeSettings, NumericWidgetKind};

#[derive(reflect::ImGuiReflect, Default)]
struct ColorConfig {
    #[imgui(name = "Color", tuple_render = "grid", tuple_columns = 4)]
    color: (f32, f32, f32, f32),
}

fn configure_color_tuple() {
    reflect::with_settings(|settings| {
        // color[0]: slider in [0, 1]
        let slider01 = NumericTypeSettings::default().slider_0_to_1(3);
        settings
            .for_member::<ColorConfig>("color[0]")
            .numerics_f32 = Some(slider01.clone());

        // color[3]: read-only copy of [0, 1] slider
        settings
            .for_member::<ColorConfig>("color[3]")
            .numerics_f32 = Some(slider01);
        settings.for_member::<ColorConfig>("color[3]").read_only = true;
    });
}

The same configuration can be expressed using MemberSettings helpers:

fn configure_color_tuple_with_helpers() {
    reflect::with_settings(|settings| {
        settings
            .for_member::<ColorConfig>("color[0]")
            .numerics_f32_slider_0_to_1(3);

        settings
            .for_member::<ColorConfig>("color[3]")
            .numerics_f32_slider_0_to_1(3)
            .read_only = true;
    });
}

Global tuple defaults live in ReflectSettings::tuples():

use dear_imgui_reflect as reflect;
use reflect::TupleRenderMode;

reflect::with_settings(|s| {
    let tuples = s.tuples_mut();
    tuples.dropdown = false;
    tuples.render_mode = TupleRenderMode::Grid;
    tuples.columns = 4;
    tuples.same_line = true;
    tuples.min_width = Some(80.0);
});

Numeric Presets (Type-level Helpers)

NumericTypeSettings provides small helper methods to quickly configure common slider/drag patterns without writing out all fields:

use dear_imgui_reflect as reflect;
use reflect::NumericTypeSettings;

fn configure_numeric_presets() {
    reflect::with_settings(|s| {
        // f32 defaults: slider in [0, 1] with clamping and "%.3f" format
        *s.numerics_f32_mut() = NumericTypeSettings::default()
            .slider_0_to_1(3);

        // f64 defaults: drag widget with explicit speed and "%.4f" format
        *s.numerics_f64_mut() = NumericTypeSettings::default()
            .drag_with_speed(0.01, 4);

        // Per-member override: f32 tuple element as 0..1 percentage slider
        s.for_member::<ColorConfig>("color[1]").numerics_f32 =
            Some(NumericTypeSettings::default().percentage_slider_0_to_1(2));
    });
}

These presets are thin convenience wrappers over the widget, range, speed, clamp, and format fields and can be mixed with manual configuration when needed.

glam / mint Integration

Enable the glam and/or mint features to get out-of-the-box ImGuiValue implementations for common math types:

[dependencies]
dear-imgui-reflect = { version = "0.8", features = ["glam", "mint"] }
glam = "0.29"
mint = "0.5"

use dear_imgui_reflect as reflect;
use reflect::ImGuiReflect;
use glam::{Vec2, Vec3, Vec4};
use mint::{Vector2, Vector3, Vector4};

#[derive(ImGuiReflect, Default)]
struct Transform {
    position: Vec3,
    scale: Vec3,
    dir: Vector3<f32>,
    uv: Vector2<f32>,
    color: Vector4<f32>,
}

These are rendered using input_float2/3/4 behind the scenes and participate in ImGuiReflect just like other supported field types.

Settings Scope Helper

ReflectSettings is stored globally (inside this crate) and can be modified at runtime. For localized overrides, use with_settings_scope, which snapshots settings, runs a closure, and then restores the previous state:

use dear_imgui_reflect as reflect;
use reflect::{NumericRange, NumericTypeSettings, NumericWidgetKind};

fn draw_debug_panel(ui: &reflect::imgui::Ui, state: &mut DebugState) {
    reflect::with_settings_scope(|| {
        // Temporarily change f32 default to drag slider in [0, 1]
        reflect::with_settings(|s| {
            *s.numerics_f32_mut() =
                NumericTypeSettings::default().slider_0_to_1(3);
        });

        ui.window("Debug").build(|| {
            ui.input_reflect("Debug State", state);
        });
    });
    // At this point, global settings are restored.
}

Example Demo

The repository includes a full demo that exercises most features:

• File: examples/reflect_demo.rs
• Binary: reflect_demo (part of dear-imgui-examples)

Run it with:

cargo run -p dear-imgui-examples --bin reflect_demo --features reflect

ImReflect Compatibility (Overview)

dear-imgui-reflect is designed to closely mirror the behavior of the C++ ImReflect library for the covered Rust types.

A detailed checklist is maintained in docs/dear-imgui-reflect-compat.md. High-level status:

• Matched ([x])
  • Primitive numerics: input/drag/slider selection, as_input / as_drag / slider, min/max, step/step_fast, speed, log/clamp/wrap_around/flags, default half-range sliders.
  • Bool widgets: checkbox/button/radio/dropdown (including text labels).
  • Text: single-line, multiline, hints, read_only, display-only text.
  • Containers: Option<T>, Vec<T>, small fixed arrays, string-keyed maps (HashMap<String, V> / BTreeMap<String, V>), including insertable/removable/reorderable and const-map configurations.
  • Tuples: line/grid layouts, dropdown wrapping, global defaults, per-member overrides, and per-element numeric overrides.
  • Pointers: Box<T>, Rc<T>, Arc<T> with unique/editable vs shared/read-only behavior.
  • Math interop: glam::Vec2/3/4 and mint::Vector2/3/4<f32> when features are enabled.
  • Global and member-level settings: ImSettings-style configuration for numerics, containers, tuples, bools, and read-only semantics.
• Implemented but more general / partially audited ([~])
  • Core architecture: Rust traits + derive macros instead of a fully generic reflected type graph.
  • Settings model: single global ReflectSettings plus with_settings_scope instead of a full push/pop stack of ImSettings.
• Intentionally incomplete or TODO ([ ])
  • Non-string map keys and more exotic STL/container shapes.
  • Additional math types (matrices, quaternions, etc.).
  • Some of ImReflect's richer numeric/text formatting helpers.

When in doubt, refer to docs/dear-imgui-reflect-compat.md for the exact status of each feature and behavioral notes.

Limitations

• Derive macro currently supports:
  • Structs with named fields.
  • C-like enums without payloads.
• Map support is limited to String keys (for HashMap/BTreeMap); other key types need custom ImGuiValue + wrappers.
• Settings use a single global ReflectSettings instance with manual snapshot helpers; there is no full push/pop stack like ImReflect's ImSettings, but common use-cases are covered.
• For very deep or large object graphs, you may want to selectively #[imgui(skip)] certain fields or use custom editors for performance.

License

MIT OR Apache-2.0