CnDashboardGrid

Low-level drag-and-drop grid layout engine powered by GridStack. Manages widget placement, drag, and resize interactions and emits layout changes for persistence. Does not handle widget rendering — the parent provides content via the #widget scoped slot.

Used internally by CnDashboardPage. Only use this directly if you need fine-grained control over the grid without the full dashboard page shell.

Requires: gridstack (bundled dependency)

Try it

Loading CnDashboardGrid playground…

Usage

<CnDashboardGrid
  :layout="placements"
  :editable="isEditing"
  :columns="12"
  :cell-height="80"
  @layout-change="onLayoutChange">
  <template #widget="{ item }">
    <MyWidget :config="item" />
  </template>
</CnDashboardGrid>

// Layout item shape
const placements = [
  { id: 1, gridX: 0, gridY: 0, gridWidth: 6, gridHeight: 3 },
  { id: 2, gridX: 6, gridY: 0, gridWidth: 6, gridHeight: 3 },
]

function onLayoutChange(updated) {
  // updated is the full layout array with new x/y/w/h values
  saveLayout(updated)
}

Props

Prop	Type	Required	Default	Description
layout	Array	✓	—	Array of layout items: { id, gridX, gridY, gridWidth, gridHeight, ...extra }
editable	Boolean		false	Enables drag and resize interactions
columns	Number		12	Number of grid columns
cellHeight	Number		80	Cell height in pixels
margin	Number		12	Gap between grid items in pixels
minWidth	Number		2	Minimum widget width in grid units
minHeight	Number		2	Minimum widget height in grid units
columnOpts	Object		null	GridStack v12 responsive columnOpts bag; when set the grid reflows its column count across screen sizes. Build it with getDashboardColumnOpts. Default null = fixed columns.
cellHeightCssVar	String		null	When set, cellHeight is mirrored into this CSS custom property on the document root at init (e.g. --app-cell-height). Default null = none.
itemKey	Function		null	Optional (item) => string|number to derive each item's render key; forces a re-render when an item changes in a way its id doesn't capture (e.g. style edits). Default null = key on item.id.

Events

Event	Payload	Description
layout-change	layout[]	Emitted when any item is dragged or resized; payload is the full updated layout array

Slots

Slot	Scope	Description
widget	{ item }	Content to render inside each grid cell; item is the layout object

Reference (auto-generated)

The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnDashboardGrid.vue and update automatically whenever the component changes.

Props

Name	Type	Required	Default	Description
layout	array	✓	—	Array of layout items: { id, gridX, gridY, gridWidth, gridHeight, ...extra }
editable	boolean		false	Whether drag and resize are enabled
columns	number		12	Number of grid columns
cellHeight	number		80	Cell height in pixels
margin	number		12	Grid margin in pixels
minWidth	number		2	Minimum widget width in grid units
minHeight	number		2	Minimum widget height in grid units
columnOpts	union		null	GridStack v12 responsive columnOpts bag (breakpoints + reflow layout). When set, the grid reflows column count across screen sizes. Build it with getDashboardColumnOpts(). Default null = fixed columns, no responsive reflow (backwards-compatible).
cellHeightCssVar	union		null	When set, cellHeight is mirrored into this CSS custom property on the document root at init (e.g. '--app-cell-height'), so app CSS can align to the grid geometry. Default null = no CSS var written.
itemKey	union		null	Optional (item) => string|number to derive each item's render key. Use it to force a re-render when an item changes in a way its id doesn't capture (e.g. style edits — return \${item.id}:\${item.updatedAt}). Default null = key on item.id.

Events

Name	Payload	Description
layout-change	—

Slots

Name	Bindings	Description
widget	item