Skip to Content

Grid

TanStack Table 기반의 선언적 데이터 그리드 컴포넌트입니다.


개요

Grid 컴포넌트는 <TableColumn> 자식 컴포넌트로 열을 선언적으로 정의하고, TanStack Table을 내부 엔진으로 사용하여 정렬, 페이지네이션, 행 선택 등을 지원합니다.

주요 특징

  • 선언적 API: <TableColumn> children으로 열 구성
  • 페이지네이션: Foundation Pagination 기반, 페이지 크기 선택 및 직접 이동 지원
  • 행 선택: 체크박스(다중) / 라디오(단일) 모드
  • 정렬: 클라이언트/서버 사이드 정렬 지원
  • 셀 유형: link, button, range(progress/rate), 조건부 서식
  • 커스텀 렌더링: renderCell prop으로 자유로운 셀 커스터마이징
  • 디자인 토큰: Foundation 토큰 시스템 호환

기본 사용

<Grid>datagetRowId를 전달하고, <TableColumn>으로 열을 정의합니다.

ID
상품명
가격
1
상품1
1,000
2
상품2
2,500

행 선택

체크박스 (다중 선택)

selectable + selectionMode="checkbox"로 다중 행 선택을 활성화합니다.

ID
상품명
1
상품1
2
상품2
3
상품3

라디오 (단일 선택)

selectionMode="radio"로 단일 행 선택을 활성화합니다.

ID
상품명
1
상품1
2
상품2

페이지네이션

pageSize, pageSizeOptions, useGoToPage으로 페이지네이션을 구성합니다.

ID
이름
1
항목 1
2
항목 2
3
항목 3
4
항목 4
5
항목 5
30

셀 유형 (uiType)

TableColumn의 uiType prop으로 셀 표시 유형을 지정합니다.

링크
재고율
350/500

조건부 서식

conditionalFormatting으로 조건에 따라 셀 스타일을 적용합니다.

ID
재고
1
50
2
200
3
400

커스텀 셀 렌더링

renderCell prop으로 셀을 자유롭게 커스터마이징합니다.

ID
상태
1
● 활성
2
● 비활성

API Reference

Grid Props

PropTypeDefaultDescription
dataT[][]테이블에 표시할 데이터 배열
getRowId(row: T) => string-행 고유 ID 추출 함수 (필수)
childrenReactNode-<TableColumn> 자식 컴포넌트들
loadingbooleanfalse로딩 상태 표시
heightnumber | string-그리드 높이
classNamestring-그리드 컨테이너 CSS 클래스
selectablebooleanfalse행 선택 활성화
selectionMode"checkbox" | "radio""checkbox"선택 방식
selectedRowsstring[]-선택된 행 ID 배열 (controlled)
paginationbooleantrue페이지네이션 표시 여부
pageSizenumber20페이지당 행 수
pageSizeOptionsnumber[][10, 20, 50, 100]페이지 크기 선택 목록
useGoToPagebooleanfalse페이지 직접 이동 입력란 표시
manualPaginationbooleanfalse서버 사이드 페이징 여부
manualSortingbooleanfalse서버 사이드 정렬 여부
showRowNumberbooleanfalse행 번호 열 표시
stripedbooleanfalse줄무늬 행 표시
fullSizebooleanfalse화면 가득 채움
enableColumnResizebooleantrue열 너비 조절 활성화
backgroundColorstring-그리드 배경색

Grid Events

EventTypeDescription
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

PropTypeDefaultDescription
fieldstring-데이터 필드명 (필수)
titlestring-열 헤더 텍스트 (필수)
widthnumber-열 너비 (px)
minWidthnumber-최소 열 너비
sortablebooleanfalse정렬 가능 여부
visiblebooleantrue열 표시 여부
enabledbooleantrue열 활성화 여부
uiType"text" | "link" | "button" | "range" | …"text"셀 표시 유형
formatterTableColumnFormatter-값 포맷터 (천단위 구분 등)
conditionalFormattingTableColumnConditionalRule[]-조건부 서식 규칙
renderCell(value, row, rowIndex) => ReactNode-커스텀 셀 렌더 함수
onLinkClick(row: T) => void-uiType=“link” 클릭 콜백
onButtonClick(row: T) => void-uiType=“button” 클릭 콜백

접근성

권장 사항

  • <table> 시맨틱 요소를 사용하여 스크린 리더 호환
  • ✅ 로딩 시 aria-busy="true" 자동 적용
  • ✅ 체크박스/라디오는 키보드(Space)로 토글 가능
  • ✅ 페이지 탐색 버튼은 키보드로 접근 가능

관련 컴포넌트

Last updated on