Skip to content

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

Component Source
<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

Component Source
<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.

Component Source
<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.

Component Source
<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>
PropTypeDefault
bgImage

Image URL rendered behind the children with object-cover.

string—
bgVideo

Video URL rendered as a muted, looping, autoplaying background.

string—
bgPoster

Poster for bgVideo. Shown while loading and when the visitor prefers reduced motion.

string—
bgSize

How the media fits the box.

"cover" | "contain""cover"
bgOverlays

Comma-separated overlay layers, composited top to bottom. See Overlay presets below.

string—
bgVideoPaused

Set 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:

SyntaxExampleDescription
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.

PreviewPresetDescription
dark-20Solid black at 20% opacity — subtle darkening for light readability.
dark-30Solid black at 30% opacity — moderate darkening.
dark-50Solid black at 50% opacity — strong darkening for white text legibility.
dark-75Solid black at 75% opacity — heavy darkening for dramatic contrast.
light-20Solid white at 20% opacity — subtle lightening for dark readability.
light-30Solid white at 30% opacity — moderate lightening.
light-50Solid white at 50% opacity — strong lightening for dark text legibility.
gradient-bottomLinear gradient from transparent (top) to 80% black (bottom) — for bottom-aligned text overlays.
gradient-topLinear gradient from transparent (bottom) to 80% black (top) — for top-aligned text overlays.
gradient-radialRadial gradient from transparent (center) to 85% black (edges) — focused-center vignette.
vignetteRadial gradient from transparent (40% radius) to 85% black (edges) — classic vignette.
scrimSoft linear gradient from 10% (top) to 85% (bottom) black — gentle content scrim.

Props

PropTypeDefaultDescription
bgVideostring—Background video URL (mp4, webm, etc.). Renders an autoPlay/loop/muted <video> element behind children.
bgImagestring—Background image URL. Renders an <img> with object-cover (default) or object-contain.
bgSize"cover" | "contain"coverBackground media fit. "cover" fills the container (default), "contain" fits within.
bgOverlaysstring—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.
bgVideoPausedbooleanfalseWhen true, pauses the background video (renders a static poster frame instead of autoplay).
asElementTypedivPolymorphic element tag: div, section, ul, etc. Default "div".
translucentboolean—Whether to apply translucent panel styling with data-panel attribute.
surfaceSurface—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"—
Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font