CominsTableRef

comins-table@0.2.2React

CominsTableRef<TData> is the imperative API for a mounted table: selection, sorting, column layout, and expansion. ref.current can be null before mounting and after disposal. Check readiness in event handlers or effects.

All 20 methods

copySelection

copySelection: (target?: CominsCopyTarget) => Promise<string | null>

Accepts “auto” (default), “cells”, or “rows”. Auto prioritizes multiple cells, selected rows, then a single cell. Returns the copied text, or null for no copyable selection. Rejects if OS clipboard writing fails. Call from a user gesture and handle errors. The clipboard prop controls keyboard copy, not this ref method.

getSelectedRows

getSelectedRows: () => TData[]

Returns selected row data in data order without changing selection. Row objects retain application-owned references. In Viewport mode, only currently loaded selected data is returned.

getSelectedCells

getSelectedCells: () => CominsSelectedCell[]

Returns selected cell rowId, columnId, and raw value. Ranges follow projected display order. Cell values retain application-owned references.

getSelection

getSelection: () => CominsSelectionState

Returns a selection snapshot with row IDs, cell addresses, and ranges. Selection arrays and addresses are copied; the read does not change selection.

setSelectedRow

setSelectedRow: (index: number) => void

Selects one row by visible index after sorting and pagination in an array-backed table. Viewport mode uses absolute indexes and skips unloaded rows.

setSelectedRows

setSelectedRows: (indexes: number[]) => void

Updates row selection from indexes. An empty array clears row selection. Index semantics match setSelectedRow.

getSortState

getSortState: () => CominsSortState | null

Returns the single-sort state, or null when absent. Use getSortModel to read the complete multi-sort model.

getSortModel

getSortModel: () => CominsSortModel

Returns the complete current sort model. Treat the returned model as read-only and apply changes through setters.

setSortState

setSortState: (sort: CominsSortState | null) => void

Updates internal single-sort state; null clears it. onChangeSort is a notification, with no corresponding sort input prop.

setSortModel

setSortModel: (sortModel: CominsSortModel) => void

Updates the internal sort model. Configure multiSort for multiple rules. onChangeSortModel is a change notification.

clearSort

clearSort: () => void

Clears internal sorting and reports the change. The parent does not need to reorder data to clear sorting.

getColumnLayout

getColumnLayout: () => CominsColumnLayout

Serializes the current column layout. This is not a snapshot of all row data.

setColumnLayout

setColumnLayout: (layout: CominsColumnLayout) => void

Applies column layout and reports changes through onChangeColumnLayout. Use a layout compatible with current column definitions.

setMoveTargetRow

setMoveTargetRow: (targetIdx: number, sourceIdx: number) => void

Moves the source visible row to the target position in an ordinary array-backed table and clears sorting. Commit new data through onChangeData. This is a no-op with Tree, Viewport, Row Grouping, or columnFiltering.

expand

expand: (nodeIds?: readonly CominsRowId[]) => void

Expands Tree nodes; omission applies to all eligible nodes. Tree-only, with no effect in an ordinary table. Apply the tree-node array received through onChangeData to parent data.

fold

fold: (nodeIds?: readonly CominsRowId[]) => void

Folds Tree nodes; omission applies to all eligible nodes. Follows the same Tree state contract as expand.

expandGroups

expandGroups: (groupIds?: readonly CominsRowId[]) => void

Expands groups; omission targets all groups. Requires valid groups and rowGrouping.onChangeExpandedGroupIds. The parent must commit the callback result.

foldGroups

foldGroups: (groupIds?: readonly CominsRowId[]) => void

Folds groups; omission folds all groups. Follows the same controlled callback contract as expandGroups.

Read selected rows

Select the first row, then press getSelectedRows(). The read button does not change selection; the status shows the last retrieved result.

Preview

Code

TableDemo.tsx

import { useRef, useState } from 'react';
import { CominsTable, type CominsTableRef, type CominsTableColumn } from 'comins-table';
import 'comins-table/styles.css';
import { modules } from '../../module-catalog';

type Module = { id: string; name: string; version: string };
const data: Module[] = modules.map(module => ({ id: module.id, name: module.label, version: module.version }));
const columns: CominsTableColumn<Module>[] = [
  { id: 'name', field: 'name', label: 'Module', width: 240, sort: true },
  { id: 'version', field: 'version', label: 'Version', width: 160 },
];
export default function TableDemo({ lang = 'ko' }: { lang?: string }) {
  const ref = useRef<CominsTableRef<Module>>(null);
  const [selected, setSelected] = useState<Module[]>([]);
  const ko = lang === 'ko';
  return <div className="demo" data-demo="table">
    <div className="demo-toolbar">
      <button onClick={() => ref.current?.setSelectedRow(0)}>{ko ? '첫 번째 행 선택' : 'Select first row'}</button>
      <button onClick={() => setSelected(ref.current?.getSelectedRows() ?? [])}>getSelectedRows()</button>
      <button onClick={() => { ref.current?.setSelectedRows([]); setSelected([]); }}>{ko ? '선택 해제' : 'Clear selection'}</button>
    </div>
    <div className="table-viewport"><CominsTable ref={ref} columns={columns} data={data} getRowId={row => row.id} rowSelectionOnClick /></div>
    <p role="status" className="demo-status">{ko ? '조회한 선택 행' : 'Retrieved selected rows'}: {selected.length ? selected.map(row => row.name).join(', ') : (ko ? '없음' : 'None')}</p>
  </div>;
}

State timing

Setters request React state updates. An immediate getter call in the same call stack is not proof that a render has committed. Controlled data, tree nodes, and group expansion require the parent to commit callback values. Sorting and selection are internal state; their callbacks are notifications. This demo uses separate user events for selection and retrieval.

Search terms

Read selected rows, select rows, clear selection, reset sort, column layout, getSelectedRows, setSelectedRows, CominsTableRef.

Source

Version-pinned selection guide · npm 0.2.0

fillSelection

fillSelection: (direction: "down" | "right") => boolean;

"down" repeats the first selected row downward; "right" repeats the first selected column to the right. Requires fillHandle, cellSelection and onChangeData. Returns true only for an actual change; disabled, unchanged or rejected operations return false. Preserves source types and runs validateFill. Does not fetch unloaded Viewport ranges. Runnable example.