strapi-design-graphs

A set of composable, theme-aware chart components for Strapi plugins. Built on top of Recharts, this package acts like Shadcn Charts but is styled natively to match the Strapi Design System.

Components communicate hierarchically using React Context. This allows you to compose your charts exactly like standard Recharts code, while the container automatically handles theme-color mappings, grid/axis colors, legends, tooltips, and localization.

Installation

Add the package to your Strapi project:

npm install strapi-design-graphs

Install the required deps that won't be available/installed already via Strapi:

npm install recharts

Quick Start (Bar Chart Example)

Here is how you build a standard bar chart that automatically updates its series colors and fonts depending on whether the Strapi theme is Light or Dark:

import React from 'react';
import { BarChart, Bar, XAxis, YAxis, CartesianGrid } from 'recharts';
import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
  ChartLegend,
  ChartLegendContent,
  type ChartConfig
} from 'strapi-design-graphs';

// 1. Setup your data keys, labels, and Strapi theme color tokens
const chartConfig = {
  desktop: {
    label: 'Desktop Traffic',
    color: 'primary600', // Uses active theme's primary600
  },
  mobile: {
    label: 'Mobile Traffic',
    color: 'secondary600',
  },
} satisfies ChartConfig;

const data = [
  { month: 'Jan', desktop: 186, mobile: 80 },
  { month: 'Feb', desktop: 305, mobile: 200 },
  { month: 'Mar', desktop: 237, mobile: 120 },
];

export function TrafficChart() {
  return (
    // 2. Wrap your chart in ChartContainer to inject CSS variables and context
    <ChartContainer config={chartConfig} aspectRatio={16 / 9}>
      <BarChart data={data} margin={{ top: 10, right: 10, left: -20, bottom: 0 }}>
        {/* Style the grid with theme colors via CSS variables */}
        <CartesianGrid stroke="var(--grid-color)" strokeDasharray="3 3" vertical={false} />
        
        <XAxis
          dataKey="month"
          stroke="var(--axis-color)"
          tick={{ fill: 'var(--axis-text-color)', fontSize: 11 }}
          axisLine={false}
          tickLine={false}
        />
        <YAxis
          stroke="var(--axis-color)"
          tick={{ fill: 'var(--axis-text-color)', fontSize: 11 }}
          axisLine={false}
          tickLine={false}
        />
        
        {/* Render themed tooltips and legends using config data */}
        <ChartTooltip content={<ChartTooltipContent indicator="dot" />} cursor={false} />
        <ChartLegend content={<ChartLegendContent indicator="dot" />} />
        
        {/* Reference color variables dynamically injected by the container */}
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={[4, 4, 0, 0]} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={[4, 4, 0, 0]} />
      </BarChart>
    </ChartContainer>
  );
}

Component API

ChartContainer / GraphContainer

Wraps the chart to inject CSS variables and theme properties. It serves up the hierarchical context that inner components like legends and tooltips read from.

Props:

• config: A configuration object specifying the label, color token, and formatting details for each series key.
• aspectRatio: Ratio of width to height (e.g. 16 / 9 or 1). Default: 1.77 (16/9).
• style: Optional custom React styles merged into the container.

ChartTooltip & ChartTooltipContent

Configures and formats the interactive hover tooltip.

Props on ChartTooltipContent:

• indicator: Visual shape of the series color indicator. Choose between 'dot' | 'line' | 'dash'. Default: 'dot'.
• hideIndicator: If true, hides the color shape altogether.
• hideLabel: If true, hides the category/X-Axis header label.
• labelFormatter: Custom function to format the tooltip header: (label, payload) => ReactNode.
• formatter: Custom function to format series values: (value, name, item, index, payload) => ReactNode.

ChartLegend & ChartLegendContent

Renders matching legend keys with support for series colors, custom labels, and icons.

Props on ChartLegendContent:

• indicator: Match indicator shapes between tooltip and legend. 'dot' | 'line' | 'dash'.
• hideIndicator: Hides the color dot/line.
• align: Legend alignment. 'left' | 'center' | 'right'.

Helpful Hooks & Utilities

This package ships with a few utility functions to make data transformations and custom coloring easy:

useStrapiChartPalette(count?: number): string[]

A React hook that reads the active Strapi Design System theme and returns an array of resolved hex color codes (rotating through primary, success, warning, danger, secondary, and alternative theme colors). Very useful for pie charts or when you have dynamic series keys.

import { useStrapiChartPalette } from 'strapi-design-graphs';

function CustomChart() {
  const paletteColors = useStrapiChartPalette(5); // ['#4945ff', '#328048', ...]
  // ...
}

formatGraphValue(value: any, format?: string, options?: object): string

A localized formatter function to display values cleanly on tooltips and axes:

import { formatGraphValue } from 'strapi-design-graphs';

formatGraphValue(1234.56, 'currency', { currency: 'EUR' }); // "€1,234.56"
formatGraphValue(0.125, 'percent'); // "12.5%"
formatGraphValue('2026-07-05', 'date'); // "Jul 5, 2026"

Configuration-Driven Formatting

You can set up format properties directly inside your ChartConfig so the tooltips automatically inherit the right display settings:

const config = {
  sales: {
    label: 'Sales',
    color: 'success600',
    format: 'currency',
    formatOptions: { currency: 'GBP', precision: 0 },
  }
};

Publishing & Usage Notes

• Install: npm install strapi-design-graphs
• Peer dependencies: ensure react, react-dom, recharts, styled-components, and @strapi/design-system are installed in your project.
• Importing: the package exports named components and hooks. Example:

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
  ChartLegend,
  ChartLegendContent,
  useStrapiChartPalette,
  formatGraphValue,
} from 'strapi-design-graphs';

• Publishing: this repository is configured to build with Vite and includes generated type declarations. Before publishing run:

npm run build
npm publish --access public

Be sure package.json fields like name, version, repository, and license are correct before publishing.

Using inside a Strapi plugin

This package is designed to be consumed from a Strapi plugin's admin UI. Install the package into your plugin (or workspace) and import components inside your plugin's admin React code. Example for a plugin's admin/src/index.tsx:

import React from 'react';
import { prefixPluginTranslations } from '@strapi/helper-plugin';
import { ChartContainer, ChartTooltipContent } from 'strapi-design-graphs';

const App = () => (
  <ChartContainer config={{ sales: { label: 'Sales', color: 'primary600' } }}>
    {/* your chart markup here */}
  </ChartContainer>
);

export default {
  register(app) {
    // register your plugin admin routes and components
  },
  bootstrap() {},
};

When packaging your plugin, make sure the plugin's package.json lists this package as a dependency or peerDependency depending on how you distribute the plugin.