Grid
CSS Grid container — columns, rows, gap, templateColumns, templateRows, and the rest of the grid API as token-aware props. The right reach when you need explicit row × column placement.
Plain <div>. Grid layout has no implicit semantics — pair with semantic children (<article>, headings) when grid items represent content; otherwise leave a Grid as a layout-only wrapper.
Preview
tsx
import { Box, Grid } from '@arshad-shah/cynosure-react';
export default function Example() {
return (
<Grid
columns={{ base: 1, sm: 2, md: 3 }}
gap="3"
padding="4"
background="bg.subtle"
borderRadius="md"
>
<Box padding="3" background="bg.surface" borderRadius="sm">
A
</Box>
<Box padding="3" background="bg.surface" borderRadius="sm">
B
</Box>
<Box padding="3" background="bg.surface" borderRadius="sm">
C
</Box>
</Grid>
);
}
Columns (responsive)
Section titled “Columns (responsive)”The shortcut columns={n} produces an evenly-divided n-column track. Pass a responsive map to shift column count per breakpoint — the most common dashboard / card-grid pattern.
Preview
tsx
import { Box, Grid } from '@arshad-shah/cynosure-react';
const CELLS = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'];
export default function Example() {
return (
<Grid
columns={{ base: 1, sm: 2, md: 3, lg: 4 }}
gap="3"
padding="4"
background="bg.subtle"
borderRadius="md"
>
{CELLS.map((cell) => (
<Box key={cell} padding="3" background="bg.surface" borderRadius="sm">
Cell {cell}
</Box>
))}
</Grid>
);
}
Explicit tracks
Section titled “Explicit tracks”templateColumns accepts a raw grid-template-columns string (or a responsive map) when you need non-uniform tracks — e.g. "240px 1fr" for a sidebar + main shell. Combine with gridColumn / gridRow on children to span tracks.
Preview
tsx
import { Box, Grid } from '@arshad-shah/cynosure-react';
export default function Example() {
return (
<Grid templateColumns="160px 1fr" gap="3" padding="4" background="bg.subtle" borderRadius="md">
<Box padding="3" background="bg.surface" borderRadius="sm">
Sidebar (160px)
</Box>
<Box padding="3" background="bg.surface" borderRadius="sm">
Main column (1fr)
</Box>
<Box padding="3" background="bg.surface" borderRadius="sm" gridColumn="1 / -1">
Footer (spans both columns)
</Box>
</Grid>
);
}
PropTypeDefaultDescription
className
string
—
Additional class names appended after Cynosure's base classes.
style
CSSProperties
—
Inline style overrides merged last.
children
ReactNode
—
Grid children. Use `LayoutProps.gridColumn`/`gridRow`/`gridArea` on
children for placement.
columns
Responsive<number>
—
Column-count shorthand — emits `repeat(N, minmax(0, 1fr))`.
Superseded by `templateColumns` when both are set.
rows
Responsive<number>
—
Row-count shorthand — emits `repeat(N, minmax(0, auto))`.
Superseded by `templateRows` when both are set.
templateColumns
Responsive<string>
—
Raw `grid-template-columns` — use for mixed tracks like
`"200px 1fr 200px"`. Wins over `columns`.
autoFlow
Responsive<GridAutoFlow>
—
`grid-auto-flow` — direction new tracks are added (`row`, `column`, or
`dense` variants).
align
Responsive<GridAlignItems>
—
`align-items` — how each item sits within its cell on the block axis.
justifyItems
Responsive<GridAlignItems>
—
`justify-items` — how each item sits within its cell on the inline axis.
alignContent
Responsive<GridJustifyContent>
—
`align-content` — how tracks are distributed when the grid is shorter
than its container on the block axis.
justify
Responsive<GridJustifyContent>
—
`justify-content` — how tracks are distributed along the inline axis.
Matches Radix/Chakra semantics.
paddingX
—
Horizontal padding (left + right). Overrides `padding` on the X axis.
paddingY
—
Vertical padding (top + bottom). Overrides `padding` on the Y axis.
height
—
Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.
minWidth
—
Minimum width — useful for preventing flex children from collapsing.
background
—
Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.
borderColor
—
Border colour. Pair with `borderWidth` to make the border visible.
opacity
Responsive<number | `${number}`>
—
Opacity 0–1. Use sparingly — prefer surface tokens over translucency.
overflowX
—
Horizontal-axis overflow control. Overrides `overflow` for the X axis.
display
—
CSS `display` value. `"contents"` removes the element's box from layout.
position
—
CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.
top
—
Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.
flex
Responsive<"1" | "none" | "auto" | "initial" | (string & {})>
—
Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.
asChild
boolean
—
When `true`, renders the primitive's single React child via `Slot`,
forwarding className/style/ref/event handlers onto it.
as
ElementType
"div"
Rendered intrinsic element or component.
ref
ForwardedRef<Element>
—
Recipes
Section titled “Recipes”- Card grids:
<Grid columns={{ base: 1, sm: 2, lg: 3, xl: 4 }} gap="4" />is the canonical responsive card layout. - For uniform columns without writing the responsive map, reach for
SimpleGrid— it’sGridtuned for the 90% case. - App shells with sidebar + main:
templateColumns="240px 1fr"keeps the sidebar pinned and the main column responsive in one prop. Boxand every layout primitive exposegridArea,gridColumn,gridRowso a Grid child can claim a span without a wrapper.