mates-charts

Reactive Chart.js components for the Mates framework. Build beautiful, interactive charts with automatic reactive updates using Mates atoms.

Installation

npm install mates-charts chart.js mates

Peer Dependencies:

• mates (any version)
• chart.js (^4.0.0)

Features

• 🎯 Simple API: Pass a single configAtom with your Chart.js configuration
• 🔄 Reactive: Charts automatically update when atoms change
• 📊 Full Chart.js Support: All Chart.js chart types and customization options
• 🎨 TypeScript: Full TypeScript support with proper type definitions
• 🚀 Unified Component: Single Chart component for all chart types

Chart.js Documentation

For detailed Chart.js configuration options, please refer to the official Chart.js documentation.

The Chart function accepts a Chart.js configuration object (as defined in Chart.js documentation) wrapped in a Mates atom. You can use all Chart.js features, options, and customization as documented in their official docs.

Important Notes

⚠️ Template Function Only: The Chart function can only be used inside Mates template functions (inside html tagged template literals). It returns a view that must be rendered within a template context.

📋 Chart.js Configuration: You must pass a Chart.js configuration object (chartJsConfig) wrapped in a Mates atom. This configuration follows the same structure and options as described in the Chart.js documentation.

Quick Start

import { html, atom } from "mates";
import { Chart, type ChartJsConfiguration } from "mates-charts";

const App = () => {
  // Create a chart config atom with Chart.js configuration
  const chartConfigAtom = atom<ChartJsConfiguration<"line">>({
    type: "line",
    data: {
      labels: ["January", "February", "March", "April", "May", "June", "July"],
      datasets: [
        {
          label: "Sales",
          data: [65, 59, 80, 81, 56, 55, 40],
          borderColor: "rgb(75, 192, 192)",
          backgroundColor: "rgba(75, 192, 192, 0.2)",
        },
      ],
    },
    options: {
      responsive: true,
      plugins: {
        title: {
          display: true,
          text: "Monthly Sales Data",
        },
      },
    },
  });

  // Update the chart by setting the atom
  const updateData = () => {
    chartConfigAtom.set({
      ...chartConfigAtom(),
      data: {
        ...chartConfigAtom().data,
        datasets: [
          {
            ...chartConfigAtom().data.datasets[0],
            data: Array.from({ length: 7 }, () => Math.floor(Math.random() * 100)),
          },
        ],
      },
    });
  };

  return () => html`
    <div>
      <h1>My Dashboard</h1>
      ${Chart(chartConfigAtom)}
      <button @click=${updateData}>Update Data</button>
    </div>
  `;
};

API

Chart Function

Chart(configAtom: Atom<ChartJsConfiguration<ChartType>>)

The Chart function takes a Mates atom containing a Chart.js configuration object and returns a view that can only be used inside template functions.

Parameters:

• configAtom: A Mates atom containing a Chart.js configuration object (ChartJsConfiguration). This must follow the Chart.js configuration format. See Chart.js configuration documentation for details.

Returns:

• A view component that can only be used inside Mates template functions (inside html tagged template literals).

Usage:

// Inside a template function
return () => html`
  <div>
    ${Chart(chartConfigAtom)}
  </div>
`;

Supported Chart Types

The unified Chart component supports all Chart.js chart types. Simply set the type property in your Chart.js configuration:

Line Chart

