DataGrid - 시작하기 | reopt design docs

시작하기

패키지 설치와 첫 DataGrid 렌더링까지의 빠른 시작 가이드

reopt design업데이트 2026년 8월 2일

1. 패키지 설치

권장 설정: 전용 스킬

신규 설치와 업그레이드를 자동 판별하고, 다른 grid에서의 마이그레이션·패키지 문서 확인·검증까지 처리합니다.

소비자 프로젝트 루트에서 스킬을 에이전트 런타임에 설치합니다. 이미 설치했다면 이 명령은 생략할 수 있습니다.

bash

npx skills add reopt-ai/reopt-skills/opt-datagrid-install

설치 후 에이전트에게 아래처럼 요청하세요. 스킬은 현재 설치 상태를 확인해 신규 설치와 업그레이드를 구분합니다.

text

opt-datagrid-install 스킬로 이 프로젝트에 @reopt-ai/opt-datagrid을 설정하고 결과까지 검증해줘.

스킬은 소비자 프로젝트의 AGENTS.md(없으면 CLAUDE.md)에 reopt marker 블록을 멱등하게 갱신하고, 설치된 패키지 버전의 문서를 읽은 뒤 typecheck·doctor 등 해당 모듈의 검증을 실행합니다.

아래 패키지 설치 명령은 스킬을 사용할 수 없거나 설정 과정을 직접 통제해야 할 때의 수동 대안입니다. 스킬 소스와 최신 지원 범위 확인.

@reopt-ai/opt-datagrid는 npmjs.org에 public으로 배포됩니다. 아래는 스킬을 사용하지 않을 때의 수동 설치 명령이며, 별도 registry나 인증 설정은 필요하지 않습니다.

bash

npm install @reopt-ai/opt-datagrid
# 또는
bun add @reopt-ai/opt-datagrid

Peer dependencies: react ^19, react-dom ^19가 필요합니다. 프로젝트에 이미 React 19가 설치되어 있다면 별도 작업은 필요 없습니다.

2. 첫 번째 그리드

가장 기본적인 DataGrid는 columns, rows, height 세 가지만 있으면 렌더링됩니다. 각 컬럼에는 id, title, getValue가 필수입니다.

tsx

"use client";

import { DataGrid, type DataGridColumn } from "@reopt-ai/opt-datagrid";
import { useState } from "react";

interface Employee {
  id: string;
  name: string;
  department: string;
  salary: number;
}

const initialRows: Employee[] = [
  { id: "1", name: "김민수", department: "엔지니어링", salary: 5500 },
  { id: "2", name: "이지은", department: "디자인", salary: 4800 },
  { id: "3", name: "박서준", department: "마케팅", salary: 4200 },
  { id: "4", name: "최유리", department: "엔지니어링", salary: 6100 },
];

const columns: DataGridColumn<Employee>[] = [
  { id: "name", title: "이름", getValue: (row) => row.name, width: 160 },
  {
    id: "department",
    title: "부서",
    getValue: (row) => row.department,
    width: 140,
  },
  {
    id: "salary",
    title: "급여 (만원)",
    getValue: (row) => row.salary,
    width: 120,
    align: "right",
  },
];

export default function BasicGrid() {
  const [rows] = useState(initialRows);

  return (
    <DataGrid
      columns={columns}
      rows={rows}
      getRowId={(row) => row.id}
      height={320}
    />
  );
}

3. 편집 활성화

컬럼에 editable: true와 setValue를 추가하면 셀 편집이 활성화됩니다. 상위 컴포넌트에서 onRowsChange로 변경된 행 배열을 받아 상태를 업데이트합니다.

tsx

