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:
Built-in themes
Recharts ships four themes:
| Theme | What it does |
|---|---|
lightTheme | A complete light-mode style: dark text, light grid. |
darkTheme | The dark-mode counterpart: light text, dark grid. It expects a dark page. On a light page its light text and axes are not legible. |
autoTheme | Automatically 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. |
emptyTheme | Theming 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:
- SVG properties defined in the
datainput array. See Styling data points guide for details. - Props in the JSX.
- Theme (i.e. RechartsThemeProvider is present in the current React context)
- 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:
pageBackgroundis 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.chartis 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. Thestyleprop 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
labelprop of graphical items, and the default Pie label draw, take their styles from thelabelof theirgraphicalItemsentry. 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.
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.
To start from scratch instead, define styles for every component your chart uses, as in this example:
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.
autoTheme does nothing on its own: it follows the color-scheme that your page sets.
Some things to keep in mind:
light-dark()needs Chrome 123, Firefox 120, or Safari 17.5. If you support older browsers, switch betweenlightThemeanddarkThemein React state, or use CSS variables.- Like
darkTheme,autoThemeonly styles what Recharts draws. The background behind the chart belongs to your page, so let the page background follow the samecolor-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.
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.
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:
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.
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.