dear-imgui-rs

dear-imgui-rs is a Rust bindings ecosystem for Dear ImGui, featuring docking support, WGPU/GL/Vulkan backends, and a rich set of extensions (ImPlot/ImPlot3D, ImGuizmo/ImGuIZMO.quat, ImNodes, imgui-node-editor, ImGui Test Engine, file browser, reflection-based UI).

What’s in this repo

• Core
  • dear-imgui-sys — low-level FFI via cimgui (docking branch), with pregenerated bindings for Dear ImGui v1.92.8
  • dear-imgui-rs — safe, idiomatic Rust API (RAII + builder style similar to imgui-rs)
  • Backends: dear-imgui-wgpu, dear-imgui-glow, dear-imgui-ash, dear-imgui-winit, dear-imgui-sdl3, dear-imgui-bevy
    • dear-imgui-bevy is an experimental Bevy-native backend on Bevy 0.19.0-rc.2, with docking, texture interop, and native multi-viewport on supported targets.
  • dear-app — convenient Winit + WGPU application runner (docking, themes, add-ons)
• Extensions
  • dear-imguizmo — 3D gizmo (cimguizmo C API) + a pure‑Rust GraphEditor
  • dear-imnodes — node editor (cimnodes C API)
  • dear-node-editor — richer native node editor (cimnodes_editor / imgui-node-editor)
  • dear-implot — plotting (cimplot C API)
  • dear-implot3d — 3D plotting (cimplot3d C API)
  • dear-imguizmo-quat — quaternion + 3D gizmo (cimguizmo_quat C API)
  • dear-imgui-test-engine — Dear ImGui UI automation/test runner integration
  • dear-file-browser — native dialogs (rfd) + pure ImGui in-UI file browser
  • dear-imgui-reflect — reflection-based UI helpers (auto-generate ImGui widgets from Rust types)

All crates are maintained together in this workspace.

Hello, ImGui (Hello World)

use dear_imgui_rs::*;

let mut ctx = Context::create();
// If you are not using a platform backend (e.g. dear-imgui-winit / dear-imgui-sdl3),
// you must set `io.DisplaySize` before calling `Context::frame()`.
ctx.io_mut().set_display_size([300.0, 120.0]);
ctx.io_mut().set_delta_time(1.0 / 60.0);

let ui = ctx.frame();
ui.window("Hello")
  .size([300.0, 120.0], Condition::FirstUseEver)
  .build(|| {
      ui.text("Hello, world!");
      if ui.button("Click me") { println!("clicked"); }
  });
let _draw_data = ctx.render();
// Rendering is done by a backend (e.g. dear-imgui-wgpu or dear-imgui-glow)
// Tip: pass `.opened(&mut open)` if you want a title-bar close button (X).

// Tip: For fallible creation, use `Context::try_create()`

Migration Notes

The README focuses on current supported usage. For source-breaking migrations between releases, read CHANGELOG.md; for release-train, dependency, MSRV, and backend compatibility baselines, see docs/COMPATIBILITY.md.

The safe API intentionally encodes Dear ImGui FFI invariants in Rust types. Source breaks are accepted when the previous safe wrapper shape could preserve stale handles, unchecked sizes, invalid sentinels, wrong-context access, or other states that should remain outside safe Rust.

Examples

# Clone with submodules

git clone https://github.com/Latias94/dear-imgui-rs

git submodule update --init --recursive


# Core & docking examples

cargo run --bin game_engine_docking

cargo run --bin dockspace_minimal


# dear-app examples (application runner with docking support)

cargo run --bin dear_app_quickstart

cargo run --bin dear_app_docking


# Extension examples (using wgpu + winit directly)

cargo run --bin imguizmo_basic --features imguizmo

cargo run --bin imnodes_basic --features imnodes

# imgui-node-editor: basic interaction and blueprints-style showcase

cargo run -p dear-imgui-examples --bin node_editor_basic --features node-editor

