Stack

Import

use maud_ui::primitives::stack::{self, Align, Direction, Justify, Props, Space, Tag};

Example

use maud::html;
use maud_ui::primitives::{badge, stack};

html! {
    (stack::render(stack::Props {
        direction: stack::Direction::Horizontal,
        gap: stack::Space::Sm,
        align: stack::Align::Center,
        justify: stack::Justify::Between,
        children: html! {
            span { "Status" }
            (badge::render(badge::Props {
                label: "Healthy".into(),
                variant: badge::Variant::Success,
                ..Default::default()
            }))
        },
        ..Default::default()
    }))
}

Variants / Enums

Direction

• Vertical: children flow top-to-bottom (flex-direction: column) — the default
• Horizontal: children flow left-to-right (flex-direction: row)

Reversed directions are deliberately absent: row-reverse / column-reverse decouple visual order from DOM order, which sends keyboard focus and screen-reader output somewhere other than what a sighted user sees. Reorder the children instead.

Space

Shared by gap and padding. Mirrors tokens::spacing, resolving through the --mui-space-* custom properties, so a consumer theme retunes the whole scale in one place.

• None: 0 — the padding default
• Xs: 0.25rem
• Sm: 0.5rem
• Md: 0.75rem — explicit compact gap
• Lg: --mui-stack-gap (normally 1rem) — the gap default
• Xl: 1.5rem
• Xxl: 2rem

Align

Cross-axis alignment (align-items).

• Stretch: children fill the cross axis — the default
• Start: pack to the cross-axis start (flex-start)
• Center: centre on the cross axis
• End: pack to the cross-axis end (flex-end)
• Baseline: align children's text baselines

Stretch is the default because it matches flexbox's own, and it is what you want for a column of inputs or cards. It is not what you want for a column containing an intrinsically-sized child — a badge in a Vertical stack stretches into a full-width bar rather than staying a chip. Use Align::Start there.

Justify

Main-axis distribution (justify-content).

• Start: pack to the main-axis start (flex-start) — the default
• Center: centre on the main axis
• End: pack to the main-axis end (flex-end)
• Between: equal space between children, none at the edges (space-between)
• Around: equal space around each child (space-around)
• Evenly: equal space between children and at the edges (space-evenly)

Tag

The element the stack renders as. A page assembled entirely from divs has no landmarks, so assistive tech gets one undifferentiated blob.

• Div: no semantics — the default
• Section: a thematic grouping. Requires aria_label
• Article: a self-contained composition
• Aside: tangentially related content (complementary landmark)
• Nav: navigation links (navigation landmark)
• Header: introductory content (banner landmark at page scope)
• Footer: closing content (contentinfo landmark at page scope)
• Main: the document's primary content — at most one per page

Helper Functions

Related

Card (a styled container with header/body/footer, often filled with a stack), Separator (a rule between stacked items), Item (a row with leading/trailing slots), AspectRatio (fixed-ratio box)

Shadcn reference

No direct shadcn/Base UI equivalent — shadcn leans on Tailwind utility classes (flex flex-col gap-4) for this role. stack fills the same need in a utility-free, enumerable form.

Shared page rhythm (0.13.0)

Bare .mui-stack and stack::vertical are vertical stacks with gap: var(--mui-stack-gap) (16px). Immediate child block margins are reset, so a stack of three cards has exactly two gaps. Record pages, shell content, card bodies, grouped worklists and the vertical parts of record/worklist/attention blocks use this contract. .mui-page-stack remains compatible. Caller-owned page wrappers must opt into one of these containers; do not add sibling margins as well. Explicit Space::Md now emits mui-stack--gap-md and keeps 12px; explicit horizontal/compact layouts remain available.