Grid
Grid is the explicit two-dimensional layout primitive in Fission.
It lets you define row and column tracks and then place children into those tracks, usually by wrapping them in GridItem. This is the right tool when both axes matter at the same time, such as dashboards, inspector panels, data-heavy cards, or editorial layouts.
Use Grid when track definitions are meaningful. Do not use it when you only need a vertical stack, a horizontal row, or a responsive card wrap. Those cases are usually easier with Column, Row, or SimpleGrid.
Example
use fission::prelude::*;
const PRODUCT_CARD_MIN_WIDTH: f32 = 220.0;
let (_ctx, view) = fission::build::current::<CatalogState>();
let spacing = &view.env().theme.tokens.spacing;
let widget: Widget = Grid {
columns: vec![GridTrack::auto_fit(GridTrack::minmax(
GridTrack::Points(PRODUCT_CARD_MIN_WIDTH),
GridTrack::Fr(1.0),
))],
rows: vec![GridTrack::Auto],
column_gap: Some(spacing.l),
row_gap: Some(spacing.l),
children: cards
.iter()
.map(|card| GridItem::new(ProductCard { card }).into())
.collect(),
..Default::default()
}
.into();
Field table
Field | Type | Meaning | Notes / default behavior |
|---|---|---|---|
id | Option<WidgetId> | Stable widget identity. | Defaults to None. |
children | Vec<Widget> | Grid children, usually GridItem nodes. | Defaults to an empty list. |
columns | Vec<GridTrack> | Column track definitions. | Defaults to an empty list, so define these explicitly in real layouts. |
rows | Vec<GridTrack> | Row track definitions. | Defaults to an empty list. |
column_gap | Option<f32> | Horizontal gap between columns. | Defaults to None. |
row_gap | Option<f32> | Vertical gap between rows. | Defaults to None. |
padding | [f32; 4] | Inner padding in [left, right, top, bottom] order. | Defaults to [0.0; 4]. |
Track types you will encounter
Track type | Meaning | When to use it |
|---|---|---|
GridTrack::Points(x) | Fixed track size in layout points. | Use for known fixed rails such as headers or side gutters. |
GridTrack::Percent(x) | Track as a percentage. | Use when the design is explicitly percentage-based. |
GridTrack::Fr(x) | Fractional remaining space. | Use for most flexible dashboard-style layouts. |
GridTrack::Auto | Size from content and constraints. | Good for content-driven tracks. |
GridTrack::MinContent / MaxContent | Content-based intrinsic sizing. | Use only when you intentionally want intrinsic track behavior. |
GridTrack::minmax(min, max) | Track constrained between two track definitions. | Use for responsive cards that should never shrink below a readable size. |
GridTrack::repeat(count, tracks) | Fixed repeated track list. | Use for regular grids with a known number of columns or rows. |
GridTrack::auto_fit(track) | Repeat a track up to the available space and collapse empty tracks. | Use for responsive product or card grids. |
GridTrack::auto_fill(track) | Repeat a track up to the available space and keep empty tracks. | Use when empty slots should still reserve grid space. |
Specific advice
Choose Grid because it matches the structure of the problem, not because it feels more powerful. If the layout is really one-dimensional, using Grid often makes the code harder to read.
When you do use it, define tracks intentionally. A grid with clear Fr, Points, or Auto choices is easier to maintain than a grid that tries to guess everything.
Production checklist
For Grid, review the fields that change behavior before treating the widget as finished: id, children, columns, rows, column_gap, row_gap. The goal is to make the product rule visible in state and actions, not hidden inside ad-hoc construction code.
•
If this widget appears inside an interactive flow, keep the surrounding action binding in the parent component and test that the flow still has one clear reducer path.
•
When child widgets are generated from data, give reordered or filtered rows an explicit WidgetId so retained local state and scroll behavior do not drift between items.
•
Set id only when identity must be stable across filtering, reordering, diagnostics, or tests; otherwise let Fission derive identity from structure.
•
Check the semantics tree for the user-facing label or role that makes this widget understandable without relying only on pixels.
•
Prefer parent layout and design-system sizing first; use explicit size or spacing fields when the product layout requires that constraint on this widget specifically.
•
Add at least one component or harness test that confirms the visible text, semantic role, action dispatch, and layout constraint that matter for this widget in context.
If a screen starts repeating the same Grid setup, extract a named component around this widget. That keeps the reference API small while making product code easier to read and safer for generated code to copy.
Related
GridItem, SimpleGrid, Row, and Column.
Previous
Responsive
Next
GridItem