cargo run -p dear-imgui-examples --bin node_editor_showcase --features node-editor

cargo run --bin implot_basic --features implot

cargo run --bin imguizmo_quat_basic --features imguizmo-quat

cargo run --bin reflect_demo --features reflect

cargo run --bin imgui_test_engine_basic --features test-engine

  # Smoke test (auto-run + exit)

  cargo run --bin imgui_test_engine_basic --features test-engine -- --exit-when-done --group tests


# implot3d example (uses dear-app)

cargo run --bin implot3d_basic --features implot3d


# Vulkan (Ash) renderer examples (native)

cargo run --bin ash_basic

cargo run --bin ash_textures

# Multi-viewport (winit + Vulkan/Ash, native only)

cargo run -p dear-imgui-examples --bin multi_viewport_ash --features multi-viewport

# SDL3 + Vulkan/Ash multi-viewport (native only)

cargo run -p dear-imgui-examples --bin sdl3_ash_multi_viewport --features sdl3-ash-multi-viewport


# WebAssembly (WASM) web demo (import-style, ImGui + optional ImPlot/ImPlot3D/ImNodes/ImGuizmo/ImGuIZMO.quat)

# Note: this import-style WASM path is developed on `main` and shipped in the 0.7.x+ release trains.

# For the full setup (bindings generation, web demo build, provider build, and troubleshooting),

# see the "WebAssembly (WASM) support" section below and docs/WASM.md.


# SDL3 backends (native)

# SDL3 + OpenGL3 with official C++ backends (multi-viewport via imgui_impl_sdl3/imgui_impl_opengl3)

cargo run -p dear-imgui-examples --bin sdl3_opengl_multi_viewport --features multi-viewport,sdl3-opengl3

# SDL3 + Glow (experimental multi-viewport using Rust Glow renderer)

cargo run -p dear-imgui-examples --bin sdl3_glow_multi_viewport --features multi-viewport,sdl3-platform

# SDL3 + WGPU (single-window)

cargo run -p dear-imgui-examples --bin sdl3_wgpu --features sdl3-platform

# SDL3 + WGPU (experimental multi-viewport, native only)

cargo run -p dear-imgui-examples --bin sdl3_wgpu_multi_viewport --features sdl3-wgpu-multi-viewport


# winit + WGPU (experimental multi-viewport testbed, native only)

# Enabled on Windows/macOS/Linux; tested on Windows/macOS, Linux untested.

cargo run -p dear-imgui-examples --bin multi_viewport_wgpu --features multi-viewport

Tip: The ImNodes example includes multiple tabs (Hello, Multi-Editor, Style, Advanced Style, Save/Load, Color Editor, Shader Graph, MiniMap Callback).

See examples/README.md for a curated index and the planned from‑easy‑to‑advanced layout.

File Browser

# OS-native dialogs (rfd)

cargo run --bin file_dialog_native --features file-browser


# Pure ImGui in-UI file browser

cargo run --bin file_browser_imgui --features file-browser

Installation

Core + Backends

[dependencies]

dear-imgui-rs = "0.14.0"

# Choose a backend + platform integration

dear-imgui-wgpu = "0.14.0"   # or dear-imgui-glow / dear-imgui-ash

dear-imgui-winit = "0.14.0"  # or dear-imgui-sdl3

dear-imgui-wgpu defaults to wgpu-29 on the current main branch.

If you need wgpu = 28 compatibility for the WGPU renderer backend:

[dependencies]

dear-imgui-rs = "0.14.0"

dear-imgui-wgpu = { version = "0.14.0", default-features = false, features = ["wgpu-28"] }

dear-imgui-winit = "0.14.0"

If you need wgpu = 27 compatibility for the WGPU renderer backend:

[dependencies]

dear-imgui-rs = "0.14.0"

dear-imgui-wgpu = { version = "0.14.0", default-features = false, features = ["wgpu-27"] }

