Use a dashboard when your tasks belong to ordered lists rather than arbitrary positions on a canvas. Each column below is a container with a one-column inner grid; cards measure their text, stack at the top, and move between columns subject to a work-in-progress (WIP) limit.
Start in the project from your JavaScript, React, Vue, Angular or Qwik quick start. Keep its entry file, stylesheet imports and framework configuration. Add the component below to your existing application rather than replacing the starter's entry file.
1. Declare columns and content-sized cards
dashboard turns board data into a render spec. Framework dashboard components mount that kit for you. Declare each list as a DashboardWidgetSpec carrying child widgets, columns: 1 and stack: true.
Create this shared module as src/kanban.ts (or src/app/kanban.ts in Angular). Its DashboardViewSpec array seeds one view. Its DashboardOptions use a small row unit and autoHeight: true: rows is the card's initial estimate, not its final height.
The DashboardHandle arrives after mounting. The header counts, drop policy and snapshot all read that live handle, not the seed array. This shared module defines the board without mounting on import; the entry and framework components in step 2 mount it into visible containers.
tsimport { dashboard, fromDocument, render } from '@grafloria/element';
import { DiagramSerializer } from '@grafloria/engine';
import type { DiagramDocumentEnvelope } from '@grafloria/engine';
import type {
DashboardHandle,
DashboardOptions,
DashboardViewSpec,
DashboardWidgetSpec,
} from '@grafloria/element';
export function createBoard() {
let handle: DashboardHandle | undefined;
let saved: DiagramDocumentEnvelope | undefined;
let sequence = 0;
const counts = new Map<string, HTMLElement>();
const addButtons = new Map<string, HTMLButtonElement>();
const columns = [
{ id: 'backlog', name: 'Backlog', limit: Infinity, tint: '#eceff5' },
{ id: 'doing', name: 'In progress', limit: 2, tint: '#e6eefc' },
{ id: 'done', name: 'Done', limit: Infinity, tint: '#e4f3ea' },
];
function card(title: string, description = ''): DashboardWidgetSpec {
return {
id: `card-${++sequence}`, kind: 'card', span: 1, rows: 4,
resizable: false, data: { title, description },
};
}
const views: DashboardViewSpec[] = [{
id: 'team',
widgets: columns.map((column) => ({
id: column.id, title: column.name, span: 1, rows: 33,
columns: 1, maxRows: 30, pinned: true, movable: 'row',
resizable: false, stack: true, background: column.tint,
caption: {
text: column.name, height: 48,
background: 'transparent', border: 'none',
},
footer: { height: 44 },
widgets: column.id === 'backlog'
? [card('Write release notes'), card('Review the import flow',
'Check validation, error messages and the confirmation before replacing existing work.')]
: column.id === 'doing' ? [card('Measure card content')] : [],
})),
}];
function count(id: string): number {
return handle?.toJSON().views[0]?.widgets
.find((widget) => widget.id === id)?.widgets?.length ?? 0;
}
function changed(): void {
for (const column of columns) {
const n = count(column.id);
const label = counts.get(column.id);
if (label) label.textContent = Number.isFinite(column.limit)
? `${column.name} · ${n}/${column.limit}` : `${column.name} · ${n}`;
const button = addButtons.get(column.id);
if (button) button.disabled = !handle || n >= column.limit;
}
}
function paintCard(widget: DashboardWidgetSpec, host: HTMLElement): void {
const content = document.createElement('article');
content.style.cssText = 'box-sizing:border-box;padding:12px;border:1px solid #dfe3ea;border-radius:8px;background:white;color:#1d2330;font:14px/1.4 system-ui';
const title = document.createElement('strong');
title.textContent = String(widget.data?.['title'] ?? widget.title ?? 'Task');
content.append(title);
const description = widget.data?.['description'];
if (typeof description === 'string' && description) {
const paragraph = document.createElement('p');
paragraph.textContent = description;
content.append(paragraph);
}
host.replaceChildren(content);
}
function openSaved(): void {
if (!saved) return;
let spec: ReturnType<typeof fromDocument>;
try {
spec = fromDocument(saved, { renderWidget: paintCard });
} catch (error) {
window.alert(error instanceof Error ? error.message : 'Cannot open the saved board.');
return;
}
const dialog = document.createElement('dialog');
const close = document.createElement('button');
close.textContent = 'Close saved board';
const target = document.createElement('div');
target.style.cssText = 'width:80vw;height:480px';
dialog.append(close, target);
document.getElementsByTagName('body').item(0)!.append(dialog);
dialog.showModal();
const preview = render(spec, target);
spec.handle.setStatic(true);
close.addEventListener('click', () => dialog.close());
dialog.addEventListener('close', () => {
preview.dispose();
dialog.remove();
}, { once: true });
}
const options: DashboardOptions = {
columns: 3, gap: 8, sizing: 'grow', rowHeight: 8, autoHeight: true,
canDrop: ({ to }) => {
const column = columns.find((candidate) => candidate.id === to);
return !!column && count(to) < column.limit;
},
renderCaption: (widget, host) => {
const label = document.createElement('strong');
label.style.cssText = 'display:block;padding:8px;font:600 14px system-ui';
host.replaceChildren(label);
counts.set(widget.id, label);
changed();
},
renderFooter: (widget, host) => {
const add = document.createElement('button');
add.textContent = '+ Add';
add.setAttribute('data-axdb-pass', '');
add.addEventListener('click', () => {
const column = columns.find((candidate) => candidate.id === widget.id);
if (!handle || !column || count(column.id) >= column.limit) return;
handle.addWidget(card('New task'), column.id);
});
host.replaceChildren(add);
addButtons.set(widget.id, add);
if (widget.id === 'backlog') {
const save = document.createElement('button');
save.textContent = 'Save';
const open = document.createElement('button');
open.textContent = 'Open saved';
open.disabled = true;
save.addEventListener('click', () => {
if (!handle) return;
// Materialize the live board data as a document for envelope persistence.
const staging = document.createElement('div');
staging.style.cssText = 'position:fixed;left:-10000px;width:1000px;height:560px';
document.getElementsByTagName('body').item(0)!.append(staging);
const copy = render(dashboard({
...handle.toJSON(), renderWidget: paintCard,
}), staging);
try {
saved = new DiagramSerializer().serializeEnvelope(copy.getModel());
} finally {
copy.dispose();
staging.remove();
}
open.disabled = false;
});
open.addEventListener('click', openSaved);
host.append(save, open);
}
changed();
},
};
return {
views, options, paintCard, changed,
ready(live: DashboardHandle): void {
handle = live;
changed();
},
};
}
The three parent columns each initially occupy one column by 33 rows. The inner lists reserve 30 rows as drop space; the parent slab starts with three additional rows for the caption. footer reserves a separate band for the Add button. renderCaption paints the live count, and renderFooter paints your controls.
2. Mount the board
Use the binding's own content surface: React widget components, Vue slots or Angular widget templates. JavaScript and Qwik use the shared DOM painter. These card bodies are application content; the kit still owns placement, measurement and dragging.
This board needs no packages beyond the quick start; see the JavaScript quick start for the shared package setup and your framework's quick start for its binding.
The JavaScript, React and Vue mounts below add card content and connect the live board to its counts and WIP controls; see configure dashboard layout for general mounting and widget-rendering setup.
- Angular uses
GrafloriaDashboardComponentwithGrafloriaWidgetDefDirectivefrom the Angular package. - Qwik uses
GrafloriaDiagram. Build the function-bearing kit spec inspec$, in the browser.
Place the following code in the indicated file. Render KanbanBoard from the quick start's application component; in Angular, import KanbanBoardComponent and add <app-kanban-board /> to its template. In JavaScript, add import './board-entry'; to your existing entry file without removing its stylesheet imports. This entry creates a visible container and mounts the shared board; its Close board button tears that view down.
tsimport { dashboard, render } from '@grafloria/element';
import { createBoard } from './kanban';
const container = document.createElement('div');
container.style.cssText = 'width:100%;height:560px';
const close = document.createElement('button');
close.textContent = 'Close board';
document.body.append(close, container);
const board = createBoard();
const spec = dashboard({
...board.options, views: board.views,
renderWidget: board.paintCard, onLayoutChange: board.changed,
});
const instance = render(spec, container);
board.ready(spec.handle);
close.addEventListener('click', () => {
instance.dispose();
container.remove();
close.remove();
});
tsximport { useState } from 'react';
import { GrafloriaDashboard } from '@grafloria/react';
import type { WidgetProps } from '@grafloria/react';
import { createBoard } from './kanban';
function Card({ data }: WidgetProps) {
return (
<article style={{ padding: 12, background: 'white', color: '#1d2330',
border: '1px solid #dfe3ea', borderRadius: 8, font: '14px/1.4 system-ui' }}>
<strong>{String(data['title'] ?? 'Task')}</strong>
{data['description'] ? <p>{String(data['description'])}</p> : null}
</article>
);
}
export function KanbanBoard() {
const [board] = useState(createBoard);
return (
<GrafloriaDashboard views={board.views} options={board.options}
widgetTypes={{ card: Card }} onReady={board.ready}
onLayoutChange={board.changed} style={{ height: 560 }} />
);
}
vue<script setup lang="ts"> import { GrafloriaDashboard } from '@grafloria/vue'; import { createBoard } from './kanban'; const board = createBoard(); </script> <template> <GrafloriaDashboard :views="board.views" :options="board.options" @ready="board.ready" @layout-change="board.changed" style="height:560px"> <template #widget-card="{ data }"> <article style="padding:12px;background:white;color:#1d2330;border:1px solid #dfe3ea;border-radius:8px;font:14px/1.4 system-ui"> <strong>{{ data['title'] }}</strong> <p v-if="data['description']">{{ data['description'] }}</p> </article> </template> </GrafloriaDashboard> </template>
tsimport { Component } from '@angular/core';
import { GrafloriaDashboardComponent, GrafloriaWidgetDefDirective } from '@grafloria/angular';
import { createBoard } from './kanban';
@Component({
selector: 'app-kanban-board',
imports: [GrafloriaDashboardComponent, GrafloriaWidgetDefDirective],
template: `
<grafloria-dashboard [views]="board.views" [options]="board.options"
(ready)="board.ready($event)" (layoutChange)="board.changed()"
style="display:block;height:560px">
<ng-template grafloriaWidget="card" let-data="data">
<article style="padding:12px;background:white;color:#1d2330;border:1px solid #dfe3ea;border-radius:8px;font:14px/1.4 system-ui">
<strong>{{ data['title'] }}</strong>
@if (data['description']) { <p>{{ data['description'] }}</p> }
</article>
</ng-template>
</grafloria-dashboard>
`,
})
export class KanbanBoardComponent {
readonly board = createBoard();
}
tsximport { component$ } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import { dashboard } from '@grafloria/element';
import { createBoard } from './kanban';
export const KanbanBoard = component$(() => (
<GrafloriaDiagram style={{ height: '560px' }} spec$={() => {
const board = createBoard();
const spec = dashboard({
...board.options, views: board.views,
renderWidget: board.paintCard, onLayoutChange: board.changed,
});
requestAnimationFrame(() => board.ready(spec.handle));
return spec;
}} />
));
You get Backlog with two cards, In progress with one, and an empty Done list. The longer Backlog card takes more rows than the short card. The headers show live counts, In progress shows its limit, and every list has an Add button.
3. Restrict drops and reorder lists
Drag a card into In progress: it joins that list, and the header count updates through layoutChange (or the kit's onLayoutChange). Once the count reaches two, that column refuses incoming cards and its Add button disables. The top-level team board is not an allowed destination, so cards remain inside lists.
canDrop receives widgetId, from, to and viewId. to is a view or container id; from is null for a palette item. The kit asks once per destination board per drag, but not for the source board. Reordering within a full column therefore remains possible. On refusal the dragged widget dims, the destination does not reflow, and releasing returns it home.
The policy does not run for addWidget() or undo. That is why the shared Add handler checks the limit before calling addWidget(). Omitting coordinates appends the new card through automatic placement in the list.
Drag a list's caption to trade places with another list. movable: 'row' restricts container movement to its row among other row-reorder containers; it does not move a list into another board. stack: true separately controls card order: dropping below the last card places it immediately after that card. These gestures use the kit's history; see commands and history for application-wide Undo/Redo controls.
4. Save live membership and reopen it
Choose Save in Backlog's footer, move a card, then choose Open saved. The saved board opens as a mounted, static board in a dialog; your newer edits remain in the original board. Closing the dialog disposes only the preview instance.
Save projects the live card membership into a temporary off-screen board, serializes its document, then disposes that instance while keeping the envelope in memory; see model and document for the serialization API and envelope format.
Open saved passes that envelope once to fromDocument, with the application's card painter, then mounts the returned spec. A checksum mismatch throws; the sample displays the error and leaves your current board untouched. It does not deserialize the payload a second time.
toJSON() reads live membership, including cross-column moves, instead of the original views literal. The layout-change reporter also follows history commands, undo and redo, so counts and Add-button state update when changes come from outside the button handlers.
| Saved board document content | Reopened board |
|---|---|
| Views, nested widget membership and cells | Restored from the live board tree |
| Widget payload, title, container caption and footer geometry | Retained as board data |
| Board geometry and live sizing, float, RTL and static settings | Retained; the preview deliberately enables static mode |
| Painter and callback functions | Not stored; supply application rendering and policies again |
| Camera position and selection | Not captured by the intermediate board-data projection |
This saves the board-data projection, not other diagram content outside the dashboard. For saving an existing diagram instance directly to a durable document file, use save and restore documents. The example keeps the envelope in memory and opens a separate view rather than replacing ongoing work.
Options that matter
| Option | Type | Default | What it does |
|---|---|---|---|
DashboardOptions.columns | number | 12 | Sets the parent grid width; this sample uses three columns |
DashboardOptions.gap | number | 8 | Gap between widgets and board padding, in pixels |
DashboardOptions.sizing | 'fit' | 'grow' | 'grow' on fluid boards; 'fit' on fixed boards | fit bounds the board; grow keeps row height and extends the board |
DashboardOptions.rowHeight | number | 130 | Row height in grow mode; a smaller unit gives finer content-height rounding |
DashboardOptions.autoHeight | boolean | false | Measures card content and assigns whole rows; containers ignore it |
DashboardOptions.canDrop | callback | Absent | Allows or refuses pointer drop destinations |
DashboardWidgetSpec.stack | boolean | false | Makes the inner board an ordered, top-packed list |
DashboardWidgetSpec.movable | boolean | 'row' | true | true allows dragging; false prevents pointer movement; 'row' restricts containers to list reordering |
DashboardWidgetSpec.resizable | boolean | true | Allows pointer resizing; disabled here for both lists and cards |
DashboardWidgetSpec.caption | SectionCaption | Absent | Reserves and paints the section's caption band |
SectionCaption accepts false (no band), true (use the title), a string (use that text), or a caption-options object (text, height and styling, as above). Keep gravity's default float: false; there is no need to pass it or call refresh() after history changes.
Pitfalls and related guides
Paint into a child of the supplied widget host, as paintCard() does. Replacing the host's className removes classes the kit uses to raise a dragged card above its neighbors.
For host sizing, see nest containers and lanes. For editing content after mount, see compute connected data; for Qwik's browser-only live objects, see resumable integration.
Try the live Kanban board to explore stacked cards and WIP limits. The Kanban studio expands the same list model with covers, labels, due dates, checklists and a card editor.
Continue with build a dashboard for built-in widget kinds and multiple views, or configure dashboard layout for responsive columns and split layouts.
Was this page helpful?