Grid
CSS Grid host — fixed columns, auto-fill tracks, and token gap and padding.
Grid lays out children on a CSS Grid with Vira-owned props instead of hand-written grid-template rules. Reach for it when placement is truly two-dimensional: dashboards, form columns, media tiles, and bento boards.
Set columns for a fixed track count (columns={N} builds fluid 1fr tracks), or leave columns unset and use filling with colMinWidth for responsive auto-fill / auto-fit. Gap and padding props read the same spacing tokens as Stack; hPadding and vPadding also accept [start, end] tuples.
Grid.Item owns placement: fullWidth / fullHeight, column / row spans, or subgrid when a cell should inherit parent tracks. Pass render when the grid or an item should be a semantic element.
Anatomy
Import the component and assemble its parts:
import { Grid } from '@viraui/react';
<Grid>
<Grid.Item />
</Grid>When to use
- Fixed columns, spans, or full-width bands on a shared track grid
- Responsive auto-fill / auto-fit walls from a minimum track width
- Dashboards and form layouts where row and column placement both matter
When not to use
- A single flex axis is enough → Stack
- Tile heights vary and should pack into columns → Masonry
- You only need panel chrome (color, border, radius) → Surface
Related
- Stack — default single-axis flex host
- Masonry — variable-height column packing
- Surface — themed chrome inside grid cells
- Elevator — resting / hover shadow on cell roots
Common examples
Fixed columns
A fixed track count keeps cards in even columns. Pair columnGap / rowGap with hPadding / vPadding so spacing stays on the theme scale.
Spanning items
Grid.Item breaks the default 1×1 cell when a block needs more tracks. Prefer fullWidth for a banner across every column, or row="span N" / column="span N" for a partial span. Placement stays on the item props.
Bento grid
Reach for asymmetric column / row spans when tiles should not share equal weight: feature boards, marketing mosaics, and dashboard walls where a hero cell sits beside shorter companions.
Auto-fill tracks
When columns is unset, filling defaults to 'fill' and builds repeat(auto-fill, …) tracks sized from colMinWidth (default 10rem). Pass filling="fit" for auto-fit, or false to skip the filling attribute. Tracks reflow as the host width changes; useful for media walls and card libraries.
Ask your agent
Build a two-column settings module grid with token gap and padding — Team access, Notifications, Billing, and Security cards.Last updated on