Skip to Content
ComponentsBox

Box

Box is the base component for all our other components and provides a convenient way to use our design tokens and set element styles without having to write any custom CSS.

Source

#

Documentation

#

Using design tokens

You can use props on the <Box /> component to control styles:

Using component props
import { Box } from "@optiaxiom/react";
 
export function App() {
  return (
    <Box bg="bg.success.subtle" color="fg.success.strong" p="16">
      Using component props
    </Box>
  );
}

Visit the Styling section to learn more about how to consume our design tokens.

#

Composition

Box component uses the Radix Composition  approach and accepts an asChild prop. By default it renders a <div> element but when asChild is enabled it will forward all of its own props to its child and only render the child element instead.

I am a span 
"use client";
 
import { Box } from "@optiaxiom/react";
import { useState } from "react";
 
export function App() {
  const [isHovered, setIsHovered] = useState(false);
 
  return (
    <Box
      asChild
      bg="bg.information.subtle"
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      p="8"
      rounded="md"
    >
      <span>I am a span {isHovered && "hovered"}</span>
    </Box>
  );
}

#

BoxProps

We export a BoxProps generic type that can be used to define prop types for components that extend Box.

The first argument is the element or component type which defaults to div.

The second argument is any additional custom prop types that component accepts.

import { Box, type BoxProps, extractBoxProps } from "@optiaxiom/react";
import { forwardRef } from "react";
 
type ButtonProps = BoxProps<"button", { icon?: string }>;
 
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ children, icon, ...props }, ref) => {
    const { boxProps, restProps } = extractBoxProps(props);
 
    return (
      <Box asChild {...boxProps}>
        <button ref={ref} {...restProps}>
          {icon}
          {children}
        </button>
      </Box>
    );
  },
);
 
Button.displayName = "@optiaxiom/docs/Button";

#

Related

Grid

Use Grid component to place items in a grid using equal width columns.

Group

A flexbox layout component for grouping items horizontally or vertically.

Text

Display body or any other form of text. By default it outputs the <p> paragraph element.

#

Props

#

Box

Renders a <div> element.

Prop

alignItems

Set the element’s align-items CSS property

ResponsiveValue<typeof styling.align-items>

alignSelf

Set the element’s align-self CSS property

ResponsiveValue<typeof styling.align-self>

animation

Animate element with CSS animations

typeof styling.animation

asChild

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

false | true

backgroundImage

Set the element’s background-image CSS property

"gradient.opal"

bg

Set the element’s background color. Only accepts predefined color tokens starting with bg. (e.g., bg.default, bg.accent, bg.error), or the special values current and transparent.

typeof theme.colors

border

Set the element’s border-width CSS property

typeof styling.border-width

borderB

Set the element’s border-bottom-width CSS property

typeof styling.border-width

borderColor

Set the element’s border color. Only accepts predefined color tokens starting with border. (e.g., border.default, border.accent, border.error), or the special values current and transparent.

typeof theme.colors

borderL

Set the element’s border-left-width CSS property

typeof styling.border-width

borderR

Set the element’s border-right-width CSS property

typeof styling.border-width

borderT

Set the element’s border-top-width CSS property

typeof styling.border-width

className

string

color

Set the element’s text color. Only accepts predefined color tokens starting with fg. (e.g., fg.default, fg.accent, fg.error), or the special values current and transparent.

typeof theme.colors

cursor

Set the element’s cursor CSS property

"default" | "pointer" | "text"

display

Set the element’s display CSS property

ResponsiveValue<typeof styling.display>

flex

Set the element’s flex CSS property

ResponsiveValue<typeof styling.flex>

flexDirection

Set the element’s flex-direction CSS property

ResponsiveValue<typeof styling.flex-direction>

flexWrap

Set the element’s flex-wrap CSS property

ResponsiveValue<typeof styling.flex-wrap>

fontFamily

Set the element’s font family. Only accepts predefined fontFamily tokens.

typeof theme.fontFamily

fontSize

Set the element’s font size and line height (both properties are set together). Only accepts predefined fontSize tokens.

typeof theme.fontSize

fontWeight

Set the element’s font-weight CSS property

typeof theme.fontWeight

gap

Set the element’s gap CSS property

ResponsiveValue<typeof styling.gap>

gridColumn

Set the element’s size across grid columns

ResponsiveValue<"2" | "4" | "1" | "3">

gridTemplateColumns

Control number of columns in a grid layout

ResponsiveValue<"2" | "4" | "1" | "3">

