Photonix UI - React Components, Templates & Figma Design System

Box

The most basic layout primitive for styling and containment.

Preview

Content inside Box

Usage

"use client";

import { Box } from '@photonix/ultimate';

import { LayoutPreviewCanvas, LayoutPreviewItem } from '../_shared/LayoutPreview';

export default function BoxBasicExample() {
    return (
        <Box
            bg="secondary"
            borderRadius="lg"
            p="md"
            maxW={420}
            w="100%"
        >
            <LayoutPreviewItem label="Content inside Box" fill />
        </Box>
    );
}

Component API

Box

Prop	Type	Default	Description
p	`ResponsiveValue<SpacingToken>`	`-`	Padding on all sides
px	`ResponsiveValue<SpacingToken>`	`-`	Padding inline (left/right)
py	`ResponsiveValue<SpacingToken>`	`-`	Padding block (top/bottom)
pt	`ResponsiveValue<SpacingToken>`	`-`	Padding block start (top)
pb	`ResponsiveValue<SpacingToken>`	`-`	Padding block end (bottom)
pl	`ResponsiveValue<SpacingToken>`	`-`	Padding inline start (left)
pr	`ResponsiveValue<SpacingToken>`	`-`	Padding inline end (right)
m	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin on all sides
mx	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin inline (left/right)
my	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin block (top/bottom)
mt	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin block start (top)
mb	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin block end (bottom)
ml	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin inline start (left)
mr	`ResponsiveValue<SpacingToken \| "auto">`	`-`	Margin inline end (right)
display	`ResponsiveValue<DisplayValue>`	`-`	CSS display property
aspectRatio	`ResponsiveValue<string \| number>`	`-`	Aspect Ratio
flexDirection	`ResponsiveValue<FlexDirection>`	`-`	Flex direction
flexWrap	`ResponsiveValue<boolean \| FlexWrap>`	`-`	Flex wrap behavior
flex	`ResponsiveValue<string \| number>`	`-`	Shorthand for flex-grow, flex-shrink, flex-basis
flexGrow	`ResponsiveValue<number>`	`-`	Flex grow factor
flexShrink	`ResponsiveValue<number>`	`-`	Flex shrink factor
flexBasis	`ResponsiveValue<string \| number>`	`-`	Flex basis
order	`ResponsiveValue<number>`	`-`	Order
gap	`ResponsiveValue<SpacingToken>`	`-`	Gap between items
columnGap	`ResponsiveValue<SpacingToken>`	`-`	Column gap
rowGap	`ResponsiveValue<SpacingToken>`	`-`	Row gap
alignItems	`ResponsiveValue<AlignItems>`	`-`	Align items (cross axis)
alignContent	`ResponsiveValue<string>`	`-`	Align content (multiline)
alignSelf	`ResponsiveValue<AlignSelf>`	`-`	Align self
justifyContent	`ResponsiveValue<JustifyContent>`	`-`	Justify content (main axis)
justifyItems	`ResponsiveValue<string>`	`-`	Justify items (grid)
placeItems	`ResponsiveValue<string>`	`-`	Place items (align-items + justify-items)
placeContent	`ResponsiveValue<string>`	`-`	Place content (align-content + justify-content)
bg	`ResponsiveValue<BackgroundToken>`	`-`	Background color using public background tokens mapped to canonical surface vars
pageBg	`ResponsiveValue<PageBackgroundToken>`	`-`	Page background using canonical background-* vars for page/root containers
borderRadius	`ResponsiveValue<RadiusToken>`	`-`	Border radius using border-radius-* tokens
shadow	`ResponsiveValue<ShadowToken>`	`-`	Box shadow using shadow-* tokens
opacity	`ResponsiveValue<number>`	`-`	Opacity
border	`ResponsiveValue<string>`	`-`
borderWidth	`ResponsiveValue<number \| BorderWidthToken>`	`-`
borderStyle	`ResponsiveValue<string>`	`-`
borderColor	`ResponsiveValue<string>`	`-`
textAlign	`ResponsiveValue<TextAlign>`	`-`
fontSize	`ResponsiveValue<string \| number>`	`-`
fontWeight	`ResponsiveValue<string \| number>`	`-`
lineHeight	`ResponsiveValue<string \| number>`	`-`
color	`ResponsiveValue<string>`	`-`
w	`ResponsiveValue<string \| number>`	`-`	Width - accepts CSS value
h	`ResponsiveValue<string \| number>`	`-`	Height - accepts CSS value
minW	`ResponsiveValue<string \| number>`	`-`	Min width - accepts CSS value
minH	`ResponsiveValue<string \| number>`	`-`	Min height - accepts CSS value
maxW	`ResponsiveValue<string \| number>`	`-`	Max width - accepts CSS value
maxH	`ResponsiveValue<string \| number>`	`-`	Max height - accepts CSS value
position	`ResponsiveValue<Position>`	`-`	CSS position property
top	`ResponsiveValue<string \| number>`	`-`	Top position
right	`ResponsiveValue<string \| number>`	`-`	Right position
bottom	`ResponsiveValue<string \| number>`	`-`	Bottom position
left	`ResponsiveValue<string \| number>`	`-`	Left position
inset	`ResponsiveValue<string \| number>`	`-`	Inset shortcut
zIndex	`ResponsiveValue<number>`	`-`	Z-index
overflow	`ResponsiveValue<Overflow>`	`-`	CSS overflow property
overflowX	`ResponsiveValue<Overflow>`	`-`	CSS overflow-x property
overflowY	`ResponsiveValue<Overflow>`	`-`	CSS overflow-y property
cursor	`ResponsiveValue<string>`	`-`
pointerEvents	`ResponsiveValue<string>`	`-`
userSelect	`ResponsiveValue<string>`	`-`
transform	`ResponsiveValue<string>`	`-`
transition	`ResponsiveValue<string>`	`-`

