사용법

npm i @freegridjs/core
# React
npm i @freegridjs/core @freegridjs/react
# Vue
npm i @freegridjs/core @freegridjs/vue

import { createGrid } from '@freegridjs/core';
import '@freegridjs/core/styles.css';

const grid = createGrid(document.getElementById('grid'), {
  columns: [
    { field: 'name', header: 'Name', pinned: 'left' },
    { field: 'country', header: 'Country', filter: 'set' },
    { field: 'joined', header: 'Joined', type: 'date' },
    { field: 'total', header: 'Total', type: 'number', format: '#,##0' },
  ],
  data: rows,
});

const columns = [
  { field: 'id', header: 'ID', type: 'number', format: '0', width: 80, pinned: 'left' },
  { field: 'name', header: 'Name', flex: 1, minWidth: 160 },
  { field: 'price', header: 'Price', type: 'number', format: 'currency:KRW' },
  { field: 'qty', header: 'Qty', type: 'number' },
  // computed column
  { id: 'amount', header: 'Amount', type: 'number', format: '#,##0', valueGetter: row => row.price * row.qty },
  { field: 'status', header: 'Status', filter: 'set', cellClass: p => `status-${p.value}` },
];

const grid = createGrid(el, {
  columns,
  data: rows,
  getRowId: row => String(row.id), // keeps selection and focus stable across setData
});

grid.setData(await fetch('/api/orders').then(r => r.json()));
grid.getData();               // rows as passed in
grid.getDisplayedRowCount();  // rows after filters

grid.setSort([{ colId: 'country', dir: 'asc' }, { colId: 'total', dir: 'desc' }]);
grid.getSort();
grid.setSort([]); // clear

// custom order
{ field: 'grade', comparator: (a, b) => ORDER.indexOf(a) - ORDER.indexOf(b) }

grid.setFilter('name', { type: 'text', op: 'contains', value: 'kim' });
grid.setFilter('total', { type: 'number', op: 'between', value: 1000, valueTo: 5000 });
grid.setFilter('joined', { type: 'date', op: 'after', value: '2025-01-01' });
grid.setFilter('country', { type: 'set', values: ['Japan', 'South Korea'] });
grid.setFilter('name', null);   // clear one
grid.setQuickFilter('kim seoul'); // every word must match some visible column
grid.on('filterChange', e => console.log(e.filters));

const columns = [
  { field: 'name', header: 'Name', pinned: 'left' },
  { header: 'Revenue 2026', children: [
    { header: 'First half', children: [{ field: 'q1' }, { field: 'q2' }] },
    { header: 'Second half', children: [{ field: 'q3' }, { field: 'q4' }] },
  ] },
  { field: 'total', header: 'Total', pinned: 'right' },
];

const grid = createGrid(el, {
  columns: [
    { field: 'id', lockVisible: true },       // cannot be hidden
    { field: 'internalCode', chooser: false }, // not listed in the chooser
    ...rest,
  ],
  data,
  sideBar: { open: false }, // docked Columns panel (true = closed, { open: true } = open)
});

grid.openColumnChooser();
grid.setColumnVisible('email', false);
grid.autoSizeColumns();             // all columns
grid.autoSizeColumns(['name']);     // one column

// save / restore the user's layout
localStorage.setItem('layout', JSON.stringify(grid.getColumnState()));
grid.applyColumnState(JSON.parse(localStorage.getItem('layout')));
grid.resetColumnState();

createGrid(el, {
  columns,
  data,
  summary: {
    position: 'bottom',   // 'top' | 'bottom'
    pinned: true,         // true: fixed; false: scrolls with the rows
    scope: 'filtered',    // 'filtered' | 'all' | 'selected'
    rows: [
      { label: 'Total', columns: { qty: 'sum', amount: 'sum', id: 'count' } },
      { label: 'Average', columns: { amount: { agg: 'avg', format: '#,##0.0' } } },
      { columns: {
        amount: { agg: 'max', prefix: 'max' },
        country: values => `${new Set(values).size} countries`, // custom
      } },
    ],
  },
});

grid.setSummary({ position: 'top', rows: [...] }); // change at runtime
grid.setSummary(null);                              // remove
grid.getSummaryValues();                            // [{ qty: 1234, amount: 99000, id: 50 }, …]

const COUNTRIES = { KR: ['Seoul', 'Busan'], JP: ['Tokyo', 'Osaka'] };

const grid = createGrid(el, {
  columns: [
    { field: 'id', type: 'number' },                                   // read-only
    { field: 'name', editable: true, required: true },
    { field: 'qty', type: 'number', editable: true, validate: v => v >= 0 || 'Must be 0 or more' },
    { field: 'country', editable: true, editor: { type: 'select', options: Object.keys(COUNTRIES) } },
    { field: 'city', editable: true, editor: { type: 'select', options: row => COUNTRIES[row.country] } },
    { field: 'memo', editable: true, editor: { type: 'textarea' } },
    { field: 'active', type: 'boolean', editable: true },             // Space / double-click toggles
  ],
  data,
});

