Use a dashboard when your users arrange widgets in cells rather than connect freely positioned nodes. Declare the widgets as data, mount the board, and use its handle to add widgets, update their data, switch views, and save the live layout.
The samples start in the projects from the JavaScript, React, Angular, and Qwik quick starts. Keep their entry files, configuration, and stylesheet imports. Add the files below; render the new component from your existing root, or open the new Qwik route.
Dashboard builder
The builder opens an Overview board containing a revenue KPI, a line chart, and a custom note. Its Pipeline view contains a funnel. The toolbar adds a KPI, updates revenue, selects the revenue tile, changes the drag handle or sizing, and saves a snapshot. Restore opens that snapshot in a separate static board, leaving the editable board untouched.
Try the authors' Dashboard builder for a larger palette and version browser; its source uses the same data-first authoring pattern.
1. Install the dashboard packages
The quick starts already install these packages. If your project does not have them, use the command for your binding. The framework itself comes from its starter.
JavaScript:
bashnpm install @grafloria/element @grafloria/engine @grafloria/renderer
React:
bashnpm install @grafloria/react @grafloria/element @grafloria/engine @grafloria/renderer
Angular:
bashnpm install @grafloria/angular @grafloria/element @grafloria/engine @grafloria/renderer
Qwik:
bashnpm install -D @grafloria/qwik @grafloria/element @grafloria/engine @grafloria/renderer
2. Declare the board and its live actions
Use DashboardWidgetSpec for each widget, DashboardViewSpec for each view, and DashboardOptions for board geometry. Omit x and y to flow widgets in declaration order, wrapping at the column count. span counts columns; rows counts rows.
Add this shared file at src/dashboard-data.ts in every project. All four bindings consume the same data. widgets is the single-view shorthand; do not pass it together with views to the same board.
tsimport type {
DashboardHandle,
DashboardOptions,
DashboardViewSpec,
DashboardWidgetSpec,
} from '@grafloria/element';
export const options: DashboardOptions = { columns: 6, gap: 12 };
export const widgets: DashboardWidgetSpec[] = [
{ id: 'revenue', kind: 'kpi', span: 3,
data: { label: 'Revenue', value: '$6.81M', delta: 12.4,
spark: [42, 45, 51, 61, 76] } },
{ id: 'note', kind: 'note', span: 3, title: 'Sales note',
data: { text: 'Review the forecast on Friday.' } },
{ id: 'trend', kind: 'line', span: 6, rows: 2, title: 'Revenue trend',
data: { series: [{ name: 'Revenue', values: [420, 455, 512] }],
labels: ['Jan', 'Feb', 'Mar'] } },
];
export const views: DashboardViewSpec[] = [
{ id: 'overview', name: 'Overview', widgets },
{ id: 'pipeline', name: 'Pipeline', widgets: [
{ id: 'funnel', kind: 'funnel', span: 6, rows: 2, title: 'Pipeline',
data: { stages: [{ label: 'Leads', value: 900 },
{ label: 'Won', value: 210 }] } },
] },
];
let nextWidgetId = 0;
export function actions(handle: DashboardHandle) {
return {
add: () => {
let id: string;
do { id = `added-kpi-${++nextWidgetId}`; } while (handle.widget(id));
const added = handle.addWidget({
id, kind: 'kpi', span: 3,
data: { label: 'New KPI', value: '42' },
});
if (!added) window.alert('This board has no room for another widget.');
},
update: () => handle.widget('revenue')?.update({
data: { label: 'Revenue', value: '$7.02M', delta: 3.1 },
}),
select: () => {
handle.showView('overview');
handle.selectWidget('revenue');
},
caption: () => handle.setDragHandle(true),
sizing: () => handle.setSizing(handle.getSizing() === 'fit' ? 'grow' : 'fit'),
};
}
DashboardHandle is the live façade. addWidget() creates the node and its membership as one undoable step and returns a widget handle, or undefined when the board refuses the addition. widget(id) returns a WidgetHandle, or undefined for an unknown ID. update() replaces its data and repaints it; it is a data-feed operation, not an undoable inspector edit.
showView() frames the named view and parks the others off-camera. selectWidget() adds the selection ring without moving keyboard focus. setDragHandle(true) restricts dragging to the caption strip; the custom note's top band supplies that strip when it has no kit header. getSizing() reads the active view's sizing, and setSizing() changes the grid sizing setting. A split view always reports fit.
3. Mount your binding
Each tab includes the editable multi-view board and a single-view static preview. The latter demonstrates widgets without combining it with views. Custom notes render through a framework component, slot, or template; built-in kinds need no chart package.
For JavaScript, dashboard returns a render spec and its handle. render mounts it and runs its finalization automatically. Use defaultWidgetRenderer for kinds your painter does not own.
For React, render GrafloriaDashboard and type custom component props with WidgetProps. For Vue, render GrafloriaDashboard and supply #widget-note. Angular uses GrafloriaDashboardComponent and GrafloriaWidgetDefDirective. Qwik uses GrafloriaDashboard and WidgetProps; keep its live handle in noSerialize() state.
The JavaScript entry preserves the quick start's stylesheet import. In React, add the component below to the existing app rather than replacing its entry file. In Angular, import DashboardBuilderComponent into the existing root component's imports and add <app-dashboard-builder /> to its template, retaining the router outlet. In Qwik, import the default component from ../../DashboardBuilder in src/routes/dashboard/index.tsx, render <DashboardBuilder /> in that route, and open /dashboard/.
tsimport './style.css';
import { dashboard, defaultWidgetRenderer, render } from '@grafloria/element';
import type { DashboardSnapshot, DashboardWidgetSpec } from '@grafloria/element';
import { actions, options, views, widgets } from './dashboard-data';
const app = document.getElementById('app')!;
app.replaceChildren();
const toolbar = document.createElement('nav');
const board = document.createElement('div');
board.style.height = '500px';
const preview = document.createElement('div');
preview.style.height = '300px';
const restored = document.createElement('div');
restored.style.height = '500px';
app.append(toolbar, board, preview, restored);
function paint(widget: DashboardWidgetSpec, host: HTMLElement): void {
if (widget.kind !== 'note') {
defaultWidgetRenderer(widget, host);
return;
}
const note = document.createElement('div');
note.style.cssText = 'height:100%;padding:16px;box-sizing:border-box;background:#fff4ce';
note.textContent = `${widget.title}: ${String(widget.data?.['text'] ?? '')}`;
host.replaceChildren(note);
}
const spec = dashboard({ ...options, views, renderWidget: paint });
const editor = render(spec, board);
const single = render(dashboard({ ...options, widgets, static: true,
renderWidget: paint }), preview);
let saved: DashboardSnapshot | undefined;
let restoredInstance: ReturnType<typeof render> | undefined;
const commands = actions(spec.handle);
function button(label: string, run: () => void): void {
const element = document.createElement('button');
element.textContent = label;
element.onclick = run;
toolbar.append(element);
}
button('Overview', () => spec.handle.showView('overview'));
button('Pipeline', () => spec.handle.showView('pipeline'));
button('Add KPI', commands.add);
button('Update revenue', commands.update);
button('Select revenue', commands.select);
button('Drag by caption', commands.caption);
button('Toggle sizing', commands.sizing);
button('Save', () => { saved = spec.handle.toJSON(); });
button('Restore separately', () => {
if (!saved) return;
restoredInstance?.dispose();
restoredInstance = render(dashboard({ ...saved, static: true,
renderWidget: paint }), restored);
});
button('Close dashboard', () => {
editor.dispose();
single.dispose();
restoredInstance?.dispose();
app.replaceChildren();
});
tsximport { lazy, Suspense, useRef, useState } from 'react';
import type { WidgetProps } from '@grafloria/react';
import type { DashboardHandle, DashboardSnapshot } from '@grafloria/element';
import { actions, options, views, widgets } from './dashboard-data';
const GrafloriaDashboard = lazy(() => import('@grafloria/react').then(module => ({
default: module.GrafloriaDashboard,
})));
function Note({ widget, data }: WidgetProps) {
return <div style={{ height: '100%', padding: 16, boxSizing: 'border-box',
background: '#fff4ce' }}><b>{widget.title}</b><p>{String(data['text'] ?? '')}</p></div>;
}
const widgetTypes = { note: Note };
export default function DashboardBuilder() {
const handle = useRef<DashboardHandle | null>(null);
const [tab, setTab] = useState('overview');
const [layout, setLayout] = useState<'grid' | 'split'>('grid');
const [saved, setSaved] = useState<DashboardSnapshot | null>(null);
const [restored, setRestored] = useState<DashboardSnapshot | null>(null);
const [generation, setGeneration] = useState(0);
const [lastChange, setLastChange] = useState('No committed layout changes');
function run(name: keyof ReturnType<typeof actions>) {
if (handle.current) actions(handle.current)[name]();
}
return <Suspense fallback={<p>Loading dashboard…</p>}><section>
<nav>
{views.map(v => <button key={v.id} onClick={() => setTab(v.id)}>{v.name}</button>)}
<button onClick={() => run('add')}>Add KPI</button>
<button onClick={() => run('update')}>Update revenue</button>
<button onClick={() => { setTab('overview'); run('select'); }}>Select revenue</button>
<button onClick={() => run('caption')}>Drag by caption</button>
<button onClick={() => run('sizing')}>Toggle sizing</button>
<button onClick={() => setLayout(layout === 'grid' ? 'split' : 'grid')}>Toggle layout</button>
<button onClick={() => { if (handle.current) setSaved(handle.current.toJSON()); }}>Save</button>
<button disabled={!saved} onClick={() => {
setRestored(saved); setGeneration(n => n + 1);
}}>Restore separately</button>
</nav>
<p>{lastChange}</p>
<GrafloriaDashboard views={views} options={options} activeView={tab}
layout={layout} widgetTypes={widgetTypes} className="editor-board"
style={{ height: 500 }} onReady={h => { handle.current = h; }}
onLayoutChange={({ viewId, widgets: changed }) => {
setLastChange(`${viewId}: ${changed.length} widgets in the committed layout`);
}}>
<span style={{ position: 'absolute', right: 8, bottom: 8,
pointerEvents: 'none' }}>Dashboard editor</span>
</GrafloriaDashboard>
<h3>Single-view preview</h3>
<GrafloriaDashboard widgets={widgets} options={options} static
widgetTypes={widgetTypes} style={{ height: 300 }} />
{restored && <><h3>Restored snapshot</h3>
<GrafloriaDashboard key={generation} views={restored.views} options={restored}
static widgetTypes={widgetTypes} style={{ height: 500 }} /></>}
</section></Suspense>;
}
tsimport { Component, signal } from '@angular/core';
import { GrafloriaDashboardComponent, GrafloriaWidgetDefDirective } from '@grafloria/angular';
import type { DashboardHandle, DashboardSnapshot, DashboardWidgetSpec } from '@grafloria/element';
import { actions, options, views, widgets } from '../dashboard-data';
@Component({
selector: 'app-dashboard-builder',
imports: [GrafloriaDashboardComponent, GrafloriaWidgetDefDirective],
styles: ['.note {height:100%;padding:16px;box-sizing:border-box;background:#fff4ce}'],
template: `
<nav>
@for (v of views; track v.id) {
<button (click)="tab = v.id">{{ v.name }}</button>
}
<button (click)="run('add')">Add KPI</button>
<button (click)="run('update')">Update revenue</button>
<button (click)="tab = 'overview'; run('select')">Select revenue</button>
<button (click)="run('caption')">Drag by caption</button>
<button (click)="run('sizing')">Toggle sizing</button>
<button (click)="layout.set(layout() === 'grid' ? 'split' : 'grid')">Toggle layout</button>
<button (click)="save()">Save</button>
<button [disabled]="!saved()" (click)="restore()">Restore separately</button>
</nav>
<p>{{ lastChange() }}</p>
<grafloria-dashboard [views]="views" [options]="options" [(activeView)]="tab"
[layout]="layout()" [sizing]="initialSizing" (ready)="handle.set($event)"
(layoutChange)="changed($event)" style="height:500px">
<ng-template grafloriaWidget="note" let-widget let-data="data">
<div class="note"><b>{{ widget.title }}</b><p>{{ data['text'] }}</p></div>
</ng-template>
</grafloria-dashboard>
<h3>Single-view preview</h3>
<grafloria-dashboard [widgets]="widgets" [options]="options" [static]="true" style="height:300px">
<ng-template grafloriaWidget="note" let-data="data">
<div class="note">{{ data['text'] }}</div>
</ng-template>
</grafloria-dashboard>
@for (snapshot of restored(); track snapshot) {
<h3>Restored snapshot</h3>
<grafloria-dashboard [views]="snapshot.views" [options]="snapshot" [static]="true" style="height:500px">
<ng-template grafloriaWidget="note" let-data="data">
<div class="note">{{ data['text'] }}</div>
</ng-template>
</grafloria-dashboard>
}
`,
})
export class DashboardBuilderComponent {
readonly views = views;
readonly widgets = widgets;
readonly options = options;
readonly initialSizing = 'fit';
readonly layout = signal<'grid' | 'split'>('grid');
readonly handle = signal<DashboardHandle | undefined>(undefined);
readonly saved = signal<DashboardSnapshot | undefined>(undefined);
readonly restored = signal<DashboardSnapshot[]>([]);
readonly lastChange = signal('No committed layout changes');
tab: string | undefined = 'overview';
run(name: keyof ReturnType<typeof actions>): void {
const h = this.handle();
if (h) actions(h)[name]();
}
changed(e: { viewId: string; widgets: DashboardWidgetSpec[] }): void {
this.lastChange.set(`${e.viewId}: ${e.widgets.length} widgets in the committed layout`);
}
save(): void { this.saved.set(this.handle()?.toJSON()); }
restore(): void {
const snapshot = this.saved();
if (snapshot) this.restored.set([{ ...snapshot }]);
}
}
tsximport { component$, noSerialize, useSignal } from '@builder.io/qwik';
import type { NoSerialize } from '@builder.io/qwik';
import { GrafloriaDashboard } from '@grafloria/qwik';
import type { WidgetProps } from '@grafloria/qwik';
import type { DashboardHandle, DashboardSnapshot, DashboardViewSpec, DashboardWidgetSpec } from '@grafloria/element';
import { actions, options, views, widgets } from './dashboard-data';
const Note = component$<WidgetProps>(props => (
<div style={{ height: '100%', padding: '16px', boxSizing: 'border-box', background: '#fff4ce' }}>
<b>{props.widget.title}</b><p>{String(props.data['text'] ?? '')}</p>
</div>
));
export default component$(() => {
const handle = useSignal<NoSerialize<DashboardHandle>>();
const tab = useSignal('overview');
const layout = useSignal<'grid' | 'split'>('grid');
const saved = useSignal<DashboardSnapshot>();
const restored = useSignal<DashboardSnapshot>();
const generation = useSignal(0);
const lastChange = useSignal('No committed layout changes');
return <section>
<nav>
{views.map((v: DashboardViewSpec) => <button key={v.id} onClick$={() => { tab.value = v.id; }}>{v.name}</button>)}
<button onClick$={() => { if (handle.value) actions(handle.value).add(); }}>Add KPI</button>
<button onClick$={() => { if (handle.value) actions(handle.value).update(); }}>Update revenue</button>
<button onClick$={() => {
tab.value = 'overview'; if (handle.value) actions(handle.value).select();
}}>Select revenue</button>
<button onClick$={() => { if (handle.value) actions(handle.value).caption(); }}>Drag by caption</button>
<button onClick$={() => { if (handle.value) actions(handle.value).sizing(); }}>Toggle sizing</button>
<button onClick$={() => { layout.value = layout.value === 'grid' ? 'split' : 'grid'; }}>Toggle layout</button>
<button onClick$={() => { saved.value = handle.value?.toJSON(); }}>Save</button>
<button disabled={!saved.value} onClick$={() => {
restored.value = saved.value; generation.value++;
}}>Restore separately</button>
</nav>
<p>{lastChange.value}</p>
<GrafloriaDashboard views={views} options={options} activeView={tab.value}
layout={layout.value} widgetTypes={{ note: Note }}
class="editor-board" style={{ height: '500px' }}
onReady$={(h: DashboardHandle) => { handle.value = noSerialize(h); }}
onLayoutChange$={(e: { viewId: string; widgets: DashboardWidgetSpec[] }) => {
lastChange.value = `${e.viewId}: ${e.widgets.length} widgets in the committed layout`;
}} />
<h3>Single-view preview</h3>
<GrafloriaDashboard widgets={widgets} options={options} static
widgetTypes={{ note: Note }} style={{ height: '300px' }} />
{restored.value && <><h3>Restored snapshot</h3>
<GrafloriaDashboard key={generation.value} views={restored.value.views}
options={restored.value} static widgetTypes={{ note: Note }} style={{ height: '500px' }} /></>}
</section>;
});
The React sample opens with the KPI and custom note above the line chart, plus a static single-view preview below.
In React and Qwik, widgetTypes maps a kind to a component receiving { widget, data }. In Vue, slots receive that same context. Angular's let-widget receives the full spec and let-data="data" receives the payload. Kinds without a custom renderer use the shipped painters. React's children renders inside the dashboard root; the sample uses it for the Dashboard editor overlay.
The component's ready callback or output supplies the mounted handle. Layout callbacks report the affected view and its widget specs with live cells. The status line above follows those callbacks, including layout changes from history, rather than counting toolbar clicks.
Vue: mount the dashboard kit as a component
Start in the Vue quick start project and install any missing packages:
bashnpm install @grafloria/vue @grafloria/element @grafloria/engine @grafloria/renderer
Add this component to your existing root. It uses the shared data and actions from step 2. The Overview and Pipeline buttons write the active-view binding; the note renders through #widget-note, while the KPI, line and funnel use the built-in painters. Save records the live snapshot. Open saved board mounts a separate static preview rather than replacing the editor.
vue<script setup lang="ts"> import { ref, shallowRef } from 'vue'; import { GrafloriaDashboard } from '@grafloria/vue'; import type { DashboardHandle, DashboardSnapshot } from '@grafloria/element'; import { actions, options, views } from './dashboard-data'; const active = ref('overview'); const live = shallowRef<DashboardHandle>(); const snapshot = shallowRef<DashboardSnapshot>(); const previews = shallowRef<DashboardSnapshot[]>([]); const previewKey = ref(0); const message = ref('Board ready for editing'); function capture(): void { snapshot.value = live.value?.toJSON(); } function openSaved(): void { if (snapshot.value) { previews.value = [{ ...snapshot.value }]; previewKey.value++; } } function edit(action: keyof ReturnType<typeof actions>): void { const board = live.value; if (board) actions(board)[action](); } </script> <template> <section> <nav> <button v-for="view in views" :key="view.id" @click="active = view.id"> {{ view.name }} </button> <button @click="edit('add')">Add KPI</button> <button @click="edit('update')">Update revenue</button> <button @click="active = 'overview'; edit('select')">Select revenue</button> <button @click="edit('caption')">Drag by caption</button> <button @click="edit('sizing')">Toggle sizing</button> <button @click="capture">Save</button> <button :disabled="!snapshot" @click="openSaved">Open saved board</button> </nav> <p>{{ message }}</p> <GrafloriaDashboard :views="views" :options="options" v-model:active-view="active" style="height:500px" @ready="live = $event" @layout-change="message = $event.viewId + ': layout committed'"> <template #widget-note="{ widget, data }"> <article style="height:100%;padding:16px;box-sizing:border-box;background:#fff4ce"> <strong>{{ widget.title }}</strong><p>{{ data['text'] }}</p> </article> </template> </GrafloriaDashboard> <section v-for="savedBoard in previews" :key="previewKey"> <h3>Saved board</h3> <GrafloriaDashboard :views="savedBoard.views" :options="savedBoard" :static="true" style="height:500px"> <template #widget-note="{ data }"> <article style="height:100%;padding:16px;box-sizing:border-box;background:#fff4ce"> {{ data['text'] }} </article> </template> </GrafloriaDashboard> </section> </section> </template>
The Vue component emits ready with its handle and layoutChange with the affected view and live widgets. v-model:active-view drives showView() through the binding. Keep the same slots on the saved-board component: snapshot data does not contain their rendering functions. Each saved preview is a fresh mount; changing the editor's views prop is not a reload operation.
Save and restore the live layout
- Arrange the editable board, then press Save.
toJSON()returns aDashboardSnapshotread from the live board, not the original literal. - Make another edit. Press Restore separately. The sample mounts the saved snapshot through
dashboard()or the framework component in a separate static view. It never replaces your newer work. - Supply the same custom painter, component map, slots, or templates when mounting the restored board. Functions are app code, not snapshot data.
The samples keep the snapshot in application memory. For a JSON representation, use JSON.stringify(handle.toJSON()). This dashboard snapshot is an authoring format, not an integrity-checked full diagram document. Use Save and restore documents for versioned document storage and validation.
| Snapshot content | Restored result |
|---|---|
| Views, widgets, titles, kinds, payloads, live cells and pinning | Rebuilt from the snapshot |
| Columns, gap, row height, sizing, float, RTL and static settings | Retained; the preview deliberately overrides static to true |
| Per-view layout and split trees | Retained |
| Responsive layouts | Saves the widest cached layout, not only the currently narrow arrangement |
| Painter functions and event callbacks | Supplied again by your app |
| Top-level active view, selection, camera and undo history | Not in the dashboard snapshot; the restored board starts with its boot view |
Framework boards read views, widgets, and options at mount. Updating those props does not reload the board. The React and Qwik restore samples change a key to mount a new preview; Angular replaces the tracked preview object to mount a new component. activeView, layout, sizing, and static are live switches, not reload inputs.
Choose layout, sizing, and widget kinds
These choices apply to JavaScript options and the framework inputs alike.
| Option | Type | Default | What it does |
|---|---|---|---|
layout | 'grid' | 'split' | 'grid' | grid packs widgets in cells; split covers the board with a splitter tree and percentage dividers. Split always fits. |
sizing | 'fit' | 'grow' | grow on fluid boards; fit on fixed boards | fit keeps the board height and squeezes rows; grow keeps row height and extends downward. |
columns | number | 12 | Column count; each view can override it. |
gap | number | 8 | Widget spacing and board padding in pixels. |
rowHeight | number | 130 | Row height in grow mode. |
static | boolean | false | Disables pointer dragging, resizing and handles; API operations still work. |
The layout button switches between grid and split through the component's live layout input. Toggle sizing uses the handle. The Angular sample starts with fit to keep the editable board within its host. The other samples start with fluid grow sizing.
The six built-in kinds read these payload fields:
kind | data fields | What renders |
|---|---|---|
kpi | label, value, delta, deltaLabel, spark | Formatted headline, signed delta and sparkline |
line | series, labels | A line chart; series accepts bare numbers or named series with values |
bar | bars containing label and value | Bars with labels |
donut | slices containing label, value, optional color; centerLabel, centerCaption | Donut segments and center text |
funnel | stages containing label and value | Stages scaled against the largest value, with a minimum width to fit each value |
table | columns, rows | Table cells; numeric cells right-align |
Fields are optional. Missing or invalid data paints an empty state; an unknown kind paints a titled placeholder unless you provide a custom renderer.
Pitfalls and related tasks
- Use the handle for edits after mount. Do not replace a
viewsarray and expect the live board to rebuild. - In framework bindings, custom painting belongs in
widgetTypes, slots, or templates. The bindings install their ownrenderWidgetand layout callback, replacing those functions insideoptions. - A bounded fit board can refuse an addition, move, or resize that needs more rows than it can hold. Check the return value rather than assuming an addition succeeds.
- Custom widget hosts survive canvas repaints. Give a widget its own data flow when it must react independently; see Compute connected data.
- For resolved host heights, see Nest containers and lanes. For Qwik browser-only objects, see Qwik resumable integration.
For grid policies and lower-level integration, continue with Configure dashboard layout. bindDashboardGrid binds gestures to an existing board group; the dashboard authoring API already does that for you. cellToRect projects cells into world rectangles, while pointToCell maps a world position to the nearest cell without engine clamping. Neither is needed to declare this builder. refresh() re-reads boards after out-of-band model mutations; normal handle operations and history already synchronize them.
Use Commands and history for undoable app-side edits, and Export images and vector PDF for scoped exports of one dashboard view.
Was this page helpful?