Arrange dashboard containers

Use a cell grid when widgets need column spans and gravity packing. Use a split layout when widgets need to cover the board and resize through percentage dividers. Both layouts use the same dashboard data; you can switch the mounted board without replacing its widgets.

The example starts with two KPI cards, an Operations section, and a tab container showing Filters. Its controls switch Grid/Split and Fit/Grow, mirror the board, toggle gravity, and change the section caption or active tab.

1. Declare the board

Install the packages for the binding you use in your framework project.

JavaScript:

bash
Copy
npm install @grafloria/element @grafloria/engine @grafloria/renderer

Angular:

bash
Copy
npm install @grafloria/angular @angular/common @angular/core @angular/forms @angular/platform-browser @grafloria/engine @grafloria/renderer rxjs @grafloria/element

Qwik:

bash
Copy
npm install @grafloria/qwik @builder.io/qwik @grafloria/element @grafloria/engine @grafloria/renderer

React:

bash
Copy
npm install @grafloria/react react react-dom @grafloria/element @grafloria/engine @grafloria/renderer

Vue:

bash
Copy
npm install @grafloria/vue vue @grafloria/element @grafloria/engine @grafloria/renderer

Put the following shared file beside your component or browser entry point. This example adds an inner grid and tab pages to the DashboardWidgetSpec entries in a DashboardViewSpec; see Build a dashboard for board and widget declarations.

The kit draws the kpi kind from your data, so this layout needs no chart renderer. DashboardOptions supplies the shared geometry. These options omit width: the board uses fluid sizing at zoom 1 and follows its container. sizing: 'fit' keeps its height bounded.

ts
Copy
import type {
  DashboardOptions,
  DashboardViewSpec,
  DashboardWidgetSpec,
} from '@grafloria/element';

const widgets: DashboardWidgetSpec[] = [
  {
    id: 'revenue', kind: 'kpi', span: 6, rows: 1,
    data: { label: 'Revenue', value: '$6.81M', delta: 12.4 },
  },
  {
    id: 'customers', kind: 'kpi', span: 6, rows: 1,
    data: { label: 'Customers', value: '1,284', delta: 8.1 },
  },
  {
    id: 'ops', title: 'Operations', span: 8, rows: 3,
    columns: 4, sizing: 'fit',
    caption: { subtitle: 'Today', description: 'Operational KPIs' },
    widgets: [
      {
        id: 'orders', kind: 'kpi', span: 2, rows: 1,
        data: { label: 'Orders', value: '312' },
      },
      {
        id: 'churn', kind: 'kpi', span: 2, rows: 1,
        data: { label: 'Churn', value: '1.9%' },
      },
    ],
  },
  {
    id: 'side', title: 'Side panel', span: 4, rows: 3,
    layout: 'tabs', active: 'filters', tabs: { stretch: true },
    widgets: [
      {
        id: 'filters', title: 'Filters', columns: 1, sizing: 'fit',
        widgets: [
          {
            id: 'region', kind: 'kpi', span: 1, rows: 1,
            data: { label: 'Region', value: 'EMEA' },
          },
        ],
      },
      {
        id: 'alerts', title: 'Alerts', columns: 1, sizing: 'fit',
        widgets: [
          {
            id: 'open-alerts', kind: 'kpi', span: 1, rows: 1,
            data: { label: 'Open alerts', value: '3' },
          },
        ],
      },
    ],
  },
];

export const views: DashboardViewSpec[] = [{ id: 'main', widgets }];
export const options: Partial<DashboardOptions> = {
  columns: 12,
  gap: 10,
  sizing: 'fit',
  responsive: { columnWidth: 80 },
  dragHandle: { grip: true, position: 'right', placement: 'inside' },
};

At narrower widths, responsive derives fewer columns, capped by columns. Widening again restores the cached wide layout. Omitted x and y place widgets in declaration order, wrapping at the column count.

2. Mount it and bind the switches

