0.13 - Simplified Config, Multi Instance Support

New Features

Replace Element Macros with a Single Configuration Struct

We've removed the majority of the configuration macros in favour of a large config struct that you pass to CLAY.
You can find exhaustive documentation of this struct and its fields in the README.

// Before - macros
CLAY(
    CLAY_ID("FloatingContainer"),
    CLAY_LAYOUT({
        .sizing = {
            .width = CLAY_SIZING_FIXED(300),
            .height = CLAY_SIZING_FIXED(300)
        },
        .padding = { 16, 16, 16, 16 }
    }),
    CLAY_FLOATING({
        .zIndex = 1,
        .attachment = {
            CLAY_ATTACH_POINT_CENTER_TOP,
            CLAY_ATTACH_POINT_CENTER_TOP
        },
        .offset = { 0, 0 }
    }),
    CLAY_BORDER_OUTSIDE({ .color = {80, 80, 80, 255}, .width = 2 }),
    CLAY_RECTANGLE({ .color = {140,80, 200, 200 }}
) {
    // children
}

// After - single struct
CLAY({
    .id = CLAY_ID("FloatingContainer"),
    .layout = {
        .sizing = {
            .width = CLAY_SIZING_FIXED(300),
            .height = CLAY_SIZING_FIXED(300)
        },
        .padding = { 16, 16, 16, 16 }
    },
    .backgroundColor = { 140, 80, 200, 200 },
    .floating = {
        .attachTo = CLAY_ATTACH_TO_PARENT,
        .zIndex = 1,
        .attachPoints = {
            CLAY_ATTACH_POINT_CENTER_TOP,
            CLAY_ATTACH_POINT_CENTER_TOP
        },
        .offset = { 0, 0 }
    },
    .border = {
        .width = { 2, 2, 2, 2 },
        .color = { 80, 80, 80, 255 }
    },
}) {
    // children
}

The two main benefits we get from this approach are:

1. The available configuration options are naturally discoverable for those using intellisense just by pressing . inside CLAY({ }), whereas previously you had to look up the macros in the documentation.
2. You can define the configuration for an entire element and save it as a struct:

Clay_ElementDeclaration buttonStyle = (Clay_ElementDeclaration) {
    .layout = { .padding = { .left = 16, .right = 16 } },
    .backgroundColor = COLOR_RED,
    .cornerRadius = { 16, 16, 16, 16 }
}

// later
CLAY(buttonStyle) {
    // button contents
}

// Or return a declaration from a function
Clay_ElementDeclaration GetButtonStyle(bool hovered) {
    return (Clay_ElementDeclaration) {
        .layout = { ... },
        .backgroundColor = hovered ? BLUE : RED
    };
}

// Generate element style from template
CLAY(GetButtonStyle(Clay_Hovered())) {
    // button contents
}

"Context" support (i.e. Multiple independent Clay instances & groundwork for multithreading support)

Thanks to some great discussions in the Clay discord and great work by @monodop here: #174 Clay now supports creation and management of multiple "instances" which are separate from one another. This is not only useful for systems with separate internal "windows" requiring different layout trees, but also paves the way for us to support running these instances on separate threads.

An example of the same layout rendered twice by two separate Clay instances

For more information, see the Multi Context Example

Error Handler

Clay now requires that you bind an error handler callback function when calling Clay_Initialize. This allows us to catch and report some common mistakes such as forgetting to bind a text measurement function with Clay_SetMeasureText.

Clay_GetElementData for querying bounding box data

A new function, Clay_GetElementData(Clay_ElementId id) is available for directly looking up the final calculated bounding box of an element by ID.

.textAlignment support for CLAY_TEXT_CONFIG

Wrapped text can now be aligned to LEFT, CENTER or RIGHT using the .textAlignment field of CLAY_TEXT_CONFIG.

MSVC Support & C99 Compliance

Thanks to some tireless work from @FintasticMan, Clay can now be compiled using MSVC with C11, 17, and 23, has much closer strict C99 compliance, and compiles with -Wextra and -Wpedantic.

New Renderers

Thanks to some hard work from our contributors, there are a number of new example renderers in 0.13, including:

• SDL2
• SDL3
• Cairo

New Language Bindings

Thanks to some hard work from our contributors, there are a number of new language bindings in 0.13, including:

Zig
https://codeberg.org/Zettexe/clay-zig
https://github.com/johan0A/clay-zig-bindings

Rust
https://github.com/clay-ui-rs/clay
https://crates.io/crates/clay-layout

C#
https://github.com/Orcolom/clay-cs

C++
https://github.com/TimothyHoytBSME/ClayMan

Deprecations

The preprocessor defines used for adding additional fields to element configuration structs such as CLAY_EXTEND_CONFIG_RECTANGLE have been removed in favour of the new .userData pointer field of Clay_ElementDeclaration. This was out of necessity and can be explained in more detail upon request 😅

Migration Guide

1. Wrap the inside of the CLAY(...) macro in braces for the new form CLAY({ ... })

- CLAY(
+ CLAY({
    CLAY_ID(...),
    CLAY_RECTANGLE({ ... }),
    CLAY_BORDER({ ... }),
    CLAY_FLOATING({ ... })
- )
+ })

2. Mass rename the following macros:

• CLAY_BORDER({ ... })
• CLAY_IMAGE({ ... })
• CLAY_SCROLL({ ... })
• CLAY_FLOATING({ ... })
• CLAY_CUSTOM({ ... })

into struct fields of the form .border = { ... }, .floating = { ... } etc

CLAY({
    CLAY_ID(...),
    CLAY_RECTANGLE({ ... }),
-   CLAY_BORDER({ ... }),
+   .border = { ... },
-   CLAY_FLOATING({ ... })
+   .floating = { ... },
})

3. Replace the CLAY_ID macro with the struct field .id = CLAY_ID

CLAY({
-   CLAY_ID(...),
+   .id = CLAY_ID(...),
    CLAY_RECTANGLE({ ... }),
    .border = { ... },
    .floating = { ... }
})

4. Replace CLAY_RECTANGLE macros with two struct fields, .backgroundColor and .cornerRadius

Previous, fields like .cornerRadius would need to be repeated for rectangle, image, and border configuration macros. .backgroundColor and .cornerRadius are now shared fields that affect multiple render commands, and are declared once at the top level.

CLAY({
    .id = CLAY_ID(...),
-   CLAY_RECTANGLE({ .color = COLOR_RED, .cornerRadius = { 10, 10, 10, 10 } }),
+   .backgroundColor = COLOR_RED,
+   .cornerRadius = { 10, 10, 10, 10 },
    .border = { ... },
    .floating = { ... }
})

5. Padding is now represented by four values, not just two

Padding in 0.12 was represented as a mirrored .x, .y pair. It's been changed in 0.13 to a more standard .left, .right, .top, .bottom.
You'll need to update your padding to match the new structure.

- CLAY({ .layout = { .padding = { 8, 12 } });
+ CLAY({ .layout = { .padding = { 8, 8, 12, 12 } });

// Designated initializers
- CLAY({ .layout = { .padding = { .x = 8, .y = 12 } });
+ CLAY({ .layout = { .padding = { .left = 8, .right = 8, .top = 12, .bottom = 12 } });

6. Depending on your language and compiler, CLAY_SIZING_GROW might need to be passed 0 when you don't specify min and max size:

- CLAY({ .layout = { .width = CLAY_SIZING_GROW() } });
+ CLAY({ .layout = { .width = CLAY_SIZING_GROW(0) } });

7. Update border declarations

Borders now share a single color, and use the shared .cornerRadius from the outer declaration.

- CLAY_BORDER({ .left = { 20, COLOR_BLUE }, .right = { 20, COLOR_BLUE }, .bottom = { 20, COLOR_BLUE }, .cornerRadius = { 10, 10, 10, 10 } })
+ .cornerRadius = { 10, 10, 10, 10 },
+ .border = { .width = { .left = 20, .right = 20, .bottom = 20 }, .color = COLOR_BLUE }

8. Changes to Floating Elements

Replacing CLAY_FLOATING, The .floating config of the declaration struct now has a new field, .attachTo, which can be one of several values:

CLAY_ATTACH_TO_NONE (default)
CLAY_ATTACH_TO_PARENT
CLAY_ATTACH_TO_ELEMENT_ID
CLAY_ATTACH_TO_ROOT

Unlike previously where just calling CLAY_FLOATING was enough to switch an element to floating mode, now .attachTo has to be set to some value other than the default NONE. CLAY_ATTACH_TO_PARENT is the old default behaviour, CLAY_ATTACH_TO_ELEMENT_ID requires that you set a parentId to attach the floating element to, and the new CLAY_ATTACH_TO_ROOT option allows you to position the element relative to the root of the layout (i.e. the entire screen), by using the .offset field.

// Attach to parent
- CLAY_FLOATING({ .offset = { 12, 12 } });
+ .floating = { .attachTo = CLAY_ATTACH_TO_PARENT,  .offset = { 12, 12 } };

// Attach to specific ID
- CLAY_FLOATING({ .parentId = CLAY_ID("targetElement") });
+ .floating = { .attachTo = CLAY_ATTACH_TO_ELEMENT_ID,  .parentId = CLAY_ID("targetElement") };

9. Clay_SetMeasureTextFunction must now be called after Clay_Initialize

10. Clay_Initialize now requires an error handler callback.

void HandleClayErrors(Clay_ErrorData errorData) {
    // See the Clay_ErrorData struct for more information
    printf("%s", errorData.errorText.chars);
    switch(errorData.errorType) {
        // etc
    }
}

- Clay_Initialize(arena, (Clay_Dimensions) { screenWidth, screenHeight });
+ Clay_Initialize(arena, (Clay_Dimensions) { screenWidth, screenHeight }, (Clay_ErrorHandler) { HandleCl...

0.12 - Multi type elements, performance improvements

Clay v0.12 - Multi type elements, performance improvements

Changelog

New Feature: Multi-Type Elements

Clay's element API has been refactored to allow for significantly better flexibility and modularity. Instead of elements having a single specific type, all elements use the generic CLAY() macro for definition, and then can be configured using any combination of types. The above screenshot demonstrates the significant reduction in boilerplate when defining a multi-type element such as "A scrolling container with a border and background".

New Feature: Clay_Hovered() and Clay_OnHover() functions

Two new functions have been added that can be called during element configuration and layout construction, provided a convenient mechanism for handing hover and click interactions.

See the documentation for Clay_Hovered and Clay_OnHover for details.

void HandleHeaderButtonInteraction(Clay_ElementId elementId, Clay_PointerData pointerData, intptr_t userData) {
    if (pointerData.state == CLAY_POINTER_DATA_PRESSED_THIS_FRAME) {
        // Do some click handling
    }
}

void HeaderButton(Clay_String text) {
    CLAY(CLAY_LAYOUT({ .padding = { 16, 8 } }),
        // When this element is hovered, change the background color from orange to blue
        CLAY_RECTANGLE({ .color = Clay_Hovered() ? COLOR_BLUE : COLOR_ORANGE }),
        // When this element is hovered, call the function HandleHeaderButtonInteraction with the userData = `1`.
        Clay_OnHover(HandleHeaderButtonInteraction, 1)
    ) {
        CLAY_TEXT(text, CLAY_TEXT_CONFIG(headerTextConfig));
    }
}

Improvements: Significantly faster text handling

The internal algorithm for wrapping text and caching text measurements has been rewritten from scratch, resulting in a ballpark 2-4x performance improvement of layout calculation. As a result, reasonably complex layouts now sit in the <100 microseconds range.

New Contributors

• @mikejsavage made their first contribution in #21
• @SeverinDenisenko made their first contribution in #23
• @bullno1 made their first contribution in #25
• @SogoCZE made their first contribution in #33
• @johan0A made their first contribution in #41
• @richardhozak made their first contribution in #42

Full Changelog: v0.11...v0.12

Migration Guide (C/C++)

This release contains significant breaking changes that are detailed below. For a smooth migration process, please follow the below steps in order.

Step 1. Rename Element Macros -> CLAY()

The following element macros:

• CLAY_CONTAINER()
• CLAY_RECTANGLE()
• CLAY_IMAGE()
• CLAY_BORDER_CONTAINER()
• CLAY_SCROLL_CONTAINER()
• CLAY_FLOATING_CONTAINER()
• CLAY_CUSTOM_ELEMENT()

Can all be mass renamed to just CLAY(). For example:

- CLAY_RECTANGLE(...) {
+ CLAY(...) {
-     CLAY_CONTAINER(...) {
+     CLAY(...) {
         // ... etc
    }
}

Step 2. Rename CLAY_X_CONFIG() -> CLAY_X()

The following element configuration macros:

• CLAY_RECTANGLE_CONFIG()
• CLAY_IMAGE_CONFIG()
• CLAY_BORDER_CONFIG()
• CLAY_SCROLL_CONFIG()
• CLAY_FLOATING_CONFIG()
• CLAY_CUSTOM_CONFIG()

Can all be mass renamed to remove the _CONFIG. For example:

- CLAY(id, layout, CLAY_RECTANGLE_CONFIG(...)) {
+ CLAY(id, layout, CLAY_RECTANGLE(...)) {
-     CLAY(id, layout, CLAY_BORDER_CONFIG_OUTSIDE(...)) {
+     CLAY(id, layout, CLAY_BORDER_OUTSIDE(...)) {
         // ... etc
    }
}

Step 3. Wrap macro contents in { }

All macros that previously accepted designated initializer syntax in the form of:

CLAY_RECTANGLE(.color = RED)

Now require that their contents are wrapped in braces {}.

CLAY_RECTANGLE({ .color = RED })

This is primarily for C++ syntax compatibility.

- CLAY(id, layout, CLAY_RECTANGLE(.color = RED)) {
+ CLAY(id, layout, CLAY_RECTANGLE({ .color = RED })) {
-     CLAY(id, CLAY_LAYOUT(.layoutDirection = CLAY_TOP_TO_BOTTOM), CLAY_BORDER_OUTSIDE(.width = 2, .color = RED)) {
+     CLAY(id, CLAY_LAYOUT({ .layoutDirection = CLAY_TOP_TO_BOTTOM }), CLAY_BORDER_OUTSIDE({ .width = 2, .color = RED })) {
         // ... etc
    }
}

Step 4. Swap any non layout calls to CLAY_ID for Clay_GetElementId

CLAY_ID is now used exclusively for attaching IDs to elements during layout creation, and does not return a value. If you are using CLAY_ID to retrieve element information at other times (for example, mouse or scroll container handling) it can be swapped for the new public function Clay_GetElementId.

- Clay_ScrollContainerData scrollData = Clay_GetScrollContainerData(CLAY_ID("MainContent"));
+ Clay_ScrollContainerData scrollData = Clay_GetScrollContainerData(Clay_GetElementId(CLAY_STRING("MainContent")));

Step 5. Remove all IDs from CLAY_TEXT()

CLAY_TEXT() elements no longer accept an ID as the first argument, and instead rely on an auto generated internal ID. The primary reasoning behind this is that various capabilities provided by IDs - such as attaching floating containers to an element - don't make sense when combined with text that can arbitrarily wrap, especially as the result can end up being non rectangular.

If you need to attach a tooltip or similar to CLAY_TEXT, simply wrap the text in a container.

- CLAY_TEXT(CLAY_ID("HFileSecondLine"), CLAY_STRING("~2000 lines of C99."), textConfig);
+ CLAY_TEXT(CLAY_STRING("~2000 lines of C99."), textConfig);

Step 6 (Optional) Remove all empty calls to CLAY_LAYOUT() or references to CLAY_LAYOUT_DEFAULT

Both IDs and calls to CLAY_LAYOUT() are now optional when declaring layouts. As a result, any empty calls to CLAY_LAYOUT or references to &CLAY_LAYOUT_DEFAULT simply to satisfy the compiler can be removed.

- CLAY(CLAY_ID("Button"), CLAY_LAYOUT(), CLAY_RECTANGLE({ .color = RED })) {}
+ CLAY(CLAY_ID("Button"), CLAY_RECTANGLE({ .color = RED })) {}

Migration Guide (Odin)

Step 1. Rename Element Functions -> clay.UI()

The following element functions:

• clay.Container()
• clay.Rectangle()
• clay.Image()
• clay.Border()
• clay.Scroll()
• clay.Floating()
• clay.Custom()

Should all be renamed to just Clay.UI().

- if (clay.Container(
+ if (clay.UI(
        clay.ID("Button"),
        clay.Layout({ childAlignment = {y = .CENTER}, padding = {x = 50} }),
    ) { // etc
)

Step 2. Rename clay.xConfig() -> clay.x()

The following element config functions:

• clay.RectangleConfig()
• clay.ImageConfig()
• clay.BorderConfig()
• clay.ScrollConfig()
• clay.FloatingConfig()
• clay.CustomConfig()

Should all be renamed to just Clay.__name__().

if (clay.UI(
        clay.ID("Button"),
-      clay.RectangleConfig({ color = COLOR_RED }),
+      clay.Rectangle({ color = COLOR_RED }),
    ) { // etc
)

Step 3. Remove the first ID argument from clay.Text

clay.Text no longer supports IDs, and instead uses an auto generated internal ID.

- clay.Text(clay.ID("HeroBlobText", index), text, clay.TextConfig({fontSize = fontSize, fontId = fontId, textColor = color}))
+ clay.Text(text, clay.TextConfig({fontSize = fontSize, fontId = fontId, textColor = color}))

v0.11

Clay 0.11

Changelog

• New Feature: Visual Debug Tools. Similar to the inspector in Chrome or Firefox. Browse your layout hierarchy, inspect bounding boxes and config, and view any warnings output during layout. To activate the debug tools, call the new function Clay_SetDebugModeEnabled. See the README for more details.

• New Feature: Text Wrap Modes. A new feature of TEXT_CONFIG, this allows you to choose between three modes:
• CLAY_TEXT_WRAP_WORDS - Text will wrap on whitespace characters as container width shrinks.
• CLAY_TEXT_WRAP_NEWLINES - Text will only wrap when encountering newline characters
• CLAY_TEXT_WRAP_NONE - Text will never wrap even if its container is compressed beyond the text measured width.

I am considering a wrap mode which will wrap on individual characters in future but haven't decided on an implementation yet.

• Improved performance of text layout when wrap is disabled or no wrapping needs to occur.
• Fixed a bug that occurred when multiple nested floating containers were used.
• Fixed a bug where the text measurement cache would not be used correctly.
• Fixed a bug in the HTML renderer where text could be measured and cached before custom fonts had loaded.
• Fixed a bug in the HTML renderer where alpha wasn't correctly respected.

Upgrade Guide

Unfortunately, this release contains some small breaking changes to the public API.

While I do my best to avoid breaking changes, Clay is still in alpha and the API is subject to change.

• Element's uint32_t id has changed to a struct, Clay_ElementId. CLAY_ID and CLAY_IDI now return this struct, so layout definitions that use macros should not require migration. There are several cases where you might need to change the type of variables.

// Before
uint32_t id = CLAY_ID("Button");
// After
Clay_ElementId id = CLAY_ID("Button");

While functions that previously took uint32_t id as an argument have been updated, the parentId field of CLAY_FLOATING_CONFIG is still uint32_t. You can access the .id field of the Clay_ElementId struct in this case:

CLAY_FLOATING_CONTAINER(CLAY_ID("ScrollBar"), CLAY_LAYOUT(), CLAY_FLOATING_CONFIG(.parentId = CLAY_ID("OuterScrollContainer").id), {

• Clay_BeginLayout and Clay_EndLayout now take no arguments, and there is a seperate function Clay_SetLayoutDimensions which is used to update the layout dimensions before the current frame. See the README for more details.
• Clay_Initialize now expects Clay_Dimensions to set the initial layout dimensions. See the README for more details.
• Clay_SetPointerPosition has been renamed to Clay_SetPointerState, and now expects a second argument isPointerDown representing whether or not the main mouse button / touch is currently held down.

v0.10

First release of clay.h