Skip to content
RefineUI

Layout

Spatial rhythm, containers, grids, alignment, and responsive rules.

Layout foundations describe how space is composed. The React primitives that implement them are Box, Stack, Grid, Container (plus Resizable and ScrollArea).

Principles

Section titled “Principles”
  1. Token gaps and padding — Use spacing keys (sizeSmall, sizeLarge), not arbitrary px.
  2. Compose primitives — Prefer Stack / Grid / Container over one-off flex CSS in product screens.
  3. One primary reading width — Constrain long text with Container or a Foundation max-width token.

Container

Section titled “Container”

A container centers content and caps width so long pages stay readable. In React, use the Container primitive with spacing-token padding.

When to use

  • Documentation and marketing pages
  • Form or settings columns that should not stretch edge-to-edge on wide screens

Rules

  • Prefer Foundation / component max-width tokens over inventing a new breakpoint width.
  • Pair with page-level vertical spacing (sizeXXLarge / sizeXXXLarge) rather than ad-hoc margins.
  • Nested containers are usually unnecessary — one page shell is enough.

Grid

Section titled “Grid”

Use a grid when content is two-dimensional (cards, dashboards, galleries). In React, use Grid with columns or minItem (Foundation size) and spacing-token gaps.

When to use

  • Repeating cards or tiles
  • Form fields in two columns on desktop
  • Dense data that still needs aligned columns

Rules

  • Gaps come from spacing tokens (gap="sizeLarge").
  • Prefer minItem auto-fit for fluid card grids; fixed columns when the count is intentional.
  • Collapse to a single column on small viewports (see Responsive).

Alignment

Section titled “Alignment”

Alignment controls how children sit along the main and cross axes. In React, Stack and Grid expose align and justify (start, center, end, between, …).

  • Align labels and controls to a shared start edge in forms.
  • Center only when the block is intentionally focal (empty states, dialogs).
  • Prefer between for toolbars (title left, actions right) instead of manual margin-left: auto on every child.

Responsive

Section titled “Responsive”

Layouts should reflow with the viewport while keeping spacing and type tokens stable. Prefer fewer columns, stacked stacks, and full-width controls on small screens.

  1. Same tokens — Do not invent a second spacing scale for mobile.
  2. Collapse structure — Grids become one column; side-by-side stacks become direction="column".
  3. Touch targets — Keep control sizes from the component API (size="md" / lg); do not shrink below Foundation control heights.
  4. Navigation — Desktop rails become drawers on small screens (see Drawer and Sidebar).
Section titled “Related components”