Dashboard Grid

Drag-and-resize dashboard widgets on a CSS grid with pure, collision-resolving layout functions.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { DashboardGrid, DashboardGridItem } from "@vizejs/ui/dashboard-grid";

Or copy the source into your project with vize lib pull dashboard-grid (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Metrics dashboard whose widgets can be dragged and resized on a twelve-column grid. -->
<script setup lang="ts">
import { ref } from "vue";

import { DashboardGrid, DashboardGridItem } from "@vizejs/ui/dashboard-grid";
import type { DashboardLayout } from "@vizejs/ui/dashboard-grid";

const layout = ref<DashboardLayout>([
  { id: "revenue", x: 0, y: 0, w: 6, h: 2 },
  { id: "signups", x: 6, y: 0, w: 3, h: 2 },
  { id: "churn", x: 9, y: 0, w: 3, h: 2 },
]);
const titles: ReadonlyMap<string, string> = new Map([
  ["revenue", "Revenue"],
  ["signups", "Sign-ups"],
  ["churn", "Churn"],
]);

function titleOf(id: string): string {
  return titles.get(id) ?? id;
}
</script>

<template>
  <DashboardGrid v-model:layout="layout" :columns="12" :row-height="48" label="Metrics">
    <DashboardGridItem
      v-for="item in layout"
      :id="item.id"
      :key="item.id"
      :label="titleOf(item.id)"
    >
      <template #default="{ handleProps, resizeHandleProps }">
        <h3 v-bind="handleProps">{{ titleOf(item.id) }}</h3>
        <p>{{ item.w }} × {{ item.h }} cells</p>
        <span v-bind="resizeHandleProps">⤡</span>
      </template>
    </DashboardGridItem>
  </DashboardGrid>
</template>

API

DashboardGrid

Source: src/families/layout/dashboard-grid/dashboard-grid.vue

Props

Events

Slots

Exposed

DashboardGridItem

Source: src/families/layout/dashboard-grid/dashboard-grid-item.vue

Props

Slots

Exposed

Behavior

Normative state x input -> outcome table for dashboard-grid.vue and dashboard-grid-item.vue (@vizejs/ui/dashboard-grid). Rows are proven by dashboard-grid-layout.test.ts, dashboard-grid.test.ts, and dashboard-grid-ssr.test.ts; compile-only assertions live in dashboard-grid.types.test-d.ts.

Placement is pure CSS grid (grid-column/grid-row spans), so server output is final layout; pointer input only needs the measured grid width.