DataGrid 계층
DataGrid를 목적별로 빠르게 적용할 수 있도록 기능/활용 시나리오를 분리한 문서 모음입니다.
reopt designUpdated
Editable grids, performance tuning, remote integration contracts, column models, and selection behavior.
When to use it and what to try
Edit inventory, campaigns, and ledger rows with the keyboard, or explore operations data across many columns. Validate editing with local rows before connecting a remote data source.
For a simple read-only list, opt-ui DataTable is a lighter starting point. Choose DataGrid for cell editing, selection, windowing, and remote saves; define stable row IDs and save-failure recovery first.
Try the live examples
Change cell values and inspect focus movement and selection behavior.
Remote windowInspect viewport changes and data loading, then follow the remote protocol guide.
Package boundary: @reopt-ai/opt-datagrid는 root export 하나로 DataGrid, remote datasource hooks, column hooks, AI invalidation helpers를 제공합니다. 별도 CSS import는 없고, 런타임 peer dependency는 React/React DOM입니다. 대규모 데이터에서는 getRowId, valueCache, rowBufferPx, maxRenderedRows를 먼저 결정한 뒤 remote protocol을 붙이는 순서가 안전합니다.
DataGrid의 전체 기능을 한 화면에서 실험하려면 Fullscreen Playground를 사용하세요.
Playground 열기1. 변형 기반 빠른 미리보기
하나의 엔진으로 편집형, 운영형, 대용량형 UX를 구성할 수 있습니다. 아래 탭으로 빠르게 체험한 뒤 세부 문서로 들어가서 구현 패턴을 확인하세요.
스프레드시트 스타일로 즉시 편집 가능한 기본 데이터그리드. 셀 커밋 로그를 확인할 수 있습니다.
Last commit: -
2. 기능별/활용별 문서
시작하기
설치, .npmrc 설정, 첫 DataGrid 렌더링까지의 빠른 시작 가이드
핵심 개념
컬럼 정의, 셀 편집 파이프라인, 가상화 모델, 선택/클립보드 아키텍처
편집형 데이터 입력
셀 편집, typed editor, custom editor component, 입력 검증/인터셉트 패턴
운영 모니터링
읽기 전용 운영 테이블과 상태/정렬 중심 가시화
대규모 데이터
getRowId, valueCache, rowBufferPx 중심의 대량 데이터 렌더링 가이드
성능 비교
100만 행 retained heap·update 성능 비교와 격리된 benchmark 재현 방법
원격 연동 계약
openView, window load, batch save, push invalidation까지 백엔드 계약 정리
마이그레이션 플레이북
기존 grid 모델을 opt-datagrid의 row, column, edit pipeline으로 옮기는 단계별 가이드
앱 조합 가이드
opt-ui 레이아웃 안에 DataGrid를 넣는 경계와 상위 상태 분리 기준
컬럼 설계 플레이북
getValue/setValue/renderCell과 custom editor component, 파생 컬럼 invalidation, renderer refresh 설계
Skills
설치, 마이그레이션, backend contract, 업그레이드, release action skill 정리
릴리즈 노트
opt-datagrid 버전별 변경 사항과 하이라이트
Hook 레퍼런스
useAsyncDataSource, useColumnSort 등 11개 Hook 시그니처와 사용 예제
타입 레퍼런스
DataGridColumn, DataGridSelection, 에디터 타입 등 핵심 타입 정의
3. 변형 선택 가이드
| 시나리오 | 적합한 상황 | 핵심 API |
|---|---|---|
| 편집형 데이터 입력 | 관리자가 테이블 안에서 바로 수정하고 저장 흐름을 처리해야 할 때 | onRowsChangeonCellCommitonCellsEditedonPaste |
| 운영 모니터링 | 읽기 전용 운영 대시보드에서 상태/지표를 빠르게 스캔해야 할 때 | onHeaderMenuActiononVisibleRegionChangedheight |
| 대규모 데이터 | 수천 행 이상 데이터를 스크롤하며 지연 로딩을 연결할 때 | getRowIdvalueCachevalueCacheStrategyrowBufferPxmaxRenderedRowsonVisibleRegionChanged |
| 컬럼 설계 플레이북 | 여러 화면에서 컬럼 스키마를 재사용하고 진화시켜야 할 때 | onColumnsChangeonColumnResizeonColumnMovedonHeaderMenuAction |
4. Performance Model
아래 다섯 축을 기준으로 어떤 설정이 어떤 비용을 줄이는지 확인하세요. 100만 행 retained heap과 visible-row update의 직접 비교, 측정 코드, 재현 명령은 성능 비교 문서에 공개되어 있습니다.
Stable row identity
`getRowId`는 sort/reorder 이후에도 rendered row key와 refresh intent를 안정적으로 유지합니다.
Cached value access
`valueCache`는 active cell 이동이나 selection 변화처럼 interaction-only update에서 `getValue` 재계산을 줄입니다.
Pixel-based row buffering
`rowBufferPx`와 `maxRenderedRows`는 dynamic row height와 큰 viewport에서 render window를 더 안정적으로 제어합니다.
Renderer reuse
`rendererRefreshMode`와 `refreshCellRenderer`는 mount 비용이 큰 셀을 remount 대신 reuse하도록 돕습니다.
Benchmark regression checks
`benchmark`, baseline, history 흐름으로 감에 의존하지 않고 변경 전후를 비교할 수 있습니다.
5. Recommended Scale Config
대규모 데이터셋의 시작점은 `getRowId`, `valueCache`, `valueCacheStrategy="row-id"`, `rowBufferPx`, `maxRenderedRows` 조합입니다. 이후에만 도메인별 viewport sync나 renderer reuse 정책을 추가하세요.
import { DataGrid } from "@reopt-ai/opt-datagrid";
<DataGrid
rows={rows}
columns={columns}
getRowId={(row) => String(row.id)}
valueCache
valueCacheStrategy="row-id"
rowBufferPx={480}
maxRenderedRows={600}
height={440}
ariaLabel="Scale grid"
/>;6. API 매트릭스
아래 목록은 callback만이 아니라 성능을 조정하는 tuning surface도 함께 포함합니다. 특히 `getRowId`, `valueCache`, `rowBufferPx` 같은 항목은 대규모 데이터셋의 비용 구조를 먼저 결정합니다.
입력/변경 파이프라인
셀 편집, 붙여넣기, 삭제, 배치 변경을 제어합니다.
onRowsChange내부 편집 결과를 외부 rows 상태로 반영하는 기본 콜백
onCellCommit한 셀 편집 커밋 시점의 이전/다음 값을 수집
onCellsEdited붙여넣기/삭제/fill-handle 일괄 변경을 가로채는 훅
onPaste클립보드 파싱 결과를 직접 적용하거나 차단
onDelete선택 영역 삭제 동작을 도메인 정책으로 제어
onFillPatternfill handle 드래그 확장 규칙을 커스터마이즈
선택/포커스 제어
활성 셀과 선택 영역을 외부 상태로 제어합니다.
initialActiveCell초기 포커스 셀 좌표 지정
gridSelection선택 영역 제어형 모드 입력값
onActiveCellChange활성 셀 이동 추적
onGridSelectionChange선택 영역 변경 추적
컬럼 인터랙션
리사이즈/재정렬/헤더 메뉴 동작을 도메인 로직에 연결합니다.
onColumnsChange컬럼 배열 제어형 모드 업데이트
onColumnResize사용자 리사이즈 결과를 저장
onColumnMoved드래그 재정렬 결과를 저장
onHeaderClicked헤더 클릭을 정렬/필터 UI 트리거로 연결
onHeaderMenuClick헤더 메뉴 버튼 오픈 액션을 커스터마이즈
onHeaderMenuAction헤더 메뉴 액션(sort 등)을 도메인 정렬 로직에 연결
성능/뷰포트
row identity, value recomputation, pixel buffer, renderer reuse를 튜닝합니다.
height그리드 viewport 높이
rowHeight행 높이 튜닝값
rowBufferPxdynamic row height에 맞는 pixel-based render buffer
maxRenderedRows과도한 render window를 안전하게 제한하는 상한
getRowId정렬/삽입/reorder 이후에도 stable row identity를 유지
valueCacheinteraction-only update에서 getValue 재계산을 줄이는 캐시
valueCacheStrategyvalue cache identity를 row-ref 또는 row-id로 선택
rendererRefreshMode비용이 큰 셀에서 remount 대신 renderer reuse 정책을 제어
onVisibleRegionChanged현재 뷰포트 행/열 범위 변경 이벤트
7. 기본 사용 코드
import * as React from "react";
import { DataGrid, type DataGridColumn } from "@reopt-ai/opt-datagrid";
interface TeamRow {
id: number;
name: string;
role: string;
}
const columns: DataGridColumn<TeamRow>[] = [
{
id: "name",
title: "Name",
width: 200,
editable: true,
getValue: (row) => row.name,
setValue: (row, nextValue) => ({ ...row, name: nextValue }),
},
{
id: "role",
title: "Role",
width: 160,
editable: true,
getValue: (row) => row.role,
setValue: (row, nextValue) => ({ ...row, role: nextValue }),
},
];
export function Example() {
const [rows, setRows] = React.useState<TeamRow[]>([
{ id: 1, name: "Mina", role: "Owner" },
{ id: 2, name: "Joon", role: "Editor" },
]);
return (
<DataGrid
rows={rows}
columns={columns}
onRowsChange={(nextRows) => setRows(Array.from(nextRows))}
height={420}
ariaLabel="Team grid"
/>
);
}8. Row Evaluation
useDataGridRowEvaluation은 선택한 행의 평가 큐·취소·재시도·결과 만료를 관리합니다. 렌더나 스크롤로 평가를 실행하지 않으며, 공급자와 rubric 버전은 evaluatorKey에 포함합니다. Jev는 서버 전용 /jev entry로 연결합니다.