@madebylars.com/mbl-graph

A Grafana-inspired chart module for Nuxt 4. Drop a <MblGraph> anywhere in your app to get interactive time-series charts with a built-in toolbar: graph type selector, timespan presets, aggregation interval, and auto-refresh.

• ✨  Release Notes

Features

• 4 chart types — line, bar, area, pie (switchable at runtime)
• Timespan picker — preset buttons (5m → 30d) plus a custom date/time range
• Aggregation control — bucket data into 1m, 5m, 15m, 1h, 6h, or 1d intervals
• Auto-refresh — configurable interval (5s → 5m) with a manual refresh button
• Two data modes — fetch from a URL endpoint or pass a static data prop
• Dark & light themes — dark by default, fully overridable via CSS custom properties
• SSR safe — chart canvas is client-only; the rest of the page renders normally
• Tree-shaken ECharts — only the chart types you use are bundled

Quick Setup

npm install @madebylars.com/mbl-graph

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@madebylars.com/mbl-graph'],
})

Usage

Fetch data from an API endpoint

The component calls url with ?from=, ?to=, and ?aggregation= query parameters whenever the timespan or aggregation changes.

<MblGraph
  title="Server metrics"
  url="/api/metrics"
  :refresh-interval="30"
  height="400px"
/>

Your endpoint receives:

| Parameter | Example | Description | |---|---|---| | from | 2025-05-15T09:00:00.000Z | Start of the selected range (ISO 8601) | | to | 2025-05-15T10:00:00.000Z | End of the selected range (ISO 8601) | | aggregation | 5m | Bucket interval chosen by the user |

It should return an array of data points:

[
  { "timestamp": "2025-05-15T09:00:00.000Z", "value": 42 },
  { "timestamp": "2025-05-15T09:05:00.000Z", "value": 58 }
]

Pass static data directly

<script setup>
const data = [
  { timestamp: '2025-05-15T09:00:00Z', value: 42 },
  { timestamp: '2025-05-15T09:05:00Z', value: 58 },
]
</script>

<template>
  <MblGraph title="Static chart" :data="data" type="bar" />
</template>

Multiple series

Pass a series array with the field names you want to plot. Each gets its own color automatically.

<MblGraph
  title="CPU / Memory / Disk"
  url="/api/metrics?metrics=cpu,memory,disk"
  :series="['cpu', 'memory', 'disk']"
/>

Your endpoint should return data points that include all the named fields:

[
  { "timestamp": "2025-05-15T09:00:00.000Z", "cpu": 42, "memory": 78, "disk": 23 },
  { "timestamp": "2025-05-15T09:05:00.000Z", "cpu": 55, "memory": 81, "disk": 24 }
]

A legend is shown automatically when more than one series is active.

Pie chart with labels

For pie charts, set the optional label field on each data point to control what is shown in the legend:

<MblGraph
  title="Distribution"
  type="pie"
  :show-toolbar="false"
  :data="[
    { timestamp: 'q1', label: 'Q1', value: 820 },
    { timestamp: 'q2', label: 'Q2', value: 932 },
    { timestamp: 'q3', label: 'Q3', value: 701 },
    { timestamp: 'q4', label: 'Q4', value: 1134 },
  ]"
/>

Props

| Prop | Type | Default | Description | |---|---|---|---| | url | string | — | API endpoint. Receives from, to, and aggregation as query params. | | data | DataPoint[] | — | Static data array. Used when no url is set. | | series | string[] | ['value'] | Data point field names to plot. Each becomes its own colored series. | | type | 'line' \| 'bar' \| 'area' \| 'pie' | 'line' | Initial chart type. | | title | string | — | Panel title shown in the toolbar. | | aggregation | AggregationInterval | '1h' | Initial aggregation bucket size. | | refreshInterval | number | 0 | Auto-refresh in seconds. 0 disables it. | | height | string \| number | '400px' | CSS height of the chart. | | showToolbar | boolean | true | Show or hide the entire toolbar. | | theme | 'dark' \| 'light' | 'dark' | Color theme. | | zoom | boolean | true | Enable scroll/slider zoom on time-series charts. | | legend | boolean | true | Show or hide the legend. | | legendPosition | 'top' \| 'right' \| 'bottom' \| 'left' | 'bottom' | Where to place the legend. | | presetMs | number | 3600000 | Initial timespan preset in milliseconds. | | from | Date | — | Controlled range start (overrides preset). | | to | Date | — | Controlled range end (overrides preset). |

Events

| Event | Payload | Description | |---|---|---| | update:type | GraphType | Emitted when the user switches chart type. | | update:aggregation | AggregationInterval | Emitted when the user changes aggregation. | | update:refreshInterval | number | Emitted when the user changes the refresh interval. | | data-updated | DataPoint[] | Emitted after every successful fetch. |

Types

type GraphType = 'line' | 'bar' | 'area' | 'pie'
type AggregationInterval = '1m' | '5m' | '15m' | '1h' | '6h' | '1d'

interface DataPoint {
  timestamp: string | number  // ISO string or Unix ms timestamp
  value: number
  label?: string              // used as legend label in pie charts
  [key: string]: unknown
}

Theming

The component exposes CSS custom properties on .mbl-graph. Override them to match your design system:

.mbl-graph {
  --mbl-bg: #111827;
  --mbl-border: #1f2937;
  --mbl-text: #d1d5db;
  --mbl-text-dim: #6b7280;
  --mbl-btn-bg: #1f2937;
  --mbl-btn-hover: #374151;
  --mbl-btn-active-bg: #3b82f6;
  --mbl-btn-active-text: #fff;
  --mbl-input-bg: #1f2937;
  --mbl-select-bg: #1f2937;
  --mbl-accent: #3b82f6;
}

Module options

export default defineNuxtConfig({
  modules: ['@madebylars.com/mbl-graph'],
  mblGraph: {
    prefix: 'Mbl',  // change to rename components, e.g. 'Graph' → <GraphGraph>
  },
})

Standalone components

MblTimespanPicker is also exported as a standalone component if you want to build a custom toolbar:

<MblTimespanPicker
  v-model:preset="presetMs"
  v-model:from="customFrom"
  v-model:to="customTo"
/>

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release