Use dashboard() and render() in JavaScript. render() mounts the spec and initializes its live DashboardHandle. Its return value is the renderer's DiagramInstance; keep that for teardown, and use the dashboard handle for board operations.

For framework components, use GrafloriaDashboardComponent in Angular, GrafloriaDashboard in Qwik, GrafloriaDashboard in React, or GrafloriaDashboard in Vue. Each binding supplies the handle through its ready event. Bind layout and sizing as props or inputs: changes call the live handle rather than remounting the board.

Choose one tab below. The framework examples are components to render in your application; the JavaScript entry point runs in the browser. All import ./board from step 1.

ts
Copy
import { dashboard, render } from '@grafloria/element';
import { options, views } from './board';

export function mountDashboard(parent: HTMLElement): () => void {
  const wrapper = document.createElement('section');
  const toolbar = document.createElement('div');
  const host = document.createElement('div');
  host.style.height = '480px';
  wrapper.append(toolbar, host);
  parent.append(wrapper);

  const spec = dashboard({ ...options, views });
  const instance = render(spec, host);
  const handle = spec.handle;
  const button = (label: string, action: () => void): void => {
    const control = document.createElement('button');
    control.textContent = label;
    control.addEventListener('click', action);
    toolbar.append(control);
  };
  button('Grid', () => handle.setLayout('grid'));
  button('Split', () => handle.setLayout('split'));
  button('Fit', () => handle.setSizing('fit'));
  button('Grow', () => handle.setSizing('grow'));
  button('RTL', () => handle.setRtl(!handle.getRtl()));
  button('Float', () => handle.setFloat(!handle.getFloat()));
  button('Caption chip', () => {
    handle.setCaption('ops', { text: 'Operations', position: 'tab', icon: '▤' });
  });
  button('Alerts tab', () => { handle.activateTab('side', 'alerts'); });
  button('Frame board', () => handle.fit());

  return () => {
    instance.dispose();
    wrapper.remove();
  };
}

mountDashboard(document.body);

ts
Copy
import { Component, signal } from '@angular/core';
import { GrafloriaDashboardComponent } from '@grafloria/angular';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

@Component({
  selector: 'app-arrange-dashboard',
  standalone: true,
  imports: [GrafloriaDashboardComponent],
  template: `
    <div>
      <button (click)="layout.set('grid')">Grid</button>
      <button (click)="layout.set('split')">Split</button>
      <button (click)="sizing.set('fit')">Fit</button>
      <button (click)="sizing.set('grow')">Grow</button>
      <button (click)="handle?.setRtl(!handle?.getRtl())">RTL</button>
      <button (click)="handle?.setFloat(!handle?.getFloat())">Float</button>
      <button (click)="captionChip()">Caption chip</button>
      <button (click)="handle?.activateTab('side', 'alerts')">Alerts tab</button>
      <button (click)="handle?.fit()">Frame board</button>
    </div>
    <grafloria-dashboard
      [views]="views" [options]="options"
      [layout]="layout()" [sizing]="sizing()"
      (ready)="handle = $event"
      style="display:block; height:480px" />
  `,
})
export class ArrangeDashboardComponent {
  readonly views = views;
  readonly options = options;
  readonly layout = signal<'grid' | 'split'>('grid');
  readonly sizing = signal<'fit' | 'grow'>('fit');
  handle?: DashboardHandle;

  captionChip(): void {
    this.handle?.setCaption('ops', {
      text: 'Operations', position: 'tab', icon: '▤',
    });
  }
}

tsx
Copy
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaDashboard } from '@grafloria/qwik';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

