Clay — High-Performance UI Layout Library in C

Introduction

Clay is a microsecond-performance UI layout engine written as a single C header file. It handles element sizing, positioning, scrolling, and text wrapping using a declarative API inspired by flexbox and CSS Grid. Clay computes layout only—rendering is handled by whatever backend you choose (Raylib, SDL, WebGL, or any custom renderer).

What Clay Does

• Computes responsive layouts in under 10 microseconds for complex UIs
• Provides flexbox-like containers with grow, shrink, padding, and gap controls
• Handles text wrapping and measurement via a pluggable text engine callback
• Supports floating elements, scroll containers, and z-index ordering
• Outputs a flat render command list consumable by any graphics backend

Architecture Overview

Clay operates as a retained-mode layout engine with immediate-mode ergonomics. Each frame, you declare elements using a macro-based DSL. Clay builds an internal element tree, walks it in two passes (measure then place), and outputs a sorted array of render commands. The entire state fits in a single arena allocation with zero heap allocations during layout. No GPU, no OS dependencies—just pure C99 math.

Self-Hosting & Configuration

• Copy clay.h into your project and define CLAY_IMPLEMENTATION in one translation unit
• No build system required—works with GCC, Clang, MSVC, and Emscripten
• Configure maximum element count at initialization via the arena size
• Provide a text measurement callback for your font engine (e.g., Raylib MeasureText)
• Official renderer examples available for Raylib, SDL2, SDL3, and HTML5 Canvas

Key Features

• Entire library is a single ~2000-line header with no external dependencies
• Fully deterministic layout with no floating-point inconsistencies across platforms
• Built-in debug overlay for inspecting element hierarchy and layout boxes
• Pointer interaction system with hover detection and scroll event handling
• Compile to WASM for browser-based UIs with near-native layout speed

Comparison with Similar Tools

• Dear ImGui — immediate-mode with its own rendering; Clay is layout-only and renderer-agnostic
• Yoga (Meta) — flexbox engine in C++; Clay is simpler, single-header C with faster benchmarks
• CSS Flexbox — browser-native; Clay brings similar semantics to native and embedded apps
• Nuklear — single-header GUI with rendering; Clay separates layout from rendering
• egui — Rust immediate-mode GUI; Clay is C-native with explicit layout control

FAQ

Q: Does Clay handle rendering? A: No. Clay computes layout and outputs render commands (rectangles, text, images). You feed these to your renderer of choice.

Q: Can I use Clay from languages other than C? A: Yes. Community bindings exist for Rust, Go, Zig, Odin, Python, and C#. The C API is simple enough to bind via FFI.

Q: How does Clay handle responsive design? A: Elements support percentage-based sizing, grow/shrink factors, and min/max constraints. Re-running layout with different root dimensions produces a responsive result.

Q: What is the memory footprint? A: Clay uses a single pre-allocated arena. A typical UI with hundreds of elements needs under 1 MB. There are zero runtime allocations.

Sources

• https://github.com/nicbarker/clay
• https://www.nicbarker.com/clay