Components / Layout

Box

Box is the atom of motif. Every style prop the library exposes, every responsive key, every pseudo-state — Box is the surface they apply to. Every other primitive renders a Box underneath.

Loading playground…

What it is

A theme-aware, responsive <div> (on web) or <View> (on native). The whole style-prop catalogue is wired in directly — bg, p, borderRadius, _hover, enterStyle, the responsive object form — all of it works on Box. Anything that has style props in motif is a Box behind the curtain.

Install

Box is exported from usemotif. No separate install.

example.tsx

import { Box } from 'usemotif';

API

Box

stable

function Box(props: BoxProps): JSX.Element

asElementType

Element to render. Defaults to `"div"` on web and `View` on native. Pass any HTML tag, any motif component, or a React component that forwards props.

classNamestring

Extra class name(s) — concatenated with the class motif emits for responsive and pseudo-state rules.

styleCSSProperties

Inline style overrides — merged on top of the resolved style. Use sparingly; prefer the typed style props.

childrenReactNode

Content.

…StylePropsResponsive<StyleProps>

The full style-prop catalogue. Each prop accepts a literal value, a `$`-prefixed token reference, or a responsive object/array.

_hover / _focus / _active / _disabledStateStyleBag

Pseudo-state style bags applied via the matching CSS pseudo-class.

_before / _afterPseudoElementStyleBag

Pseudo-element style bags. `content` defaults to `""` when omitted.

enterStyle / exitStyle / transition / animationMotionStyleProps

Motion props — drive mount, unmount, and prop-change transitions. See the [Animation recipe](/recipes/animation-patterns) for the surface.

BoxProps extends every style-prop axis plus the standard React HTML attributes (id, data-*, aria-*, event handlers).

Examples

Styled card:

example.tsx

<Box
p="$space.4"
borderRadius="$radii.md"
bg="$colors.surface.muted"
color="$colors.text.default"
>
A theme-aware card.
</Box>

Responsive padding:

example.tsx

<Box p={{ base: '$2', md: '$4', lg: '$8' }}>
Tighter on phones, looser on desktops.
</Box>

Pseudo-state and motion:

example.tsx

<Box
bg="$colors.action.primary.bg"
_hover={{ bg: '$colors.action.primary.bgHover' }}
transition={{ property: 'background-color', duration: '$durations.2' }}
>
Hover me.
</Box>

Render as a different element:

example.tsx

<Box as="section" aria-label="Featured">
Renders a <section>, not a <div>.
</Box>

Cross-platform notes

On web Box renders as <div> by default; the as prop accepts any HTML tag. On native Box renders as a React Native <View>; the as prop accepts native components instead (Pressable, ScrollView, etc.). Style props resolve through the same token tree on both platforms — bg, p, borderRadius mean the same thing.

A handful of CSS-only style props (backdropFilter, container queries, position: sticky) are ignored on native. The library does not warn; the rest of the bag still applies.