const editableColumns: DataGridColumn<Employee>[] = [
  {
    id: "name",
    title: "이름",
    getValue: (row) => row.name,
    setValue: (row, value) => ({ ...row, name: value as string }),
    editable: true,
    editor: { kind: "text" },
    width: 160,
  },
  {
    id: "department",
    title: "부서",
    getValue: (row) => row.department,
    setValue: (row, value) => ({ ...row, department: value as string }),
    editable: true,
    editor: {
      kind: "select",
      options: [
        { value: "엔지니어링", label: "엔지니어링" },
        { value: "디자인", label: "디자인" },
        { value: "마케팅", label: "마케팅" },
      ],
    },
    width: 140,
  },
  {
    id: "active",
    title: "재직",
    getValue: (row) => row.active,
    setValue: (row, value) => ({ ...row, active: value as boolean }),
    editable: true,
    editor: { kind: "checkbox" },
    width: 80,
  },
];

function EditableGrid() {
  const [rows, setRows] = useState(initialRows);

  return (
    <DataGrid
      columns={editableColumns}
      rows={rows}
      getRowId={(row) => row.id}
      onRowsChange={setRows}
      height={320}
    />
  );
}

4. 키보드 내비게이션

DataGrid는 별도 설정 없이 스프레드시트 수준의 키보드 내비게이션을 지원합니다.

키	동작
`Arrow Keys`	셀 간 이동
`Enter`	셀 편집 시작 / 편집 확정 후 아래로 이동
`Tab / Shift+Tab`	편집 확정 후 오른쪽/왼쪽 셀로 이동
`Escape`	편집 취소, 원래 값 복원
`Ctrl+C / Ctrl+V`	선택 영역 복사 / 붙여넣기 (TSV 형식)
`Ctrl+Z / Ctrl+Y`	Undo / Redo (useDataGridUndoRedo 연동 시)
`Delete / Backspace`	선택된 셀 값 삭제

keyboardFlow 옵션으로 Enter/Tab 이동 방향을 커스텀할 수 있습니다.

tsx

<DataGrid
  columns={columns}
  rows={rows}
  height={320}
  keyboardFlow={{
    enterDirection: "down",   // "down" | "right" | "none"
    tabDirection: "right",    // "right" | "down" | "none"
    wrapAround: true,         // 마지막 셀에서 다음 행으로 이동
  }}
/>

5. 다음 단계

핵심 개념

컬럼 정의, 편집 파이프라인, 가상화 모델

컬럼 설계 플레이북

파생 값, renderer refresh, 재사용 패턴

Hook 레퍼런스

비동기 데이터, 정렬, 컬럼 이동, Undo/Redo

시작하기

패키지 설치와 첫 DataGrid 렌더링까지의 빠른 시작 가이드

reopt design업데이트 2026년 8월 2일

1. 패키지 설치

권장 설정: 전용 스킬

신규 설치와 업그레이드를 자동 판별하고, 다른 grid에서의 마이그레이션·패키지 문서 확인·검증까지 처리합니다.

소비자 프로젝트 루트에서 스킬을 에이전트 런타임에 설치합니다. 이미 설치했다면 이 명령은 생략할 수 있습니다.

bash

npx skills add reopt-ai/reopt-skills/opt-datagrid-install

설치 후 에이전트에게 아래처럼 요청하세요. 스킬은 현재 설치 상태를 확인해 신규 설치와 업그레이드를 구분합니다.

text

opt-datagrid-install 스킬로 이 프로젝트에 @reopt-ai/opt-datagrid을 설정하고 결과까지 검증해줘.

아래 패키지 설치 명령은 스킬을 사용할 수 없거나 설정 과정을 직접 통제해야 할 때의 수동 대안입니다. 스킬 소스와 최신 지원 범위 확인.

bash

npm install @reopt-ai/opt-datagrid
# 또는
bun add @reopt-ai/opt-datagrid

Peer dependencies: react ^19, react-dom ^19가 필요합니다. 프로젝트에 이미 React 19가 설치되어 있다면 별도 작업은 필요 없습니다.

2. 첫 번째 그리드

