Grid layout
Lay UI out in rows and columns with Display::Grid: track sizes with GridTrack and RepeatedGridTrack, placing and spanning items, auto flow and alignment.
Flexbox lays children out along one line. Grid lays them out in rows and columns at once, which suits inventories, level-select screens, scoreboards and whole-screen frames with a header, sidebar and footer. It follows the CSS grid rules.
Set display: Display::Grid on the parent and describe its tracks (columns and rows). Children fill the cells in order unless you place them.
An inventory#
commands.spawn((
Node {
display: Display::Grid,
width: px(420),
aspect_ratio: Some(6.0 / 4.0),
grid_template_columns: RepeatedGridTrack::flex(6, 1.0),
grid_template_rows: RepeatedGridTrack::flex(4, 1.0),
row_gap: px(6),
column_gap: px(6),
padding: px(6).all(),
..default()
},
BackgroundColor(Color::srgb(0.12, 0.12, 0.16)),
)).with_children(|grid| {
for _ in 0..24 {
grid.spawn((Node::default(), BackgroundColor(Color::srgb(0.25, 0.25, 0.3))));
}
});Track sizes#
grid_template_columns and grid_template_rows are lists of tracks. Build single tracks with GridTrack and repeated ones with RepeatedGridTrack; both convert into the list's element type, so you can mix them with vec![...].
GridTrack:: | CSS | Size |
|---|---|---|
px(100.) | 100px | Fixed. |
percent(25.) | 25% | Percent of the grid. |
flex(1.0) | minmax(0, 1fr) | A share of the leftover space; can shrink to nothing. Usually what you want. |
fr(1.0) | 1fr | A share of the leftover space, but never smaller than its content. |
auto() | auto | Sized by content, stretched to fill. |
min_content(), max_content() | min-content, max-content | The content's smallest or largest size. |
fit_content_px(200.) | fit-content(200px) | Content size, capped. |
minmax(min, max) | minmax() | Between two sizing functions. |
RepeatedGridTrack::flex(4, 1.0) is four flex(1.0) tracks. The repetition can also be GridTrackRepetition::AutoFill or AutoFit to fit as many tracks as there's room for: RepeatedGridTrack::px(GridTrackRepetition::AutoFill, 64.).
Node {
display: Display::Grid,
width: percent(100),
height: percent(100),
grid_template_columns: vec![GridTrack::min_content(), GridTrack::flex(1.0)],
grid_template_rows: vec![GridTrack::auto(), GridTrack::flex(1.0), GridTrack::px(20.)],
..default()
}grid_auto_rows and grid_auto_columns size tracks the grid adds when there are more children than cells.
Place and span items#
A child's grid_column and grid_row say where it goes. Lines are numbered from 1; negative numbers count from the end.
GridPlacement:: | What it does |
|---|---|
auto() | The next free cell (the default). |
span(n) | Take n tracks, placed automatically. |
start(i), end(i) | Start or end at line i. |
start_span(i, n) | Start at line i and take n tracks. |
start_end(i, j) | From line i to line j. |
Node {
grid_column: GridPlacement::span(2),
padding: px(6).all(),
..default()
}grid_auto_flow sets the order automatic placement fills cells: GridAutoFlow::Row (the default), Column, RowDense or ColumnDense. The dense variants back-fill gaps left by spanning items.
Alignment#
Inside its cell, a child is placed by the grid's justify_items (horizontal) and align_items (vertical), or its own justify_self and align_self. The default stretches children to fill the cell. justify_content and align_content position the tracks inside the grid when they don't fill it.
Examples#
| Example | What it shows |
|---|---|
grid | A full-screen frame with header, sidebar, footer, a square grid of cells and an overlay. |
Run it from the engine core's workspace: cargo run --example grid.