dear-imgui-winit = "0.14.0"

Application Runner (Recommended for Quick Start)

[dependencies]

dear-app = "0.14.0"  # Includes dear-imgui-rs, wgpu backend, and docking support

Apple Platform Examples

For Apple/mobile integration, use the repository-owned iOS smoke examples as reference integrations:

• examples-ios/dear-imgui-ios-smoke
  • dear-imgui-winit + dear-imgui-wgpu
• examples-ios/dear-imgui-ios-sdl3-smoke
  • dear-imgui-sdl3 + dear-imgui-wgpu

These examples exist to validate and teach the integration boundary. They are not a turn-key mobile runtime layer.

For Apple-specific integration notes and example boundaries, see docs/workstreams/apple-platform-support.md. For the checked-in iOS smoke templates and a quick route-selection index, see examples-ios/README.md.

Low-level Backend Shim And Android

Most users should stay on the safe backends (dear-imgui-winit, dear-imgui-sdl3, dear-imgui-wgpu, dear-imgui-glow, dear-imgui-ash).

For engine integrations or platform stacks that are not wrapped by a dedicated crate yet, dear-imgui-sys can expose selected official backend pieces behind backend-shim-* feature gates. These are repository-owned C shim entry points, not direct promises about the upstream imgui_impl_* C++ ABI.

Example: low-level Android route without a dedicated Android convenience crate:

[dependencies]

dear-imgui-rs = "0.14.0"

dear-imgui-sys = { version = "0.14.0", features = ["backend-shim-android", "backend-shim-opengl3"] }

Recommended ownership split:

• dear-imgui-rs owns the safe core Context, Io, frame lifecycle, and draw data handling.
• dear-imgui-sys::backend_shim::{android, opengl3} exposes the low-level official backend pieces.
• The application still owns Android lifecycle glue, EGL / GLES context creation, packaging, and signing.

The repository includes a concrete template for this path at examples-android/dear-imgui-android-smoke/. It is intentionally kept outside the default workspace build so we can document and validate the Android route without expanding the normal desktop/web CI matrix, and it is not intended to be a separately published runtime crate. For the current Android smoke-template overview, see examples-android/README.md.

If your application already uses SDL3, prefer dear-imgui-sdl3 as the higher level Android integration direction. Even there, the application still owns SDL3 Android packaging, NDK toolchain configuration, and final APK / app-bundle assembly.

Extensions

[dependencies]

# Plotting

dear-implot = "0.14.0"      # 2D plotting

dear-implot3d = "0.14.0"    # 3D plotting



# 3D Gizmos

dear-imguizmo = "0.14.0"         # Standard 3D gizmo + GraphEditor

dear-imguizmo-quat = "0.14.0"    # Quaternion-based gizmo



# Node Editor

dear-imnodes = "0.14.0"

dear-node-editor = "0.14.0"  # native-only imgui-node-editor integration



# Test automation

dear-imgui-test-engine = "0.14.0"



# File Browser

dear-file-browser = "0.14.0"  # Native dialogs + ImGui file browser



# Reflection-based UI helpers

dear-imgui-reflect = "0.14.0"

Reflection-based UI (dear-imgui-reflect)

dear-imgui-reflect lets you derive ImGuiReflect on your structs/enums and automatically get Dear ImGui editors for them. It is inspired by the C++ ImReflect library but implemented in pure Rust on top of dear-imgui-rs.

Typical flow:

use dear_imgui_reflect as reflect;
use reflect::ImGuiReflect;
use reflect::ImGuiReflectExt;

#[derive(ImGuiReflect, Default)]
struct Settings {
    #[imgui(slider, min = 0, max = 100)]
    volume: i32,
    fullscreen: bool,
}

fn ui_frame(ui: &reflect::imgui::Ui, settings: &mut Settings) {
    ui.input_reflect("Settings", settings);
}

Build Strategy

