Container

Width-constrained content container with size presets (xs to full) and background media props. Useful for centered hero content with full-bleed media backdrops.

// Plain markup
import { Container } from "@shavin/ui";

Constrained Reading Container

Centered container content with maximum width constraints.

Component Source

<Container size="md">
  <div className="border border-hairline p-4 rounded-[var(--radius-panel)] bg-surface text-sm text-fg">
    Centered container content with maximum width constraints.
  </div>
</Container>

Background Media

Container accepts bgVideo, bgImage, bgOverlays, bgSize, and bgVideoPaused props. Useful for centered hero content with a full-bleed 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.

Container with Background Image + Dark Overlay

A Container with a background image and dark-50 overlay. Content remains centered and readable.

Centered Hero

Container with bg image + dark-50 overlay

A Container with a background image and dark-50 overlay. Content remains centered and readable.

<Container
  size="lg"
  bgImage="https://images.unsplash.com/photo-1789953067753-6a1fcefe07d8"
  bgOverlays="dark-50"
  surface="dark-always"
  className="h-[300px] rounded-[var(--radius-panel)] overflow-hidden"
>
  <Flex direction="column" align="center" justify="center" gap="3" className="text-center">
    <Heading size="2xl">Centered Hero</Heading>
    <Text color="muted">Container with bg image + dark-50 overlay</Text>
    <Button size="lg">Learn More</Button>
  </Flex>
</Container>

Container with Background Video + Multi-Layer Overlays

Background video with three composited overlay layers — dark-20 base, gradient-radial focus, and a light-20 highlight.

Triple Layer

dark-20 + gradient-radial@60% + light-20@30%

Background video with three composited overlay layers — dark-20 base, gradient-radial focus, and a light-20 highlight.

<Container
  size="md"
  bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
  bgOverlays="dark-20, gradient-radial/60, light-20/30"
  surface="dark-always"
  className="h-[280px] rounded-[var(--radius-panel)] overflow-hidden"
>
  <Flex direction="column" align="center" justify="center" gap="2" className="text-center">
    <Heading size="xl">Triple Layer</Heading>
    <Text size="sm" color="muted">dark-20 + gradient-radial@60% + light-20@30%</Text>
  </Flex>
</Container>

Container with Custom Gradient + Token Overlay

Custom linear gradient with hex stops and a semantic accent token — all in shorthand.

Gradient + Accent

linear gradient + semantic accent token — shorthand only

Custom linear gradient with hex stops and a semantic accent token — all in shorthand.

<Container
  size="md"
  bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
  bgOverlays="linear(180deg, #000/0%, #000/100%)/70, (accent)/15"
  surface="dark-always"
  className="h-[300px] rounded-[var(--radius-panel)] overflow-hidden"
>
  <Flex direction="column" align="center" justify="center" gap="3" className="text-center">
    <Heading size="2xl">Gradient + Accent</Heading>
    <Text size="sm" color="muted">linear gradient + semantic accent token — shorthand only</Text>
    <Button size="lg">Get Started</Button>
  </Flex>
</Container>

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, main, article, 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.
size	"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full"	"md"	—