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 experimental. They are exported from the main recharts entry point and they work, but the shape of RechartsTheme can still change in a minor or patch release. Charts without a theme provider keep rendering exactly as they always have.

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, lightTheme } from 'recharts';

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

That is the whole API surface. There is no theme prop on the chart root; a provider around one chart is how you theme one chart.

Built-in themes

Recharts ships three themes:

You can try lightTheme and darkTheme right here: the sun / moon button in the navigation bar at the top of this page switches this whole website between the two, and every chart on the page - including the one below - follows along. That button is not a documentation gimmick, it is the real thing: ColorModePicker flips a color mode and the site's layout hands the matching Recharts theme to a single RechartsThemeProvider.

The chart below has no theme provider of its own, so it inherits whatever the page is using. The control lets you swap that inherited theme for the two states the navigation bar cannot express: emptyTheme, and no provider at all. The difference between those two is the interesting one - no provider means every component falls back to its own historical defaults, while emptyTheme means "a theme is in charge, and it says: nothing".

import { CSSProperties, ReactNode } from 'react';
import {
  Bar,
  BarChart,
  CartesianGrid,
  emptyTheme,
  Legend,
  RechartsTheme,
  RechartsThemeProvider,
  ReferenceLine,
  Tooltip,
  XAxis,
  YAxis,
} from 'recharts';
import { generateMockData, RechartsDevtools } from '@recharts/devtools';
import type { Lever } from '../../Shared/levers/Levers.tsx';
import { themeLever, ThemeLeverValue } from '../../Shared/levers/gallery/themeLever.tsx';

const data = generateMockData(7, 314);

/*
 * `undefined` is a valid value for the provider and it means the same thing as
 * having no provider at all: every component falls back to its own legacy defaults.
 * We need it here because this documentation website already wraps everything
 * in a theme provider, so the example has to reset it explicitly.
 */
const themeOverrides: Record<Exclude<ThemeLeverValue, 'inherit'>, RechartsTheme | undefined> = {
  empty: emptyTheme,
  none: undefined,
};

/*
 * Neither `emptyTheme` nor the legacy defaults give Bar a color, so those two
 * variants draw black bars. We put them on a light surface on purpose - on a dark
 * page they would be invisible, which is exactly the point of those two options.
 * The `inherit` variant paints nothing and lets the page background show through.
 */
const surfaceStyles: Record<ThemeLeverValue, CSSProperties> = {
  inherit: {},
  empty: { backgroundColor: '#ffffff' },
  none: { backgroundColor: '#ffffff' },
};

type ThemeSwitcherControlsState = {
  themeName: ThemeLeverValue;
};

export const themeSwitcherDefaultState: ThemeSwitcherControlsState = {
  themeName: 'inherit',
};

export const themeSwitcherLevers = [themeLever<ThemeSwitcherControlsState>()] satisfies ReadonlyArray<
  Lever<ThemeSwitcherControlsState>
>;

function WithTheme({ themeName, children }: { themeName: ThemeLeverValue; children: ReactNode }) {
  if (themeName === 'inherit') {
    // No provider of our own: the chart uses whichever theme the page provides.
    return children;
  }

  return <RechartsThemeProvider value={themeOverrides[themeName]}>{children}</RechartsThemeProvider>;
}

export default function ThemeSwitcherExample(props: Partial<ThemeSwitcherControlsState>) {
  const { themeName } = { ...themeSwitcherDefaultState, ...props };

  return (
    <div style={{ padding: 12, borderRadius: 8, ...surfaceStyles[themeName] }}>
      <WithTheme themeName={themeName}>
        <BarChart
          style={{ width: '100%', maxWidth: 600, maxHeight: '70vh', aspectRatio: 1.618 }}
          responsive
          data={data}
          margin={{ top: 10, right: 10, left: 10, bottom: 10 }}
        >
          <CartesianGrid />
          <XAxis dataKey="label" />
          <YAxis />
          <ReferenceLine y={600} label="target" />
          <Tooltip defaultIndex={3} />
          <Legend />
          <Bar dataKey="x" isAnimationActive={false} />
          <Bar dataKey="y" isAnimationActive={false} />
          <RechartsDevtools />
        </BarChart>
      </WithTheme>
    </div>
  );
}

The "no provider" option is worth a closer look: the grid, the axes and the reference line all fall back to the greys they have used since Recharts 2.x, but the bars come out black. That is not a bug - Bar and Scatter have never had a default color, so without a theme you have to pass fill yourself. Line and Area do have a legacy default, but it is a single blue for every series. Giving multi-series charts sensible colors out of the box is one of the reasons themes exist.