• Default: build from source on all platforms. Prebuilt binaries are optional and off by default.
• Windows: we publish prebuilt packages (MD/MT, with/without freetype). Linux/macOS may have CI artifacts but are not used automatically.
• Opt-in prebuilt download from Release: enable the crate feature prebuilt (the env toggle <CRATE>_SYS_USE_PREBUILT=1 is still accepted but requires that feature). Otherwise builds only use prebuilt when you explicitly point to them (e.g., <CRATE>_SYS_LIB_DIR or <CRATE>_SYS_PREBUILT_URL).

Test engine hooks (important):

• Enabling dear-imgui-sys/test-engine defines IMGUI_ENABLE_TEST_ENGINE and makes the ImGui objects reference hook symbols (e.g. ImGuiTestEngineHook_*).
  • When enabled, dear-imgui-sys also provides the hook symbols, so workspace feature-unification won't cause linker errors.
  • To actually run UI automation/tests, link dear-imgui-test-engine (or dear-imgui-test-engine-sys), which registers the real hook implementations at runtime.

Env vars per -sys crate:

• <CRATE>_SYS_LIB_DIR — link from a dir containing the static lib
• <CRATE>_SYS_PREBUILT_URL — explicit URL or local path to .a/.lib or .tar.gz (HTTP(S) and .tar.gz extraction require feature prebuilt)
• <CRATE>_SYS_USE_PREBUILT=1 — allow auto download from GitHub Releases (requires feature prebuilt)
• <CRATE>_SYS_PACKAGE_DIR — local dir with .tar.gz packages
• <CRATE>_SYS_CACHE_DIR — cache root for downloads/extraction
• <CRATE>_SYS_SKIP_CC — skip C/C++ compilation
• <CRATE>_SYS_FORCE_BUILD — force source build
• IMPLOT_SYS_USE_CMAKE — prefer CMake for dear-implot-sys when available; otherwise cc
• IMGUI_SYS_USE_CMAKE — accepted for compatibility, but dear-imgui-sys currently warns and uses the cc source build because the native stack-layout ABI patches the imgui.cpp build copy
• CARGO_NET_OFFLINE=true — forbid network; use only local packages or repo prebuilt

Freetype: enable once anywhere. Turning on freetype in any extension (imnodes/node-editor/imguizmo/implot) propagates to dear-imgui-sys. When using a prebuilt dear-imgui-sys with freetype, ensure the package manifest includes features=freetype (our packager writes this). dear-imgui-sys prebuilts are also required to declare features=stack-layout, because the default native build includes the stack layout ABI used by the node-editor blueprints example.

Quick examples (enable auto prebuilt download):

• Feature: cargo build -p dear-imgui-sys --features prebuilt
• Env (Unix): IMGUI_SYS_USE_PREBUILT=1 cargo build -p dear-imgui-sys --features prebuilt
• Env (Windows PowerShell): $env:IMGUI_SYS_USE_PREBUILT='1'; cargo build -p dear-imgui-sys --features prebuilt

Compatibility (Latest)

The workspace follows a release-train model. The table below lists the latest, recommended combinations. See docs/COMPATIBILITY.md for version history and compatibility policy.

Core

Backends

Application Runner

Extensions

Note: if your ecosystem is pinned to wgpu = 28 or wgpu = 27, you can use dear-imgui-wgpu 0.14.0 with default-features = false, features = ["wgpu-28"] or default-features = false, features = ["wgpu-27"]. dear-app follows the workspace default wgpu = 29 path.

Maintenance rules

• Upgrade dear-imgui-sys together with all -sys extensions to avoid C ABI/API drift.
• dear-imgui-rs upgrades may require minor changes in backends/extensions if public APIs changed.
• Backend external deps (wgpu/winit/glow) have their own breaking cycles and may drive backend bumps independently.

CI (Prebuilt Binaries)

