Struct ContainerBuilder 

pub struct ContainerBuilder<'a> { /* private fields */ }

Fluent builder for configuring containers before calling .col() or .row().

Obtain one via Context::container or Context::bordered. Chain the configuration methods you need, then finalize with .col(|ui| { ... }) or .row(|ui| { ... }).

Example

use slt::{Border, Color};
ui.container()
    .border(Border::Rounded)
    .p(1)
    .grow(1)
    .col(|ui| {
        ui.text("inside a bordered, padded, growing column");
    });

Implementations

impl<'a> ContainerBuilder<'a>

pub fn apply(self, style: &ContainerStyle) -> Self

Apply a reusable ContainerStyle recipe. Only set fields override the builder’s current values. Chain multiple .apply() calls to compose.

If the style has an ContainerStyle::extends base, the base is applied first, then the style’s own fields override.

ThemeColor fields (theme_bg, theme_text_color, theme_border_fg) are resolved against the active theme at apply time.

pub fn border(self, border: Border) -> Self

Set the border style.

pub fn border_top(self, show: bool) -> Self

Show or hide the top border.

pub fn border_right(self, show: bool) -> Self

Show or hide the right border.

pub fn border_bottom(self, show: bool) -> Self

Show or hide the bottom border.

pub fn border_left(self, show: bool) -> Self

Show or hide the left border.

pub fn border_sides(self, sides: BorderSides) -> Self

Set which border sides are visible.

pub fn border_x(self) -> Self

Show only left and right borders. Shorthand for horizontal border sides.

pub fn border_y(self) -> Self

Show only top and bottom borders. Shorthand for vertical border sides.

pub fn rounded(self) -> Self

Set rounded border style. Shorthand for .border(Border::Rounded).

pub fn border_style(self, style: Style) -> Self

Set the style applied to the border characters.

pub fn border_fg(self, color: Color) -> Self

Set the border foreground color.

pub fn dark_border_style(self, style: Style) -> Self

Border style used when dark mode is active.

pub fn bg(self, color: Color) -> Self

Set the background color.

pub fn text_color(self, color: Color) -> Self

Set the default text color for all child text elements in this container. Individual .fg() calls on text elements will still override this.

pub fn dark_bg(self, color: Color) -> Self

Background color used when dark mode is active.

pub fn group_hover_bg(self, color: Color) -> Self

Background color applied when the parent group is hovered.

pub fn group_hover_border_style(self, style: Style) -> Self

Border style applied when the parent group is hovered.

pub fn p(self, value: u32) -> Self

Set uniform padding on all sides.

pub fn pad(self, value: u32) -> Self

👎Deprecated since 0.20.0:

Use p() instead

Set uniform padding on all sides. Deprecated alias for p.

pub fn px(self, value: u32) -> Self

Set horizontal padding (left and right).

pub fn py(self, value: u32) -> Self

Set vertical padding (top and bottom).

pub fn pt(self, value: u32) -> Self

Set top padding.

pub fn pr(self, value: u32) -> Self

Set right padding.

pub fn pb(self, value: u32) -> Self

Set bottom padding.

pub fn pl(self, value: u32) -> Self

Set left padding.

pub fn padding(self, padding: Padding) -> Self

Set per-side padding using a Padding value.

pub fn m(self, value: u32) -> Self

Set uniform margin on all sides.

pub fn mx(self, value: u32) -> Self

Set horizontal margin (left and right).

pub fn my(self, value: u32) -> Self

Set vertical margin (top and bottom).

pub fn mt(self, value: u32) -> Self

Set top margin.

pub fn mr(self, value: u32) -> Self

Set right margin.

pub fn mb(self, value: u32) -> Self

Set bottom margin.

pub fn ml(self, value: u32) -> Self

Set left margin.

pub fn margin(self, margin: Margin) -> Self

Set per-side margin using a Margin value.

pub fn w(self, value: u32) -> Self

Set a fixed width (sets both min and max width).

pub fn xs_w(self, value: u32) -> Self

Width applied only at Xs breakpoint (< 40 cols).

Example

ui.container().w(20).md_w(40).lg_w(60).col(|ui| { ... });

pub fn sm_w(self, value: u32) -> Self

