Arrange widgets and restore per-column layouts

comins-grid-layout@0.3.0React

Compare auto arrangement, row width filling, targeted expansion, and switching between 6 and 12 columns.

Steps to try

Reset before each comparison below. float: true preserves the initial vertical gaps.

Action	Expected result
Auto arrange	Places A → B → C in array order on the first row, keeping widths 3, 3, and 4.
Fill row widths	A and B at the same y become 6 columns each; C’s separate row fills all 12 columns.
Give remaining width to A	Keeps B at width 3 and expands A to 9. C is retained.
6 columns → rearrange → 12 columns	Restores the last layout used at 12 columns.
Return to 6 columns	Restores the layout retained for 6 columns.
Reset	Restores the initial 12-column A/B/C layout.

Choose a method

autoArrangeWidgets packs rows in widget array order. fitWidgetsToColumns distributes free width among widgets at the same y. fitWidgetToColumns(id) gives that row’s remaining width to a specific widget. These are not the same operation as the engine’s compact().

setColumns retains per-column geometry and restores it when revisiting a column count. This example explicitly changes columns; it does not demonstrate automatic responsive breakpoints based on container width.

Connect React and the engine

Wire widgets, columns, and refreshKey to the hook result, and onLayoutCommit to commands.applyLayoutSnapshot. Dragging and resizing also appear in the JSON below. Do not overwrite initial state through prop changes; request a reset with commands.resetLayout().

The table assumes this example’s unconstrained widgets. Added min/max size constraints and engine settings can change the final geometry.

Persistence boundary

The displayed JSON contains only the current column geometry. To persist per-column caches too, store serializeState() and restore it with restoreLayout(). This example runs in browser memory and does not restore across page reloads.

Related documentation

20 state commands · Initial options · Engine compact · Persistence

Try it live

Preview

Code

GridArrangeDemo.tsx

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

export default function GridArrangeDemo({ lang = 'ko' }: { lang?: string }) {
  const ko = lang === 'ko';
  const grid = useDashboardGrid({ initialColumns: 12, initialWidgets: [
    { id: 'a', title: 'A', layout: { id: 'a', x: 0, y: 0, w: 3, h: 2 } },
    { id: 'b', title: 'B', layout: { id: 'b', x: 6, y: 0, w: 3, h: 2 } },
    { id: 'c', title: 'C', layout: { id: 'c', x: 0, y: 3, w: 4, h: 2 } },
  ] });
  return <div className="demo grid-demo" data-demo="grid-arrange">
    <div className="demo-toolbar">
      <button onClick={grid.commands.autoArrangeWidgets}>{ko ? '자동 배치' : 'Auto arrange'}</button>
      <button onClick={grid.commands.fitWidgetsToColumns}>{ko ? '행 너비 채우기' : 'Fill row widths'}</button>
      <button onClick={() => grid.commands.fitWidgetToColumns('a')}>{ko ? 'A에 남은 너비 주기' : 'Give remaining width to A'}</button>
      <button onClick={() => grid.commands.setColumns(6)}>{ko ? '6열' : '6 columns'}</button>
      <button onClick={() => grid.commands.setColumns(12)}>{ko ? '12열' : '12 columns'}</button>
      <button onClick={() => grid.commands.resetLayout()}>{ko ? '초기화' : 'Reset'}</button>
    </div>
    <DashboardGrid widgets={grid.widgets} columns={grid.columns} refreshKey={grid.refreshVersion}
      editable movable resizable showControls={false}
      engineOptions={{ cellHeight: 50, margin: 6, float: true, animate: false }}
      onLayoutCommit={grid.commands.applyLayoutSnapshot}
      renderWidget={widget => <div className="widget-content">{widget.title}</div>}
    />
    <p role="status">{ko ? '현재 열 수' : 'Current columns'}: <span data-column-count>{grid.columns}</span></p>
    <details open><summary>{ko ? '현재 배치' : 'Current layout'}</summary><pre data-arrange-layout>{JSON.stringify(grid.commands.serializeLayout(), null, 2)}</pre></details>
  </div>;
}