Both of those unstyled variants draw black bars, so the example puts them on a white surface. On a dark page they would simply be invisible - which is the honest answer to "what does an unthemed chart look like in dark mode".

How a style is resolved

For every themed property, Recharts asks three questions in order:

1. Did you pass the prop explicitly? If yes, your prop wins. Always. A theme never overrides something you wrote in JSX.
2. Is there a theme provider, and does its theme contain the relevant section? If yes, the theme value is used.
3. Is there no theme provider at all? Then the component uses its own legacy default - the value it has used since Recharts 2.x.

The case worth calling out is the combination of "there is a provider" and "the theme does not define this section". In that case Recharts renders nothing for that property rather than falling back to the legacy default. This is what makes emptyTheme possible, and it means a partial theme is a real design decision: a theme with no grid section gives you an unstyled CartesianGrid, not the default dashed grey one.

Merging happens field by field, not object by object. If a theme sets stroke and strokeWidth and you only pass stroke, you keep the theme's strokeWidth.

What a theme contains

A theme is a flat set of semantic sections rather than a per-component configuration object. Several components usually share one section, which is what keeps a theme small enough to write by hand.

The theme does not set the chart size. Set the chart size with the style prop instead - see the chart size guide.

Colors for multiple series

graphicalItems is an array, and each graphical item in a chart picks one entry from it. The interesting question is which entry.

Recharts does not use render order. Render order is not stable: series get toggled, conditionally rendered, or reordered, and React does not guarantee the traversal order you might expect. Coloring by position means colors jump around when any of that happens.

Instead, most graphical items derive their index from a hash of their dataKey. The same dataKey therefore always gets the same color, in every chart, across renders and reloads.

• Line, Area, Bar, Scatter, Radar and RadialBar hash their dataKey into the array. An item with no dataKey gets no themed color.
• Pie, Funnel and Treemap draw many shapes from a single series, so they walk the array by position instead: sector i gets entry i % graphicalItems.length.

Hashing is best-effort, not a guarantee. Two dataKeys can land on the same entry, especially with a short array - "x" and "y" collide in a two-color theme, for instance. A longer palette makes collisions less likely; an explicit fill or stroke prop removes the question entirely.

Each entry can also carry an active block, which styles the highlighted representation of that item: the active dot of Line, Area and Radar, and the active sector of Pie.

Writing your own theme

A RechartsTheme is a plain object: build it inline, import it from a shared module, or fetch it as JSON. Only graphicalItems is required.

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

/*
 * Option 1: start from scratch. Only `graphicalItems` is required.
 * Everything you leave out renders unstyled.
 */
const minimalTheme: RechartsTheme = {
  graphicalItems: [{ fill: '#4338ca' }, { fill: '#0f766e' }],
};

/*
 * Option 2: start from a built-in theme and override what you need.
 * These are plain objects, so a spread is all it takes.
 */
const brandTheme: RechartsTheme = {
  ...lightTheme,
  typography: { ...lightTheme.typography, fontFamily: 'Inter, sans-serif' },
  grid: { ...lightTheme.grid, stroke: '#e2e8f0', strokeDasharray: '1 4' },
};

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

The example below defines a complete theme from scratch and applies it to a line chart:

import {
  CartesianGrid,
  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,
  },
  /*
   * `revenue` picks index 0 and `profit` picks index 1 of this array.
   * The index comes from a hash of the dataKey, not from the render order.
   */
  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' },
  },
};

export default function CustomThemeExample() {
  return (
    <div style={{ padding: 12, borderRadius: 8, backgroundColor: '#ffffff' }}>
      <RechartsThemeProvider value={brandTheme}>
        <LineChart
          style={{ width: '100%', maxWidth: 600, maxHeight: '70vh', aspectRatio: 1.618 }}
          responsive
          data={data}
          margin={{ top: 10, right: 20, left: 10, bottom: 10 }}
        >
          <CartesianGrid />
          <XAxis dataKey="month" />
          <YAxis />
          <ReferenceLine y={6000} />
          <Tooltip defaultIndex={2} />
          <Legend />
          <Line dataKey="revenue" isAnimationActive={false} />
          <Line dataKey="profit" isAnimationActive={false} />
          <RechartsDevtools />
        </LineChart>
      </RechartsThemeProvider>
    </div>
  );
}

Nested providers

Providers nest, and the nearest one wins. This is how you give one chart or one section its own look without touching the rest of the page.

One thing to watch: a nested provider replaces the outer theme, it does not merge with it. Recharts reads the nearest theme object and nothing else. If you only want to change the palette, spread the outer theme into the new one - otherwise everything you did not repeat becomes unstyled.