가장 기본적인 DataGrid는 columns, rows, height 세 가지만 있으면 렌더링됩니다. 각 컬럼에는 id, title, getValue가 필수입니다.

tsx

"use client";

import { DataGrid, type DataGridColumn } from "@reopt-ai/opt-datagrid";
import { useState } from "react";

interface Employee {
  id: string;
  name: string;
  department: string;
  salary: number;
}

const initialRows: Employee[] = [
  { id: "1", name: "김민수", department: "엔지니어링", salary: 5500 },
  { id: "2", name: "이지은", department: "디자인", salary: 4800 },
  { id: "3", name: "박서준", department: "마케팅", salary: 4200 },
  { id: "4", name: "최유리", department: "엔지니어링", salary: 6100 },
];

const columns: DataGridColumn<Employee>[] = [
  { id: "name", title: "이름", getValue: (row) => row.name, width: 160 },
  {
    id: "department",
    title: "부서",
    getValue: (row) => row.department,
    width: 140,
  },
  {
    id: "salary",
    title: "급여 (만원)",
    getValue: (row) => row.salary,
    width: 120,
    align: "right",
  },
];

export default function BasicGrid() {
  const [rows] = useState(initialRows);

  return (
    <DataGrid
      columns={columns}
      rows={rows}
      getRowId={(row) => row.id}
      height={320}
    />
  );
}

3. 편집 활성화

컬럼에 editable: true와 setValue를 추가하면 셀 편집이 활성화됩니다. 상위 컴포넌트에서 onRowsChange로 변경된 행 배열을 받아 상태를 업데이트합니다.

tsx

const editableColumns: DataGridColumn<Employee>[] = [
  {
    id: "name",
    title: "이름",
    getValue: (row) => row.name,
    setValue: (row, value) => ({ ...row, name: value as string }),
    editable: true,
    editor: { kind: "text" },
    width: 160,
  },
  {
    id: "department",
    title: "부서",
    getValue: (row) => row.department,
    setValue: (row, value) => ({ ...row, department: value as string }),
    editable: true,
    editor: {
      kind: "select",
      options: [
        { value: "엔지니어링", label: "엔지니어링" },
        { value: "디자인", label: "디자인" },
        { value: "마케팅", label: "마케팅" },
      ],
    },
    width: 140,
  },
  {
    id: "active",
    title: "재직",
    getValue: (row) => row.active,
    setValue: (row, value) => ({ ...row, active: value as boolean }),
    editable: true,
    editor: { kind: "checkbox" },
    width: 80,
  },
];

function EditableGrid() {
  const [rows, setRows] = useState(initialRows);

  return (
    <DataGrid
      columns={editableColumns}
      rows={rows}
      getRowId={(row) => row.id}
      onRowsChange={setRows}
      height={320}
    />
  );
}

4. 키보드 내비게이션

DataGrid는 별도 설정 없이 스프레드시트 수준의 키보드 내비게이션을 지원합니다.

키	동작
`Arrow Keys`	셀 간 이동
`Enter`	셀 편집 시작 / 편집 확정 후 아래로 이동
`Tab / Shift+Tab`	편집 확정 후 오른쪽/왼쪽 셀로 이동
`Escape`	편집 취소, 원래 값 복원
`Ctrl+C / Ctrl+V`	선택 영역 복사 / 붙여넣기 (TSV 형식)
`Ctrl+Z / Ctrl+Y`	Undo / Redo (useDataGridUndoRedo 연동 시)
`Delete / Backspace`	선택된 셀 값 삭제

keyboardFlow 옵션으로 Enter/Tab 이동 방향을 커스텀할 수 있습니다.

tsx

<DataGrid
  columns={columns}
  rows={rows}
  height={320}
  keyboardFlow={{
    enterDirection: "down",   // "down" | "right" | "none"
    tabDirection: "right",    // "right" | "down" | "none"
    wrapAround: true,         // 마지막 셀에서 다음 행으로 이동
  }}
/>