Theming

A theme is a single object that sets the default visual style - colors, fonts, strokes, tooltip and legend styles - for every chart below it in the React tree. Instead of repeating stroke, fill and style props on every component in every chart, you set them once.

Themes are available since Recharts v3.11.

A theme is the defaults layer. When a single chart needs to differ - one bar with its own shape, one axis with its own tick format, one custom tooltip - that is a prop on that component, and the Customize guide covers it. Explicit props always win over the theme, so the two never fight.

Quick start

Wrap your charts in RechartsThemeProvider and give it a theme:

import { Bar, BarChart, CartesianGrid, Legend, RechartsThemeProvider, Tooltip, XAxis, YAxis, autoTheme } from 'recharts';

export function App() {
  return (
    <RechartsThemeProvider value={autoTheme}>
      <BarChart data={data}>
        <CartesianGrid />
        <XAxis dataKey="month" />
        <YAxis />
        <Tooltip />
        <Legend />
        <Bar dataKey="revenue" />
        <Bar dataKey="profit" />
      </BarChart>
    </RechartsThemeProvider>
  );
}

Built-in themes

Recharts ships four themes:

ThemeWhat it does
lightThemeA complete light-mode style: dark text, light grid.
darkThemeThe dark-mode counterpart: light text, dark grid. It expects a dark page. On a light page its light text and axes are not legible.
autoThemeAutomatically switches between light or dark, following the CSS color-scheme of the page. It has the colors of lightTheme and darkTheme, and the browser picks between them. See Switching themes at runtime below.
emptyThemeTheming reset. Removes all built-in styling so you can style everything yourself. All SVG properties fall back to browser defaults. Same idea as a CSS reset. Useful when a chart is fully custom and Recharts defaults get in the way.

You can see the light and dark colors right here on this website. The navigation bar has a button that switches this whole website between light and dark, and every chart on the page with it. ColorModePicker sets the CSS color-scheme of the page, and a single RechartsThemeProvider with autoTheme follows it. See Frame.tsx and defineColorModeStore.ts for implementation.

How a style is resolved

For every themed property, Recharts checks these places, in order:

  1. SVG properties defined in the data input array. See Styling data points guide for details.
  2. Props in the JSX.
  3. Theme (i.e. RechartsThemeProvider is present in the current React context)
  4. If there is no theme present at all (i.e. the RechartsThemeProvider is not in the React tree at all), Recharts falls back to its legacy defaults, the same it had since version 2.x. You will find that these defaults are inconsistent and not quite accessible - that is why presence of the theme turns it off completely.

The final style is then created by merging properties from those sources.

Graphical items are the exception for colors. The theme fill and stroke are designed as a pair, and they never mix with your colors. If a graphical item sets its own fill or stroke, it ignores both the fill and the stroke of its graphicalItems entry. For example, <Bar fill="red" /> renders red bars without the theme stroke. The rest of the entry still applies, including its strokeWidth and its label styles. The same rule applies to colors defined in the data array. Other style props, such as strokeWidth or strokeDasharray, do not bring a color, so they merge with the theme field by field: <Line strokeDasharray="5 5" /> is a dashed line in the theme colors.

Chart background

Default Recharts themes do not paint a background behind the chart. The chart is part of your page, and the page shows through it. Each built-in theme is designed for one page background: lightTheme for white, darkTheme for a dark page, and autoTheme for a page whose background follows its color-scheme.

Custom themes can draw the chart background.

A theme has two background settings, and they do different things:

  • pageBackground is the color behind the chart. Recharts never paints it. It draws gaps and halos in this color, so that they look like holes cut into the chart: the outlines between Treemap tiles, and the separators and label halos of SunburstChart. Set it to the background of your page. The built-in themes set it to the background they are designed for.
  • chart is painted on the element that wraps the chart. The Legend renders inside that element, so a background here covers the Legend too. The built-in themes leave it empty. The style prop of the chart takes precedence over it.

If you paint chart.backgroundColor and leave pageBackground unset, Recharts uses chart.backgroundColor as the pageBackground, so the separators match the color that is actually behind them. An explicit pageBackground always wins. The built-in themes set pageBackground, so when you spread a built-in theme and paint chart.backgroundColor, also set pageBackground to the same color. Do the same when you paint the background shorthand or an image.

Labels

A theme styles labels in two places.

  • Data labels, the ones that LabelList, the label prop of graphical items, and the default Pie label draw, take their styles from the label of their graphicalItems entry. Each series can have its own label styles, and Pie and Funnel take one entry per sector or trapezoid, the same entry that colors the shape. See Label colors guide for details.
  • All other labels take the top-level label.