Variants

Padding & Margin

Control spacing using padding and margin props.

Outer flow

Inner item after padding="md"

The solid Box shows the padded container.

Padding & Margin

"use client";

import { Box, Flex } from '@photonix/ultimate';

import { LayoutPreviewCanvas, LayoutPreviewItem, LayoutPreviewLabel } from '../_shared/LayoutPreview';

export default function BoxPaddingMarginExample() {
    return (
        <Flex direction="column" gap="md">
            <LayoutPreviewLabel>Outer flow</LayoutPreviewLabel>
            <Box p="md" bg="secondary" borderRadius="md" maxW={320}>
                <LayoutPreviewItem label='Inner item after padding="md"' fill />
            </Box>
            <LayoutPreviewLabel>The solid Box shows the padded container.</LayoutPreviewLabel>
        </Flex>
    );
}

Background & Border

Apply surface backgrounds with bg and page-level backgrounds with pageBg.

Surface Box

Content block

Background & Border

"use client";

import { Box, Flex } from '@photonix/ultimate';

import { LayoutPreviewCanvas, LayoutPreviewItem, LayoutPreviewLabel } from '../_shared/LayoutPreview';

export default function BoxBackgroundExample() {
    return (
        <Flex direction="column" gap="md">
            <LayoutPreviewLabel>Surface Box</LayoutPreviewLabel>
            <Box bg="secondary" borderRadius="md" p="sm" shadow="sm">
                <LayoutPreviewItem label="Content block" fill />
            </Box>
        </Flex>
    );
}

Page Background

Use pageBg for full-page shells so background-* stays separate from surface-*.

Header surface

Content surface

Page Background

"use client";

import { Box, Flex } from '@photonix/ultimate';

import { LayoutPreviewCanvas, LayoutPreviewItem } from '../_shared/LayoutPreview';

export default function BoxPageBackgroundExample() {
    return (
        <Box pageBg="primary" minH={280} p="md" borderRadius="lg">
            <Box bg="secondary" borderRadius="md" p="sm" shadow="sm">
                <Flex direction="column" gap="sm">
                    <LayoutPreviewItem label="Header surface" fill />
                    <LayoutPreviewItem label="Content surface" minH={72} fill />
                </Flex>
            </Box>
        </Box>
    );
}

Responsive Styles

Visual properties also support responsive values.

Resize to see padding, radius, and background change

Responsive Styles

"use client";

import { Box } from '@photonix/ultimate';

import { LayoutPreviewCanvas, LayoutPreviewItem } from '../_shared/LayoutPreview';

export default function BoxResponsiveExample() {
    return (
        <Box
            p={{ base: 'sm', md: 'md' }}
            bg={{ base: 'secondary', md: 'brand-primary' }}
            borderRadius={{ base: 'xs', md: 'md' }}
        >
            <LayoutPreviewItem label="Resize to see padding, radius, and background change" fill />
        </Box>
    );
}

Box

Preview

Component API

Box

Variants

Padding & Margin

Background & Border

Page Background

Responsive Styles

On this page