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="subtle" p="6" rounded="xl" border="normal" borderColor="base" 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>
);
}shadow
Layout & spacing
p
bg
rounded
w
border
borderColor
import { Box } from "astralis-ui";
<Box>Box content</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" size="16" rounded="xl" shadow="md" />
<Box bg="transparent" size="16" rounded="xl" border="thick" borderColor="brand" />
<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" }} />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 …).
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" – "96" (spacing scale) | None | Padding: all sides, per axis, or per edge. |
m · mx · my · mt/mb/ml/mr | "0" – "96" (spacing scale) | "auto" | None | Margin: 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/maxH | spacing scale | "xs"–"8xl" | fractions | "auto" | "full" | "fit" | "prose" … | None | Sizing. size sets width and height at once. |
bg | "base" | "subtle" | "muted" | "raised" | "inverted" | "{hue}" (solid) | "{hue}-subtle" | "{hue}-muted" | "{hue}-50"–"{hue}-950" | None | Background 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" | None | Text color token; children inherit it. |
border (+ borderT/R/B/L) · borderStyle · borderColor | "normal"–"thickest" · CSS styles · "base" | "subtle" | "muted" | "{hue}" (stroke) | None | Border 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" | None | Corner radius: all corners, per side, or per corner. |
display | "block" | "flex" | "grid" | "hidden" | … | None | CSS display. |
position · inset · top/right/bottom/left · zIndex | position tokens + offset scale | None | Positioning. |
shadow | "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "inner" | None | Box shadow token. |
opacity · overflow(X/Y) · cursor · pointerEvents · aspectRatio | token maps | None | Misc utilities, all typed. |
basis · flex · grow · shrink · order · alignSelf | sizing scale · "1" | "auto" | "initial" | "none" · boolean | "0" | "1" · "1"–"12" · "auto" | "start" | "center" | "end" | "stretch" | "baseline" | None | How 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. |
container | boolean | false | Makes this element the query container that descendants' @sm–@xl responsive keys measure against, instead of the viewport. |
as | ElementType | "div" | Element or component to render; HTML props follow it type-safely. |