• Workflow: .github/workflows/prebuilt-binaries.yml
  • Inputs:
    • tag (release) or branch (manual; default main)
    • crates: comma-separated list (all, dear-imgui-sys, dear-implot-sys, dear-imnodes-sys, dear-node-editor-sys, dear-imguizmo-sys)
  • Artifacts (branch builds) or Release assets (tag builds) include .tar.gz packages named: dear-<name>-prebuilt-<version>-<target>-static[-mt|-md].tar.gz
  • Release download URLs default to owner/repo configured in tools/build-support/src/lib.rs. Override via env: BUILD_SUPPORT_GH_OWNER, BUILD_SUPPORT_GH_REPO.

Version & FFI

• FFI layer is generated from the cimgui docking_inter branch matching Dear ImGui v1.92.8.
• We avoid the C++ ABI by using C APIs plus checked-in bindgen output. The safe layer mirrors imgui-rs style (RAII + builder).

Crates (workspace)

dear-imgui-rs/         # Safe Rust bindings (renamed from dear-imgui)
dear-imgui-sys/        # cimgui FFI (docking; ImGui v1.92.8)
backends/
  dear-imgui-wgpu/     # WGPU renderer
  dear-imgui-glow/     # OpenGL renderer
  dear-imgui-winit/    # Winit platform
dear-app/              # Application runner (Winit + WGPU + docking + themes)
extensions/
  dear-imguizmo/       # ImGuizmo + pure‑Rust GraphEditor
  dear-imnodes/        # ImNodes (node editor)
  dear-node-editor/    # imgui-node-editor (native-only node editor)
  dear-implot/         # ImPlot (2D plotting)
  dear-implot3d/       # ImPlot3D (3D plotting)
  dear-imguizmo-quat/  # ImGuIZMO.quat (quaternion gizmo)
  dear-imgui-test-engine/ # ImGui Test Engine integration
  dear-file-browser/   # File dialogs (rfd) + pure ImGui browser
  dear-imgui-reflect/  # Reflection-based UI helpers for dear-imgui-rs

WebAssembly (WASM) support

This workspace includes an import-style WASM build that reuses a separate cimgui provider module (imgui-sys-v0) and shares a single WebAssembly.Memory between the Rust app (wasm-bindgen) and the provider.

Status:

• The web demo (dear-imgui-web-demo) is wired up and runs on wasm32-unknown-unknown.
• The core UI + WGPU backend are supported; clipboard, raw draw callbacks and multi-viewport remain disabled on wasm for safety.
• Font atlas access on wasm is available behind an experimental feature flag.
• Import-style WASM bindings and the xtask wasm-bindgen-* / web-demo / build-cimgui-provider helpers are developed on main and shipped in the 0.7.x release train; for 0.6.x on crates.io, use a git dependency on this repository if you need these flows.

Prerequisites:

• Rust target:
  • rustup target add wasm32-unknown-unknown
• wasm-bindgen CLI (version must match the crate’s dependency):
  • cargo install -f wasm-bindgen-cli --version 0.2.105
• wasm-tools (used by xtask web-demo to patch memory imports/exports):
  • cargo install -f wasm-tools
• Emscripten SDK (emsdk) for building the cimgui provider:
  • Install emsdk and run its env script (emsdk_env.*) or set EMSDK so that emcc/em++ are on PATH.

Quick start (web demo):

# 1) Generate wasm bindings for dear-imgui-sys (optional; xtask will also

#    generate them on-demand if missing, using import module name imgui-sys-v0)

cargo run -p xtask -- wasm-bindgen imgui-sys-v0


# 2) Build the main wasm module + JS glue (optionally enable experimental fonts)

cargo run -p xtask -- web-demo --features experimental-fonts


# 3) Build the cimgui provider (emscripten) and import map

cargo run -p xtask -- build-cimgui-provider


# 4) Serve and open in the browser

python -m http.server -d target/web-demo 8080

# Then open http://127.0.0.1:8080

