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 { Box, Text } from "astralis-ui";
export function BoxDemo() {
return (
<Box bg="panel" p="6" rounded="xl" border="normal" borderColor="subtle" shadow="sm" maxW="sm">
<Text weight="semibold">A humble Box</Text>
<Text size="sm" color="muted">
Every layout primitive in Astralis builds on this — spacing, sizing,
color, borders and radius as typed token props.
</Text>
</Box>
);
}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.
import { Box, HStack } from "astralis-ui";
export function BoxStyleProps() {
return (
<HStack gap="4" wrap="wrap" justifyContent="center">
<Box bg="brand-subtle" size="16" rounded="md" />
<Box bg="brand-muted" size="16" rounded="lg" />
<Box bg="brand-solid" size="16" rounded="xl" shadow="md" />
<Box bg="transparent" size="16" rounded="xl" border="thick" borderColor="brand-stroke" />
<Box bg="inverted" size="16" rounded="full" />
</HStack>
);
}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.
import { Box, Text } from "astralis-ui";
export function BoxResponsive() {
return (
<Box
bg="green-subtle"
rounded={{ base: "md", md: "2xl" }}
p={{ base: "4", md: "8", lg: "12" }}
>
<Text size="sm" color="muted">
Resize the window — padding and radius step up at md and lg.
</Text>
</Box>
);
}<Box p={{ base: "4", md: "8", lg: "12" }} rounded={{ base: "md", md: "2xl" }} />Polymorphism#
as swaps the rendered element — reach for it whenever the semantic element
matters (section, aside, nav, figure …).
import { Box, Text } from "astralis-ui";
export function BoxAs() {
return (
/* Renders a semantic <aside>; any element or component works. */
<Box as="aside" bg="blue-subtle" p="5" rounded="lg" maxW="md">
<Text size="sm" weight="medium">
Did you know?
</Text>
<Text size="sm" color="muted">
Box is polymorphic — the `as` prop swaps the rendered element while
keeping every style prop.
</Text>
</Box>
);
}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).
| Prop | Type | Default | Description |
|---|---|---|---|
p · px · py · pt/pb/pl/pr | "0.5" – "96" (spacing scale) | — | Padding — all sides, per axis, or per edge. |
m · mx · my · mt/mb/ml/mr | "0.5" – "96" (spacing scale) | — | Margin — all sides, per axis, or per edge. |
w · h · size · minW/maxW · minH/maxH | spacing scale | "xs"–"8xl" | fractions | "auto" | "full" | "fit" | "prose" … | — | Sizing. size sets width and height at once. |
bg | "base" | "panel" | "subtle" | … | "{hue}-solid/subtle/muted/emphasized" | "{hue}-50"–"{hue}-950" | — | Background from semantic roles, palette roles, or raw shades. Transparent by default. |
color | "base" | "muted" | "subtle" | "inverted" | status tokens … | — | Text color token; children inherit it. |
border · borderStyle · borderColor | "normal"–"thickest" · CSS styles · "base" | "subtle" | "{hue}-stroke" … | — | Border width, style and color tokens. |
rounded (+ roundedT/R/B/L, corner variants) | "none" | "2xs"–"4xl" | "full" | — | Corner radius — all corners, per side, or per corner. |
display | "block" | "flex" | "grid" | "hidden" | … | — | CSS display. |
position · inset · top/right/bottom/left · zIndex | position tokens + offset scale | — | Positioning. |
shadow | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "inner" | — | Box shadow token. |
opacity · overflow(X/Y) · cursor · pointerEvents · aspectRatio | token maps | — | Misc utilities, all typed. |
as | ElementType | "div" | Element or component to render; HTML props follow it type-safely. |