Box
Polymorphic layout component providing consistent spacing, elevation, rounding, and self-alignment
Box is a polymorphic layout component that renders as any HTML element or custom component via the as prop. It provides consistent spacing, elevation, rounding, and self-alignment within flex or grid containers.
Important: Since Flex and Grid extend Box, prefer them for layouts. Use Box only when you need a non-flex, non-grid container.
Installation
npm install --save @godaddy/antaresProps
The Box component accepts the following props:
as?(ElementType & C) | undefined'div'Polymorphic element type.
padding?Spacing | Spacing[] | undefined—Padding on all sides. Accepts single value or array.
inlinePadding?Spacing | Spacing[] | undefined—Padding on inline (horizontal) direction.
inlinePaddingStart?Spacing | undefined—Padding on inline start (left in LTR).
inlinePaddingEnd?Spacing | undefined—Padding on inline end (right in LTR).
blockPadding?Spacing | Spacing[] | undefined—Padding on block (vertical) direction.
blockPaddingStart?Spacing | undefined—Padding on block start (top).
blockPaddingEnd?Spacing | undefined—Padding on block end (bottom).
elevation?"base" | "card" | "raised" | "overlay" | undefined—Elevation levels for visual depth.
rounding?Rounding | undefined—Rounding values for border radius.
alignSelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | undefined—In Flex/Grid layout. Cross-axis alignment within flex/grid container.
justifySelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | "left" | "right" | undefined—In Flex/Grid layout. Main-axis alignment within flex/grid container.
order?string | number | undefined—In Flex/Grid layout. Layout order within flex/grid container.
flex?string | number | undefined—In Flex/Grid layout. Flex shorthand for grow, shrink, and basis.
flexGrow?string | number | undefined—In Flex/Grid layout. How much the item will grow relative to siblings.
flexShrink?string | number | undefined—In Flex/Grid layout. How much the item will shrink relative to siblings.
flexBasis?string | undefined—In Flex/Grid layout. Initial main size before growing/shrinking.
gridArea?string | undefined—In Flex/Grid layout. Named grid area for placement.
gridColumnStart?string | undefined—In Flex/Grid layout. Grid column start line.
gridColumnEnd?string | undefined—In Flex/Grid layout. Grid column end line.
gridRowStart?string | undefined—In Flex/Grid layout. Grid row start line.
gridRowEnd?string | undefined—In Flex/Grid layout. Grid row end line.
Scale Sizes
The spacing props use semantic t-shirt sizes for padding, gap, and other spacing properties:
xs- Extra small spacingsm- Small spacingmd- Medium spacinglg- Large spacingxl- Extra large spacing2xl- 2x extra large spacing
Custom CSS values are also supported for edge cases.
Examples
Padding
The padding props support t-shirt sizes and CSS logical properties for RTL support.
import { Box, Flex, type BoxProps } from '@godaddy/antares';export function PaddingExample(attrs: BoxProps) { return ( <Flex direction="column" gap="md"> <Box padding="md" elevation="card" {...attrs}> Padding: md </Box> <Box blockPadding="lg" elevation="card"> Block Padding: lg </Box> <Box inlinePadding="xl" elevation="card"> Inline Padding: xl </Box> <Box blockPaddingStart="sm" blockPaddingEnd="lg" elevation="card"> Block Padding Start: sm, End: lg </Box> </Flex> );}Elevation
The elevation prop adds visual depth using box-shadow.
import { Box, Flex } from '@godaddy/antares';export function ElevationExample() { return ( <Flex direction="column" gap="lg" padding="md"> <Box padding="md" elevation="base"> Elevation: base </Box> <Box padding="md" elevation="card"> Elevation: card </Box> <Box padding="md" elevation="raised"> Elevation: raised </Box> <Box padding="md" elevation="overlay"> Elevation: overlay </Box> </Flex> );}Rounding
The rounding prop sets border-radius. Use full for fully rounded corners.
import { Box, Flex } from '@godaddy/antares';export function RoundingExample() { return ( <Flex wrap="wrap" direction="column" gap="md"> <Box padding="md" rounding="xs" elevation="card"> xs </Box> <Box padding="md" rounding="sm" elevation="card"> sm </Box> <Box padding="md" rounding="md" elevation="card"> md </Box> <Box padding="md" rounding="lg" elevation="card"> lg </Box> <Box padding="md" rounding="xl" elevation="card"> xl </Box> <Box padding="md" rounding="2xl" elevation="card"> 2xl </Box> <Box padding="md" rounding="full" elevation="card" style={{ width: '80px', height: '80px' }}> full </Box> <Box padding="md" rounding="full" elevation="card" style={{ width: '200px', height: '80px' }}> pill </Box> </Flex> );}Polymorphic as Prop
Box is fully polymorphic - the as prop allows rendering as any HTML element or custom component while preserving type-safe props.
HTML Elements: When using as="button", TypeScript enforces button-specific props like type, disabled, and onClick.
Custom Components: When using as={MyComponent}, Box accepts that component's props. If there's a prop name conflict, Box's props take priority.
Typed Refs: Refs are correctly typed based on the as value - useRef<HTMLButtonElement> works with as="button".
import { useRef } from 'react';import { Box, Flex, type BoxProps } from '@godaddy/antares';export function AsExample() { return ( <Flex direction="column" gap="md"> <AsSemanticElements /> <AsInteractiveElements /> <AsWithTypedRefs /> <AsCustomComponent /> </Flex> );}function AsSemanticElements() { return ( <Flex direction="column" gap="sm"> <Box padding="sm" elevation="base"> Default (div) </Box> <Box as="section" padding="sm" elevation="base"> As section </Box> <Box as="article" padding="sm" elevation="base"> As article </Box> <Box as="span" padding="sm" elevation="base"> As span </Box> </Flex> );}/** Interactive elements with their specific props. */function AsInteractiveElements() { return ( <Flex direction="column" gap="sm"> <Box as="button" padding="sm" elevation="base" type="button"> As button (click me) </Box> {/* Anchor with href - TypeScript enforces anchor-specific props */} <Box as="a" padding="sm" elevation="base" href="https://example.com" target="_blank" rel="noopener noreferrer"> As anchor (link) </Box> {/* Input element */} <Box as="input" padding="sm" elevation="base" type="text" placeholder="As input element" /> </Flex> );}/** Demonstrating typed refs for different elements. */function AsWithTypedRefs() { // Each ref is typed to match the "as" element const buttonRef = useRef<HTMLButtonElement>(null); const anchorRef = useRef<HTMLAnchorElement>(null); const divRef = useRef<HTMLDivElement>(null); return ( <Flex direction="column" gap="sm"> <Box as="button" ref={buttonRef} padding="sm" elevation="base"> Button with typed ref </Box> <Box as="a" ref={anchorRef} href="#" padding="sm" elevation="base"> Anchor with typed ref </Box> <Box ref={divRef} padding="sm" elevation="base"> Div with typed ref (default) </Box> </Flex> );}/** Using Box with a custom component. */function AsCustomComponent() { return ( <Flex direction="column" gap="sm"> <Box as={Card} type="A"> Custom Card </Box> <Box as={Card} type="B"> Custom Card </Box> </Flex> );}/** Custom component to demonstrate polymorphism with custom components. */function Card(props: BoxProps & { type?: 'A' | 'B' }) { return ( <Box {...props}> {props.type === 'A' ? 'type A! ' : 'type B! '} {props.children} </Box> );}Alignment
Self-alignment props allow Box to position itself within flex or grid containers.
import { Box, Flex } from '@godaddy/antares';export function AlignmentExample() { return ( <Flex gap="md" style={{ height: '150px' }}> <Box padding="sm" alignSelf="start" elevation="card"> align-self: start </Box> <Box padding="sm" alignSelf="center" elevation="card"> align-self: center </Box> <Box padding="sm" alignSelf="end" elevation="card"> align-self: end </Box> <Box padding="sm" alignSelf="stretch" elevation="card"> align-self: stretch </Box> </Flex> );}RTL Support
Box uses CSS logical properties (padding-inline-start, padding-block-end, etc.) which automatically adapt to RTL layouts. No additional configuration is needed.
Design Tokens
All spacing, elevation, and rounding values are derived from the theme. If no theme is provided, default values are used. This ensures consistency across the design system.