grid.addRows([{ name: 'New' }], 0);
grid.removeSelectedRows();
grid.undo(); grid.redo();

// send only what changed
const { created, updated, deleted } = grid.getModifiedRows();
await save({ created, updated, deleted, cells: grid.getChanges() });
grid.commitChanges(); // or grid.revertChanges()

createGrid(el, {
  columns: [
    { field: 'region', merge: true },                 // identical neighbours become one tall cell
    { field: 'team', merge: (a, b, ra, rb) => a === b && ra.region === rb.region },
    { field: 'q1', type: 'number', editable: true, wrapHeaderText: true },
  ],
  data: rowsSortedByRegion,
  statusBar: true,     // "1,000 rows · Count 12  Sum 48,000  Average 4,000 …"
  fillHandle: true,    // drag the corner: 1, 2 → 3, 4, 5 …; Mon → copies; "item 7" → "item 8"
  pinnedTopRows: [{ region: 'Target', q1: 50000 }],
});

grid.find('Seoul');    // highlights matches, focuses the first; Ctrl+F opens the same as a bar
grid.findNext();

// Row grouping with totals
createGrid(el, {
  columns: [
    { field: 'country' },
    { field: 'name' },
    { field: 'sales', type: 'number', aggFunc: 'sum' },   // shown in each group row
  ],
  data: rows,
  groupBy: ['country'],      // or api.setGroupBy(['country', 'city'])
  groupPanel: true,          // drag headers above the grid to group
  groupDefaultExpanded: 1,   // 0 = collapsed, -1 = everything open
});

// Tree data: rows point at their parent
createGrid(el, {
  columns: [{ field: 'name' }, { field: 'budget', type: 'number' }],
  data: orgRows,
  getRowId: r => r.id,
  treeData: { getParentId: r => r.parent },
});

// Master / detail and row drag
createGrid(el, {
  columns, data,
  detailHeight: 160,
  detailRenderer: ({ row }) => `<p>Orders of ${row.name}</p>`,   // or return an element
  rowDrag: true,
});

// Pages in the browser
createGrid(el, { columns, data, pagination: { pageSize: 50, pageSizes: [20, 50, 100] } });

// Rows from your server, 100 at a time, as people scroll
createGrid(el, {
  columns,
  datasource: {
    async getRows({ start, end, sort, filters, quickFilter }) {
      const res = await fetch('/api/orders?' + new URLSearchParams({
        start, end, sort: JSON.stringify(sort), filters: JSON.stringify(filters), q: quickFilter,
      }));
      const { rows, total } = await res.json();
      return { rows, total };        // leave out total for infinite scroll
    },
  },
  blockSize: 100,
  // pagination: { pageSize: 50 },   // add this for server-side pages
});

// Download what people see (current sort and filters)
grid.exportXlsx('orders.xlsx');
grid.exportCsv('orders.csv', { separator: ';' });

// Pick columns and rows
grid.exportXlsx('picked.xlsx', { columns: ['name', 'total'], rows: 'selected', sheetName: 'Picked' });

// Read a file chosen by the user
input.addEventListener('change', async () => {
  const { rows, skipped } = await grid.importFile(input.files[0]);   // { mode: 'replace' } to swap
});

// Filters in a side panel next to the columns panel
createGrid(el, { columns, data, sideBar: { open: true, panels: ['filters', 'columns'] } });

// Without a grid
import { writeXlsx, readXlsx } from '@freegridjs/core';
const bytes = writeXlsx([{ name: 'Report', rows: [['Name', 'Total'], ['Kim', 1200]] }]);

// Sales by country (rows) and year (columns), with totals
grid.setPivot({
  rows: ['region', 'country'],        // region becomes a group with subtotals
  columns: ['year'],
  values: [{ colId: 'sales', aggFunc: 'sum' }, { colId: 'margin', aggFunc: 'avg' }],
});
grid.setPivot(null);                   // back to the normal rows

// Let people build it themselves
createGrid(el, { columns, data, sideBar: { open: true, panels: ['pivot', 'columns'] } });

// Charts: the selected range, or everything on screen
const chart = grid.createChart({ type: 'bar', title: 'Sales' });
chart.setType('line');
grid.createChart({ type: 'pie', container: document.querySelector('#chart') });

// Without a grid
import { renderChart } from '@freegridjs/core';
renderChart(el, { type: 'line', categories: ['Jan', 'Feb'], series: [{ name: 'Sales', values: [120, 180] }] });