import { Bar, BarChart, CartesianGrid, lightTheme, RechartsTheme, RechartsThemeProvider, XAxis, YAxis } from 'recharts';
import { RechartsDevtools } from '@recharts/devtools';

const data = [
  { month: 'Jan', desktop: 320, mobile: 180 },
  { month: 'Feb', desktop: 410, mobile: 260 },
  { month: 'Mar', desktop: 380, mobile: 300 },
  { month: 'Apr', desktop: 500, mobile: 220 },
];

/*
 * A nested provider REPLACES the outer theme, it does not merge with it.
 * Spread the theme you want to build on so that the sections you do not
 * override keep working.
 */
const campaignTheme: RechartsTheme = {
  ...lightTheme,
  graphicalItems: [
    { fill: '#7c3aed', fillOpacity: 0.9 },
    { fill: '#db2777', fillOpacity: 0.9 },
  ],
};

function TrafficChart({ mobileFill }: { mobileFill?: string }) {
  return (
    <BarChart
      style={{ width: '100%', maxHeight: '70vh', aspectRatio: 1.2 }}
      responsive
      data={data}
      margin={{ top: 10, right: 10, left: 0, bottom: 10 }}
    >
      <CartesianGrid />
      <XAxis dataKey="month" />
      <YAxis />
      <Bar dataKey="desktop" isAnimationActive={false} />
      <Bar dataKey="mobile" fill={mobileFill} isAnimationActive={false} />
      <RechartsDevtools />
    </BarChart>
  );
}

export default function NestedThemeExample() {
  return (
    <RechartsThemeProvider value={lightTheme}>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 16, padding: 12, backgroundColor: '#ffffff' }}>
        <figure style={{ margin: 0, width: 240 }}>
          <TrafficChart />
          <figcaption style={{ color: '#18181b' }}>outer lightTheme</figcaption>
        </figure>

        <RechartsThemeProvider value={campaignTheme}>
          <figure style={{ margin: 0, width: 240 }}>
            <TrafficChart />
            <figcaption style={{ color: '#18181b' }}>nested campaignTheme</figcaption>
          </figure>

          <figure style={{ margin: 0, width: 240 }}>
            <TrafficChart mobileFill="#f59e0b" />
            <figcaption style={{ color: '#18181b' }}>nested theme + explicit fill</figcaption>
          </figure>
        </RechartsThemeProvider>
      </div>
    </RechartsThemeProvider>
  );
}

Switching themes at runtime

Dark mode is 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.

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>
    </>
  );
}

This is not a hypothetical - it is how this website works, and you have been using it all along. The button in the navigation bar cycles light, dark and system; the site layout reads that color mode and renders one RechartsThemeProvider around the entire page with either lightTheme or darkTheme. Every chart in these docs, in every guide and every example, is themed by that single provider. Press it and watch the charts on this page change. See the source code of this page here: on github.

Remember that darkTheme only styles what Recharts draws. The background behind the chart belongs to your page - the site pairs the theme switch with its own CSS color scheme.

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;
}

.dark {
  --chart-text: #f5f5f4;
  --chart-grid: #3f3f46;
  --chart-axis: #d6d3d1;
  --chart-1: #a5b4fc;
  --chart-2: #5eead4;
  --chart-3: #fcd34d;
}

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)' },
};

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

Matching an existing design system

Recharts does not ship adapters for Material UI, Mantine, Chakra, Ant Design or anything else, and it does not need to: a theme is a plain object, so mapping your design system's tokens onto it is a useMemo away.

import { useMemo } from 'react';
import { useTheme } from '@mui/material/styles';
import { RechartsThemeProvider, 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 rechartsTheme = useMemo<RechartsTheme>(
    () => ({
      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: { stroke: muiTheme.palette.divider, fill: 'none' },
      axis: { stroke: muiTheme.palette.text.secondary },
      tooltip: {
        contentStyle: {
          backgroundColor: muiTheme.palette.background.paper,
          border: `1px solid ${muiTheme.palette.divider}`,
          borderRadius: muiTheme.shape.borderRadius,
        },
      },
    }),
    [muiTheme],
  );

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

Reading the theme yourself

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>;
}

Current limitations

• The API is marked experimental. RechartsTheme can change shape in a minor or patch release.
• Not every component is themed yet. Sankey and SunburstChart still use their own defaults regardless of the theme.
• Themes are not deep-merged. Nested providers replace, and there is no createTheme helper to merge for you.
• Series colors are assigned by a hash, which is stable but not collision-free. Use explicit props when a specific color matters.