# Box
URL: /lynx/foundation/layout/box
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/foundation/layout/box.mdx

Box 컴포넌트는 Lynx에서 가장 기초적인 레이아웃 표면을 구성하는 컴포넌트입니다.

## Installation

- npm: npm install @seed-design/lynx-react @seed-design/lynx-css
- pnpm: pnpm add @seed-design/lynx-react @seed-design/lynx-css
- yarn: yarn add @seed-design/lynx-react @seed-design/lynx-css
- bun: bun add @seed-design/lynx-react @seed-design/lynx-css

## Usage

```tsx
import { Box, Text } from "@seed-design/lynx-react";

export function App() {
  return (
    <Box bg="bg.brandWeak" borderColor="stroke.brandWeak" borderWidth={1} borderRadius="r3" p="x4">
      <Text textStyle="t5Bold" color="fg.brand">
        Box
      </Text>
    </Box>
  );
}
```

`Box`는 Lynx 네이티브 `<view>`를 렌더링합니다. `bg`, `p`, `borderRadius` 같은 스타일 prop은 SEED 토큰을 직접 object style 값으로 변환해 적용합니다.

<Callout>
  Lynx에서는 웹 `Box`처럼 CSS variable을 클래스에 주입하는 방식이 아니라, 지원 가능한 스타일 prop만 직접 계산해 `<view style={...}>`에 적용합니다.
</Callout>

<Callout type="warning">
  `Box`는 편의를 위한 primitive입니다. 많은 항목을 반복 렌더링하는 화면에서는 primitive 컴포넌트와 object style 계산 비용이 누적될 수 있으므로, 앱 코드에서는 native `<view>`/`<text>`에 Tailwind utility className을 직접 사용하는 방식을 우선 고려하세요. 패키지 컴포넌트 내부에서는 native tag와 recipe className을 사용하고, inline style은 safe area처럼 런타임 값이 필요한 경우에만 제한적으로 사용합니다.
</Callout>

## Props

## Style Props

현재 `Box`에서 여는 스타일 prop은 Lynx에서 안정적으로 검증한 범위로 제한합니다.

| 분류   | Props                                                                                                                            |
| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| 색상   | `bg`, `background`, `color`, `borderColor`                                                                                       |
| 테두리  | `borderWidth`, `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`, `borderRadius`와 corner radius props |
| 크기   | `width`, `minWidth`, `maxWidth`, `height`, `minHeight`, `maxHeight`                                                              |
| 패딩   | `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`과 longhand padding props                                                                  |
| Flex | `display`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `alignItems`, `justifyContent`, `gap`                          |
| 배치   | `position`, `top`, `right`, `bottom`, `left`, `zIndex`, `overflowX`, `overflowY`                                                 |

명시적인 `style` prop은 마지막에 merge되므로, 필요한 경우 계산된 스타일을 덮어쓸 수 있습니다.

```tsx
<Box p="x3" style={{ paddingLeft: "24px" }}>
  <Text>paddingLeft만 직접 override</Text>
</Box>
```

## 웹 버전과의 차이

<Callout type="warning">
  Lynx `Box`는 React `Box`와 다음과 같은 차이가 있습니다.

  - `as`, `asChild`를 지원하지 않습니다. Lynx 컴파일러 제약 때문에 네이티브 `<view>`를 컴포넌트 파일 안에서 직접 렌더링합니다.
  - `bgGradient`, `boxShadow`, `bleedX`, `bleedY`, `unstable_transform`처럼 아직 Lynx에서 검증하지 않은 StyleProps는 열지 않습니다.
  - margin 계열 shorthand는 제공하지 않습니다. 레이아웃 간격은 `VStack` / `HStack`의 `gap` 또는 명시적인 `style`을 사용합니다.
  - 이벤트는 웹의 `onClick` 대신 Lynx의 `bindtap` 계열 prop을 사용합니다.
</Callout>