DashboardGridHandle

comins-grid-layout@0.3.0React

Nine ref methods to inspect and refresh the mounted GridStack engine.

Readiness and state ownership

Pass useRef<DashboardGridHandle>(null) to DashboardGrid.ref. The engine can still be initializing asynchronously after the React ref exists, so handle null query results too. Do not reuse the ref after unmount.

DashboardGridHandle inspects, measures, and compacts the engine. DashboardGridCommands changes React state. Connect onLayoutCommit={grid.commands.applyLayoutSnapshot} to accept engine geometry.

All 9 methods

getGridStack

getGridStack(): GridStack | null;

Returns the active GridStack instance, or null before engine initialization. React owns widget DOM and teardown; do not change component membership through raw addWidget, removeWidget, load, or destroy. Use Comins state commands.

getColumnCount

getColumnCount(): number | null;

Returns the engine’s active column count, which can differ from the base columns under responsive configuration. Returns null before initialization.

getRowCount

getRowCount(): number | null;

Returns the engine’s grid row count, not widget count or pixel height. Returns null before initialization.

getFloat

getFloat(): boolean | null;

Returns the current engine float setting. false is a valid setting, distinct from the uninitialized null result.

isAreaEmpty

isAreaEmpty(layout: Omit<DashboardWidgetLayout, "id">): boolean | null;

Accepts a layout without an ID and reports whether its (x, y, w, h) area is empty. Does not insert or reserve a widget. Returns null before initialization.

willItFit

willItFit(layout: Omit<DashboardWidgetLayout, "id">): boolean | null;

Checks whether the layout without an ID can fit under engine constraints such as maxRow. This is neither insertion confirmation nor the same query as area emptiness. Returns null before initialization.

refresh

refresh(): void;

Refreshes sizing and drag handles, then measures again in the next animation frame. With sizeToContent enabled it also resizes content. Returns void, not a completion promise. Does nothing before initialization.

compact

compact(layout?: CompactOptions, doSort?: boolean): DashboardLayoutSnapshot | null;

Defaults to layout="compact" and doSort=true. "compact" may reorder to fill gaps; "list" preserves left-to-right order. Sorting uses engine coordinates. Mutates engine geometry and passes through commit, returning a geometry snapshot. Returns null before initialization, rather than the fluent GridStack instance.

commitLayout

commitLayout(): DashboardLayoutSnapshot | null;

Reads the current engine geometry snapshot and, when needed, notifies onWidgetLayoutChange and onLayoutCommit. Identical commits do not repeat callbacks. In non-responsive mode, a mismatch between engine and controlled column counts returns the snapshot without notifying. Returns null before initialization. Does not perform network persistence.

External type boundary

GridStack and CompactOptions come from the installed gridstack@13.2.0. This page describes the nine Comins wrapper methods. For other engine capabilities, see advanced GridStack access and that version’s declarations.

Live example

Preview

Code

GridApiDemo.tsx

import { useRef, useState } from 'react';
import { DashboardGrid, useDashboardGrid, type DashboardGridHandle } from 'comins-grid-layout';
import 'gridstack/dist/gridstack.min.css';
import 'comins-grid-layout/styles.css';

export default function GridApiDemo({ lang = 'ko' }: { lang?: string }) {
  const ko = lang === 'ko';
  const handle = useRef<DashboardGridHandle>(null);
  const sequence = useRef(0);
  const [inspection, setInspection] = useState('');
  const grid = useDashboardGrid({ initialColumns: 12, initialWidgets: [
    { id: 'first', title: 'A', layout: { id: 'first', x: 0, y: 0, w: 4, h: 2 } },
    { id: 'second', title: 'B', layout: { id: 'second', x: 6, y: 0, w: 4, h: 2 } },
  ] });
  return <div className="demo grid-demo" data-demo="grid-api">
    <div className="demo-toolbar">
      <button onClick={() => {
        const id = `added-${++sequence.current}`;
        grid.commands.addWidget({ id, title: id, layout: { id, x: 0, y: 0, w: 3, h: 2 } });
      }}>{ko ? '위젯 추가' : 'Add widget'}</button>
      <button onClick={() => grid.commands.resizeWidget('first', { w: 8, h: 3 })}>{ko ? 'A 크기 8×3' : 'Resize A to 8×3'}</button>
      <button onClick={() => grid.commands.restoreWidget('first')}>{ko ? 'A 크기 복원' : 'Restore A size'}</button>
      <button onClick={() => grid.commands.removeWidget('first')}>{ko ? 'A 삭제' : 'Remove A'}</button>
      <button onClick={() => {
        const snapshot = handle.current?.compact('list');
        setInspection(snapshot ? JSON.stringify(snapshot, null, 2) : (ko ? '그리드 준비 중' : 'Grid is initializing'));
      }}>compact('list')</button>
      <button onClick={() => {
        const ref = handle.current;
        const probe = { x: 0, y: 20, w: 2, h: 1 };
        setInspection(JSON.stringify({ columns: ref?.getColumnCount() ?? null, rows: ref?.getRowCount() ?? null,
          float: ref?.getFloat() ?? null, empty: ref?.isAreaEmpty(probe) ?? null,
          fits: ref?.willItFit(probe) ?? null }, null, 2));
      }}>{ko ? '그리드 조회' : 'Inspect grid'}</button>
      <button onClick={() => { grid.commands.resetLayout(); setInspection(''); }}>{ko ? '초기화' : 'Reset'}</button>
    </div>
    <DashboardGrid ref={handle} widgets={grid.widgets} columns={grid.columns}
      refreshKey={grid.refreshVersion} onLayoutCommit={grid.commands.applyLayoutSnapshot}
      editable movable resizable showControls={false}
      engineOptions={{ cellHeight: 60, margin: 6, animate: false }}
      renderWidget={widget => <div className="widget-content">{widget.title}</div>}
    />
    <p role="status">{ko ? '위젯 수' : 'Widget count'}: <span data-widget-count>{grid.widgets.length}</span></p>
    <details open><summary>{ko ? '현재 React 상태' : 'Current React state'}</summary>
      <pre data-grid-state>{JSON.stringify(grid.commands.serializeLayout(), null, 2)}</pre>
    </details>
    {inspection && <pre data-grid-inspection aria-live="polite">{inspection}</pre>}
  </div>;
}

Evidence

The npm declarations below were compared with a fixed source snapshot. The snapshot is the commit recorded in the public artifact provenance.

• comins-grid-layout/dist/gridstack/adapter.d.ts
• npm 0.3.0 · Source snapshot