On this page

Flexbox

ui::row() and ui::col() start a flex container. Each is a ui::style whose layout calls chain straight through to the lay_style inside it.

Main axis and cross axis

A row lays children left to right and a column lays them top to bottom. justify places children along that main axis and items places them across it. centre() sets both at once, and self overrides the cross placement for one child. The lay_align values are start, centre, end, stretch, between, around and evenly. lay_align_auto means "whatever the container says". Children stretch across the cross axis by default.

flex_basics.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// a toolbar row, the spacer takes whatever space is left over so the two
// buttons stay pinned to the far edge
static void toolbar(ui::ctx* u)
{
    ui_box(u, ui::row().pad(12.0f).gap(12.0f).items(lay_align_centre))
    {
        ui::text(u, "isolen", ui::head(u));
        ui::spacer(u);
        ui::button(u, "settings");
        ui::button_accent(u, "publish");
    }
}

// three panes that must add up to the row's width, the sidebar shrinks half
// as eagerly as the other two once the row runs out of room
static void three_panes(ui::ctx* u)
{
    ui_box(u, ui::row().grow().gap(0.0f))
    {
        ui_box(u, ui::col().width(240.0f).shrink(0.5f).bg("#111111"))
        {
            ui::text(u, "sidebar", ui::caption(u));
        }
        ui_box(u, ui::col().width(240.0f).shrink(1.0f).grow())
        {
            ui::text(u, "body", ui::body(u));
        }
        ui_box(u, ui::col().width(240.0f).shrink(1.0f))
        {
            ui::text(u, "inspector", ui::caption(u));
        }
    }
}

// justify spaces children along the main axis, between puts the first and
// last flush against the edges and splits the rest evenly
static void step_indicator(ui::ctx* u, const char* const* steps, uint32_t n)
{
    ui_box(u, ui::row().grow().pad(8.0f).justify(lay_align_between))
    {
        for (uint32_t i = 0; i < n; ++i) {
            ui::key(u, uint64_t(i));
            ui::text(u, steps[i], ui::caption(u));
        }
    }
}

// centre is justify and items at once, self overrides the cross axis for
// one child only
static void empty_state(ui::ctx* u)
{
    ui_box(u, ui::col().grow().centre().gap(8.0f))
    {
        ui::text(u, "nothing here yet", ui::head(u));
        ui_box(u, ui::row().self(lay_align_end))
        {
            ui::button(u, "import");
        }
    }
}

Grow and shrink

grow(w) takes a share of leftover space. shrink(w) weights how much a box gives up once the children do not fit. Each box gives up in proportion to its shrink weight times its base size, so in the three pane example the sidebar gives up half as much as the others. Left at their defaults, a grow size grows and a fixed size holds its ground.

Flex sizinginteractive illustration
case
sidebarwidth(240).shrink(0.5)0 px
bodywidth(240).shrink(1)0 px
inspectorwidth(240).shrink(1)0 px
When fixed widths overflow, each box gives up space in proportion to its shrink weight times its size. The row is a browser flexbox with the same rules the solver uses.

Wrap and reverse

wrap() lets a row spill onto more lines. Its argument is how the wrapped lines share the cross axis. reverse() flips the order a row or column lays out in without touching any child.

flex_wrap_reverse.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// red is the low byte and alpha the high byte, see the styles page
constexpr uint32_t abgr(uint32_t r, uint32_t g, uint32_t b, uint32_t a = 255u)
{
    return r | (g << 8) | (b << 16) | (a << 24);
}

// a chip row that wraps once it runs out of width, wrapped lines are packed
// against the start of the cross axis
static void chip_row(ui::ctx* u, const char* const* tags, uint32_t count)
{
    ui_box(u, ui::row().wrap(lay_align_start).gap(8.0f))
    {
        for (uint32_t i = 0; i < count; ++i) {
            ui::key(u, tags[i]);
            ui::badge(u, tags[i], abgr(0x8a, 0x64, 0xe5));
        }
    }
}

// a status strip that reads right to left, useful for rtl or a log that
// grows backwards
static void status_strip_reversed(ui::ctx* u)
{
    ui_box(u, ui::row().reverse().gap(8.0f).pad(8.0f))
    {
        ui::dot(u, abgr(0x64, 0xc8, 0x6e), true);
        ui::text(u, "recording", ui::caption(u));
    }
}
ui::style and lay_style name a few calls differently. ui::style::wrap is lay_style::wraps, ui::style::gap is lay_style::spacing, ui::style::pad(x, y) is lay_style::pad_xy, self is align_self, and place is place_self. Keep to one api within a chain.

Last updated 23 October 2026