Grid

개요

Grid는 Box를 확장하며 display: grid가 기본 적용됩니다. 별도의 props 없이 $css를 통해 gridTemplateColumns, gridTemplateRows, gap 등 CSS Grid 속성을 직접 전달합니다.

언제 사용하나요

카드, 대시보드 패널, 썸네일 등 2차원 격자 배치
열 너비를 균등하게 나누고 싶을 때 (1fr 단위)
반응형으로 열 수를 breakpoint마다 다르게 조정할 때

언제 사용하면 안 되나요

단일 행 배치 → HStack 또는 Flex
단일 열 배치 → VStack
flex 기반 정렬이 필요하다면 → Flex

접근성

Grid는 시각적 레이아웃 컨테이너로, 기본 요소는 <div>입니다. 목록, 영역 등 의미 있는 구조가 필요하다면 render prop으로 시맨틱 요소를 지정하세요.

<Grid render={<ul />} ...>  ← 카드 목록
<Grid render={<section />} ...>  ← 페이지 섹션

Usage

기본 그리드

<Grid $css={{ gridTemplateColumns: 'repeat(3, 1fr)', gap: '$spacing-300' }}>
{Array.from({ length: 6 }, (_, i) => (
  <Box
    key={i}
    $css={{
      padding: '$spacing-400',
      bgColor: '$background-2',
      rounded: '$radius-200',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <Typo variant="$body-2">{'Cell ' + (i + 1)}</Typo>
  </Box>
))}
</Grid>

반응형 열 수

breakpoint별로 gridTemplateColumns를 다르게 지정합니다.

<Grid
$css={{
  gridTemplateColumns: { mobile: '1fr', tablet: 'repeat(2, 1fr)', desktop: 'repeat(4, 1fr)' },
  gap: { mobile: '$spacing-200', desktop: '$spacing-400' },
}}
>
{Array.from({ length: 8 }, (_, i) => (
  <Box
    key={i}
    $css={{
      padding: '$spacing-400',
      bgColor: '$background-2',
      rounded: '$radius-200',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <Typo variant="$body-2">{'Item ' + (i + 1)}</Typo>
  </Box>
))}
</Grid>

auto-fill / auto-fit

열 수를 고정하지 않고 컨테이너 너비에 따라 자동으로 채웁니다. auto-fill은 빈 열을 유지하고, auto-fit은 빈 열을 접습니다.

<Grid
$css={{
  gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))',
  gap: '$spacing-300',
}}
>
{Array.from({ length: 5 }, (_, i) => (
  <Box
    key={i}
    $css={{
      padding: '$spacing-400',
      bgColor: '$primary-10',
      rounded: '$radius-200',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <Typo variant="$body-2">{'Item ' + (i + 1)}</Typo>
  </Box>
))}
</Grid>

gap 설정

행(row)과 열(column) gap을 독립적으로 지정할 수 있습니다.

<Grid
$css={{
  gridTemplateColumns: 'repeat(3, 1fr)',
  columnGap: '$spacing-600',
  rowGap: '$spacing-200',
}}
>
{Array.from({ length: 6 }, (_, i) => (
  <Box
    key={i}
    $css={{
      padding: '$spacing-300',
      bgColor: '$background-3',
      rounded: '$radius-100',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <Typo variant="$body-2">{'Cell ' + (i + 1)}</Typo>
  </Box>
))}
</Grid>

비대칭 열 (sidebar + content)

gridTemplateColumns에 고정 너비와 1fr을 혼합해 사이드바 레이아웃을 구성합니다.

<Grid
$css={{
  gridTemplateColumns: '200px 1fr',
  gap: '$spacing-400',
  height: '200px',
}}
>
<Box
  $css={{
    bgColor: '$background-3',
    rounded: '$radius-200',
    padding: '$spacing-400',
  }}
>
  <Typo variant="$body-2">Sidebar</Typo>
</Box>
<Box
  $css={{
    bgColor: '$background-2',
    rounded: '$radius-200',
    padding: '$spacing-400',
  }}
>
  <Typo variant="$body-2">Main content</Typo>
</Box>
</Grid>

grid-template-rows

행 높이를 고정하거나 비율로 지정할 때 gridTemplateRows를 사용합니다.

<Grid
$css={{
  gridTemplateColumns: 'repeat(2, 1fr)',
  gridTemplateRows: '80px 1fr 40px',
  gap: '$spacing-300',
  height: '300px',
}}
>
<Box $css={{ bgColor: '$support-info-2', rounded: '$radius-200', gridColumn: '1 / -1', padding: '$spacing-300' }}><Typo variant="$body-2">Header</Typo></Box>
<Box $css={{ bgColor: '$background-2', rounded: '$radius-200', padding: '$spacing-300' }}><Typo variant="$body-2">Left</Typo></Box>
<Box $css={{ bgColor: '$background-2', rounded: '$radius-200', padding: '$spacing-300' }}><Typo variant="$body-2">Right</Typo></Box>
<Box $css={{ bgColor: '$background-3', rounded: '$radius-200', gridColumn: '1 / -1', padding: '$spacing-300' }}><Typo variant="$body-2">Footer</Typo></Box>
</Grid>

$css로 추가 스타일

Grid도 Box의 모든 $css 속성을 그대로 사용합니다.

<Grid
$css={{
  gridTemplateColumns: 'repeat(3, 1fr)',
  gap: '$spacing-300',
  padding: '$spacing-400',
  bgColor: '$background-2',
  rounded: '$radius-300',
  elevation: '$elevation-1',
}}
>
{Array.from({ length: 3 }, (_, i) => (
  <Box
    key={i}
    $css={{
      padding: '$spacing-400',
      bgColor: '$background-1',
      rounded: '$radius-200',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <Typo variant="$body-2">{'Card ' + (i + 1)}</Typo>
  </Box>
))}
</Grid>

Props

Grid는 별도 props가 없습니다. BoxProps를 그대로 사용하며, display: grid가 기본 적용됩니다.

Prop

Type

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

스타일

기본 속성	값
`display`	`grid`

그 외 모든 Grid 속성은 $css를 통해 전달합니다. 토큰 기반 spacing, color, rounded 등 Box의 $css 전체 범위가 동일하게 지원됩니다.

On this page