If neither the label nor the theme sets a color, data labels pick one automatically, depending on whether they sit on top of their shape or next to it. The Label colors guide explains the rules.

Default chart size

A chart without a size renders nothing. A theme can give every chart in its tree a default size with chart.width and chart.height (the default Recharts themes do not, custom ones can). A chart uses the size from the theme only when it has no size of its own: the width and height props, the style prop and ResponsiveContainer all take precedence.

import { type RechartsTheme, lightTheme } from 'recharts';

export const sizedTheme: RechartsTheme = {
  ...lightTheme,
  chart: { width: '100%', maxHeight: '70vh', aspectRatio: 1.618 },
};

Also see the Chart size guide.

Colors for multiple series

The theme uses each graphical item's dataKey to decide which entry from graphicalItems to use for its color. Graphical items with the same dataKey show the same data, so they get the same color.

A graphical item without its own dataKey uses the dataKey of its value axis. The chart layout decides which axis that is, regardless of the axis type: YAxis in the horizontal layout, XAxis in the vertical layout, PolarRadiusAxis for Radar, and PolarAngleAxis for RadialBar.

The fill of each entry can also be a fill object with a pattern, so that series differ by more than color. As WCAG SC1.4.1 "Use of color" recommends. The Patterns and gradients guide explains how.

If you need different colors or want to control the assignment yourself, provide an explicit fill or stroke prop on the graphical item. The lightPalette, darkPalette and autoPalette exports hold the colors of the built-in themes, so you can pick from them: <Scatter fill={autoPalette[1]} />.

The theme compares dataKey values as strings. A function dataKey is compared by its source code: two functions with the same source share a color, and a minified build may order the colors differently than a development build. Prefer explicit colors for graphical items that use a function dataKey.

Writing your own theme

A RechartsTheme is a plain object: build it inline, import it from a shared module, or fetch it as JSON. Start from a built-in theme to preserve styles for components you do not override.

import { RechartsThemeProvider, lightTheme, type RechartsTheme } from 'recharts';

/*
 * Start from a built-in theme to keep styles for components you do not override.
 * Spread nested objects too when you want to preserve their other properties.
 */
const brandTheme: RechartsTheme = {
  ...lightTheme,
  graphicalItems: [
    { fill: '#4338ca', stroke: '#4338ca' },
    { fill: '#0f766e', stroke: '#0f766e' },
  ],
  typography: { ...lightTheme.typography, fontFamily: 'Inter, sans-serif' },
  grid: { ...lightTheme.grid, stroke: '#e2e8f0', strokeDasharray: '1 4' },
};

export function App() {
  return <RechartsThemeProvider value={brandTheme}>...</RechartsThemeProvider>;
}

To start from scratch instead, define styles for every component your chart uses, as in this example:

import {
  CartesianGrid,
  LabelProps,
  Legend,
  Line,
  LineChart,
  RechartsTheme,
  RechartsThemeProvider,
  ReferenceLine,
  Tooltip,
  XAxis,
  YAxis,
} from 'recharts';
import { RechartsDevtools } from '@recharts/devtools';

const data = [
  { month: 'Jan', revenue: 4200, profit: 1100 },
  { month: 'Feb', revenue: 5800, profit: 1500 },
  { month: 'Mar', revenue: 7200, profit: 2400 },
  { month: 'Apr', revenue: 6100, profit: 1800 },
  { month: 'May', revenue: 8900, profit: 3100 },
  { month: 'Jun', revenue: 7400, profit: 2600 },
];

/*
 * A theme is a plain object. There is no `createTheme` helper and none is needed:
 * you can build it inline, import it from a shared module, or parse it from JSON.
 */
const brandTheme: RechartsTheme = {
  typography: {
    color: '#1e1b4b',
    fontFamily: 'Georgia, serif',
    fontSize: 13,
  },
  graphicalItems: [
    {
      stroke: '#4338ca',
      strokeWidth: 3,
      active: { fill: '#ffffff', stroke: '#4338ca', strokeWidth: 3 },
    },
    {
      stroke: '#0f766e',
      strokeWidth: 3,
      strokeDasharray: '6 3',
      active: { fill: '#ffffff', stroke: '#0f766e', strokeWidth: 3 },
    },
  ],
  grid: {
    stroke: '#c7d2fe',
    strokeDasharray: '1 4',
    fill: 'none',
  },
  axis: {
    stroke: '#4338ca',
    strokeWidth: 1,
  },
  reference: {
    stroke: '#be123c',
    strokeWidth: 2,
    strokeDasharray: '4 4',
  },
  cursor: {
    stroke: '#4338ca',
    strokeWidth: 1,
    strokeDasharray: '3 3',
    fill: '#4338ca',
    fillOpacity: 0.08,
  },
  tooltip: {
    contentStyle: {
      margin: 0,
      padding: 12,
      backgroundColor: '#eef2ff',
      border: '2px solid #4338ca',
      borderRadius: 8,
    },
    labelStyle: { margin: 0, fontWeight: 'bold', color: '#1e1b4b' },
    itemStyle: { display: 'block', paddingTop: 2, paddingBottom: 2 },
  },
  legend: {
    wrapperStyle: { paddingTop: 8 },
    labelStyle: { letterSpacing: '0.05em', textTransform: 'uppercase' },
  },
  pageBackground: '#ffffff',
  chart: {
    width: '100%',
    maxWidth: 600,
    maxHeight: '70vh',
    aspectRatio: 1.618,
    padding: 12,
    borderRadius: 8,
    backgroundColor: '#ffffff',
  },
};

