Grid
Lays children out in columns. Set a count, or let it fit as many as the space allows. It can carry a background image or video.
// Plain markup
import { Grid } from "@shavin/ui";Auto-fit card grid
The recommended pattern for card grids. columns="auto" fits as many columns as the container allows at minWidth (xs to xl, default md). maxColumns caps the count. No breakpoints needed.
Groceries
$412 of $600 spent
Utilities
$188 of $220 spent
Dining out
$96 of $150 spent
Transport
$74 of $120 spent
<Grid columns="auto" minWidth="sm" maxColumns="4" gap="4">
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Groceries</Text>
<Text size="sm" className="text-fg-subtle">$412 of $600 spent</Text>
</Flex>
</Card>
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Utilities</Text>
<Text size="sm" className="text-fg-subtle">$188 of $220 spent</Text>
</Flex>
</Card>
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Dining out</Text>
<Text size="sm" className="text-fg-subtle">$96 of $150 spent</Text>
</Flex>
</Card>
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Transport</Text>
<Text size="sm" className="text-fg-subtle">$74 of $120 spent</Text>
</Flex>
</Card>
</Grid>Fixed columns
A number fixes the column count. stack defaults to none, so columns never collapse. Set stack="auto" to drop to two columns below large screens and one on mobile.
Groceries
$412 of $600 spent
Utilities
$188 of $220 spent
Dining out
$96 of $150 spent
<Grid columns="3" gap="4" stack="auto">
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Groceries</Text>
<Text size="sm" className="text-fg-subtle">$412 of $600 spent</Text>
</Flex>
</Card>
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Utilities</Text>
<Text size="sm" className="text-fg-subtle">$188 of $220 spent</Text>
</Flex>
</Card>
<Card padding="sm">
<Flex direction="column" gap="3">
<Text weight="semibold" className="text-fg">Dining out</Text>
<Text size="sm" className="text-fg-subtle">$96 of $150 spent</Text>
</Flex>
</Card>
</Grid>Background media
Grid takes the shared background media props: bgImage or bgVideo for the media and bgOverlays for legibility layers. Children render above the media. Use it when a feature grid shares one backdrop.
Image with a gradient overlay
Field notes
gradient-bottom keeps the caption readable.
<Grid
bgImage="https://images.unsplash.com/photo-1789953067753-6a1fcefe07d8?w=1200"
bgOverlays="gradient-bottom"
surface="dark-always"
className="h-[260px] overflow-hidden rounded-[var(--radius-panel)]"
>
<Flex direction="column" justify="end" gap="2" className="h-full p-6">
<Heading size="lg">Field notes</Heading>
<Text size="sm" color="muted">gradient-bottom keeps the caption readable.</Text>
</Flex>
</Grid>Video with layered overlays
Live backdrop
A dark layer plus a brand tint, in one string.
<Grid
bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
bgOverlays="dark-30, (brand)/15"
surface="dark-always"
className="h-[260px] overflow-hidden rounded-[var(--radius-panel)]"
>
<Flex direction="column" align="center" justify="center" gap="2" className="h-full p-6 text-center">
<Heading size="xl">Live backdrop</Heading>
<Text size="sm" color="muted">A dark layer plus a brand tint, in one string.</Text>
</Flex>
</Grid>| Prop | Type | Default |
|---|---|---|
bgImageImage URL rendered behind the children with object-cover. | string | — |
bgVideoVideo URL rendered as a muted, looping, autoplaying background. | string | — |
bgPosterPoster for bgVideo. Shown while loading and when the visitor prefers reduced motion. | string | — |
bgSizeHow the media fits the box. | "cover" | "contain" | "cover" |
bgOverlaysComma-separated overlay layers, composited top to bottom. See Overlay presets below. | string | — |
bgVideoPausedSet to "true" to show a still frame instead of playing the video. | "true" | "false" | — |
Overlay presets
bgOverlays accepts comma-separated shorthand for all overlay types. Presets (below) are the simplest form. You can also use solid colors and gradients:
| Syntax | Example | Description |
|---|---|---|
| presetKey | "dark-50" | Named preset at 100% opacity. |
| presetKey/opacity | "scrim/90" | Named preset at custom opacity (0–100). |
| #hex/opacity | "#ff5733/50" | Solid hex color with optional opacity. |
| (token)/opacity | "(brand)/30" | Semantic token color with optional opacity. |
| linear(angle, stops)/opacity | "linear(45deg, #000/0%, #000/100%)/80" | Linear gradient with angle and color stops. Each stop: color/offset%, optionally /opacity after it ("(canvas)/96%/80"). |
| radial(stops)/opacity | "radial((brand)/0%, (brand)/100%)/60" | Radial gradient with color stops. No angle needed; "at 20% 30%," moves the centre. |
| fx:key(params)/opacity | "fx:fluid-silk(speed=1.2)" | Fx backdrop; needs @shavin/fx registered, else falls back to mesh. Params are key=value; quote text with spaces in '…'. |
Combine multiple layers with commas. Mix presets, solids, and gradients freely:
bgOverlays="dark-20, (brand)/30, linear(90deg, #000/0%, #000/80%)/70"Preset keys below are shorthand for common scrim/gradient patterns. The preview column shows the overlay composited over a checkerboard.
| Preview | Preset | Description |
|---|---|---|
| dark-20 | Solid black at 20% opacity — subtle darkening for light readability. | |
| dark-30 | Solid black at 30% opacity — moderate darkening. | |
| dark-50 | Solid black at 50% opacity — strong darkening for white text legibility. | |
| dark-75 | Solid black at 75% opacity — heavy darkening for dramatic contrast. | |
| light-20 | Solid white at 20% opacity — subtle lightening for dark readability. | |
| light-30 | Solid white at 30% opacity — moderate lightening. | |
| light-50 | Solid white at 50% opacity — strong lightening for dark text legibility. | |
| gradient-bottom | Linear gradient from transparent (top) to 80% black (bottom) — for bottom-aligned text overlays. | |
| gradient-top | Linear gradient from transparent (bottom) to 80% black (top) — for top-aligned text overlays. | |
| gradient-radial | Radial gradient from transparent (center) to 85% black (edges) — focused-center vignette. | |
| vignette | Radial gradient from transparent (40% radius) to 85% black (edges) — classic vignette. | |
| scrim | Soft linear gradient from 10% (top) to 85% (bottom) black — gentle content scrim. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| bgVideo | string | — | Background video URL (mp4, webm, etc.). Renders an autoPlay/loop/muted <video> element behind children. |
| bgImage | string | — | Background image URL. Renders an <img> with object-cover (default) or object-contain. |
| bgSize | "cover" | "contain" | cover | Background media fit. "cover" fills the container (default), "contain" fits within. |
| bgOverlays | string | — | Comma-separated shorthand for overlay layers. Supports presets ("dark-50"), solid colors (#hex or (token)), gradients (linear/radial), and fx backdrops ("fx:dither-waves", "fx:fluid-silk(speed=1.2)"; needs @shavin/fx registered, else falls back to mesh). JSON array of OverlayLayer[] as fallback for advanced cases. Layers composite top-to-bottom. |
| bgVideoPaused | boolean | false | When true, pauses the background video (renders a static poster frame instead of autoplay). |
| as | ElementType | div | Polymorphic element tag: div, section, ul, etc. Default "div". |
| translucent | boolean | — | Whether to apply translucent panel styling with data-panel attribute. |
| surface | Surface | — | Surface contrast scope intent. "dark"/"light" auto-invert against the page theme (contrast band). "dark-always"/"light-always" lock to one theme regardless of page (for media backgrounds). Undefined inherits page theme. |
| columns | "1" | "2" | "3" | "4" | "5" | "6" | "auto" | "2" | — |
| minWidth | "xs" | "sm" | "md" | "lg" | "xl" | "md" | — |
| maxColumns | "none" | "2" | "3" | "4" | "5" | "6" | "none" | — |
| rows | "1" | "2" | "3" | "4" | "5" | "6" | — | — |
| align | "start" | "center" | "end" | "stretch" | "stretch" | — |
| stack | "none" | "auto" | "mobile" | "tablet" | "none" | — |
| gap | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "4" | — |