Appearance
Grid
Grid is a generic, presentational layout primitive built on CSS Grid. It arranges arbitrary children into equal or custom-width columns, with gap control, responsive reflow, auto-fit sizing, and optional cell spanning via Grid.Item. It makes no assumptions about your data — children simply flow into the tracks you define.
Grid vs. Layout: Use
Layoutfor top-level page scaffolding (header + fixed-width sidebars + main content). UseGridfor content grids within a page — KPI cards, galleries, field groups, dashboards. They are complementary; reach forGridwhenever you just need "arrange these N things into columns."
Import
tsx
import { Grid } from "@tailor-platform/app-shell";The examples below also import Card and Text from @tailor-platform/app-shell.
Basic Usage
tsx
function BasicUsage() {
return (
<Grid columns={3} gap={4}>
<Card.Root>One</Card.Root>
<Card.Root>Two</Card.Root>
<Card.Root>Three</Card.Root>
</Grid>
);
}Plain children occupy a single cell. Wrap a child in Grid.Item only when it needs to span multiple tracks or be placed explicitly.
Sub-components
| Sub-component | Description |
|---|---|
Grid | The grid container — defines columns, rows, gap, and alignment |
Grid.Item | An optional cell that spans multiple columns/rows or is placed by line |
Props
Grid Props
| Prop | Type | Default | Description |
|---|---|---|---|
columns | number | string | Responsive<number | string> | - | A number creates that many equal columns; a string is a verbatim grid-template-columns value |
rows | number | string | Responsive<number | string> | - | Same shape as columns, for grid-template-rows |
gap | number | Responsive<number> | 3 (12px) | Gap between rows and columns, in spacing-scale units (4 → 1rem) |
gapX | number | Responsive<number> | - | Horizontal (column) gap override |
gapY | number | Responsive<number> | - | Vertical (row) gap override |
minChildWidth | number | string | - | Auto-fit: each item is at least this wide and as many as fit are placed per row. Overrides columns |
flow | "row" | "column" | "dense" | "row-dense" | "column-dense" | "row" | grid-auto-flow — placement direction and dense packing |
align | "start" | "center" | "end" | "stretch" | "baseline" | - | align-items — block-axis alignment of items within their tracks |
justify | "start" | "center" | "end" | "between" | "around" | "evenly" | - | justify-content — inline-axis distribution of tracks within the grid |
className | string | - | Additional CSS classes |
children | React.ReactNode | - | Grid items (any elements, or Grid.Item) |
All standard HTML <div> props are also accepted.
Grid.Item Props
| Prop | Type | Default | Description |
|---|---|---|---|
colSpan | number | "full" | Responsive<number | "full"> | - | Columns to span, or "full" for all columns |
rowSpan | number | "full" | Responsive<number | "full"> | - | Rows to span, or "full" for all rows |
colStart | number | Responsive<number> | - | 1-based column line to start at (grid-column-start) |
colEnd | number | Responsive<number> | - | 1-based column line to end at (grid-column-end) |
className | string | - | Additional CSS classes |
children | React.ReactNode | - | Cell content |
All standard HTML <div> props are also accepted.
Responsive values
columns, rows, gap, gapX, gapY, and every Grid.Item prop accept either a single value (applied at all breakpoints) or a breakpoint object. Breakpoints align with Tailwind: initial (base), sm, md, lg, xl, 2xl.
tsx
function ResponsiveValues() {
return (
<Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
{["Revenue", "Orders", "Customers", "Returns"].map((title) => (
<Card.Root key={title}>
<Card.Content>{title}</Card.Content>
</Card.Root>
))}
</Grid>
);
}Sizing columns
There are three ways to size columns; pick whichever fits.
tsx
function ColumnSizing() {
return (
<div className="space-y-4">
<Text.p>Equal columns</Text.p>
<Grid columns={4} gap={4}>
{["One", "Two", "Three", "Four"].map((label) => (
<Card.Root key={label}>
<Card.Content>{label}</Card.Content>
</Card.Root>
))}
</Grid>
<Text.p>Custom track widths</Text.p>
<Grid columns="280px 1fr" gap={6}>
<Card.Root>
<Card.Content>280px</Card.Content>
</Card.Root>
<Card.Root>
<Card.Content>Remaining width</Card.Content>
</Card.Root>
</Grid>
<Text.p>Auto-fit columns, at least 240px wide</Text.p>
<Grid minChildWidth={240} gap={4}>
{["One", "Two", "Three"].map((label) => (
<Card.Root key={label}>
<Card.Content>{label}</Card.Content>
</Card.Root>
))}
</Grid>
</div>
);
}minChildWidth accepts a number (pixels) or a string (e.g. "16rem") and takes precedence over columns when set.
Spanning with Grid.Item
tsx
function Spanning() {
return (
<Grid columns={4} gap={4}>
<Grid.Item colSpan={2} className="rounded-lg border p-4">
Wide card
</Grid.Item>
<Card.Root>
<Card.Content>Normal</Card.Content>
</Card.Root>
<Grid.Item colSpan={{ initial: "full", md: 1 }} rowSpan={2} className="rounded-lg border p-4">
Tall
</Grid.Item>
<Grid.Item colSpan="full" className="rounded-lg border p-4">
Full-width footer row
</Grid.Item>
</Grid>
);
}Alignment
align aligns items within their row (visible when row height exceeds the item), justify distributes the columns when they are narrower than the container (e.g. fixed-width tracks), and flow controls placement order:
tsx
function Alignment() {
return (
<Grid columns="repeat(3, 96px)" rows="120px" gap={4} justify="between" align="center">
<Card.Root>
<Card.Content>One</Card.Content>
</Card.Root>
<Card.Root>
<Card.Content>Two</Card.Content>
</Card.Root>
<Card.Root>
<Card.Content>Three</Card.Content>
</Card.Root>
</Grid>
);
}Note:
justifyonly has a visible effect when the tracks do not fill the container. With fluidcolumns={n}(which uses1frtracks) the columns always fill the width, sojustifyis a no-op — use fixed-width tracks to distribute columns. Likewise,flow="…-dense"only differs from the default when items span multiple cells and leave gaps to backfill.
Examples
Responsive KPI grid
tsx
<Grid columns={{ initial: 1, sm: 2, lg: 4 }} gap={4}>
{metrics.map((m) => (
<MetricCard key={m.id} title={m.label} value={m.value} />
))}
</Grid>Auto-fitting card gallery
tsx
<Grid minChildWidth={240} gap={6}>
{products.map((p) => (
<Card.Root key={p.sku}>
<Card.Header title={p.name} description={p.sku} />
</Card.Root>
))}
</Grid>Sidebar + content (custom widths)
tsx
function SidebarContent() {
return (
<Grid columns="280px 1fr" gap={6}>
<Card.Root>
<Card.Header title="Filters" />
<Card.Content>
<Text.p>Status: Confirmed</Text.p>
</Card.Content>
</Card.Root>
<Card.Root>
<Card.Header title="Results" />
<Card.Content>
<Text.p>12 matching orders</Text.p>
</Card.Content>
</Card.Root>
</Grid>
);
}Dashboard with a featured panel
tsx
function FeaturedPanel() {
return (
<Grid columns={{ initial: 1, md: 4 }} gap={4}>
<Grid.Item colSpan={{ initial: "full", md: 2 }}>
<Card.Root>
<Card.Content>Featured</Card.Content>
</Card.Root>
</Grid.Item>
<Card.Root>
<Card.Content>Revenue: $2,400</Card.Content>
</Card.Root>
<Card.Root>
<Card.Content>Orders: 142</Card.Content>
</Card.Root>
</Grid>
);
}Styling
Grid is a presentational primitive: it renders a single <div data-slot="grid"> (and <div data-slot="grid-item"> for cells) styled with the library's internal astw:-prefixed utilities. Dynamic templates are applied via CSS custom properties, so arbitrary column counts and responsive values work without extra configuration. Pass className (plain utilities — see Styling AppShell components) or style to extend. Use columns and gap for the grid itself.
Related Components
- Layout - Page-level scaffold (header + sidebars + main)
- Card - Common child of a grid cell
- MetricCard - KPI cards for dashboard grids