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 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 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 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
}