Box
Generic div-based container primitive with translucent panel support and background media props. Useful for media-backed panels and callout boxes.
// Plain markup
import { Box } from "@shavin/ui";Basic Box Container
<Box className="p-4 border border-hairline rounded-[var(--radius-panel)] bg-surface text-sm text-fg">
This is a Box container element.
</Box>Background Media
Box accepts bgVideo, bgImage, bgOverlays, bgSize, and bgVideoPaused props. Useful for media-backed panels and callout boxes.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.
Box with Background Image + Gradient Overlay
A Box with a background image and gradient-bottom overlay for text legibility at the bottom.
Media Panel
gradient-bottom overlay ensures text readability.
<Box
bgImage="https://images.unsplash.com/photo-1719841602002-1dcc795bed24-4636190af475?w=1200"
bgOverlays="gradient-bottom"
surface="dark-always"
className="h-[280px] rounded-[var(--radius-panel)] overflow-hidden"
>
<Flex direction="column" justify="end" gap="2" className="p-6">
<Heading size="lg">Media Panel</Heading>
<Text size="sm" color="muted">gradient-bottom overlay ensures text readability.</Text>
</Flex>
</Box>Box with Background Video + Multi-Layer Overlays
Two overlay layers — a vignette for edge darkening and a dark-20 base for overall readability.
Video Panel
vignette + dark-20 at 60% opacity
<Box
bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
bgOverlays="vignette, dark-20/60"
surface="dark-always"
className="h-[260px] rounded-[var(--radius-panel)] overflow-hidden"
>
<Flex direction="column" align="center" justify="center" gap="2" className="p-6 text-center">
<Heading size="xl">Video Panel</Heading>
<Text size="sm" color="muted">vignette + dark-20 at 60% opacity</Text>
</Flex>
</Box>Box with Custom Solid + Gradient Overlay
Custom hex solid and linear gradient — all in shorthand, no JSON array needed.
Custom Overlays
Hex solid + linear gradient — shorthand only
<Box
bgImage="https://images.unsplash.com/photo-1719841602002-1dcc795bed24-4636190af475?w=1200"
bgOverlays="#0a0a1a/40, linear(90deg, #000/0%, #000/100%)/70"
surface="dark-always"
className="h-[260px] rounded-[var(--radius-panel)] overflow-hidden"
>
<Flex direction="column" justify="end" gap="2" className="p-6">
<Heading size="lg">Custom Overlays</Heading>
<Text size="sm" color="muted">Hex solid + linear gradient — shorthand only</Text>
</Flex>
</Box>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, article, span, 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. |