react-grafana-prom

Grafana-inspired React time-series charts for Prometheus, Thanos, and monitoring dashboards.

The package is built on Recharts and keeps the data contract simple: your backend or app fetches metrics, normalizes them, and passes time-series data directly to the chart. Units are chosen by your dashboard code, because Prometheus and Thanos query responses usually do not include display units.

Install

npm install react-grafana-prom recharts

Import the CSS once in your app:

import 'react-grafana-prom/styles.css';

Quick Start

'use client';

import { TimeSeriesChart } from 'react-grafana-prom';
import 'react-grafana-prom/styles.css';

const cpuSeries = [
  {
    labels: { pod: 'orderer-0', namespace: 'hlf' },
    unit: 'percentunit',
    points: [
      [1713780000, 0.43],
      [1713780300, 0.51],
      [1713780600, 0.48],
    ],
  },
  {
    labels: { pod: 'orderer-1', namespace: 'hlf' },
    unit: 'percentunit',
    points: [
      [1713780000, 0.36],
      [1713780300, 0.41],
      [1713780600, 0.39],
    ],
  },
];

export function CpuPanel() {
  return (
    <TimeSeriesChart
      title="CPU usage"
      description="Kubernetes pods"
      series={cpuSeries}
      variant="area"
      unit="percentunit"
      theme="auto"
      legend={{ template: '{{pod}}', value: 'last' }}
      tooltip={{ sort: 'desc' }}
    />
  );
}

Data Format

type TimeSeries = {
  id?: string;
  name?: string;
  labels?: Record<string, string | number | boolean | null | undefined>;
  unit?: string;
  color?: string;
  points: Array<[number | string | Date, number | null | undefined]>;
};

Time values can be Unix seconds, Unix milliseconds, ISO strings, or Date objects.

const memory = [
  {
    name: 'peer-0',
    unit: 'bytes',
    points: [
      ['2026-04-26T10:00:00Z', 523986944],
      ['2026-04-26T10:01:00Z', 534773760],
    ],
  },
];

Units and Formatters

Prometheus metric names can hint at units, but the API response normally does not tell the chart how to format values. Prefer storing the unit with your dashboard panel or attaching it when you normalize backend data.

<TimeSeriesChart series={memorySeries} unit="bytes" />
<TimeSeriesChart series={latencySeries} unit="ms" />
<TimeSeriesChart series={cpuRatioSeries} unit="percentunit" />

Common formatter IDs:

| Category | IDs | | --- | --- | | Numbers | none, short, sishort, locale, sci | | Percent | percent, percentunit | | Data | bytes, decbytes, bits, decbits, kbytes, mbytes, gbytes | | Data rate | Bps, binBps, bps, binbps, KBs, MBs, GBs | | Time | ns, us, ms, s, m, h, d, dtdurationms, dtdurations | | Throughput | ops, reqps, rps, wps, iops, eps, mps | | Currency | currencyINR, currencyUSD, currencyEUR, currencyGBP, currencyJPY, currencyBTC | | State | bool, bool_yes_no, bool_on_off |

Custom unit patterns:

<TimeSeriesChart series={blockHeightSeries} unit="suffix:blocks" />
<TimeSeriesChart series={peerSeries} unit="suffix:peers" />
<TimeSeriesChart series={txSeries} unit="count:tx/s" />
<TimeSeriesChart series={hashRateSeries} unit="si:H/s" />
<TimeSeriesChart series={healthSeries} unit="bool:Healthy/Down" />

Register a formatter for your own domain:

import { registerValueFormat } from 'react-grafana-prom';

registerValueFormat('blockHeight', (value) => ({
  text: Math.round(value ?? 0).toLocaleString(),
  suffix: ' blocks',
}));

Layout and Sizing

The chart uses ResizeObserver, waits for a positive render size, and falls back to 300x200 when mounted inside a container that has not measured yet.

<TimeSeriesChart
  title="Transaction rate"
  series={txSeries}
  unit="count:tx/s"
  height={360}
  fallbackSize={{ width: 480, height: 260 }}
/>

Use aspectRatio when the chart should size itself from its container width:

<TimeSeriesChart series={series} aspectRatio={16 / 9} />

Legend

Legends are interactive and work with large result sets.

• Click a legend item to hide or show that series.
• Double-click a legend item to isolate it.
• Ctrl, Cmd, or Alt click also isolates when behavior is toggle-or-isolate.
• A search box appears automatically when there are many series.
• Overflowing legends scroll inside the card.

<TimeSeriesChart
  series={podSeries}
  legend={{
    template: '{{namespace}} / {{pod}}',
    value: 'last',
    placement: 'right',
    searchable: true,
    maxHeight: 360,
  }}
/>

Tooltip

The tooltip is custom-built for dense monitoring data. It shows the timestamp and all visible series values, supports scrolling, and can sort values.

<TimeSeriesChart
  series={series}
  tooltip={{
    sort: 'desc',
    maxHeight: 240,
    timestampFormat: {
      dateStyle: 'medium',
      timeStyle: 'long',
    },
  }}
/>

Themes

Use theme="auto" to follow the user's color scheme, or force a mode:

<TimeSeriesChart series={series} theme="dark" />
<TimeSeriesChart series={series} theme="light" />

The component ships with shadcn-inspired card styling, rounded corners, subtle borders, dark mode variables, and Grafana-style chart interactions.

API

type TimeSeriesChartProps = {
  series: TimeSeries[];
  title?: React.ReactNode;
  description?: React.ReactNode;
  actions?: React.ReactNode;
  footer?: React.ReactNode;
  card?: boolean;
  unit?: string;
  variant?: 'line' | 'area';
  theme?: 'auto' | 'light' | 'dark';
  height?: number;
  aspectRatio?: number;
  fallbackSize?: { width: number; height: number };
  decimals?: number;
  colors?: string[];
  legend?: boolean | ChartLegendOptions;
  tooltip?: boolean | ChartTooltipOptions;
  showGrid?: boolean;
  syncId?: string;
  emptyState?: React.ReactNode;
};