const grid = createGrid(el, {
  columns: [
    { field: 'id', type: 'number' },                        // read-only
    { field: 'name', editable: true },                      // paste allowed
    { field: 'qty', type: 'number', editable: true },       // "1,234", "(5)", "12%" are parsed
    { field: 'due', type: 'date', editable: true },         // "2026-03-05", "2026. 3. 5." …
  ],
  data,
  rangeSelection: true, // default: drag / Shift+click / Shift+arrows / Ctrl+A
  contextMenu: p => [
    ...p.defaultItems,                                      // Copy, Paste, Pin, Hide, …
    'separator',
    { label: 'Open order', action: () => open(p.row) },
  ],
});

grid.on('cellValueChanged', e => save(e.row));              // persist edits
grid.on('paste', e => console.log(e.changed, 'cells changed'));

grid.setRange({ start: { rowIndex: 0, colId: 'name' }, end: { rowIndex: 9, colId: 'qty' } });
grid.copySelection({ headers: true }); // TSV, also written to the clipboard
grid.pasteText('Kim	1,234
Lee	56');

const grid = createGrid(el, { columns, data, rowSelection: 'multiple', getRowId: r => r.id });
grid.on('selectionChange', e => console.log(e.selected.length));
grid.getSelectedRows();
grid.selectAll();   // selects the filtered rows
grid.deselectAll();

{ field: 'total', type: 'number', format: '#,##0' }       // 1,234
{ field: 'rate', type: 'number', format: '0.0%' }          // 12.5%
{ field: 'price', type: 'number', format: 'currency:KRW' } // ₩12,000
{ field: 'price', type: 'number', format: { maximumSignificantDigits: 3 } } // Intl options
{ field: 'joined', type: 'date', format: 'long' }          // 2026년 3월 5일 (ko)

// element renderer
{ field: 'status', renderer: p => {
    const b = document.createElement('span');
    b.className = `badge badge-${p.value}`;
    b.textContent = p.formatted;
    return b;
} }

createGrid(el, { columns, data, theme: 'erp', fontSize: 12, fontFamily: 'Pretendard, sans-serif' });
grid.setTheme('board');
grid.setFont({ size: 14 });
grid.setFont({ family: null }); // back to the theme font

/* any class named fg-theme-<name> is a theme */
.fg-theme-brand {
  --fg-font: "Pretendard", sans-serif;
  --fg-font-size: 13px;
  --fg-bg: #fff; --fg-fg: #1d2433; --fg-muted: #6b7385;
  --fg-header-bg: #f2f5fa; --fg-header-fg: #1d2433;
  --fg-border: #d9dfe8; --fg-row-border: #edf0f5;
  --fg-col-line: inset -1px 0 #edf0f5;
  --fg-row-odd: #fff; --fg-row-hover: #f5f8ff; --fg-row-selected: #e6eeff;
  --fg-accent: #3056d3; --fg-focus: #3056d3;
  --fg-header-text-align: center; --fg-header-label-flex: 1 1 auto;
}

import ko from '@freegridjs/core/locales/ko';
createGrid(el, { columns, data, locale: ko });

// or register once and use codes
import { registerLocale } from '@freegridjs/core';
import ja from '@freegridjs/core/locales/ja';
registerLocale(ja);
grid.setLocale('ja');

// override a few messages
createGrid(el, { columns, data, locale: { ...ko, noRows: '조회 결과가 없습니다' } });

import { FreeGrid } from '@freegridjs/react';
import type { GridApi } from '@freegridjs/core';
import '@freegridjs/core/styles.css';

export function Orders({ rows }) {
  const grid = useRef<GridApi>(null);
  const columns = useMemo(() => [...], []); // keep props stable
  return (
    <FreeGrid
      ref={grid}
      columns={columns}
      data={rows}
      rowSelection="multiple"
      theme="erp"
      locale="ko"
      summary={summary}
      onCellClick={e => console.log(e.row)}
      onSelectionChange={e => setCount(e.selected.length)}
      style={{ height: 520 }}
    />
  );
}
// grid.current?.setSort([{ colId: 'total', dir: 'desc' }])

<script setup lang="ts">
import { FreeGrid } from '@freegridjs/vue';
import '@freegridjs/core/styles.css';

const grid = ref();
const sort = () => grid.value.getApi().setSort([{ colId: 'total', dir: 'desc' }]);
</script>

<template>
  <FreeGrid
    ref="grid"
    :columns="columns"
    :data="rows"
    row-selection="multiple"
    theme="erp"
    locale="ko"
    :height="520"
    :summary="summary"
    @cell-click="e => console.log(e.row)"
    @selection-change="e => (count = e.selected.length)"
  />
</template>