useDashboardGrid

comins-grid-layout@0.3.0React

Initial options, result fields, and event timing for connecting React state to DashboardGrid.

Signature

export declare function useDashboardGrid<TData = unknown>(options?: UseDashboardGridOptions<TData>): UseDashboardGridResult<TData>;

UseDashboardGridOptions

export type UseDashboardGridOptions<TData = unknown> = {
    initialColumns?: number;
    initialWidgets?: DashboardWidget<TData>[];
    onLayoutMutation?: (event: DashboardLayoutMutationEvent<TData>) => void;
};

Option	Default	Meaning
`initialColumns`	`12`	Initial column count, normalized to 1–12.
`initialWidgets`	`[]`	Initial widgets; keep `id` and `layout.id` consistent.
`onLayoutMutation`	None	Receives transitions in an effect after reducer updates, including a snapshot suitable for consumer persistence.

Initial inputs are read once on mount. Changing initialWidgets later does not synchronize state. Use restoreLayout for a complete external snapshot or individual commands for partial edits. Do not mutate the initial input objects in place.

Events contain kind, widgetIds, columns, and snapshot. The snapshot describes the full state after the transition. Events are delivered for observed commands returning a new state object, excluding refreshLayout and reads. The callback does not persist anything automatically.

UseDashboardGridResult

export type UseDashboardGridResult<TData = unknown> = {
    state: DashboardLayoutState<TData>;
    widgets: DashboardWidget<TData>[];
    columns: DashboardLayoutState<TData>["columns"];
    refreshVersion: number;
    commands: DashboardGridCommands<TData>;
};

Field	Usage
`state`	Complete current state; do not mutate directly.
`widgets`	`state.widgets`; pass to `DashboardGrid.widgets`.
`columns`	`state.columns`; pass to `DashboardGrid.columns`.
`refreshVersion`	Pass to `DashboardGrid.refreshKey`.
`commands`	20 state commands; use the current render’s object.

Connect the component

Pass state into the view and connect onLayoutCommit back to commands so drag results reach React state. The hook does not render widget content. Call it at the top level of a React function component or custom hook.

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/react/use-dashboard-grid.d.ts
npm 0.3.0 · Source snapshot