Width applied only at Sm breakpoint (40-79 cols).

pub fn md_w(self, value: u32) -> Self

Width applied only at Md breakpoint (80-119 cols).

pub fn lg_w(self, value: u32) -> Self

Width applied only at Lg breakpoint (120-159 cols).

pub fn xl_w(self, value: u32) -> Self

Width applied only at Xl breakpoint (>= 160 cols).

pub fn w_at(self, bp: Breakpoint, value: u32) -> Self

Width applied only at the given breakpoint.

pub fn h(self, value: u32) -> Self

Set a fixed height (sets both min and max height).

pub fn xs_h(self, value: u32) -> Self

Height applied only at Xs breakpoint (< 40 cols).

pub fn sm_h(self, value: u32) -> Self

Height applied only at Sm breakpoint (40-79 cols).

pub fn md_h(self, value: u32) -> Self

Height applied only at Md breakpoint (80-119 cols).

pub fn lg_h(self, value: u32) -> Self

Height applied only at Lg breakpoint (120-159 cols).

pub fn xl_h(self, value: u32) -> Self

Height applied only at Xl breakpoint (>= 160 cols).

pub fn h_at(self, bp: Breakpoint, value: u32) -> Self

Height applied only at the given breakpoint.

pub fn min_w(self, value: u32) -> Self

Set the minimum width constraint. Shorthand for min_width.

pub fn xs_min_w(self, value: u32) -> Self

Minimum width applied only at Xs breakpoint (< 40 cols).

pub fn sm_min_w(self, value: u32) -> Self

Minimum width applied only at Sm breakpoint (40-79 cols).

pub fn md_min_w(self, value: u32) -> Self

Minimum width applied only at Md breakpoint (80-119 cols).

pub fn lg_min_w(self, value: u32) -> Self

Minimum width applied only at Lg breakpoint (120-159 cols).

pub fn xl_min_w(self, value: u32) -> Self

Minimum width applied only at Xl breakpoint (>= 160 cols).

pub fn min_w_at(self, bp: Breakpoint, value: u32) -> Self

Minimum width applied only at the given breakpoint.

pub fn max_w(self, value: u32) -> Self

Set the maximum width constraint. Shorthand for max_width.

pub fn xs_max_w(self, value: u32) -> Self

Maximum width applied only at Xs breakpoint (< 40 cols).

pub fn sm_max_w(self, value: u32) -> Self

Maximum width applied only at Sm breakpoint (40-79 cols).

pub fn md_max_w(self, value: u32) -> Self

Maximum width applied only at Md breakpoint (80-119 cols).

pub fn lg_max_w(self, value: u32) -> Self

Maximum width applied only at Lg breakpoint (120-159 cols).

pub fn xl_max_w(self, value: u32) -> Self

Maximum width applied only at Xl breakpoint (>= 160 cols).

pub fn max_w_at(self, bp: Breakpoint, value: u32) -> Self

Maximum width applied only at the given breakpoint.

pub fn min_h(self, value: u32) -> Self

Set the minimum height constraint. Shorthand for min_height.

pub fn xs_min_h(self, value: u32) -> Self

Minimum height applied only at Xs breakpoint (< 40 cols).

pub fn sm_min_h(self, value: u32) -> Self

Minimum height applied only at Sm breakpoint (40-79 cols).

pub fn md_min_h(self, value: u32) -> Self

Minimum height applied only at Md breakpoint (80-119 cols).

pub fn lg_min_h(self, value: u32) -> Self

Minimum height applied only at Lg breakpoint (120-159 cols).

pub fn xl_min_h(self, value: u32) -> Self

Minimum height applied only at Xl breakpoint (>= 160 cols).

pub fn min_h_at(self, bp: Breakpoint, value: u32) -> Self

Minimum height applied only at the given breakpoint.

pub fn max_h(self, value: u32) -> Self

Set the maximum height constraint. Shorthand for max_height.

pub fn xs_max_h(self, value: u32) -> Self

Maximum height applied only at Xs breakpoint (< 40 cols).

pub fn sm_max_h(self, value: u32) -> Self

Maximum height applied only at Sm breakpoint (40-79 cols).

pub fn md_max_h(self, value: u32) -> Self

