Server Component · 0 KB client JS

Box

The foundational layout primitive: a polymorphic div with every style token as a typed prop.

A humble Box

Every layout primitive in Astralis builds on this: spacing, sizing, color, borders and radius as typed token props.

Import#

import { Box } from "astralis-ui";

Usage#

Box turns the design system's tokens into props: spacing, sizing, color, borders, radius, shadows and positioning, all typed: your editor autocompletes the valid values, and anything off-scale is a type error. Every other layout component (Flex, Stack, Grid, …) extends Box, so everything on this page applies to all of them.

Responsive props#

Every style prop also accepts a breakpoint map with base, sm, md, lg and xl keys, resolved to precompiled classes, no runtime style computation.

Resize the window: padding and radius step up at md and lg.

<Box p={{ base: "4", md: "8", lg: "12" }} rounded={{ base: "md", md: "2xl" }} />

To respond to the space a component actually has rather than the window, mark an ancestor with container and use the @sm–@xl keys, which measure that ancestor. Container queries covers the details.

<Box container>
  <Flex direction={{ base: "column", "@md": "row" }} gap="4">…</Flex>
</Box>

Polymorphism#

as swaps the rendered element. Reach for it whenever the semantic element matters (section, aside, nav, figure …).

Props#

Box is transparent and unstyled by default: every prop below is opt-in. Grouped by family; each family's values come straight from the token scale (the full reference will live on the Design Tokens page).

PropTypeDefaultDescription
p · px · py · pt/pb/pl/pr"0" – "96" (spacing scale)NonePadding: all sides, per axis, or per edge.
m · mx · my · mt/mb/ml/mr"0" – "96" (spacing scale) | "auto"NoneMargin: all sides, per axis, or per edge. auto pushes a flex item to the far edge or centres a fixed-width block.
w · h · size · minW/maxW · minH/maxHspacing scale | "xs"–"8xl" | fractions | "auto" | "full" | "fit" | "prose" …NoneSizing. size sets width and height at once.
bg"base" | "subtle" | "muted" | "raised" | "inverted" | "{hue}" (solid) | "{hue}-subtle" | "{hue}-muted" | "{hue}-50"–"{hue}-950"NoneBackground from semantic roles, palette roles, or raw shades. Transparent by default. base is the page, subtle the thing sitting on it, muted a filled control; raised is for floating layers only.
color"base" | "muted" | "subtle" | "inverted" | "{hue}" (label) | "{hue}-solid" | "{hue}-contrast"NoneText color token; children inherit it.
border (+ borderT/R/B/L) · borderStyle · borderColor"normal"–"thickest" · CSS styles · "base" | "subtle" | "muted" | "{hue}" (stroke)NoneBorder width, style and color tokens. Per-side widths mirror rounded: borderB is a header rule, borderT a footer one.
rounded (+ roundedT/R/B/L, roundedTl/Tr/Br/Bl)"none" | "2xs"–"4xl" | "full"NoneCorner radius: all corners, per side, or per corner.
display"block" | "flex" | "grid" | "hidden" | …NoneCSS display.
position · inset · top/right/bottom/left · zIndexposition tokens + offset scaleNonePositioning.
shadow"none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "inner"NoneBox shadow token.
opacity · overflow(X/Y) · cursor · pointerEvents · aspectRatiotoken mapsNoneMisc utilities, all typed.
basis · flex · grow · shrink · order · alignSelfsizing scale · "1" | "auto" | "initial" | "none" · boolean | "0" | "1" · "1"–"12" · "auto" | "start" | "center" | "end" | "stretch" | "baseline"NoneHow the element behaves as a child of a flex or grid parent. On Box, so any primitive can size itself without a Flex.Item wrapper.
containerbooleanfalseMakes this element the query container that descendants' @sm–@xl responsive keys measure against, instead of the viewport.
asElementType"div"Element or component to render; HTML props follow it type-safely.