Notes:

• The provider build emits:
  • target/web-demo/imgui-sys-v0.wasm and imgui-sys-v0.js
  • imgui-sys-v0-wrapper.js (ESM wrapper) and an import map entry mapping "imgui-sys-v0" to "./imgui-sys-v0-wrapper.js".
• xtask web-demo:
  • Patches the wasm-bindgen output to import memory from env.memory and export it.
  • Patches the JS glue to pass globalThis.__imgui_shared_memory to env.memory.
• Font atlas mutation on wasm is guarded by the feature:
  • dear-imgui-rs/wasm-font-atlas-experimental
  • examples-wasm/experimental-fonts turns this on for the web demo only.

For more details and troubleshooting, see docs/WASM.md.

Limitations

• Multi-viewport support
  • SDL3 + OpenGL3: supported via upstream C++ backends (imgui_impl_sdl3 + imgui_impl_opengl3).
    • Example: cargo run -p dear-imgui-examples --bin sdl3_opengl_multi_viewport --features multi-viewport,sdl3-opengl3
  • winit + WGPU: experimental only; not supported for production use (feature dear-imgui-wgpu/multi-viewport-winit).
    • Native only, enabled on Windows/macOS/Linux. Linux is currently untested.
      • To use in your own app, enable:
        • dear-imgui-rs/multi-viewport
        • dear-imgui-winit/multi-viewport
        • dear-imgui-wgpu/multi-viewport-winit and call Context::enable_multi_viewport().
      • Test example: cargo run -p dear-imgui-examples --bin multi_viewport_wgpu --features multi-viewport
      • Editor-style docking example also supports this mode: cargo run -p dear-imgui-examples --bin game_engine_docking --features multi-viewport
  • winit + OpenGL (glow/glutin): no official multi-viewport stack at the moment. Use SDL3 + OpenGL3 / SDL3 + Glow if you need multi-viewport OpenGL.
  • SDL3 + WGPU: experimental multi-viewport on native via Rust WGPU renderer + SDL3 platform backend; wasm/WebGPU remains single-window.
    • Example (native multi-viewport): cargo run -p dear-imgui-examples --bin sdl3_wgpu_multi_viewport --features sdl3-wgpu-multi-viewport
    • Example (single window): cargo run -p dear-imgui-examples --bin sdl3_wgpu --features sdl3-platform
• WebAssembly (WASM): Supported via the import-style build described above; some features (clipboard, raw draw callbacks, multi-viewport) remain disabled on wasm.
• dear-node-editor: First integration phase is native-only. Use dear-imnodes for the current wasm node-editor path.

Related Projects

If you're working with graphics applications in Rust, you might also be interested in:

• asset-importer - A comprehensive Rust binding for the latest Assimp 3D asset import library, providing robust 3D model loading capabilities for graphics applications
• boxdd - Safe, ergonomic Rust bindings for Box2D v3.

Acknowledgments

This project builds upon the excellent work of several other projects:

• Dear ImGui by Omar Cornut - The original C++ immediate mode GUI library
• cimgui - The C API layer used by the core Dear ImGui sys crate
• imgui-rs - Provided the API design patterns and inspiration for the Rust binding approach
• easy-imgui-rs by rodrigorc
• imgui-wgpu-rs - Provided reference implementation for WGPU backend integration
• imgui-node-editor by Michał Cichoń - Native node editor implementation and blueprint-style example references
• cimnodes_editor - C wrapper used for the dear-node-editor-sys binding layer

License

Dual-licensed under either of:

• Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (http://opensource.org/licenses/MIT)

Vendored third-party native projects keep their own licenses. In particular, imgui-node-editor is MIT-licensed, and the stack layout compatibility shim in dear-imgui-sys is derived from its MIT-licensed vendored stack layout extension. See the relevant *-sys README files and dear-imgui-sys/THIRD_PARTY_NOTICES.md for details.