Maximum height applied only at Md breakpoint (80-119 cols).

pub fn lg_max_h(self, value: u32) -> Self

Maximum height applied only at Lg breakpoint (120-159 cols).

pub fn xl_max_h(self, value: u32) -> Self

Maximum height applied only at Xl breakpoint (>= 160 cols).

pub fn max_h_at(self, bp: Breakpoint, value: u32) -> Self

Maximum height applied only at the given breakpoint.

pub fn min_width(self, value: u32) -> Self

👎Deprecated since 0.20.0:

Use min_w() instead

Set the minimum width constraint in cells. Deprecated alias for min_w.

pub fn max_width(self, value: u32) -> Self

👎Deprecated since 0.20.0:

Use max_w() instead

Set the maximum width constraint in cells. Deprecated alias for max_w.

pub fn min_height(self, value: u32) -> Self

👎Deprecated since 0.20.0:

Use min_h() instead

Set the minimum height constraint in rows. Deprecated alias for min_h.

pub fn max_height(self, value: u32) -> Self

👎Deprecated since 0.20.0:

Use max_h() instead

Set the maximum height constraint in rows. Deprecated alias for max_h.

pub fn w_pct(self, pct: u8) -> Self

Set width as a percentage (1-100) of the parent container.

pub fn h_pct(self, pct: u8) -> Self

Set height as a percentage (1-100) of the parent container.

pub fn constraints(self, constraints: Constraints) -> Self

Set all size constraints at once using a Constraints value.

pub fn gap(self, gap: u32) -> Self

Set the gap (in cells) between child elements.

pub fn gap_overlap(self, overlap: u32) -> Self

Set a negative gap, causing adjacent children to overlap by overlap cells on the main axis.

This is SLT’s analogue of ratatui’s Layout::spacing(-1). The common use is collapsing the duplicate border between two adjacent bordered panels: with gap_overlap(1) each panel’s shared edge lands in the same column (row layout) or row (column layout), so the doubled border

┌────┐┌────┐
│    ││    │
└────┘└────┘

collapses to a single shared edge.

gap_overlap(0) is identical to gap(0) (no overlap). It composes with the existing gap family: the last call wins, so call exactly one of gap / gap_overlap per builder.

Rendering note

SLT does not (yet) merge the shared cells into junction glyphs (┬, ┼, ┴). When two bordered panels overlap, both write the shared column/row and the later panel’s border character wins by buffer-diff order. To get a clean seam, give the panels compatible border styles or drop one panel’s shared side (e.g. border_sides without the left edge).

Large overlaps saturate gracefully — gap_overlap(N) past a child’s extent never panics or wraps; positions clamp at 0.

Example

use slt::Border;
// Two bordered panels sharing one border column.
ui.container().gap_overlap(1).row(|ui| {
    ui.bordered(Border::Single).w(10).col(|ui| {
        ui.text("left");
    });
    ui.bordered(Border::Single).w(10).col(|ui| {
        ui.text("right");
    });
});

pub fn row_gap(self, value: u32) -> Self

Set the gap between children for column layouts (vertical spacing). Overrides .gap() when finalized with .col().

pub fn col_gap(self, value: u32) -> Self

Set the gap between children for row layouts (horizontal spacing). Overrides .gap() when finalized with .row().

pub fn xs_gap(self, value: u32) -> Self

Gap applied only at Xs breakpoint (< 40 cols).

pub fn sm_gap(self, value: u32) -> Self

Gap applied only at Sm breakpoint (40-79 cols).

pub fn md_gap(self, value: u32) -> Self

Gap applied only at Md breakpoint (80-119 cols).

Example

ui.container().gap(0).md_gap(2).col(|ui| { ... });

pub fn lg_gap(self, value: u32) -> Self

Gap applied only at Lg breakpoint (120-159 cols).

pub fn xl_gap(self, value: u32) -> Self

Gap applied only at Xl breakpoint (>= 160 cols).

pub fn gap_at(self, bp: Breakpoint, value: u32) -> Self

Gap applied only at the given breakpoint.

pub fn grow(self, grow: u16) -> Self

Set the flex-grow factor. 1 means the container expands to fill available space.

