zgui

Layout

CSS layout in zgui — the box model, display, flexbox, grid, sizing, positioning, overflow, stacking, and CSS pixels.

Layout decides where each box goes and how big it is. zgui lays out with standard CSS, so what you know from the web applies; the notes below point out where zgui differs.

The box model

Every element is a rectangle of content surrounded by three rings.

Margin
Border
Padding
Content
The CSS box model
  • content: text, an image, or child elements.
  • padding: space inside the border. The background extends under it.
  • border: an edge that can be drawn.
  • margin: space outside the border, separating the box from its neighbours.
.card {
    padding: 16px;
    border: 1px solid #2a3242;
    margin: 8px;
}

box-sizing

zgui's user-agent sheet sets * { box-sizing: border-box }, so width and height include padding and border. A box with width: 200px, padding: 16px and a 1px border is 200 pixels wide, with 166 pixels left for content.

To size the content box instead, as browsers do by default, write box-sizing: content-box.

Display types

display chooses how a box lays out its children.

displayChildren are placed
blockstacked vertically; vertical margins collapse; floats apply
flexalong one axis, sharing leftover space
gridinto rows and columns you declare
inlineas a run of text and inline boxes, broken into lines
inline-block, inline-flex, inline-gridinside, like block/flex/grid; outside, the box sits in a line of text
contentsthe element generates no box; its children take its place in the parent's layout
noneno box at all; the subtree takes no space and receives no events

table and multi-column layout are not implemented: table displays and column-count lay out as block flow.

Each element has a default: row and column are flex containers, box is a block, text and label are inline. Change any of them with a declaration.

Use display: contents when a component needs a wrapper element for its own purposes (a class to select on, a listener) but must not add a box between its parent and its children, for example inside a flex row or a grid.

display: none is not "invisible": the box does not exist, takes no space and gets no events. Use visibility: hidden to hide a box but keep its space. To remove content entirely, use if, which also frees its state.

Flexbox

A flex container places its children along one axis and shares out the leftover space.

Main and cross axes

  • The main axis is the direction children are placed in: left to right for flex-direction: row, top to bottom for column.
  • The cross axis is the other direction.
PropertyAxisWhat it does
justify-contentmaindistributes leftover space along the main axis
align-itemscrossaligns children on the cross axis
align-selfcrossoverrides align-items for one child
align-contentcrossdistributes space between lines when the container wraps
gap, row-gap, column-gapbothspace between children
.bar {
    display: flex;
    flex-direction: row;
    justify-content: space-between;   /* first child left, last child right */
    align-items: center;              /* centred vertically */
    gap: 12px;
}

row and column are already flex containers, so you usually write only what you change:

view! {
    row(class = "bar") {
        label {"Storage"}
        spacer()
        text {"41 GB"}
    }
}
.bar { align-items: center; gap: 12px }

spacer is flex: 1 1 auto, so it takes the leftover space and pushes what follows to the far end. It often reads more clearly than justify-content: space-between, because the view shows where the gap is.

Growing and shrinking

Each flex child has three numbers:

PropertyDefaultMeaning
flex-grow0the share of extra space the child takes
flex-basisautothe starting size before growing or shrinking; auto means its content size
flex-shrink1the share of overflow the child gives up

Because flex-shrink defaults to 1, every child shrinks when the line overflows, even below its width or flex-basis. A fixed sidebar needs flex-shrink: 0:

.sidebar { flex-grow: 0; flex-shrink: 0; flex-basis: 240px }
.main    { flex-grow: 1; min-width: 0 }

min-width: 0 on the growing child solves the opposite problem. A flex item's minimum size defaults to its content's minimum size, so one long word can keep it wider than its share. min-width: 0 lets it shrink and clip or wrap inside.

Wrapping and order

.tags { display: flex; flex-wrap: wrap; gap: 8px; align-content: flex-start }
.tag--pinned { order: -1 }   /* placed before its siblings */

align-content only applies when the container wraps onto several lines. With one line it does nothing.

Grid

A grid container places children into rows and columns that you declare. Use grid for two-dimensional arrangements and flexbox for one axis at a time.

.panels {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 16px;
}
  • Tracks are the rows and columns, declared with grid-template-rows and grid-template-columns.
  • fr is a share of the leftover space; repeat(4, 1fr) is four equal columns.
  • Sizes can mix: 240px 1fr 1fr, or repeat(3, minmax(0, 1fr)).

Place children

By line numbers:

.panel--wide { grid-column-start: 1; grid-column-end: 3 }   /* spans two columns */
.panel--tall { grid-row-start: 1; grid-row-end: 3 }

Or by named areas:

