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.
- 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.
display | Children are placed |
|---|---|
block | stacked vertically; vertical margins collapse; floats apply |
flex | along one axis, sharing leftover space |
grid | into rows and columns you declare |
inline | as a run of text and inline boxes, broken into lines |
inline-block, inline-flex, inline-grid | inside, like block/flex/grid; outside, the box sits in a line of text |
contents | the element generates no box; its children take its place in the parent's layout |
none | no 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 forcolumn. - The cross axis is the other direction.
| Property | Axis | What it does |
|---|---|---|
justify-content | main | distributes leftover space along the main axis |
align-items | cross | aligns children on the cross axis |
align-self | cross | overrides align-items for one child |
align-content | cross | distributes space between lines when the container wraps |
gap, row-gap, column-gap | both | space 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:
| Property | Default | Meaning |
|---|---|---|
flex-grow | 0 | the share of extra space the child takes |
flex-basis | auto | the starting size before growing or shrinking; auto means its content size |
flex-shrink | 1 | the 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-rowsandgrid-template-columns. fris a share of the leftover space;repeat(4, 1fr)is four equal columns.- Sizes can mix:
240px 1fr 1fr, orrepeat(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
| Property | Meaning |
|---|---|
width, height | the size, as a length or a percentage |
min-width, min-height | a lower bound |
max-width, max-height | an upper bound |
aspect-ratio | derives one dimension from the other |
inline-size, block-size | logical 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:
| Keyword | Meaning |
|---|---|
min-content | as narrow as possible without overflowing; for text, the longest word |
max-content | as wide as the content wants with no wrapping |
fit-content | max-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 }position | Behaviour | Offsets are relative to |
|---|---|---|
static | the default; offsets are ignored | — |
relative | keeps its place in the flow, then shifts | its normal position |
absolute | removed from the flow | the nearest positioned ancestor, or the root |
fixed | removed from the flow, fixed to the window | the window |
sticky | in flow until it would scroll away, then sticks | its 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:
| Value | Behaviour |
|---|---|
visible | content spills out and is still drawn |
hidden | content is clipped |
auto | content is clipped and the box scrolls when needed |
scroll | the 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:
- child contexts with a negative
z-index; - block-level boxes in normal flow;
- floats;
- inline content;
- positioned boxes, and child contexts with
z-index: autoor0; - 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-indexother thanauto; position: fixedorsticky;- a flex or grid item with a
z-index; opacitybelow1;mix-blend-modeother thannormal;isolation: isolate;- any
filter,backdrop-filterorclip-path; - any
transform,rotate,scaleortranslate.
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 pixelsYou 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
Styling
Style elements with CSS — writing sheets with css!, style! and variants!, installing them, the cascade, state selectors, custom properties, and a reference of supported CSS.
Effects and lifecycle
Run your own code when state changes with RenderEffect, clean up with on_cleanup_local, keep untracked state in StoredValue, know when components mount, rebuild and unmount, and reach elements through NodeRef.