Box

모든 레이아웃 컴포넌트의 기반이 되는 박스 컴포넌트. $css prop을 통해 rainbow-sprinkles 기반 반응형 스타일을 지원하고, render prop으로 렌더링할 요소를 변경할 수 있습니다. base-ui의 useRender + mergeProps 기반.

개요

Box는 모든 레이아웃 컴포넌트의 기반입니다. 기본적으로 <div>를 렌더링하며, render prop으로 렌더링할 HTML 요소를 변경할 수 있습니다. $css prop을 통해 rainbow-sprinkles 기반의 반응형 레이아웃과 인터랙션 스타일을 선언적으로 적용할 수 있습니다.

내부적으로 base-ui의 useRender + mergeProps를 사용하여 ref 병합, 이벤트 핸들러 체이닝, className/style 지능형 병합을 제공합니다.

Usage

기본 사용법

import { Box } from '@featuring-corp/components';

<Box $css={{ padding: '$spacing-400', bgColor: '$background-2', rounded: '$radius-200' }}>
  Basic Box
</Box>

render prop으로 HTML 요소 변경

import { Box } from '@featuring-corp/components';

<Box render={<section />} $css={{ padding: '$spacing-600', bgColor: '$background-3', rounded: '$radius-200' }}>
  <Box render={<h2 />} $css={{ marginBottom: '$spacing-200' }}>
    Section Title
  </Box>
  <Box render={<p />}>Section content goes here.</Box>
</Box>

반응형 스타일

breakpoint별로 다른 값을 지정할 수 있습니다. mobile, tablet, desktop, wide 조건을 지원합니다.

import { Box } from '@featuring-corp/components';

<Box
  $css={{
    display: 'flex',
    flexDirection: { mobile: 'column', desktop: 'row' },
    gap: { mobile: '$spacing-200', desktop: '$spacing-400' },
    padding: { mobile: '$spacing-300', tablet: '$spacing-400', desktop: '$spacing-600' },
    bgColor: '$background-2',
    rounded: '$radius-200',
  }}
>
  <Box $css={{ padding: '$spacing-300', bgColor: '$background-1', rounded: '$radius-100', flexGrow: 1 }}>
    Left
  </Box>
  <Box $css={{ padding: '$spacing-300', bgColor: '$background-1', rounded: '$radius-100', flexGrow: 1 }}>
    Right
  </Box>
</Box>

인터랙션 색상 (hover, active, focus)

색상 관련 프롭은 default, hover, active, focus, disabled 등의 조건을 지원합니다.

import { Box } from '@featuring-corp/components';

<Box
  render={<button />}
  $css={{
    padding: '$spacing-400',
    paddingX: '$spacing-600',
    bgColor: {
      default: '$background-1',
      hover: '$background-3',
      active: '$background-4',
    },
    borderColor: {
      default: '$border-default',
      hover: '$border-1',
    },
    rounded: '$radius-200',
  }}
  style={{ borderWidth: '1px', borderStyle: 'solid', cursor: 'pointer' }}
>
  Hover / Active me
</Box>

동적 CSS 값

토큰에 없는 임의의 CSS 값도 직접 사용할 수 있습니다.

import { Box } from '@featuring-corp/components';

<Box
  $css={{
    width: 'calc(100% - 2rem)',
    maxWidth: '600px',
    height: '200px',
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    bgColor: '$background-2',
    rounded: '$radius-300',
  }}
>
  Dynamic width & height
</Box>

render prop 콜백 + mergeProps

render에 함수를 전달하면 내부 props에 접근할 수 있습니다. mergeProps로 추가 props를 안전하게 병합하세요.

import { Box, mergeProps } from '@featuring-corp/components';

<Box
  $css={{ padding: '$spacing-400', bgColor: '$background-2' }}
  render={(props) => (
    <nav
      {...mergeProps(props, {
        'aria-label': 'Main navigation',
        className: 'custom-nav',
      })}
    />
  )}
>
  Navigation content
</Box>

이벤트 핸들러 체이닝

render element에 이벤트 핸들러가 있어도 Box에 전달된 핸들러와 모두 실행됩니다 (덮어쓰지 않음).

import { Box } from '@featuring-corp/components';

<Box
  render={<button onClick={() => console.log('external')} />}
  onClick={() => console.log('internal')}
>
  클릭 시 'external' → 'internal' 순서로 실행
</Box>

Ref 병합

render element에 ref가 있어도 Box의 forwarded ref와 모두 동작합니다.

import { useRef } from 'react';
import { Box } from '@featuring-corp/components';

const myRef = useRef(null);

<Box ref={forwardedRef} render={<nav ref={myRef} />}>
  양쪽 ref 모두 설정됨
</Box>

Props

공통 Props — $css, render, className, style는 모든 서브컴포넌트에서 지원됩니다. useRenderComponent 가이드 →

<div> 요소의 모든 네이티브 속성을 지원합니다. render prop으로 다른 요소를 렌더링할 수 있습니다.

Prop

Type

$css 스타일 프롭

레이아웃 (반응형)

mobile, tablet, desktop, wide breakpoint를 지원합니다.

프롭	CSS 속성	토큰
`display`	`display`	`none`, `flex`, `inline-flex`, `block`, `inline-block`, `grid`, `inline-grid`
`flexDirection`	`flex-direction`	`row`, `column`, `row-reverse`, `column-reverse`
`alignItems`	`align-items`	`stretch`, `flex-start`, `center`, `flex-end`, `baseline`
`justifyContent`	`justify-content`	`flex-start`, `center`, `flex-end`, `space-between`, `space-around`, `space-evenly`
`flexWrap`	`flex-wrap`	`nowrap`, `wrap`, `wrap-reverse`
`gap`	`gap`	spacing 토큰 또는 임의 값
`padding`	`padding` (shorthand)	spacing 토큰 또는 임의 값
`paddingX`	`padding-left`, `padding-right`	spacing 토큰 또는 임의 값
`paddingY`	`padding-top`, `padding-bottom`	spacing 토큰 또는 임의 값
`margin`	`margin` (shorthand)	spacing 토큰, `auto`, 또는 임의 값
`marginX`	`margin-left`, `margin-right`	spacing 토큰, `auto`, 또는 임의 값
`marginY`	`margin-top`, `margin-bottom`	spacing 토큰, `auto`, 또는 임의 값
`width`	`width`	임의 값
`height`	`height`	임의 값
`minWidth`	`min-width`	임의 값
`maxWidth`	`max-width`	임의 값
`rounded`	`border-radius` (shorthand)	radius 토큰 또는 임의 값
`position`	`position`	`relative`, `absolute`, `fixed`, `sticky`
`overflow`	`overflow`	`visible`, `hidden`, `scroll`, `auto`
`gridTemplateColumns`	`grid-template-columns`	임의 값
`gridTemplateRows`	`grid-template-rows`	임의 값

색상 (인터랙션)

default, hover, active, focus, disabled, readOnly, focusWithin, groupHover 조건을 지원합니다.

프롭	CSS 속성	토큰
`color`	`color`	색상 토큰
`bgColor`	`background-color` (shorthand)	색상 토큰
`borderColor`	`border-color`	색상 토큰
`elevation`	`box-shadow` (shorthand)	elevation 토큰

On this page