.page {
    display: grid;
    grid-template-columns: 240px 1fr;
    grid-template-rows: auto 1fr;
    grid-template-areas:
        "side header"
        "side main";
}
.page__side   { grid-area: side }
.page__header { grid-area: header }
.page__main   { grid-area: main }

Children you do not place are placed automatically: grid-auto-flow sets the direction, and grid-auto-rows and grid-auto-columns size the tracks it creates. justify-content and align-content distribute leftover space between columns and rows.

Sizing

PropertyMeaning
width, heightthe size, as a length or a percentage
min-width, min-heighta lower bound
max-width, max-heightan upper bound
aspect-ratioderives one dimension from the other
inline-size, block-sizelogical forms of width and height

Logical forms of margins, padding and border widths are supported too.

Intrinsic sizes

These keywords size a box from its content:

KeywordMeaning
min-contentas narrow as possible without overflowing; for text, the longest word
max-contentas wide as the content wants with no wrapping
fit-contentmax-content, but no wider than the available space
.chip { width: fit-content }        /* as wide as its label */
.cell { min-width: min-content }    /* never break a word */

An intrinsic size requires measuring the content, which for text means shaping it, so it costs more than a fixed size. Measurements are cached until the content, style or scale factor changes.

Any length can also be a calc() expression: width: calc(100% - 240px).

Positioning

.thing { position: relative; top: 4px; left: 8px }
positionBehaviourOffsets are relative to
staticthe default; offsets are ignored—
relativekeeps its place in the flow, then shiftsits normal position
absoluteremoved from the flowthe nearest positioned ancestor, or the root
fixedremoved from the flow, fixed to the windowthe window
stickyin flow until it would scroll away, then sticksits scroll container

A positioned ancestor is one whose position is not static. Containers often get position: relative without any offset so that absolutely positioned children anchor to them. If no ancestor is positioned, an absolute box is placed against the root element.

top, right, bottom, left and the inset-* properties are all supported.

Positioning cannot escape a clipping or transformed ancestor. To draw outside one, render the content through a Portal.

Overflow

overflow decides what happens when content is larger than its box:

ValueBehaviour
visiblecontent spills out and is still drawn
hiddencontent is clipped
autocontent is clipped and the box scrolls when needed
scrollthe same, with the scrollbar always shown

overflow-x, overflow-y and the logical forms are supported. A box with auto or scroll is a scroll container: it clips, keeps a scroll offset and handles wheel input. The scroll element is a box with overflow: auto. See Scrolling.

text-overflow: ellipsis with white-space: nowrap (or text-wrap-mode: nowrap) keeps a line on one line and cuts it at the box edge, including when the line contains nested inline elements.

scrollbar-gutter is not supported. Reserve the space with padding-right on the scrolling element if content must not shift when the scrollbar appears.

Stacking order

The stacking order decides which box is drawn in front of which. It follows the CSS rules, which are not simply document order.

Boxes are painted in stacking contexts. Within one context, the order is:

  1. child contexts with a negative z-index;
  2. block-level boxes in normal flow;
  3. floats;
  4. inline content;
  5. positioned boxes, and child contexts with z-index: auto or 0;
  6. child contexts with a positive z-index.

A box that creates its own context is painted as a unit at its place in that order.

Stacking contexts

A new stacking context is created by:

  • the root;
  • a positioned box with a z-index other than auto;
  • position: fixed or sticky;
  • a flex or grid item with a z-index;
  • opacity below 1;
  • mix-blend-mode other than normal;
  • isolation: isolate;
  • any filter, backdrop-filter or clip-path;
  • any transform, rotate, scale or translate.

Adding opacity or a transform to an ancestor (for example, for an animation) makes the whole subtree paint as one unit, which can move it in front of or behind content unexpectedly.

z-index only affects positioned boxes and flex or grid items. Hit testing follows the same order as painting: the topmost box under the pointer receives the event.

CSS pixels and device pixels

Lengths are in CSS pixels. The window's scale factor (1.0 on a standard display, 2.0 on a high-density one) converts them to device pixels.

app().with_size(360.0, 300.0)    // CSS pixels

You never multiply by the scale factor yourself. A 16px font is 16 CSS pixels on both displays and is drawn with more device pixels on the high-density one. When a window moves to a display with a different scale factor, sizes in CSS pixels stay the same, and every box is laid out again so its edges land on the new device-pixel grid.

Performance

Layout is incremental: a size change lays out the box, its descendants, and its ancestors up to the first one whose size does not depend on it. Colour, shadow and transform changes skip layout entirely, so prefer them for animation. The cost model has measured numbers, and The layout engine explains the implementation.

Next

On this page