pub fn fill(self) -> Self

Expand to fill remaining space on the main axis. Shorthand for grow(1).

Equivalent to CSS flex: 1 and ratatui’s Constraint::Fill(1). This is the most common case in flex layouts and reads more naturally than grow(1) for new readers — the abstract “grow factor” terminology is replaced by a self-documenting verb.

ui.container().fill().col(|ui| { ... });
// identical to:
ui.container().grow(1).col(|ui| { ... });

For other weights (e.g. a 2:1 split between two siblings), use grow(N) directly.

pub fn shrink(self) -> Self

Opt this container into proportional flex-shrink.

Marks this container as a shrink participant. When the parent row / column overflows (its children’s combined width or height exceeds available space), shrink-flagged children scale their fixed sizes by available / fixed_total (CSS flex-shrink-style). Children without .shrink() keep their historic overflow-by-design size and clip naturally.

Default for every container is false — opt in per child. Equivalent to CSS flex-shrink: 1 (vs the SLT default of 0). Closes #161.

Example

Two siblings with combined fixed width 60 placed inside a 40-cell row. Without .shrink(), the row overflows; with .shrink() on both, each scales to 40 * 30/60 = 20:

// Without shrink — overflows the parent.
ui.row(|ui| {
    ui.container().w(30).col(|ui| { ui.text("left"); });
    ui.container().w(30).col(|ui| { ui.text("right"); });
});

// With shrink on both — proportional fit, no clipping.
ui.row(|ui| {
    ui.container().w(30).shrink().col(|ui| { ui.text("left"); });
    ui.container().w(30).shrink().col(|ui| { ui.text("right"); });
});

Layout

Only fixed-width children with grow == 0 participate. Grow children already absorb leftover space and ignore the shrink flag. Mixing shrink and non-shrink siblings is supported — only the flagged ones contribute to the shrink budget.

pub fn wrap(self) -> Self

Allow row children to wrap onto subsequent lines on main-axis overflow.

When a .row() finalized with wrap() has children whose combined width exceeds the available width, the overflowing children flow onto the next line, and lines stack on the cross axis. This is the immediate-mode primitive for tag clouds, chip lists, wrapping toolbars, and responsive card grids that reflow as the terminal resizes — without per-frame breakpoint math. Equivalent to CSS flex-wrap: wrap.

Spacing: within-line (main-axis) spacing uses gap / col_gap as usual; between-line (cross-axis) spacing uses row_gap when set, else gap. A child wider than the full available width occupies its own line (clipped, as a single-line row would clip) rather than producing an empty line.

Row only. On col() this is a documented no-op (vertical-axis wrap is out of scope). Default: no wrap (single-line, current overflow-by-design behavior). Closes #258.

Example

// A chip list that reflows onto as many lines as the width needs.
ui.container().wrap().gap(1).row(|ui| {
    for tag in ["rust", "tui", "flexbox", "wrap", "immediate-mode"] {
        ui.container().p(1).col(|ui| { ui.text(tag); });
    }
});

pub fn basis(self, cells: u32) -> Self

