Start

시작하기

패키지 설치, .npmrc 설정, 첫 DataGrid 렌더링까지의 빠른 시작 가이드

reopt designUpdated Jun 26, 2026

1. 패키지 설치

@reopt-ai/opt-datagrid는 GitHub Packages로 배포됩니다. 먼저 .npmrc 파일을 프로젝트 루트에 생성하세요.

bash

# .npmrc
@reopt-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

패키지를 설치합니다.

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

Start

시작하기

패키지 설치, .npmrc 설정, 첫 DataGrid 렌더링까지의 빠른 시작 가이드

reopt designUpdated Jun 26, 2026

1. 패키지 설치

@reopt-ai/opt-datagrid는 GitHub Packages로 배포됩니다. 먼저 .npmrc 파일을 프로젝트 루트에 생성하세요.

bash

# .npmrc
@reopt-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

패키지를 설치합니다.

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,         // 마지막 셀에서 다음 행으로 이동
  }}
/>