Clay Module
GX includes a Clay module for immediate-mode UI layout. Clay is a high-performance declarative layout engine written in C (~4800 lines, MIT license). It computes element positions and sizes, then outputs an array of render commands that you draw with any renderer (raylib, OpenGL, Sokol, etc.).
Clay does not draw anything — it only computes layout. You iterate the render commands and draw rectangles, text, borders, and images yourself.
Prerequisites
The module ships with Clay bundled — no external dependencies needed.
The C source is compiled automatically via @cfile.
Usage
import clay
Build with -I modules:
gx myapp.gx -I modules -o myapp.exe
Quick Example — Raylib UI Panel
import clay
import raylib.core
import raylib.input
import raylib.shapes
import raylib.text
import raylib.colors
fn main() {
InitWindow(800, 600, "GX + Clay + Raylib")
SetTargetFPS(60)
var ctx = clay.gx_clay_init(800.0, 600.0)
clay.gx_clay_use_default_measure()
while (!WindowShouldClose()) {
var dt = GetFrameTime()
var mouse = GetMousePosition()
clay.gx_clay_set_pointer(mouse.x, mouse.y, IsMouseButtonDown(0))
clay.gx_clay_update_scroll(true, 0.0, GetMouseWheelMove() * 30.0, dt)
// Declare layout
clay.gx_clay_begin_layout()
clay.gx_clay_open_id("root")
clay.gx_clay_config_full(
clay.COLUMN,
clay.SIZING_GROW, 0.0, 0.0,
clay.SIZING_GROW, 0.0, 0.0,
16, 16, 16, 16, 12,
clay.ALIGN_LEFT, clay.ALIGN_TOP,
30.0, 30.0, 30.0, 255.0,
0.0, 0.0, 0.0, 0.0
)
clay.gx_clay_text("Hello from Clay!", 255.0, 255.0, 255.0, 255.0, 0, 24)
clay.gx_clay_open_id("button")
clay.gx_clay_config_rect(80.0, 60.0, 200.0, 255.0, 6.0)
clay.gx_clay_text("Click Me", 255.0, 255.0, 255.0, 255.0, 0, 18)
clay.gx_clay_close()
clay.gx_clay_close()
// Get render commands
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)
// Draw with raylib
BeginDrawing()
ClearBackground(BLACK)
for (i = 0 : count - 1) {
var cmd = clay.gx_clay_get_command(cmds, i)
var t = clay.gx_clay_cmd_type(cmd)
if (t == clay.CMD_RECTANGLE) {
DrawRectangle(
clay.gx_clay_cmd_x(cmd), clay.gx_clay_cmd_y(cmd),
clay.gx_clay_cmd_w(cmd), clay.gx_clay_cmd_h(cmd),
Color{(u8)clay.gx_clay_cmd_rect_r(cmd), (u8)clay.gx_clay_cmd_rect_g(cmd), (u8)clay.gx_clay_cmd_rect_b(cmd), (u8)clay.gx_clay_cmd_rect_a(cmd)}
)
}
if (t == clay.CMD_TEXT) {
DrawText(
clay.gx_clay_cmd_text_chars(cmd),
clay.gx_clay_cmd_x(cmd), clay.gx_clay_cmd_y(cmd),
clay.gx_clay_cmd_text_font_size(cmd),
Color{(u8)clay.gx_clay_cmd_text_r(cmd), (u8)clay.gx_clay_cmd_text_g(cmd), (u8)clay.gx_clay_cmd_text_b(cmd), (u8)clay.gx_clay_cmd_text_a(cmd)}
)
}
}
EndDrawing()
}
CloseWindow()
}
How It Works
Clay uses an open/configure/close pattern that replaces the C macro CLAY() { }:
// C (with macros):
// CLAY(CLAY_ID("panel"), { .backgroundColor = {60,60,60,255} }) { children }
// GX (explicit calls):
clay.gx_clay_open_id("panel")
clay.gx_clay_config_bg(60.0, 60.0, 60.0, 255.0)
// ... children here ...
clay.gx_clay_close()
Each frame:
gx_clay_begin_layout()— start declaring UI- Open elements, configure them, add children, close them
gx_clay_end_layout(dt, &count)— Clay computes positions/sizes- Iterate render commands and draw with your renderer
Initialization
| Function | Signature | Description |
|---|---|---|
gx_clay_init | (f32, f32) → *void | Initialize Clay with layout width/height |
gx_clay_set_dimensions | (f32, f32) | Update dimensions on resize |
gx_clay_set_pointer | (f32, f32, bool) | Set mouse position and button state |
gx_clay_update_scroll | (bool, f32, f32, f32) | Update scroll containers |
gx_clay_use_default_measure | () | Use built-in text measurement |
gx_clay_set_measure_text | (*void) | Set custom text measure function |
var ctx = clay.gx_clay_init(800.0, 600.0)
clay.gx_clay_use_default_measure()
On window resize:
clay.gx_clay_set_dimensions(new_width, new_height)
Layout Frame
| Function | Signature | Description |
|---|---|---|
gx_clay_begin_layout | () | Begin declaring UI elements |
gx_clay_end_layout | (f32, *i32) → *void | End layout, get render commands |
gx_clay_get_command | (*void, i32) → *void | Get command by index |
clay.gx_clay_begin_layout()
// ... declare elements ...
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)
for (i = 0 : count - 1) {
var cmd = clay.gx_clay_get_command(cmds, i)
// draw it
}
Element Building
Opening & Closing
| Function | Signature | Description |
|---|---|---|
gx_clay_open | () | Open element (auto ID) |
gx_clay_open_id | (cstr) | Open element with string ID |
gx_clay_open_idi | (cstr, u32) | Open with ID + index (for loops) |
gx_clay_close | () | Close current element |
// Simple container
clay.gx_clay_open_id("panel")
clay.gx_clay_config_bg(40.0, 40.0, 40.0, 255.0)
// children
clay.gx_clay_close()
// Loop with indexed IDs
for (i = 0 : item_count - 1) {
clay.gx_clay_open_idi("item", i)
clay.gx_clay_config_rect(60.0, 60.0, 60.0, 255.0, 4.0)
clay.gx_clay_text("Item", 255.0, 255.0, 255.0, 255.0, 0, 16)
clay.gx_clay_close()
}
Text Elements
| Function | Signature | Description |
|---|---|---|
gx_clay_text | (cstr, f32, f32, f32, f32, u16, u16) | Text with color, font ID, size |
gx_clay_text_ex | (cstr, r, g, b, a, font, size, spacing, lineH, wrap, align) | Full text config |
// Simple text
clay.gx_clay_text("Score: 9500", 255.0, 255.0, 0.0, 255.0, 0, 20)
// Centered, wrapped text
clay.gx_clay_text_ex("Long description...",
200.0, 200.0, 200.0, 255.0,
0, 14,
0, 0,
clay.WRAP_WORDS, clay.TEXT_CENTER
)
Element Configuration
After opening an element, call one config function to set its properties.
Quick Configs
| Function | Signature | Description |
|---|---|---|
gx_clay_config_bg | (r, g, b, a) | Background color only |
gx_clay_config_rect | (r, g, b, a, radius) | Color + rounded corners |
gx_clay_config_row | (gap, pad_x, pad_y) | Horizontal layout |
gx_clay_config_col | (gap, pad_x, pad_y) | Vertical layout |
gx_clay_config_grow | () | Grow to fill both axes |
// Colored box with rounded corners
clay.gx_clay_open_id("card")
clay.gx_clay_config_rect(50.0, 50.0, 50.0, 255.0, 8.0)
// children
clay.gx_clay_close()
// Vertical list with 4px gap, 8px padding
clay.gx_clay_open_id("list")
clay.gx_clay_config_col(4, 8, 8)
// children
clay.gx_clay_close()
Full Configuration
For complete control, use gx_clay_config_full:
extern fn gx_clay_config_full(
direction: u8, // ROW or COLUMN
w_type: u8, // SIZING_FIT/GROW/PERCENT/FIXED
w_min: f32, // width min (or percent value, or fixed size)
w_max: f32, // width max
h_type: u8, // SIZING_FIT/GROW/PERCENT/FIXED
h_min: f32, // height min
h_max: f32, // height max
pad_left: u16, // padding left
pad_right: u16, // padding right
pad_top: u16, // padding top
pad_bottom: u16, // padding bottom
child_gap: u16, // gap between children
align_x: u8, // ALIGN_LEFT/RIGHT/CENTER
align_y: u8, // ALIGN_TOP/BOTTOM/CENTER
bg_r: f32, // background color RGBA
bg_g: f32,
bg_b: f32,
bg_a: f32,
corner_tl: f32, // corner radius (per corner)
corner_tr: f32,
corner_bl: f32,
corner_br: f32
)
Example — centered column, 50% width, grow height:
clay.gx_clay_open_id("centered")
clay.gx_clay_config_full(
clay.COLUMN,
clay.SIZING_PERCENT, 0.5, 0.0,
clay.SIZING_GROW, 0.0, 0.0,
16, 16, 16, 16, 8,
clay.ALIGN_CENTER, clay.ALIGN_TOP,
45.0, 45.0, 50.0, 255.0,
10.0, 10.0, 10.0, 10.0
)
Special Configs
| Function | Signature | Description |
|---|---|---|
gx_clay_config_border | (r, g, b, a, left, right, top, bottom, between) | Border |
gx_clay_config_scroll | (horizontal, vertical) | Scrollable container |
gx_clay_config_floating | (off_x, off_y, z_index) | Floating overlay |
gx_clay_config_image | (*void, w, h) | Image element |
Render Command Access
Each render command has a bounding box and type-specific data.
Command Properties
| Function | Returns | Description |
|---|---|---|
gx_clay_cmd_x/y/w/h | f32 | Bounding box position and size |
gx_clay_cmd_type | u8 | Command type constant |
gx_clay_cmd_id | u32 | Element ID |
Command Types
| Constant | Value | Description |
|---|---|---|
CMD_RECTANGLE | 1 | Draw filled rectangle |
CMD_BORDER | 2 | Draw border |
CMD_TEXT | 3 | Draw text |
CMD_IMAGE | 4 | Draw image |
CMD_SCISSOR_START | 5 | Begin clipping region |
CMD_SCISSOR_END | 6 | End clipping region |
CMD_CUSTOM | 9 | Custom render command |
Rectangle Data
| Function | Returns | Description |
|---|---|---|
gx_clay_cmd_rect_r/g/b/a | f32 | Background color (0-255) |
gx_clay_cmd_rect_corner_tl/tr/bl/br | f32 | Corner radius per corner |
Text Data
| Function | Returns | Description |
|---|---|---|
gx_clay_cmd_text_chars | cstr | Text string |
gx_clay_cmd_text_len | i32 | String length |
gx_clay_cmd_text_r/g/b/a | f32 | Text color |
gx_clay_cmd_text_font_id | u16 | Font ID |
gx_clay_cmd_text_font_size | u16 | Font size |
Border Data
| Function | Returns | Description |
|---|---|---|
gx_clay_cmd_border_r/g/b/a | f32 | Border color |
gx_clay_cmd_border_left/right/top/bottom | u16 | Border width per side |
Rendering with Raylib
for (i = 0 : count - 1) {
var cmd = clay.gx_clay_get_command(cmds, i)
var t = clay.gx_clay_cmd_type(cmd)
var x = clay.gx_clay_cmd_x(cmd)
var y = clay.gx_clay_cmd_y(cmd)
var w = clay.gx_clay_cmd_w(cmd)
var h = clay.gx_clay_cmd_h(cmd)
if (t == clay.CMD_RECTANGLE) {
DrawRectangle(x, y, w, h, Color{(u8)clay.gx_clay_cmd_rect_r(cmd), (u8)clay.gx_clay_cmd_rect_g(cmd), (u8)clay.gx_clay_cmd_rect_b(cmd), (u8)clay.gx_clay_cmd_rect_a(cmd)})
}
if (t == clay.CMD_TEXT) {
DrawText(clay.gx_clay_cmd_text_chars(cmd), x, y,
clay.gx_clay_cmd_text_font_size(cmd),
Color{(u8)clay.gx_clay_cmd_text_r(cmd), (u8)clay.gx_clay_cmd_text_g(cmd), (u8)clay.gx_clay_cmd_text_b(cmd), (u8)clay.gx_clay_cmd_text_a(cmd)})
}
if (t == clay.CMD_SCISSOR_START) {
BeginScissorMode(x, y, w, h)
}
if (t == clay.CMD_SCISSOR_END) {
EndScissorMode()
}
}
Interaction
| Function | Signature | Description |
|---|---|---|
gx_clay_hovered | () → bool | Is current element hovered? |
gx_clay_pointer_over | (cstr) → bool | Is element with ID under pointer? |
gx_clay_hash_id | (cstr) → u32 | Hash a string to element ID |
// Hover-reactive button
clay.gx_clay_open_id("btn")
var is_hov = clay.gx_clay_hovered()
if (is_hov) {
clay.gx_clay_config_rect(100.0, 80.0, 220.0, 255.0, 6.0)
} else {
clay.gx_clay_config_rect(80.0, 60.0, 200.0, 255.0, 6.0)
}
clay.gx_clay_text("Hover Me", 255.0, 255.0, 255.0, 255.0, 0, 18)
clay.gx_clay_close()
Sizing Types
| Constant | Value | Description |
|---|---|---|
SIZING_FIT | 0 | Shrink-wrap to content size |
SIZING_GROW | 1 | Expand to fill available space |
SIZING_PERCENT | 2 | Percentage of parent (0.0 - 1.0) |
SIZING_FIXED | 3 | Exact pixel size |
For SIZING_FIT and SIZING_GROW, w_min/w_max set min/max constraints.
For SIZING_PERCENT, w_min is the percentage (e.g. 0.5 = 50%).
For SIZING_FIXED, w_min is the exact size in pixels.
Debug Mode
Clay includes a built-in debug overlay that visualizes the element tree:
clay.gx_clay_set_debug(true)
Constants Reference
Layout
| Constant | Value | Description |
|---|---|---|
ROW | 0 | Left-to-right layout |
COLUMN | 1 | Top-to-bottom layout |
ALIGN_LEFT / ALIGN_TOP | 0 | Align start |
ALIGN_RIGHT / ALIGN_BOTTOM | 1 | Align end |
ALIGN_CENTER | 2 | Align center |
Text
| Constant | Value | Description |
|---|---|---|
WRAP_WORDS | 0 | Break on whitespace |
WRAP_NEWLINES | 1 | Break on newlines only |
WRAP_NONE | 2 | No wrapping |
TEXT_LEFT | 0 | Left-align text |
TEXT_CENTER | 1 | Center text |
TEXT_RIGHT | 2 | Right-align text |
Renderer Sub-modules
Instead of manually iterating render commands, use a renderer module for one-call rendering. Each renderer is a separate module to avoid pulling in unnecessary dependencies.
Feature Matrix
| Feature | clay_raylib | clay_sokol |
|---|---|---|
| Filled rectangles | Yes | Yes |
| Rounded rectangles | Yes | No (drawn as sharp) |
| Text rendering | Yes (with fonts) | No (skipped) |
| Borders (uniform) | Yes (outline) | Yes (4 rects) |
| Borders (per-side) | Yes (4 rects) | Yes (4 rects) |
| Images/textures | Yes | Yes |
| Scissor/clipping | Yes | Yes |
| Text measurement | Yes (automatic) | No |
Raylib Renderer (clay_raylib)
Full-featured renderer with text, rounded corners, and automatic text measurement.
import clay
import clay_raylib
import raylib.core
import raylib.input
import raylib.text
import raylib.colors
fn main() {
InitWindow(800, 600, "Clay + Raylib")
SetTargetFPS(60)
var ctx = clay.gx_clay_init(800.0, 600.0)
// Set up fonts: index 0 = default font
var font = GetFontDefault()
clay_raylib.gx_clay_raylib_init(&font, 1)
while (!WindowShouldClose()) {
clay.gx_clay_set_pointer(GetMouseX(), GetMouseY(), IsMouseButtonDown(0))
clay.gx_clay_begin_layout()
// ... declare UI elements ...
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(GetFrameTime(), &count)
BeginDrawing()
ClearBackground(BLACK)
clay_raylib.gx_clay_render_raylib(cmds, count) // one call!
EndDrawing()
}
CloseWindow()
}
Font table: Pass a pointer to your Font array. The array index matches
Clay’s font_id in text elements. gx_clay_raylib_init also installs the
text measurement callback so Clay can compute accurate text layouts.
Multiple fonts:
var fonts: Font[3]
fonts[0] = LoadFontEx("regular.ttf", 16, 0, 0)
fonts[1] = LoadFontEx("bold.ttf", 16, 0, 0)
fonts[2] = LoadFontEx("mono.ttf", 14, 0, 0)
clay_raylib.gx_clay_raylib_init(&fonts, 3)
// Use font_id to select font:
clay.gx_clay_text("Normal text", 255.0, 255.0, 255.0, 255.0, 0, 16) // font 0
clay.gx_clay_text("Bold text", 255.0, 255.0, 255.0, 255.0, 1, 16) // font 1
| Function | Signature | Description |
|---|---|---|
gx_clay_raylib_init | (*void, i32) | Set font table + install text measurement |
gx_clay_render_raylib | (*void, i32) | Render all commands (between Begin/EndDrawing) |
Sokol GP Renderer (clay_sokol)
Basic renderer for Sokol GP. Handles rectangles, borders, images, and scissor. Text and rounded corners are not supported (Sokol GP lacks these natively).
import clay
import clay_sokol
import sokol.app
import sokol.gfx
import sokol.gp
// In your frame callback:
clay.gx_clay_begin_layout()
// ... declare UI ...
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)
sgp_begin(width, height)
clay_sokol.gx_clay_render_sokol(cmds, count) // one call!
sgp_flush()
sgp_end()
| Function | Signature | Description |
|---|---|---|
gx_clay_render_sokol | (*void, i32) | Render all commands (between sgp_begin/end) |
Writing a Custom Renderer
If you need a different backend, iterate commands manually:
var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)
for (i = 0 : count - 1) {
var cmd = clay.gx_clay_get_command(cmds, i)
var t = clay.gx_clay_cmd_type(cmd)
if (t == clay.CMD_RECTANGLE) {
// draw rect at cmd_x/y/w/h with cmd_rect_r/g/b/a color
}
if (t == clay.CMD_TEXT) {
// draw cmd_text_chars at cmd_x/y with cmd_text_font_size
}
// ... handle CMD_BORDER, CMD_IMAGE, CMD_SCISSOR_START/END
}
Platform Notes
- TCC: Compiled with
-DCLAY_DISABLE_SIMD(TCC lacks SSE intrinsics). Layout performance is still excellent for typical UI workloads. - Clang/GCC (
-O2+): SIMD acceleration is available. RemoveCLAY_DISABLE_SIMDfrom cflags for optimized builds if desired. - Clay uses zero
malloccalls — all memory is pre-allocated in a single arena.
Module Layout
modules/
clay/ Core layout engine
c/
clay.h Clay header + implementation (~4800 lines)
clay_impl.c Single-TU compilation (#define CLAY_IMPLEMENTATION)
gx_clay.h GX helper wrappers
gx/
clay.gx Module declarations, constants, extern functions
clay_raylib/ Raylib renderer (import clay_raylib)
c/
gx_clay_render_raylib.h Render loop + text measurement + font table
gx/
clay_raylib.gx Module declaration, 2 extern functions
clay_sokol/ Sokol GP renderer (import clay_sokol)
c/
gx_clay_render_sokol.h Render loop (basic: rects, borders, images, scissor)
gx/
clay_sokol.gx Module declaration, 1 extern function