Clay 2D UI Layout Library

Unlike the C API which uses macros, the Odin bindings use if statements to create the scope for declaring child elements. This is the equivalent of the C CLAY element macros. When you call clay.UI(), it returns a boolean that allows you to wrap child elements within an if block.

// Odin form of element macros
if clay.UI(clay.ID("Outer"))({ layout = { padding = clay.PaddingAll(16) }}) {
    // Child elements here
}

Floating elements (configured via Clay_FloatingElementConfig) are used for UI components that need to appear above other content, such as tooltips or modals.

Mental Model: Think of a floating container as a completely separate UI hierarchy that is attached to a specific (x, y) coordinate on its 'parent' element.

Characteristics:

• By default, they attach to the top-left corner of their parent.
• They do not affect the width or height of their parent.
• They do not affect the positioning of sibling elements.
• They can partially or completely occlude other elements depending on their z-index.
• Aside from positioning, they function like standard elements (e.g., they can expand to fit their children).

The .attachPoints field in Clay_FloatingElementConfig uses a coordinate-matching mental model. You specify a point on the floating container (.element) and a point on the target parent (.parent). Clay then aligns these two points on top of each other.

For example, to place the bottom-center of a tooltip directly above the top-center of a button, you would use: { .element = CLAY_ATTACH_POINT_CENTER_BOTTOM, .parent = CLAY_ATTACH_POINT_CENTER_TOP }.

CLAY(CLAY_ID("Floating"), {
    .floating = {
        .attachPoints = {
            .element = CLAY_ATTACH_POINT_LEFT_CENTER,
            .parent = CLAY_ATTACH_POINT_RIGHT_TOP
        }
    }
}) {};

Clay uses IDs to identify elements for querying state (like hover) or dimensions.

• CLAY_ID("string"): Produces a stable ID from a string. Use this for elements that need to be queried by name or for stable transitions.
• CLAY_AUTO_ID({ ... }): Generates a unique ID. Useful for elements that don't need persistent identity.
• CLAY_IDI("string", index): Generates unique IDs in loops (e.g., Item0, Item1) to avoid manual string construction.

Warning: Avoid duplicate IDs if you intend to attach floating containers to specific elements, as it may cause unexpected behavior.

// Stable ID
CLAY(CLAY_ID("OuterContainer"), { ...configuration }) {}

// Unique ID
CLAY_AUTO_ID({ ...configuration }) {}

// ID in a loop
for (int index = 0; index < items.length; index++) {
    CLAY(CLAY_IDI("Item", index), { ..configuration }) {}
}

Standard elements are laid out within their parent and affect siblings. To create elements that overlap others (like tooltips or modals), use the CLAY_FLOATING() macro. Floating elements have a z-index and do not affect the layout of their parent or siblings.

Use .floating.attachTo = CLAY_ATTACH_TO_PARENT to anchor a floating element to its containing element.

CLAY(CLAY_ID("Outer"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM } }) {
    CLAY_TEXT(text, &headerTextConfig);
    // This tooltip floats over the other elements
    CLAY(CLAY_ID("Tooltip"), { .floating = { .attachTo = CLAY_ATTACH_TO_PARENT } }) {}
    CLAY_TEXT(text, &headerTextConfig);
}

Clay uses specific prefixes to distinguish between different types of functions and macros:

• **CAPITAL_LETTERS()**: Used for macros.
• **Clay__** (double underscore): Used for internal functions. These are not intended for user use and are subject to change.
• **Clay_** (single underscore): Used for public API functions that can be called by the user.

To build and run this example on macOS, you must have sdl2 installed via Homebrew. The build process uses a specific macOS Makefile.

# Install dependencies
brew install sdl2

# Configure with CMake
cmake -B build

# Build using the macOS Makefile
make -f Makefile.macos

# Run the executable
./macos-sidebar-scrolling-container-sdl2

To build the Playdate console example for use with the Playdate simulator, you must have the Playdate SDK installed. When initializing your CMake directory, you must enable the Playdate examples using the -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON flag.

Follow these steps:

1. Initialize the build directory with the Playdate example flag.
2. Build the project using CMake.

The resulting .pdx file will be located at examples/playdate-project-example/clay_playdate_example.pdx.

cmake -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON cmake-build-debug
cmake --build cmake-build-debug