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.

Want to skip the docs? Try our MCP Server

#
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.

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";

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`
`children` `ReactNode`
`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 size tokens. `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. Only accepts predefined spacing tokens. `typeof styling.margin`
`maxH` Set the element’s maximum height. Only accepts predefined maxSize tokens. `ResponsiveValue<typeof theme.size>`
`maxW` Set the element’s maximum width. Only accepts predefined maxSize tokens. `ResponsiveValue<typeof theme.size>`
`mb` Set the element’s bottom margin. Only accepts predefined spacing tokens. `typeof styling.margin`
`ml` Set the element’s left margin. Only accepts predefined spacing tokens. `typeof styling.margin`
`mr` Set the element’s right margin. Only accepts predefined spacing tokens. `typeof styling.margin`
`mt` Set the element’s top margin. Only accepts predefined spacing tokens. `typeof styling.margin`
`mx` Set the element’s left and right margin. Only accepts predefined spacing tokens. `typeof styling.margin`
`my` Set the element’s top and bottom margin. Only accepts predefined spacing tokens. `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. Only accepts predefined spacing tokens. `typeof styling.padding`
`pb` Set the element’s bottom padding. Only accepts predefined spacing tokens. `typeof styling.padding`
`pl` Set the element’s left padding. Only accepts predefined spacing tokens. `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. Only accepts predefined spacing tokens. `typeof styling.padding`
`pt` Set the element’s top padding. Only accepts predefined spacing tokens. `typeof styling.padding`
`px` Set the element’s left and right padding. Only accepts predefined spacing tokens. `typeof styling.padding`
`py` Set the element’s top and bottom padding. Only accepts predefined spacing tokens. `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 size tokens. 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 size tokens. `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

Box

#
Documentation

#
Using design tokens

#
Composition

#
BoxProps

#
Related

Grid

Group

Text

#
Props

#
Box

#
Changelog

#
0.1.0