Grid
TanStack Table 기반의 선언적 데이터 그리드 컴포넌트입니다.
개요
Grid 컴포넌트는 <TableColumn> 자식 컴포넌트로 열을 선언적으로 정의하고, TanStack Table을 내부 엔진으로 사용하여 정렬, 페이지네이션, 행 선택 등을 지원합니다.
주요 특징
- ✅ 선언적 API:
<TableColumn>children으로 열 구성 - ✅ 페이지네이션: Foundation Pagination 기반, 페이지 크기 선택 및 직접 이동 지원
- ✅ 행 선택: 체크박스(다중) / 라디오(단일) 모드
- ✅ 정렬: 클라이언트/서버 사이드 정렬 지원
- ✅ 셀 유형: link, button, range(progress/rate), 조건부 서식
- ✅ 커스텀 렌더링: renderCell prop으로 자유로운 셀 커스터마이징
- ✅ 디자인 토큰: Foundation 토큰 시스템 호환
기본 사용
<Grid>에 data와 getRowId를 전달하고, <TableColumn>으로 열을 정의합니다.
Preview
ID | 상품명 | 가격 |
|---|---|---|
1 | 상품1 | 1,000 |
2 | 상품2 | 2,500 |
행 선택
체크박스 (다중 선택)
selectable + selectionMode="checkbox"로 다중 행 선택을 활성화합니다.
Preview
ID | 상품명 | |
|---|---|---|
1 | 상품1 | |
2 | 상품2 | |
3 | 상품3 |
라디오 (단일 선택)
selectionMode="radio"로 단일 행 선택을 활성화합니다.
Preview
ID | 상품명 | |
|---|---|---|
1 | 상품1 | |
2 | 상품2 |
페이지네이션
pageSize, pageSizeOptions, useGoToPage으로 페이지네이션을 구성합니다.
Preview
ID | 이름 |
|---|---|
1 | 항목 1 |
2 | 항목 2 |
3 | 항목 3 |
4 | 항목 4 |
5 | 항목 5 |
총 30건
셀 유형 (uiType)
TableColumn의 uiType prop으로 셀 표시 유형을 지정합니다.
Preview
링크 | 재고율 |
|---|---|
350/500 |
조건부 서식
conditionalFormatting으로 조건에 따라 셀 스타일을 적용합니다.
Preview
ID | 재고 |
|---|---|
1 | 50 |
2 | 200 |
3 | 400 |
커스텀 셀 렌더링
renderCell prop으로 셀을 자유롭게 커스터마이징합니다.
Preview
ID | 상태 |
|---|---|
1 | ● 활성 |
2 | ● 비활성 |
API Reference
Grid Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | T[] | [] | 테이블에 표시할 데이터 배열 |
getRowId | (row: T) => string | - | 행 고유 ID 추출 함수 (필수) |
children | ReactNode | - | <TableColumn> 자식 컴포넌트들 |
loading | boolean | false | 로딩 상태 표시 |
height | number | string | - | 그리드 높이 |
className | string | - | 그리드 컨테이너 CSS 클래스 |
selectable | boolean | false | 행 선택 활성화 |
selectionMode | "checkbox" | "radio" | "checkbox" | 선택 방식 |
selectedRows | string[] | - | 선택된 행 ID 배열 (controlled) |
pagination | boolean | true | 페이지네이션 표시 여부 |
pageSize | number | 20 | 페이지당 행 수 |
pageSizeOptions | number[] | [10, 20, 50, 100] | 페이지 크기 선택 목록 |
useGoToPage | boolean | false | 페이지 직접 이동 입력란 표시 |
manualPagination | boolean | false | 서버 사이드 페이징 여부 |
manualSorting | boolean | false | 서버 사이드 정렬 여부 |
showRowNumber | boolean | false | 행 번호 열 표시 |
striped | boolean | false | 줄무늬 행 표시 |
fullSize | boolean | false | 화면 가득 채움 |
enableColumnResize | boolean | true | 열 너비 조절 활성화 |
backgroundColor | string | - | 그리드 배경색 |
Grid Events
| Event | Type | Description |
|---|---|---|
onRowClick | (row: T, rowIndex: number) => void | 행 클릭 |
onRowDoubleClick | (row: T, rowIndex: number) => void | 행 더블클릭 |
onLoad | (params: GridLoadParams) => void | 데이터 로드 요청 |
onSortChange | (sorting: SortingState) => void | 정렬 변경 |
onPageChange | (pageIndex: number) => void | 페이지 변경 |
onPageSizeChange | (pageSize: number) => void | 페이지 크기 변경 |
onSelectionChange | (selectedIds: string[], selectedRows: T[]) => void | 선택 변경 |
onColumnResize | (columnId: string, width: number) => void | 열 너비 변경 |
TableColumn Props
| Prop | Type | Default | Description |
|---|---|---|---|
field | string | - | 데이터 필드명 (필수) |
title | string | - | 열 헤더 텍스트 (필수) |
width | number | - | 열 너비 (px) |
minWidth | number | - | 최소 열 너비 |
sortable | boolean | false | 정렬 가능 여부 |
visible | boolean | true | 열 표시 여부 |
enabled | boolean | true | 열 활성화 여부 |
uiType | "text" | "link" | "button" | "range" | … | "text" | 셀 표시 유형 |
formatter | TableColumnFormatter | - | 값 포맷터 (천단위 구분 등) |
conditionalFormatting | TableColumnConditionalRule[] | - | 조건부 서식 규칙 |
renderCell | (value, row, rowIndex) => ReactNode | - | 커스텀 셀 렌더 함수 |
onLinkClick | (row: T) => void | - | uiType=“link” 클릭 콜백 |
onButtonClick | (row: T) => void | - | uiType=“button” 클릭 콜백 |
접근성
권장 사항
- ✅
<table>시맨틱 요소를 사용하여 스크린 리더 호환 - ✅ 로딩 시
aria-busy="true"자동 적용 - ✅ 체크박스/라디오는 키보드(Space)로 토글 가능
- ✅ 페이지 탐색 버튼은 키보드로 접근 가능
관련 컴포넌트
- Foundation Table: 기본 테이블 시맨틱 컴포넌트
- Foundation Pagination: 페이지네이션 프리미티브
Last updated on