Build a dashboard

how-to

3 min readUpdated 2026-10-06

Declare widgets as data, mount the board, then use its handle for view changes, layout changes, programmatic moves and persistence. The result is a live board whose built-in widget painters draw KPI, line, donut, bar, funnel and table widgets; users can drag and resize it when the board is not static.

When to use this

Use the dashboard kit when your page needs a grid of independently movable widgets, more than one board view, or a saved layout. Give the mounted element a height: a dashboard in a zero-height container has no visible board.

1. Declare the board

dashboard takes DashboardOptions and returns a DashboardSpec. Each widget is a DashboardWidgetSpec; each view follows DashboardViewSpec. Omit renderWidget to use the shipped painters.

ts
import { dashboard, render } from '@grafloria/element';

const spec = dashboard({
  columns: 12,
  sizing: 'grow',
  views: [
    {
      id: 'overview',
      name: 'Overview',
      widgets: [
        {
          id: 'revenue',
          kind: 'kpi',
          span: 3,
          rows: 1,
          data: { label: 'Revenue', value: '$6.81M', delta: 12.4 },
        },
        {
          id: 'trend',
          kind: 'line',
          span: 9,
          rows: 2,
          title: 'Revenue trend',
          data: {
            series: [{ name: 'Revenue', values: [420, 455, 512] }],
            labels: ['Jan', 'Feb', 'Mar'],
          },
        },
      ],
    },
    {
      id: 'sales',
      name: 'Sales',
      widgets: [
        {
          id: 'regions',
          kind: 'donut',
          span: 6,
          rows: 2,
          title: 'By region',
          data: { slices: [{ label: 'EMEA', value: 1920 }, { label: 'APAC', value: 1340 }] },
        },
      ],
    },
  ],
});

const canvas = document.createElement('div');
canvas.id = 'dashboard';
canvas.style.display = 'block';
canvas.style.width = '1180px';
canvas.style.height = '660px';
document.body.append(canvas);
const instance = render(spec, canvas);
const handle = spec.handle;

handle.showView('sales');
handle.setLayout('grid');
handle.widget('regions')?.resize(8, 3);
localStorage.setItem('dashboard', JSON.stringify(handle.toJSON()));

window.addEventListener('unload', () => instance.dispose());

The render() call mounts the spec and returns a live diagram instance. The handle exposes the dashboard facade: showView() changes the on-camera view, setLayout() changes the active view between the cell grid and split layout, widget() finds one widget, and resize() accepts cell span and row count. The last line saves plain data, not a renderer object.

2. Mount it in each framework

The same views data drives all bindings. The examples below mount a board with a real height, switch between grid and split layouts, move and resize a widget through the typed handle, and save the snapshot.

js
import { dashboard, render } from '@grafloria/element';

const views = [{ id: 'main', name: 'Main', widgets: [
  { id: 'revenue', kind: 'kpi', span: 4, rows: 1, data: { label: 'Revenue', value: '$6.81M' } },
  { id: 'trend', kind: 'line', span: 8, rows: 2, title: 'Trend', data: { series: [[1, 2, 3]], labels: ['A', 'B', 'C'] } },
]}];
const spec = dashboard({ views, sizing: 'grow' });
const canvas = document.createElement('div');
canvas.id = 'dashboard';
canvas.style.display = 'block';
canvas.style.width = '1180px';
canvas.style.height = '660px';
document.body.append(canvas);
const instance = render(spec, canvas);
const handle = spec.handle;
handle.setLayout('split');
handle.widget('trend')?.moveTo(2, 0);
void handle.widget('trend')?.resize(6, 2);
localStorage.setItem('dashboard', JSON.stringify(handle.toJSON()));
window.addEventListener('unload', () => instance.dispose());

tsx
import { useState } from 'react';
import { GrafloriaDashboard } from '@grafloria/react';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

const views: DashboardViewSpec[] = [{ id: 'main', name: 'Main', widgets: [
  { id: 'revenue', kind: 'kpi', span: 4, rows: 1, data: { label: 'Revenue', value: '$6.81M' } },
  { id: 'trend', kind: 'line', span: 8, rows: 2, title: 'Trend', data: { series: [[1, 2, 3]], labels: ['A', 'B', 'C'] } },
]}];

