Chart.js — type:time Axis Requires a Date Adapter

Chart.js does not bundle a date/time parsing library. When a chart uses type: 'time' on an axis (common for time-series dashboards), Chart.js requires an external date adapter to be registered. Without it, the chart initialization crashes silently in JavaScript before any data is rendered — the canvas element renders blank with no visible error in the chart itself.

Key Points

type: 'time' axis fails silently without a registered date adapter — no visible error in the chart; JavaScript throws internally but the chart just renders blank
chartjs-adapter-date-fns is the most common adapter — requires importing both chart.js and chartjs-adapter-date-fns; the adapter registers itself on import
The blank canvas symptom is identical to "no data" — always check for a missing adapter before debugging data fetching or chart config
chart.js/auto import is NOT sufficient — the auto bundle includes Chart.js with all chart types but still excludes the date adapter
The adapter must be imported before new Chart(...) is called; it registers itself globally via side effect

Details

The Failure Mode

// Chart config with time axis
const config = {
  type: 'line',
  data: { datasets: [/* ... */] },
  options: {
    scales: {
      x: {
        type: 'time',          // ← requires date adapter
        time: { unit: 'hour' }
      }
    }
  }
};

new Chart(ctx, config);
// If adapter is missing: Chart.js throws internally
// "Error: This method is not implemented: Check that a complete date adapter is provided"
// The canvas stays blank — no user-visible error if exception is caught silently

The Fix

// 1. Install the adapter
// npm install chartjs-adapter-date-fns date-fns
// or
// <script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-date-fns/dist/chartjs-adapter-date-fns.bundle.min.js"></script>

// 2. Import it before using Chart.js — it self-registers
import 'chartjs-adapter-date-fns';
import { Chart } from 'chart.js';

// Now type: 'time' works correctly
new Chart(ctx, config);

For CDN / script tag usage (no bundler):

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<!-- Must come AFTER chart.js, BEFORE your chart code -->
<script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-date-fns/dist/chartjs-adapter-date-fns.bundle.min.js"></script>
<script src="your-chart-code.js"></script>

Why the Failure Is Silent

Chart.js catches the adapter error internally and attempts to degrade gracefully. The error message "This method is not implemented" may appear in the browser console (F12 → Console), but:

Dashboard apps often have global error handlers that suppress console output
The chart canvas is present and sized correctly — it just has no content
It looks identical to "data is empty" or "data fetch failed"

Always open browser DevTools → Console before assuming the data pipeline is broken.

Alternative Adapters

Adapter	Library	Bundle Size
`chartjs-adapter-date-fns`	date-fns	~8 KB (bundled)
`chartjs-adapter-luxon`	Luxon	~14 KB
`chartjs-adapter-moment`	Moment.js	~30 KB+
`chartjs-adapter-dayjs`	Day.js	~4 KB

chartjs-adapter-date-fns is the standard recommendation for new projects — date-fns is tree-shakable and the combined bundle is small.

Context: Power & Cost Dashboard (2026-04-21)

A homelab monitoring dashboard used Chart.js with type: 'time' on the X axis to display power consumption over time. The refresh() function that fetched data from Prometheus never ran because the chart initialization threw before reaching it. The symptom was a completely blank dashboard — no charts, no errors displayed. Adding chartjs-adapter-date-fns resolved the initialization crash and all charts appeared.

wiki/concepts/prometheus-joules-watts-gotcha — the other Chart.js dashboard bug found in the same session (wrong units)
wiki/concepts/beszel-monitoring-deployment — Beszel as a monitoring alternative that doesn't require Chart.js setup
wiki/homelab/_index — homelab monitoring stack context

Sources

daily/2026-04-21.md — Power & Cost dashboard blank due to Chart.js type: 'time' crash; missing chartjs-adapter-date-fns; adding the adapter resolved the initialization crash and data loaded correctly

4.7 KiB Raw Blame History