const xAxisLabel: LabelProps = { position: 'insideBottomRight', value: 'Month' };
const yAxisLabel: LabelProps = { value: 'Revenue [AUD]', angle: -90, textAnchor: 'end', position: 'insideTopLeft' };
const referenceLineLabel: LabelProps = { position: 'insideTopRight', value: 6000 };

export default function CustomThemeExample() {
  return (
    <RechartsThemeProvider value={brandTheme}>
      <LineChart responsive data={data}>
        <CartesianGrid />
        <XAxis dataKey="month" height="auto" label={xAxisLabel} />
        <YAxis width="auto" label={yAxisLabel} />
        <ReferenceLine y={6000} label={referenceLineLabel} />
        <Tooltip defaultIndex={2} />
        <Legend />
        <Line dataKey="revenue" />
        <Line dataKey="profit" />
        <RechartsDevtools />
      </LineChart>
    </RechartsThemeProvider>
  );
}

When you design your own theme, check that readers can tell the series apart from the page and from each other, also with a color vision deficiency. The Theme color testing guide does that for any theme, and shows how to keep checking it in unit tests.

Switching themes at runtime

There are two ways to switch between light and dark: let CSS do it with autoTheme, or swap the theme object in React state.

Following the color scheme with autoTheme

Every color in autoTheme is a CSS light-dark() value, for example light-dark(#2373e6, #5396ff). The browser picks the light or the dark color from the color-scheme of the element. Switching needs no React state and no re-render, and server-rendered pages show the right colors from the first paint.

import { RechartsThemeProvider, autoTheme } from 'recharts';

export function Dashboard() {
  return (
    <RechartsThemeProvider value={autoTheme}>
      <RevenueChart />
      <TrafficChart />
    </RechartsThemeProvider>
  );
}

autoTheme does nothing on its own: it follows the color-scheme that your page sets.

/* app.css */

/* Follow the operating system: */
:root {
  color-scheme: light dark;
}

/* Or follow your own toggle. Many toggles already set color-scheme on <html>. */
:root[data-theme='light'] {
  color-scheme: light;
}
:root[data-theme='dark'] {
  color-scheme: dark;
}

/* A toggle that only sets a class needs one extra rule: */
.dark {
  color-scheme: dark;
}

Some things to keep in mind:

  • light-dark() needs Chrome 123, Firefox 120, or Safari 17.5. If you support older browsers, switch between lightTheme and darkTheme in React state, or use CSS variables.
  • Like darkTheme, autoTheme only styles what Recharts draws. The background behind the chart belongs to your page, so let the page background follow the same color-scheme. See the Chart background section above.

Switching in React state

You can also switch with an ordinary React state update: swap the object you pass to value and leave the chart markup alone. No chart re-declares anything, no component takes a new prop. This works with any pair of themes, including your own, and your code always reads plain colors from the theme.

import { useState } from 'react';
import { RechartsThemeProvider, darkTheme, lightTheme } from 'recharts';

export function Dashboard() {
  const [mode, setMode] = useState<'light' | 'dark'>('light');

  return (
    <>
      <ThemeToggle value={mode} onChange={setMode} />
      <RechartsThemeProvider value={mode === 'dark' ? darkTheme : lightTheme}>
        <RevenueChart />
        <TrafficChart />
      </RechartsThemeProvider>
    </>
  );
}

Remember that darkTheme only styles what Recharts draws. Switch the background of your page together with the theme. See the Background section above.

Switching with CSS variables instead

Because theme values are handed to the DOM unchanged, any valid CSS value works - including var(--token). That lets a single theme object serve both color schemes and moves the actual switch into CSS, with no React re-render and no flash on server-rendered pages.

/* app.css */
:root {
  --chart-text: #18181b;
  --chart-grid: #d6d3d1;
  --chart-axis: #52525b;
  --chart-1: #4338ca;
  --chart-2: #0f766e;
  --chart-3: #b45309;
  --chart-page: #ffffff;
}

.dark {
  --chart-text: #f5f5f4;
  --chart-grid: #3f3f46;
  --chart-axis: #d6d3d1;
  --chart-1: #a5b4fc;
  --chart-2: #5eead4;
  --chart-3: #fcd34d;
  --chart-page: #18181b;
}
import { type RechartsTheme } from 'recharts';

/*
 * Theme values are passed to the DOM as-is, so any valid CSS value works,
 * including var() references. One theme object then covers both color schemes
 * and switching is done in CSS, without a React re-render.
 */
export const cssVariableTheme: RechartsTheme = {
  typography: { color: 'var(--chart-text)' },
  graphicalItems: [
    { fill: 'var(--chart-1)', stroke: 'var(--chart-1)' },
    { fill: 'var(--chart-2)', stroke: 'var(--chart-2)' },
    { fill: 'var(--chart-3)', stroke: 'var(--chart-3)' },
  ],
  grid: { stroke: 'var(--chart-grid)', fill: 'none' },
  axis: { stroke: 'var(--chart-axis)' },
  pageBackground: 'var(--chart-page)',
};

The same trick works with any token layer: Tailwind and shadcn/ui semantic variables, Chakra's --chakra-* variables, or your own design tokens.

Match an existing design system

Map your design system's tokens onto a RechartsTheme with useMemo:

import { useMemo } from 'react';
import { useTheme } from '@mui/material/styles';
import { RechartsThemeProvider, darkTheme, lightTheme, type RechartsTheme } from 'recharts';

/*
 * Recharts ships no adapters for design systems. Because RechartsTheme is a plain
 * object, a small mapper in your own code is all you need - and it works the same
 * way for Material UI, Mantine, Chakra, Ant Design, or your in-house tokens.
 */
function Charts({ children }) {
  const muiTheme = useTheme();
  const baseTheme = muiTheme.palette.mode === 'dark' ? darkTheme : lightTheme;

  const rechartsTheme = useMemo<RechartsTheme>(
    () => ({
      ...baseTheme,
      typography: {
        ...baseTheme.typography,
        color: muiTheme.palette.text.primary,
        fontFamily: muiTheme.typography.fontFamily,
        fontSize: muiTheme.typography.body2.fontSize,
      },
      graphicalItems: [
        { fill: muiTheme.palette.primary.main, stroke: muiTheme.palette.primary.main },
        { fill: muiTheme.palette.secondary.main, stroke: muiTheme.palette.secondary.main },
        { fill: muiTheme.palette.warning.main, stroke: muiTheme.palette.warning.main },
      ],
      grid: { ...baseTheme.grid, stroke: muiTheme.palette.divider },
      axis: { ...baseTheme.axis, stroke: muiTheme.palette.text.secondary },
      pageBackground: muiTheme.palette.background.paper,
      tooltip: {
        ...baseTheme.tooltip,
        contentStyle: {
          ...baseTheme.tooltip?.contentStyle,
          backgroundColor: muiTheme.palette.background.paper,
          border: `1px solid ${muiTheme.palette.divider}`,
          borderRadius: muiTheme.shape.borderRadius,
        },
      },
    }),
    [muiTheme, baseTheme],
  );

  return <RechartsThemeProvider value={rechartsTheme}>{children}</RechartsThemeProvider>;
}

Reading the theme

Custom shapes, custom tooltip content and custom legends are your components, so Recharts does not style them - see the Customize guide for how those render props work. If you want them to follow the theme, read it with useRechartsTheme. It returns the nearest theme as-is, with no defaults applied, and undefined when there is no provider.

import { useRechartsTheme } from 'recharts';

/*
 * Read the active theme from your own components, for example to paint
 * the page background or a custom Tooltip content that matches the chart.
 */
function CustomTooltipContent({ payload }) {
  const theme = useRechartsTheme();

  return <div style={theme?.tooltip?.contentStyle}>{payload[0]?.value}</div>;
}

API contract

Recharts themes are available as a public API since version 3.11. We consider the overall shape to be the API, so there will be no backwards incompatible changes in minor and patch versions.

However. What we do not consider a public API:

  • Specific styles: colors, stroke widths, dasharrays, the like
  • Number of items in the graphicalItems

If you want to receive the latest updates and accessibility fixes, use the latest theme and all is good. If you want to lock in colors and have a guarantee they never change, create your own custom theme.

Roadmap

In Recharts v4, the autoTheme will be the default theme. The legacy defaults (i.e. "no RechartsThemeProvider present") will be removed.