export default function DashboardPage() {
  const [handle, setHandle] = useState<DashboardHandle>();
  const [layout, setLayout] = useState<'grid' | 'split'>('grid');
  const [status, setStatus] = useState('Ready');
  async function moveTrend() { setStatus('Moving trend…'); const accepted = await handle?.widget('trend')?.moveTo(2, 0); setStatus(accepted ? 'Trend moved to column 2' : 'Move refused'); }
  async function resizeTrend() { setStatus('Resizing trend…'); const accepted = await handle?.widget('trend')?.resize(6, 2); setStatus(accepted ? 'Trend resized to 6 columns by 2 rows' : 'Resize refused'); }
  return <div style={{ height: 500 }}>
    <button onClick={() => { const next = layout === 'grid' ? 'split' : 'grid'; setLayout(next); handle?.setLayout(next); }}>Switch layout</button>
    <button onClick={moveTrend}>Move trend</button>
    <button onClick={resizeTrend}>Resize trend</button>
    <button onClick={() => localStorage.setItem('dashboard', JSON.stringify(handle?.toJSON()))}>Save</button>
    <output>{status}</output>
    <GrafloriaDashboard views={views} layout={layout} onReady={setHandle} style={{ display: 'block', height: 440 }} />
  </div>;
}

vue
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

const handle = ref<DashboardHandle | null>(null);
const layout = ref<'grid' | 'split'>('grid');
const status = ref('Ready');
const views: DashboardViewSpec[] = [{ id: 'main', name: 'Main', widgets: [
  { id: 'revenue', kind: 'kpi', span: 4, rows: 1, data: { label: 'Revenue', value: '$6.81M' } },
  { id: 'trend', kind: 'line', span: 8, rows: 2, title: 'Trend', data: { series: [[1, 2, 3]], labels: ['A', 'B', 'C'] } },
]}];
function switchLayout() { layout.value = layout.value === 'grid' ? 'split' : 'grid'; handle.value?.setLayout(layout.value); }
function save() { localStorage.setItem('dashboard', JSON.stringify(handle.value?.toJSON())); }
async function moveTrend() { status.value = 'Moving trend…'; const accepted = await handle.value?.widget('trend')?.moveTo(2, 0); status.value = accepted ? 'Trend moved to column 2' : 'Move refused'; }
async function resizeTrend() { status.value = 'Resizing trend…'; const accepted = await handle.value?.widget('trend')?.resize(6, 2); status.value = accepted ? 'Trend resized to 6 columns by 2 rows' : 'Resize refused'; }
</script>
<template>
  <div style="height:500px">
    <button @click="switchLayout">Switch layout</button>
    <button @click="moveTrend">Move trend</button>
    <button @click="resizeTrend">Resize trend</button>
    <button @click="save">Save</button>
    <output>{{ status }}</output>
    <GrafloriaDashboard :views="views" :layout="layout" @ready="handle = $event" style="display:block;height:440px" />
  </div>
</template>

ts
import { Component } from '@angular/core';
import { GrafloriaDashboardComponent } from '@grafloria/angular';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

@Component({
  standalone: true,
  imports: [GrafloriaDashboardComponent],
  template: `
    <button (click)="switchLayout()">Switch layout</button>
    <button (click)="moveTrend()">Move trend</button>
    <button (click)="resizeTrend()">Resize trend</button>
    <button (click)="save()">Save</button>
    <output>{{ status }}</output>
    <grafloria-dashboard [views]="views" [layout]="layout" (ready)="handle = $event"
      style="display:block;height:440px" />
  `,
})
export class DashboardPage {
  handle?: DashboardHandle;
  layout: 'grid' | 'split' = 'grid';
  status = 'Ready';
  views: DashboardViewSpec[] = [{ id: 'main', name: 'Main', widgets: [
    { id: 'revenue', kind: 'kpi', span: 4, rows: 1, data: { label: 'Revenue', value: '$6.81M' } },
    { id: 'trend', kind: 'line', span: 8, rows: 2, title: 'Trend', data: { series: [[1, 2, 3]], labels: ['A', 'B', 'C'] } },
  ]}];
  switchLayout() { this.layout = this.layout === 'grid' ? 'split' : 'grid'; this.handle?.setLayout(this.layout); }
  async moveTrend() { this.status = 'Moving trend…'; const accepted = await this.handle?.widget('trend')?.moveTo(2, 0); this.status = accepted ? 'Trend moved to column 2' : 'Move refused'; }
  async resizeTrend() { this.status = 'Resizing trend…'; const accepted = await this.handle?.widget('trend')?.resize(6, 2); this.status = accepted ? 'Trend resized to 6 columns by 2 rows' : 'Resize refused'; }
  save() { localStorage.setItem('dashboard', JSON.stringify(this.handle?.toJSON())); }
}