Perfect for showing trends over time.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"line">>({
  type: "line",
  data: {
    labels: ["Jan", "Feb", "Mar", "Apr"],
    datasets: [{
      label: "Sales",
      data: [10, 20, 30, 40],
      borderColor: "rgb(75, 192, 192)",
      backgroundColor: "rgba(75, 192, 192, 0.2)",
    }],
  },
  options: {
    responsive: true,
    scales: {
      y: {
        beginAtZero: true,
      },
    },
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Bar Chart

Great for comparing categories.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"bar">>({
  type: "bar",
  data: {
    labels: ["Q1", "Q2", "Q3", "Q4"],
    datasets: [{
      label: "Revenue",
      data: [100, 200, 150, 300],
      backgroundColor: "rgba(54, 162, 235, 0.6)",
    }],
  },
  options: {
    responsive: true,
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Pie Chart

Ideal for showing proportions.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"pie">>({
  type: "pie",
  data: {
    labels: ["Red", "Blue", "Yellow"],
    datasets: [{
      data: [12, 19, 3],
      backgroundColor: [
        "rgba(255, 99, 132, 0.6)",
        "rgba(54, 162, 235, 0.6)",
        "rgba(255, 206, 86, 0.6)",
      ],
    }],
  },
  options: {
    responsive: true,
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Doughnut Chart

Similar to pie chart with a different visual style.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"doughnut">>({
  type: "doughnut",
  data: {
    labels: ["Chrome", "Firefox", "Safari"],
    datasets: [{
      data: [65, 15, 20],
      backgroundColor: [
        "rgba(255, 99, 132, 0.6)",
        "rgba(54, 162, 235, 0.6)",
        "rgba(255, 206, 86, 0.6)",
      ],
    }],
  },
  options: {
    responsive: true,
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Area Chart

Line chart with filled area beneath the line.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"line">>({
  type: "line",
  data: {
    labels: ["Jan", "Feb", "Mar", "Apr"],
    datasets: [{
      label: "Area Dataset",
      data: [10, 20, 30, 40],
      borderColor: "rgb(75, 192, 192)",
      backgroundColor: "rgba(75, 192, 192, 0.2)",
      fill: true,
    }],
  },
  options: {
    responsive: true,
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Bubble Chart

For displaying three-dimensional data (x, y, radius).

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"bubble">>({
  type: "bubble",
  data: {
    datasets: [{
      label: "Bubble Dataset",
      data: [
        { x: 20, y: 30, r: 15 },
        { x: 40, y: 10, r: 10 },
        { x: 30, y: 20, r: 20 },
      ],
      backgroundColor: "rgba(255, 99, 132, 0.6)",
    }],
  },
  options: {
    responsive: true,
    scales: {
      x: {
        beginAtZero: true,
      },
      y: {
        beginAtZero: true,
      },
    },
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Scatter Chart

For displaying points with x and y coordinates.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"scatter">>({
  type: "scatter",
  data: {
    datasets: [{
      label: "Scatter Dataset",
      data: [
        { x: 10, y: 20 },
        { x: 15, y: 10 },
        { x: 25, y: 30 },
      ],
      backgroundColor: "rgba(255, 99, 132, 0.6)",
    }],
  },
  options: {
    responsive: true,
    scales: {
      x: {
        type: "linear",
        position: "bottom",
      },
    },
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Radar Chart

For displaying multi-variable data in a radial format.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"radar">>({
  type: "radar",
  data: {
    labels: ["Eating", "Drinking", "Sleeping", "Designing", "Coding", "Cycling", "Running"],
    datasets: [{
      label: "My First Dataset",
      data: [65, 59, 90, 81, 56, 55, 40],
      fill: true,
      backgroundColor: "rgba(255, 99, 132, 0.2)",
      borderColor: "rgb(255, 99, 132)",
    }],
  },
  options: {
    responsive: true,
    scales: {
      r: {
        beginAtZero: true,
      },
    },
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

Polar Area Chart

Similar to pie chart but with equal angle segments.

import { Chart } from "mates-charts";
import type { ChartConfiguration } from "chart.js";

const configAtom = atom<ChartJsConfiguration<"polarArea">>({
  type: "polarArea",
  data: {
    labels: ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
    datasets: [{
      label: "Dataset",
      data: [11, 16, 7, 3, 14, 6],
      backgroundColor: [
        "rgba(255, 99, 132, 0.6)",
        "rgba(54, 162, 235, 0.6)",
        "rgba(255, 206, 86, 0.6)",
        "rgba(75, 192, 192, 0.6)",
        "rgba(153, 102, 255, 0.6)",
        "rgba(255, 159, 64, 0.6)",
      ],
    }],
  },
  options: {
    responsive: true,
  },
});

// Inside template function
return () => html`
  ${Chart(configAtom)}
`;

ChartJsConfiguration

The configAtom should contain a Chart.js configuration object (ChartJsConfiguration). This follows the exact same structure as documented in the Chart.js configuration documentation.

{
  type: "line" | "bar" | "pie" | "doughnut" | "bubble" | "scatter" | "radar" | "polarArea";  // Chart type
  data: ChartData;                             // Chart data (labels, datasets)
  options?: ChartOptions;                     // Chart.js options (optional)
}

For complete configuration options, please refer to the Chart.js documentation.

Reactive Updates

Charts automatically update when the configAtom changes. Simply update the atom value:

const configAtom = atom<ChartJsConfiguration<"line">>({ /* initial config */ });

// Update the entire config
configAtom.set({
  ...configAtom(),
  data: { /* new data */ },
});

// Or update specific parts
const currentConfig = configAtom();
configAtom.set({
  ...currentConfig,
  data: {
    ...currentConfig.data,
    datasets: [
      ...currentConfig.data.datasets,
      // ... modified dataset
    ],
  },
});

Examples

See the demo directory for complete working examples of all chart types.

TypeScript Support

Full TypeScript support with proper type definitions. All chart configurations are fully typed using Chart.js types:

import { Chart, type ChartJsConfiguration } from "mates-charts";

const configAtom = atom<ChartJsConfiguration<"line">>({ /* ... */ });

License

MIT