Nuklear is a notable example of a single-header immediate-mode GUI library written in C89, designed to be minimal, portable, and embeddable. What stands out is its use of the NK_IMPLEMENTATION macro pattern, which simplifies distribution but demands strict uniformity in macro flags across translation units — any mismatch can cause silent stack corruption. This tradeoff between convenience and fragility is a fascinating case study in C library design.
What Nuklear does and how it works
At its core, Nuklear provides a pure UI logic layer that operates in immediate mode. Unlike traditional retained-mode GUI libraries that keep widget states internally, Nuklear requires the application to rebuild the UI every frame by feeding input states and consuming draw commands. This approach means Nuklear doesn’t manage rendering or windowing — it outputs drawing instructions for the caller to execute with their chosen backend.
The library is implemented entirely in a single header file, about 18,000 lines long, and written in plain C89, which ensures wide compiler compatibility and portability. It has zero dependencies and doesn’t ship with any default render backend or platform window management. Instead, it relies on the embedding application to provide these.
Internally, Nuklear embeds stb libraries for font baking and rectangle packing, which aid in text rendering and layout. Despite its size, Nuklear maintains a very small memory footprint and gives full control over allocations to the host application, which is critical for embedding in constrained environments.
The immediate-mode GUI paradigm Nuklear uses means each frame the UI must be rebuilt from scratch based on the current input state. This eliminates the need to manage complex widget trees or persistent UI state inside the library, making it highly embeddable and straightforward to integrate with existing render loops.
The macro gating pattern: convenience with a sharp edge
Nuklear uses a common single-header C library pattern where the header file holds both declarations and optionally the implementation. To activate the implementation, the NK_IMPLEMENTATION macro must be defined in exactly one translation unit. This pattern lets users include the header everywhere without linker issues.
However, Nuklear’s implementation gating goes further: all macro flags that affect the implementation must be consistently defined before including the header in every translation unit. If even one translation unit differs in these macro definitions, it leads to silent stack corruption bugs that are difficult to diagnose.
This fragility is a direct consequence of how the library manages static data and inlines functions depending on those flags. It’s a tradeoff: the header-only model simplifies distribution and integration but requires developers to be disciplined about macro definitions.
The codebase itself is surprisingly clean for a single-header project of this size. It organizes UI widgets, drawing commands, and input handling systematically. The embedded stb libraries are also well integrated, maintaining minimal external dependencies.
Explore the project
The Nuklear repository centers around the single header file nuklear.h. The README provides a thorough overview of the architecture and usage patterns.
Key files and resources:
nuklear.h: the entire library, with both declarations and implementation toggled byNK_IMPLEMENTATION- Examples directory: contains sample applications demonstrating integration with various rendering backends
- Documentation in the README covers API usage, the immediate-mode paradigm, and macro flag requirements
Since Nuklear doesn’t provide a default renderer or window manager, the examples show how to hook Nuklear’s draw commands to OpenGL, SDL, or other platforms. Studying these examples is the best way to understand how to embed and drive Nuklear in a real application.
Verdict
Nuklear is a solid choice if you want a minimal, portable immediate-mode GUI library in pure C with zero dependencies. Its single-header approach and zero dependency stance make it very attractive for embedding in engines, tools, or games where you want full control over rendering and input.
However, the macro flag consistency requirement is a serious gotcha. If you’re working in a large codebase or with multiple translation units, you must be disciplined about how and where you define NK_IMPLEMENTATION and related macros to avoid subtle, hard-to-debug stack corruption.
Its immediate-mode nature also means you’re responsible for rebuilding UI state each frame, which might not suit applications needing complex retained UI structures or sophisticated widget state management.
Overall, Nuklear shines as a lean, embeddable UI toolkit for developers comfortable with C, immediate-mode paradigms, and careful macro management. It’s worth understanding even if you don’t adopt it directly — the design tradeoffs are instructive for any C library author or user.
→ GitHub Repo: Immediate-Mode-UI/Nuklear ⭐ 11,104 · C