h

Set the element’s height. Only accepts predefined values: size tokens (xs, sm, md, etc.), numeric spacing values (16, 24, 32), fractional percentages (1/2, 1/3), or special keywords (auto, full, fit, max, min).

⚠️ COMMON MISTAKE: Do not use arbitrary pixel values like “200” or “300”. Use the closest valid token from the allowed values instead.

💡 TIP: When width and height are the same, use size instead of setting both w and h separately.

ResponsiveValue<typeof theme.size>

justifyContent

Set the element’s justify-content CSS property

ResponsiveValue<typeof styling.justify-content>

justifyItems

Set the element’s justify-items CSS property

ResponsiveValue<"normal" | "stretch" | "center" | "end" | "start">

m

Set the element’s margin on all sides

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

maxH

Set the element’s maximum height. Only accepts predefined maxSize tokens.

⚠️ COMMON MISTAKE: Do not use arbitrary pixel values like “200” or “300”. Use the closest valid token from the allowed values instead.

ResponsiveValue<typeof theme.size>

maxW

Set the element’s maximum width. Only accepts predefined maxSize tokens.

⚠️ COMMON MISTAKE: Do not use arbitrary pixel values like “200” or “300”. Use the closest valid token from the allowed values instead.

ResponsiveValue<typeof theme.size>

mb

Set the element’s bottom margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

ml

Set the element’s left margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

mr

Set the element’s right margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

mt

Set the element’s top margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

mx

Set the element’s left and right margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

my

Set the element’s top and bottom margin

⚠️ WARNING: Do NOT use arbitrary values like “10px”, “5rem”, or negative numbers like “-8”. Only predefined spacing tokens are accepted.

typeof styling.margin

objectFit

Set the element’s object-fit CSS property

typeof theme.objectFit

overflow

Set the element’s overflow CSS property

typeof theme.overflow

overflowX

Set the element’s overflow-x CSS property

"auto" | "hidden" | "visible"

overflowY

Set the element’s overflow-y CSS property

"auto" | "hidden" | "visible"

p

Set the element’s padding on all sides

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

pb

Set the element’s bottom padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

pl

Set the element’s left padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

placeItems

Set the element’s place-items CSS property

ResponsiveValue<"center">

pointerEvents

Set the element’s pointer-events CSS property

"none" | "auto"

pr

Set the element’s right padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

pt

Set the element’s top padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

px

Set the element’s left and right padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

py

Set the element’s top and bottom padding

⚠️ WARNING: Do NOT use arbitrary values like “10px” or “5rem”. Only predefined spacing tokens are accepted.

typeof styling.padding

rounded

Set the element’s border radius. Only accepts predefined borderRadius tokens.

typeof theme.borderRadius

shadow

Set the element’s box shadow. Only accepts predefined boxShadow tokens.

typeof theme.boxShadow

size

Set the element’s width and height. Only accepts predefined values: size tokens (xs, sm, md, etc.), numeric spacing values (16, 24, 32), fractional percentages (1/2, 1/3), or special keywords (auto, full, fit, max, min).

⚠️ COMMON MISTAKE: Do not use arbitrary pixel values like “200” or “300”. Use the closest valid token from the allowed values instead.

💡 TIP: When width and height are the same, use size instead of setting both w and h separately (e.g., prefer size="24" over w="24" h="24").

ResponsiveValue<typeof theme.size>

textAlign

Set the element’s text-align CSS property

typeof theme.textAlign

textTransform

Set the element’s text-transform CSS property

"none" | "capitalize" | "uppercase"

transition

Control which CSS properties should transition

typeof styling.transition-property

w

Set the element’s width. Only accepts predefined values: size tokens (xs, sm, md, etc.), numeric spacing values (16, 24, 32), fractional percentages (1/2, 1/3), or special keywords (auto, full, fit, max, min).

⚠️ COMMON MISTAKE: Do not use arbitrary pixel values like “200” or “300”. Use the closest valid token from the allowed values instead.

💡 TIP: When width and height are the same, use size instead of setting both w and h separately.

ResponsiveValue<typeof theme.size>

whiteSpace

Set the element’s white-space CSS property

"nowrap"

z

Set the element’s stacking order. Only accepts predefined zIndex tokens (e.g., popover, toast, tooltip) or numeric values (0, 10, 20, 30, auto).

typeof theme.zIndex

#

Changelog

#

0.1.0

  • Added component
Last updated on
Cover