Nuklear: Single-Header Immediate-Mode GUI Toolkit in ANSI C

Immediate-Mode GUI: What the Model Means in Practice

Immediate-mode GUI (IMGUI) is a rendering pattern where the UI is rebuilt from scratch on every frame rather than maintained as a persistent object tree. A retained-mode GUI (like most widget toolkits) holds a hierarchy of widget objects and updates them in response to events. An immediate-mode GUI instead reconstructs the widget layout each frame by calling functions that both describe the widget and return its current interaction state.

Nuklear describes itself as a "minimal-state" toolkit using this model. The caller drives the frame loop: at the start of each frame, input state is mirrored into Nuklear; the layout is declared by calling widget functions; and at the end of the frame, Nuklear produces a list of draw commands describing primitive shapes. The caller then hands those commands to whatever renderer is in use.

This design has a specific trade-off: building the UI on every frame costs CPU time proportional to the number of widgets, even when nothing has changed. For game engines and tools with high frame rates, the cost is negligible. For applications that update rarely (a settings dialog that stays open for minutes), it is wasteful. The README does not describe a mechanism to skip rebuild when inputs are unchanged.

Including Nuklear in a Project

Nuklear is distributed as a single header file: nuklear.h. There is no build system integration to configure and no separate compiled library to link against. Including the library requires one preprocessor definition before the include in exactly one .c or .cpp file:

#define NK_IMPLEMENTATION
#include "nuklear.h"

The README states: "IMPORTANT: Every time you include `nuklear.h` you have to define the same optional flags. This is very important; not doing it either leads to compiler errors, or even worse, stack corruptions."

All other files in the project include nuklear.h without the NK_IMPLEMENTATION define, which includes the declarations only. The actual implementation compiles once from the file that defines NK_IMPLEMENTATION.

The library is written in C89 (ANSI C), which means it compiles with any C compiler from the last several decades. Optional features and modules can be compiled out with preprocessor flags. The README states the library can function without even the standard C library if needed, which reflects a design aimed at embedded and constrained environments.

The Per-Frame Loop: Input, Layout, and Draw Commands

The README gives the general structure of a Nuklear application through its example code. The application initializes the context once at startup by providing font metrics and a fixed memory buffer, then enters the main loop:

nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);

while (running) {
    nk_input_begin(&ctx);
    /* nk_input_motion(&ctx, ...), nk_input_button(&ctx, ...),
     * nk_input_key(&ctx, ...), ... */
    nk_input_end(&ctx);

Between `nk_input_begin` and `nk_input_end`, the caller copies mouse position, button state, and key events from the OS into the Nuklear context. This is the step that requires OS-specific integration: Nuklear does not poll for input itself. After the input block, the caller declares the UI layout for that frame using widget calls, and then Nuklear populates its internal draw command buffer.

The caller extracts those draw commands and hands them to the renderer. The renderer (OpenGL, Vulkan, Direct3D, Metal, or a software rasterizer) translates Nuklear's primitive shapes into actual pixels. Nuklear imposes no constraints on how the drawing happens, which is what allows it to target any platform with any renderer.

Ready-to-Use Backends in the Demo Folder

Nuklear ships complete rendering backends in its demo/ directory. The README lists backends for GLFW with OpenGL 2 and 3, SDL with OpenGL 2 and OpenGL ES 2, SDL3, X11, GDI, GDI+, Direct3D 9, 11, and 12, Vulkan (via GLFW), SFML with OpenGL 2 and 3, and raw framebuffer output. Each has its own subdirectory with a Makefile and build instructions.

Building a demo uses the platform-specific Makefile in the demo subdirectory:

make -C demo/glfw_opengl3

More complete example programs are in the example/ directory. The demo and example programs serve as working reference implementations that show how to initialize a specific backend, feed input from that backend's event system, and pass the resulting draw commands to the renderer. New integrations are typically built by studying the relevant demo backend and adapting it.

The Makefile also generates the packed nuklear.h from source files in src/ using the MACRO and PUB variables, and the DOCS_PATH variable points to the documentation output. The documentation is generated with Doxygen and is also hosted online.

What Nuklear Intentionally Omits

Nuklear has no default render backend. There is no path where the developer includes nuklear.h and gets a working window on screen. Every deployment requires writing or reusing a backend that translates the draw command output to actual rendered pixels. For developers new to immediate-mode GUIs, this is a meaningful first hurdle.

There is no OS window creation, event loop, or input polling. All of that is the caller's responsibility. Nuklear does not know what platform it is running on.

The widget set is functional but limited compared to larger GUI frameworks. The README lists: buttons, toggles, selectable items, sliders, knobs, progress bars, text editors, scrollbars, charts, color pickers, combo boxes, tooltips, context menus, panels, windows, popups, trees, groups, and list views. There is no built-in data grid, no tree view with checkboxes, and no rich text widget.

The library is at v4.13.3, released in May 2026. The last push to the repository was on September 20, 2026. Bug fixes and backend additions continue, but the overall feature scope has been stable rather than expanding.

Dear ImGui as the Primary Alternative and License Terms

Dear ImGui (also called imgui) is the most common alternative in the same immediate-mode GUI space. It is written in C++ rather than ANSI C, which means it requires a C++ compiler and links against the C++ standard library. Dear ImGui has a larger widget set, a more active development pace, and a large ecosystem of contributed extensions. The difference in approach comes down to language and scope: Nuklear targets C environments and minimalist footprints, while Dear ImGui targets C++ environments and provides a wider feature set.

For C projects, game engines without a C++ runtime, or any environment where ANSI C89 compatibility is a hard requirement, Nuklear is the single-header option with no C++ dependency. For C++ projects where the richer widget set and larger ecosystem matter more than the C++ dependency, Dear ImGui is the more common choice.

Nuklear's bindings list in the README covers Java, D, Golang, Rust, Chicken, Nim, two Lua libraries, two Python libraries, C#/.NET, and V. The README notes that the binding quality and maintenance status varies across these.

Nuklear is available under either the MIT license or public domain, as stated in the README. Public domain removes all license obligations. MIT requires retaining the copyright notice but places no other restrictions.

Editorial conclusion

Nuklear suits C and C++ projects that need to embed a GUI toolkit without adding external library dependencies, particularly game engines, emulators, and tools where the developer already controls the render loop. The no-dependency constraint means it works in constrained environments that Dear ImGui cannot target. The per-frame rebuild model is natural for real-time applications but inefficient for UIs that change rarely, so evaluate it against the actual update frequency of the target interface. For projects where C++ is acceptable and a larger widget set is needed, Dear ImGui provides more features. For pure C portability and minimal footprint, Nuklear remains the primary single-header option.

Frequently asked questions

Official sources

1. Immediate-Mode-UI/Nuklear on GitHub
2. Issues
3. Project website
4. README
5. Releases