export default component$(() => {
  const handle = useSignal<NoSerialize<DashboardHandle>>();
  const layout = useSignal<'grid' | 'split'>('grid');
  const sizing = useSignal<'fit' | 'grow'>('fit');

  return (
    <section>
      <div>
        <button onClick$={() => { layout.value = 'grid'; }}>Grid</button>
        <button onClick$={() => { layout.value = 'split'; }}>Split</button>
        <button onClick$={() => { sizing.value = 'fit'; }}>Fit</button>
        <button onClick$={() => { sizing.value = 'grow'; }}>Grow</button>
        <button onClick$={() => handle.value?.setRtl(!handle.value.getRtl())}>RTL</button>
        <button onClick$={() => handle.value?.setFloat(!handle.value.getFloat())}>Float</button>
        <button onClick$={() => handle.value?.setCaption('ops', {
          text: 'Operations', position: 'tab', icon: '▤',
        })}>Caption chip</button>
        <button onClick$={() => handle.value?.activateTab('side', 'alerts')}>Alerts tab</button>
        <button onClick$={() => handle.value?.fit()}>Frame board</button>
      </div>
      <GrafloriaDashboard
        views={views} options={options} layout={layout.value} sizing={sizing.value}
        onReady$={(value) => { handle.value = noSerialize(value); }}
        style={{ height: '480px' }} />
    </section>
  );
});

tsx
Copy
import { useState } from 'react';
import { GrafloriaDashboard } from '@grafloria/react';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

export default function ArrangeDashboard() {
  const [handle, setHandle] = useState<DashboardHandle | null>(null);
  const [layout, setLayout] = useState<'grid' | 'split'>('grid');
  const [sizing, setSizing] = useState<'fit' | 'grow'>('fit');

  return (
    <section>
      <div>
        <button onClick={() => setLayout('grid')}>Grid</button>
        <button onClick={() => setLayout('split')}>Split</button>
        <button onClick={() => setSizing('fit')}>Fit</button>
        <button onClick={() => setSizing('grow')}>Grow</button>
        <button onClick={() => handle?.setRtl(!handle.getRtl())}>RTL</button>
        <button onClick={() => handle?.setFloat(!handle.getFloat())}>Float</button>
        <button onClick={() => handle?.setCaption('ops', {
          text: 'Operations', position: 'tab', icon: '▤',
        })}>Caption chip</button>
        <button onClick={() => handle?.activateTab('side', 'alerts')}>Alerts tab</button>
        <button onClick={() => handle?.fit()}>Frame board</button>
      </div>
      <GrafloriaDashboard
        views={views} options={options} layout={layout} sizing={sizing}
        onReady={setHandle} style={{ height: '480px' }} />
    </section>
  );
}

vue
Copy
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

const handle = shallowRef<DashboardHandle | null>(null);
const layout = ref<'grid' | 'split'>('grid');
const sizing = ref<'fit' | 'grow'>('fit');

function captionChip(): void {
  handle.value?.setCaption('ops', {
    text: 'Operations', position: 'tab', icon: '▤',
  });
}
</script>

<template>
  <section>
    <div>
      <button @click="layout = 'grid'">Grid</button>
      <button @click="layout = 'split'">Split</button>
      <button @click="sizing = 'fit'">Fit</button>
      <button @click="sizing = 'grow'">Grow</button>
      <button @click="handle?.setRtl(true)">RTL</button>
      <button @click="handle?.setFloat(!handle.getFloat())">Float</button>
      <button @click="captionChip">Caption chip</button>
      <button @click="handle?.activateTab('side', 'alerts')">Alerts tab</button>
      <button @click="handle?.fit()">Frame board</button>
    </div>
    <GrafloriaDashboard
      :views="views" :options="options" :layout="layout" :sizing="sizing"
      @ready="handle = $event" style="height:480px" />
  </section>
</template>

The JavaScript sample starts with Revenue and Customers above Operations and the Filters page.

The Angular component shows Orders and Churn inside Operations, beside Region in the active Filters page.

The Qwik component shows the same initial grid with the toolbar above it.

The React component starts with the Operations subtitle Today and the Filters page showing EMEA.

The Vue component also starts in the grid, with Filters selected and Alerts available beside it.

Press Split to replace grid resize corners with dividers; drag a divider to change pane proportions. Press Grid to project the split tree back into cells. These controls change the view's layout, not the Operations section's inner grid or the side panel's tabs. To switch a section or page separately, pass its id as the second argument to setLayout(), such as setLayout('split', 'ops').