Set the flex-basis: the initial main-axis size (in cells) that grow grows from and shrink (#161) shrinks from.

CSS resolves flex sizing as basis (initial) → distribute free space by grow → distribute the deficit by shrink. By default SLT uses a child’s min size as that base; basis(n) overrides it so a child can say “start at n cells, then grow / shrink from there”. None (default, i.e. not calling this) falls back to the min size, preserving current behavior. Equivalent to CSS flex-basis: <n>. Closes #258.

Example

// Two cards that each start at 10 cells, then split the leftover.
ui.row(|ui| {
    ui.container().basis(10).grow(1).col(|ui| { ui.text("a"); });
    ui.container().basis(10).grow(1).col(|ui| { ui.text("b"); });
});

pub fn xs_grow(self, value: u16) -> Self

Grow factor applied only at Xs breakpoint (< 40 cols).

pub fn sm_grow(self, value: u16) -> Self

Grow factor applied only at Sm breakpoint (40-79 cols).

pub fn md_grow(self, value: u16) -> Self

Grow factor applied only at Md breakpoint (80-119 cols).

pub fn lg_grow(self, value: u16) -> Self

Grow factor applied only at Lg breakpoint (120-159 cols).

pub fn xl_grow(self, value: u16) -> Self

Grow factor applied only at Xl breakpoint (>= 160 cols).

pub fn grow_at(self, bp: Breakpoint, value: u16) -> Self

Grow factor applied only at the given breakpoint.

pub fn xs_p(self, value: u32) -> Self

Uniform padding applied only at Xs breakpoint (< 40 cols).

pub fn sm_p(self, value: u32) -> Self

Uniform padding applied only at Sm breakpoint (40-79 cols).

pub fn md_p(self, value: u32) -> Self

Uniform padding applied only at Md breakpoint (80-119 cols).

pub fn lg_p(self, value: u32) -> Self

Uniform padding applied only at Lg breakpoint (120-159 cols).

pub fn xl_p(self, value: u32) -> Self

Uniform padding applied only at Xl breakpoint (>= 160 cols).

pub fn p_at(self, bp: Breakpoint, value: u32) -> Self

Padding applied only at the given breakpoint.

pub fn align(self, align: Align) -> Self

Set the cross-axis alignment of child elements.

pub fn center(self) -> Self

Center children on the cross axis. Shorthand for .align(Align::Center).

pub fn justify(self, justify: Justify) -> Self

Set the main-axis content distribution mode.

pub fn space_between(self) -> Self

Distribute children with equal space between; first at start, last at end.

pub fn space_around(self) -> Self

Distribute children with equal space around each child.

pub fn space_evenly(self) -> Self

Distribute children with equal space between all children and edges.

pub fn flex_center(self) -> Self

Center children on both axes. Shorthand for .justify(Justify::Center).align(Align::Center).

pub fn align_self(self, align: Align) -> Self

Override the parent’s cross-axis alignment for this container only. Like CSS align-self.

pub fn title(self, title: impl Into<String>) -> Self

Set a plain-text title rendered in the top border.

pub fn title_styled(self, title: impl Into<String>, style: Style) -> Self

Set a styled title rendered in the top border.

pub fn with_if(self, cond: bool, f: impl FnOnce(Self) -> Self) -> Self

Apply f only if cond is true. Returns the builder for chaining.

Use this to attach a block of builder modifiers without breaking the fluent chain. The closure takes the builder by value and must return it (matching the rest of ContainerBuilder’s by-value API), so any builder method (.border(), .title(), .bg(), etc.) can be chained inside.

Zero allocation: the closure is inlined and skipped entirely when cond is false.

Example

use slt::Border;
let highlighted = true;
ui.container()
    .p(1)
    .with_if(highlighted, |c| c.border(Border::Single).title("Active"))
    .col(|ui| {
        ui.text("body");
    });

pub fn theme(self, theme: Theme) -> Self

Override the active theme for all widgets rendered inside this container.

The override is scoped to the container body (the closure passed to .col(), .row(), or .line()). The parent theme is restored when the container closes — including on panic.

All built-in widgets read ctx.theme directly for color decisions, so this swap propagates through every nested widget without requiring them to opt in. Nested .theme(...) calls correctly nest: the innermost theme wins inside its own subtree, and the outer theme resumes once it closes.

Independent of Context::provide / Context::use_context — this directly mutates the active theme used by SLT-owned widgets, while provide/use_context is the general-purpose context injection mechanism for user code.

Example

use slt::{Border, Theme};
ui.container()
    .theme(Theme::light())
    .border(Border::Rounded)
    .col(|ui| {
        ui.text("This subtree renders with the light theme");
        ui.button("Click me"); // also uses light theme colors
    });

pub fn with(self, f: impl FnOnce(Self) -> Self) -> Self

Apply f unconditionally. Useful for factoring out a block of builder modifier calls while keeping the fluent chain intact.

The closure takes the builder by value and must return it.

Example

use slt::Border;
ui.container()
    .with(|c| c.border(Border::Rounded).p(1))
    .col(|ui| {
        ui.text("body");
    });

pub fn cached(self, version_key: u64, f: impl FnOnce(&mut Context)) -> Response

Opt-in: declare a subtree stable when version_key is unchanged from the previous frame at this call site.

This is an author-controlled cache, not reactive binding. Your closure is still the app (Principle 2 — “Your Closure IS the App”): f runs every frame exactly like .col(f), so the rendered output is byte-for-byte identical to an uncached container — there is no retained widget identity, no message passing, no reactive subscription, and no behavior change whatsoever when you do not call cached.

What cached adds is a single, principle-preserving signal: it records the version_key you supply (a value you already own — e.g. a hash of the non-streaming inputs, or StreamingTextState::version of the other panes) and compares it to the key this call site recorded last frame. A match is a cache hit (the subtree is declared unchanged); a change, a new call site, the first frame, or a terminal resize is a miss. The hit/miss tally is exposed via Context::region_cache_hits / Context::region_cache_misses.

Why output is identical even on a hit (current implementation)

Skipping f on a hit would require splicing the prior frame’s recorded Commands, replaying its focus / hit-map / scroll / raw-draw feedback, and reusing its rendered cells — without that full replay the immediate- mode invariant breaks (focus and interaction would silently drop). That replay is deliberately out of scope here (it risks reintroducing a retained tree, the thing Principle 2 forbids). So cached keeps the invariant absolute — f always runs — and instead lands the safe, reversible half: a measured, author-keyed stability gate plus diagnostics. The streaming benchmark bench_streaming_append_chat (benches/benchmarks.rs) quantifies the upstream cost this gate is designed to eventually elide; see docs/PERFORMANCE.md.

Pattern: cache the chrome, not the stream

During token streaming, wrap the static surroundings (chat history, sidebar, status bar) keyed off everything except the stream, and leave the stream itself uncached — it changes every token:

ui.container().cached(history_version, |ui| {
    ui.text("…long chat transcript…"); // unchanged this token
});
ui.streaming_text(&mut stream);         // changes every token

pub fn col(self, f: impl FnOnce(&mut Context)) -> Response

Finalize the builder as a vertical (column) container.

The closure receives a &mut Context for rendering children. Returns a Response with click/hover state for this container.

pub fn row(self, f: impl FnOnce(&mut Context)) -> Response

Finalize the builder as a horizontal (row) container.

The closure receives a &mut Context for rendering children. Returns a Response with click/hover state for this container.

pub fn line(self, f: impl FnOnce(&mut Context)) -> Response

Finalize the builder as an inline text line.

Like row but gap is forced to zero for seamless inline rendering of mixed-style text.

pub fn draw(self, f: impl FnOnce(&mut Buffer, Rect) + 'static)

Finalize the builder as a raw-draw region with direct buffer access.

The closure receives (&mut Buffer, Rect) after layout is computed. Use buf.set_char(), buf.set_string(), buf.get_mut() to write directly into the terminal buffer. Writes outside rect are clipped.

The closure must be 'static because it is deferred until after layout. To capture local data, clone or move it into the closure:

let data = my_vec.clone();
ui.container().w(40).h(20).draw(move |buf, rect| {
    // use `data` here
});

pub fn draw_with<D: 'static>( self, data: D, f: impl FnOnce(&mut Buffer, Rect, &D) + 'static, )

Like draw, but carries owned per-frame data through to the deferred closure as a borrow.

Raw-draw closures must be 'static because they run after layout is computed — which normally forces callers to snapshot any borrowed state into an owned value before passing it in. draw_with makes that explicit: hand the snapshot over, borrow it inside the closure.

Example

let points: Vec<(u32, u32)> = (0..20).map(|i| (i, i * 2)).collect();
ui.container().w(40).h(20).draw_with(points, |buf, rect, points| {
    for (x, y) in points {
        if rect.contains(*x, *y) {
            buf.set_char(*x, *y, '●', Style::new());
        }
    }
});

pub fn draw_interactive( self, f: impl FnOnce(&mut Buffer, Rect) + 'static, ) -> Response

Custom drawing with click and hover detection.

Like draw, but the returned Response reports clicked and hovered based on the laid-out region — exactly like .col() or .row().

Example

let resp = ui.container()
    .w(40).h(10)
    .draw_interactive(|buf, rect| {
        buf.set_string(rect.x, rect.y, "Click me!", slt::Style::new());
    });
if resp.clicked {
    // handle click
}