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 (^12.0.0) as a peer dependency — install it yourself (npm install gridstack@^12.0.0) and import its stylesheet from that same copy (e.g. import 'gridstack/dist/gridstack.min.css'). nc-vue no longer bundles GridStack or its CSS: GridStack's JS drives layout through CSS custom properties (e.g. --gs-column-width) that only its own matching stylesheet reads, so the JS and CSS must come from the exact same installed version — a version mismatch is what previously made every grid item render at 0px width.
Try it
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, sizeToContent?, ...extra } |
↳ item.sizeToContent | Boolean | Number | undefined | Per-item: hand this row's height to its content instead of its authored gridHeight (true, or a number as a row maximum: GridStack sizes to content but never taller than N rows, so shorter content stays short and taller content is clipped at N; it is not a minimum). Use it for a widget that may decide at runtime it has nothing to show — a banner whose condition is false, a list that came back empty. Without it that widget still costs its whole row: the row is reserved from the layout before the component renders, and the engine positions items absolutely, so no CSS can reclaim the space. Leave it off for anything with a deliberate size (a map, a chart), where gridHeight should stay authoritative. | |
editable | Boolean | false | Enables drag and resize interactions | |
columns | Number | 12 | Number of grid columns | |
cellHeight | Number | 80 | Cell height in pixels | |
columnWeights | Array | null | Optional weights for the twelve-column grid's column groups, as [{ span, weight }] (e.g. three groups of 4 weighted 352/435/352). Applies only on the full twelve-column grid and not while editing; items on a side-column track are left alone. null keeps twelve equal shares. | |
margin | Number | 12 | Gap between grid items in pixels | |
marginBottom | Number | null | Margin under each item in pixels, in place of margin on that side only (CnDetailPage passes 8 in the board look, so stacked cards stand 20px apart) | |
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. | |
keyboardRepositioning | Boolean | true | Makes grid items keyboard-operable: focusable in edit mode and repositionable/resizable with the arrow keys (WCAG 2.1 SC 2.1.1). See Keyboard operation. | |
itemLabel | Function | null | Optional (item, index) => string returning a grid item's accessible name; used verbatim. Default null = derived from the item (title → name → label → widgetTitle → widgetId → "Widget N"). | |
activateOpensContextMenu | Boolean | true | Whether Enter/Space on a focused item also dispatches a bubbling contextmenu event from inside it, so right-click widget menus become keyboard-reachable without extra wiring. |
Events
| Event | Payload | Description |
|---|---|---|
layout-change | layout[] | Emitted when any item is dragged, resized, or moved with the keyboard; payload is the full updated layout array |
item-activate | { item, element, clientX, clientY } | Emitted when the user presses Enter or Space on a focused grid item. The coordinates are anchored to the item's top-left corner so a consumer menu positions itself the same way it does for a right-click |
Slots
| Slot | Scope | Description |
|---|---|---|
widget | { item } | Content to render inside each grid cell; item is the layout object |
Keyboard operation and accessibility
GridStack's drag and resize gestures are pointer-only. CnDashboardGrid ships the keyboard equivalent required by WCAG 2.1 SC 2.1.1, enabled by default:
- Every grid item is an ARIA
groupwith an accessible name. In edit mode the name also carries the item's grid coordinates ("Revenue, column 5 of 12, row 1, 4 columns wide, 2 rows tall") — without them a screen-reader user tabbing an edit-mode dashboard has no idea where anything sits. - In edit mode (
editableandkeyboardRepositioning) each item is a tab stop with a visible focus ring, described by a shared, visually-hidden key map. - Move and resize results are spoken through a polite live region.
With a grid item focused:
| Key | Action |
|---|---|
ArrowLeft / ArrowRight | Move one column left / right |
ArrowUp / ArrowDown | Move one row up / down |
Shift + ArrowLeft / ArrowRight | Shrink / grow width by one column |
Shift + ArrowUp / ArrowDown | Shrink / grow height by one row |
Home / End | Jump to the first / last column of the current row |
Enter / Space | Activate — emits item-activate and (by default) a synthetic contextmenu |
Keys are only honoured while the grid item element itself holds focus, so
buttons, inputs and menus rendered inside the #widget slot keep their own key
handling.
Every keyboard change is applied with GridStack.update() — the same engine call
drag and resize end in — so collision handling, the layout-change payload and
the consumer's persistence are identical for both input modes. There is
deliberately no second, keyboard-only update path.
Wiring a widget menu to the keyboard
Consumers that open a per-widget menu on right-click get the keyboard path for
free: Enter dispatches a bubbling contextmenu from inside the item, anchored
to its top-left corner, exactly as browsers do for the Menu key. Prefer the
explicit event in new code:
<CnDashboardGrid
:layout="placements"
:editable="isEditing"
:activate-opens-context-menu="false"
@item-activate="({ item, clientX, clientY }) => openMenu(item, clientX, clientY)"
@layout-change="onLayoutChange" />
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.
OpenRegister reliance
none: this component does not touch OpenRegister, directly or through anything it imports. 0 direct references, 0 files reached through imports.
See the reliance overview for the filterable list.
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 | |
marginBottom | number | null | Margin under each item in pixels, in place of margin on that side only; null keeps margin on every side. | |
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. | |
keyboardRepositioning | boolean | true | Whether grid items are keyboard-operable: focusable in edit mode and repositionable/resizable with the arrow keys (WCAG 2.1 SC 2.1.1 — the keyboard equivalent of the pointer-only GridStack drag). Turning it off leaves the items non-focusable and drag-only. Default true. | |
itemLabel | ((item: object, index: number) => string)|null | null | Optional (item, index) => string returning the accessible name for a grid item. Use it when the layout items don't carry a human-readable field (the built-in fallback walks title → name → label → widgetTitle → widgetId, then a positional "Widget N"). The returned string is used verbatim — no coordinates are appended. | |
activateOpensContextMenu | boolean | true | Whether a keyboard activation (Enter / Space on a focused grid item) also dispatches a bubbling contextmenu event from inside the item, so consumers that open a per-widget menu on right-click get the keyboard path for free — mirroring what browsers do for the Menu key. Set false to rely purely on the item-activate event. Default true. | |
float | boolean | true | GridStack's float. True (the default) keeps every item on the row it was placed on, with empty rows above it if need be. False packs items upward, so a size-to-content cell that shrinks, or a widget that is not shown, closes its gap instead of leaving a band. | |
sideColumn | object | null | A side column of a fixed width: { width, from? }. The layout items that say which track they are on (track: "main" or "side") are drawn on two scales: from column from (8 by default) on at width px (the card, not counting the item margins), the columns before it sharing the rest, so the side cards keep their width on any screen (DqMijnWerk). Items without a track keep the twelve shares, so a row of four tiles stays four equal tiles. Only on the full twelve-column grid and not while editing; GridStack keeps the twelve columns underneath. | |
columnWeights | array | null | Weights for groups of the twelve columns: [{ span, weight }], the spans adding up to 12. Each group takes its weight's share of the width, split evenly over its columns, so three groups of four can be drawn 332 / 415 / 332 (PqWerkplekKlant in a call). Items on a sideColumn track keep that column. Only on the full twelve-column grid and not while editing; GridStack keeps the twelve columns underneath. | |
fillHeight | boolean | false | Fill the height the host gives the grid instead of growing with the content: in view mode the layout rows divide the grid's own height, so the page around it does not scroll. A row whose items all set fitRows: true takes the height of its content; every other row takes an equal share of what is left. A widget that is taller than its share scrolls inside its own cell. The host gives the grid a definite height (a flex child with min-height: 0, say). Edit mode, and a grid narrower than fillMinWidth, keep the GridStack grid of cellHeight rows. | |
fillMinWidth | number | 960 | The narrowest grid, in pixels, that fillHeight still fills. Narrower, the cards take their cellHeight rows (and GridStack's columnOpts reflow) and the page scrolls. |
Events
| Name | Payload | Description |
|---|---|---|
layout-change | — | Fired whenever the grid geometry changed — by drag, by resize, or by a keyboard nudge. Payload is the full layout array with the moved items' gridX/gridY/gridWidth/gridHeight updated. |
item-activate | — | Fired when the user activates a focused grid item with Enter or Space. Payload { item, element, clientX, clientY } — the layout item, its DOM element, and viewport coordinates anchored to the item's top-left corner so a consumer menu can position itself the same way it does for a right-click. |
Slots
| Name | Bindings | Description |
|---|---|---|
widget | item |
float
float (default true) is GridStack's own setting: every item stays on the row it was placed on. false packs items upward, so a size-to-content cell that shrinks, or a widget that is not shown, closes its gap instead of leaving a band (CnDashboardPage gridFloat, manifest config.gridFloat). A sizeToContent cell lets its content take its own height, so it can shrink to it.
fillHeight
fillHeight (Boolean, default false) and fillMinWidth (Number, default 960): in view mode, on a grid at least fillMinWidth px wide, the layout rows divide the height the host gives the grid instead of growing with the content, so the page around it does not scroll (LpVandaag). A row whose items all set fitRows: true takes its content's height; the other rows share what is left, and a cell scrolls what does not fit. Edit mode and a narrower grid keep GridStack's cellHeight rows.
sideColumn
sideColumn ({ width, from? }, default null) draws a side column at a fixed width: layout items with track: "side" are width px wide from column from (8 by default), the card without its item margins, and items with track: "main" share what is left. An item without a track keeps the twelve shares, so a row of four tiles across the split stays four equal tiles. GridStack keeps its twelve columns underneath; only each item's left edge and width are drawn on the two scales. It applies on the full twelve-column grid and not while editing (CnDashboardPage gridSideColumn, manifest config.gridSideColumn or a view's gridSideColumn).