Press Grow in grid mode to keep row heights and let the board extend downward; Fit keeps the board height and squeezes rows. Split layout always fits, so it does not become a growing grid when you press Grow. Frame board calls fit() to reframe the current view's camera—it does not change the sizing mode.

The ready callback gives Qwik a live handle in the browser; noSerialize() keeps it out of resumable state. The framework components dispose their renderer on unmount. In JavaScript, keep the function returned by mountDashboard() and call it when your application removes the panel.

3. Tune the geometry and interaction

Fixed size or fluid size

For a fixed design surface, replace the shared options export with mode: 'fixed', width: 1180, height: 660 alongside your other options. The camera frames those authored dimensions. An explicit width also implies fixed mode unless you set mode yourself. A fluid board takes its dimensions from the container instead; see Theme a canvas for container sizing.

The following options govern the board, not the renderer's zoom-to-content operation:

A bounded fit grid refuses a drop, resize, or addWidget() that needs more rows than its capacity. addWidget() returns undefined when the widget does not fit. An already oversized board—loaded from a document or switched from Grow—still squeezes to the frame rather than scrolling. With overflow: 'scroll', you explicitly opt out of that bound.

Gravity, RTL, and columns

Use Float in grid mode to toggle whether gaps are legal. Turning float off repacks widgets upward. In the Vue sample, RTL calls setRtl(true) to mirror widget pixels without rewriting their cells; repeated clicks keep RTL enabled rather than reversing the mirror.

For explicit column controls, call setColumns(6, 'moveScale', 'main') on the ready handle. It returns void; read getColumns('main') for the live count. The optional reflow argument uses GridColumnLayout:

One column forces a single stack in every mode. A manual setColumns() call pins the grid's column count instead of continuing to follow the width observer. Keep the sample's responsive rule for automatic resizing, or use explicit column controls for a user-selected count; do not expect both to drive the same grid simultaneously.

Sections, captions, tabs, and grips

Operations has four inner columns regardless of its outer span. Its sizing: 'fit' refuses child growth beyond the pane; a container's default 'grow' instead grows its slab in the parent when a child needs another row. maxRows defines the inner grid's designed row count, while limits.maxRows limits a widget's own resize. Containers can nest; nesting beyond two levels is not exercised by the library's gates.

SectionCaption accepts true for the section title, a string for explicit text, false for no caption, or SectionCaptionOptions. The initial subtitle reserves a second caption line. Caption chip changes it to a title-sized chip at the section's leading corner; both position: 'inside' and 'tab' reserve space inside the section. setCaption() returns false for a non-container; a successful change repaints and records one undo step.

For caption behavior, show: 'design' removes the band and its reserve in static mode; show: 'hover' overlays content without reserving space. Caption action buttons call onCaptionAction instead of selecting the section.

TabsOptions controls the strip's alignment, height, and stretching. The sample stretches Filters and Alerts across the strip. Alerts tab calls activateTab('side', 'alerts'): it shows that page and persists the active id. The call returns false for an invalid container or page. Use setLayout('split', 'alerts') to change that page's inner layout, not the tab container itself. setLayout() accepts only grid and split; declare a tab container with layout: 'tabs' in its widget spec.

DragGripOptions places a painted grip at the left, center, or right of the card's top edge, inside the header or outside as a tab. The sample chooses the right side inside the header. Click a card to select it: only the selected card shows its grip. Call focusWidget('revenue') on the ready handle to select it and move keyboard focus there; the method returns false for an unknown id.

To make the entire caption the drag target, call setDragHandle(true); use false for the whole card, or a selector string for your own handle element. Static mode paints no grip. These handle switches apply across views.

See it running

Open the Fluid dashboard demo to try Fit/Grow, Grid/Split, captions, tabs, and drag grips. The Grid options demo explores gravity, RTL, responsive columns, and nested boards.

Related

• Build a dashboard: widget content and the initial board.
• Commands and history: user-facing edits and undo.
• Save and restore documents: persist the live document instead of projecting framework data.