Grid
CSS Grid container primitive supporting column/row counts, token gap scale, cross-axis alignment, and background media props (bgVideo, bgImage, bgOverlays, bgSize, bgVideoPaused).
// Plain markup
import { Grid } from "@shavin/ui";Responsive 3-Column Grid
<Grid columns="3" gap="4">
<Card p="4">Card 1</Card>
<Card p="4">Card 2</Card>
<Card p="4">Card 3</Card>
</Grid>Background Media
Grid accepts bgVideo, bgImage, bgOverlays, bgSize, and bgVideoPaused props. Useful for feature grids with a shared media backdrop.bgOverlays supports comma-separated shorthand: presets (dark-50), hex colors (#ff5733/50), semantic tokens ((accent)/30), and gradients (linear(45deg, #000/0%, #000/100%)/80). Mix freely in one string.
Grid with Background Image + Vignette Overlay
A 2-column grid with a background image and vignette overlay. Card content remains readable above the media.
Feature One
Grid items render above the media layer.
Feature Two
Vignette overlay focuses attention center.
<Grid
columns="2"
gap="4"
bgImage="https://images.unsplash.com/photo-1719841602002-1dcc795bed24-4636190af475?w=1200"
bgOverlays="vignette"
surface="dark-always"
className="h-[300px] rounded-[var(--radius-panel)] overflow-hidden p-6"
>
<Card className="p-4 bg-surface/80 backdrop-blur">
<Heading size="sm">Feature One</Heading>
<Text size="xs" color="muted">Grid items render above the media layer.</Text>
</Card>
<Card className="p-4 bg-surface/80 backdrop-blur">
<Heading size="sm">Feature Two</Heading>
<Text size="xs" color="muted">Vignette overlay focuses attention center.</Text>
</Card>
</Grid>Grid with Background Video + Multi-Layer Overlays
Background video with two overlay layers: a dark-30 base scrim and a gradient-radial for centered focus.
Item 1
Item 2
Item 3
<Grid
columns="3"
gap="3"
bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
bgOverlays="dark-30, gradient-radial/70"
surface="dark-always"
className="h-[280px] rounded-[var(--radius-panel)] overflow-hidden p-6"
>
<Text size="xs" color="muted">Item 1</Text>
<Text size="xs" color="muted">Item 2</Text>
<Text size="xs" color="muted">Item 3</Text>
</Grid>Grid with Custom Gradient + Token Overlay
Custom linear gradient with hex stops and a semantic accent token — no JSON needed for gradients.
Linear gradient + accent token
Shorthand only — no JSON
<Grid
columns="2"
gap="3"
bgImage="https://images.unsplash.com/photo-1719841602002-1dcc795bed24-4636190af475?w=1200"
bgOverlays="linear(180deg, #1a1a2e/0%, #1a1a2e/100%)/60, (accent)/15"
surface="dark-always"
className="h-[280px] rounded-[var(--radius-panel)] overflow-hidden p-6"
>
<Text size="xs" color="muted">Linear gradient + accent token</Text>
<Text size="xs" color="muted">Shorthand only — no JSON</Text>
</Grid>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 | "(accent)/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%. |
| radial(stops)/opacity | "radial((accent)/0%, (accent)/100%)/60" | Radial gradient with color stops. No angle needed. |
Combine multiple layers with commas. Mix presets, solids, and gradients freely:
bgOverlays="dark-20, (accent)/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)), and gradients (linear/radial). 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" | — |