tsx
// In a Qwik component, follow the dashboard demo's binding:
// import { GrafloriaDashboard } from '@grafloria/qwik';
// import { $, noSerialize, useSignal } from '@builder.io/qwik';
//
// <GrafloriaDashboard
//   views={views}
//   layout={layout.value}
//   sizing={sizing.value}
//   onReady$={$((value) => { handle.value = noSerialize(value); })}
// />
//
// The toolbar handlers call the same live handle as the other bindings:
// handle.value?.setLayout('split');
// await handle.value?.widget('trend')?.moveTo(2, 0);
// await handle.value?.widget('trend')?.resize(6, 2);
// localStorage.setItem('dashboard', JSON.stringify(handle.value?.toJSON()));

In every binding, the board paints the declared cards inside the sized container. Pointer drag and corner resize use the same live grid as moveTo() and resize(); a committed change is reported by onLayoutChange (or the Angular/Vue output). Use that callback instead of maintaining a second copy of the layout.

3. Persist and restore the board

DashboardSnapshot is the whole board as plain data. Save handle.toJSON() after a user change. To restore it in JavaScript, pass the parsed snapshot back to dashboard, supplying the rendering callback if you use custom widgets.

ts
import { dashboard, render } from '@grafloria/element';
import type { DashboardSnapshot } from '@grafloria/element';

const canvas = document.createElement('div');
canvas.id = 'dashboard';
canvas.style.display = 'block';
canvas.style.width = '1180px';
canvas.style.height = '660px';
document.body.append(canvas);
const source = dashboard({ widgets: [
  { id: 'revenue', kind: 'kpi', span: 4, rows: 1, data: { label: 'Revenue', value: '$6.81M' } },
] });
const snapshot: DashboardSnapshot = source.handle.toJSON();
localStorage.setItem('dashboard', JSON.stringify(snapshot));
const saved = localStorage.getItem('dashboard');
if (!saved) throw new Error('Dashboard snapshot was not saved');
const restored = dashboard(JSON.parse(saved) as DashboardSnapshot);
render(restored, canvas);

For a controlled framework board, keep the snapshot in application state and provide its views and options to the component. Do not recreate the board for each gesture; use the ready handle and the layout-change callback.

Options that matter

Option	Type	Default	What it does
`columns`	`number`	`12`	Sets the column count for every view unless a view overrides it.
`gap`	`number`	`8`	Sets the widget gap and board padding in pixels.
`sizing`	`'fit' \| 'grow'`	`'grow'`	`grow` keeps row height and extends the board; `fit` keeps the board height and squeezes rows.
`layout`	`'grid' \| 'split'`	`'grid'`	Selects the cell grid or splitter layout.
`rowHeight`	`number`	`130`	Sets row height in `grow` mode.
`float`	`boolean`	`false`	When false, gravity packs widgets upward; when true, gaps are allowed.
`rtl`	`boolean`	`false`	Mirrors pixels so column zero renders at the right edge without changing cells.
`responsive`	`DashboardResponsiveOptions`	—	Derives the live column count from board width.
`static`	`boolean`	`false`	Disables pointer drag, resize and handles while API and keyboard access remain available.
`views` / `widgets`	`DashboardViewSpec[]` / `DashboardWidgetSpec[]`	—	Use `views` for tabs, or `widgets` as shorthand for one unnamed view; they are mutually exclusive.

Pitfalls

Give the host a height. The kit cannot paint a useful board into a zero-height element.
fit is bounded: a drop, resize or addWidget() that needs another row is refused. Use grow or overflow: 'scroll' when the board must accommodate more rows.
static is a viewing mode. It removes drag, resize and handles; it does not remove API operations.
width and height are fixed-board dimensions. A fluid board follows its container instead.
A widget with pinned: true refuses the mover and survives reflow. Use movable: false or resizable: false when only one gesture must be disabled.

Live demos

Dashboard builder shows tabbed views, built-in widget kinds, palette additions, pinning, fit/grow, layout switching and versioned saves.
Fluid dashboard shows fluid sizing, grid and split layouts, drag-handle modes and live additions.

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →