Migration guides

Guides for migrating between major versions of Recharts

This page provides guidance for migrating your code when upgrading between major versions of Recharts.

Version 2.0.0

Version 2.0.0 is a major release with breaking changes. Please review this guide carefully before upgrading.

TypeScript rewrite

Version 2.0.0 was completely rewritten in TypeScript. This provides better type safety and improved developer experience.

What changed:

• Source code is now TypeScript (src/ contains .ts and .tsx files)
• Full type definitions included
• Better autocomplete and type checking in TypeScript projects

Action required:

• Update your TypeScript types if you were using custom type definitions
• Remove any community-provided type packages like @types/recharts

React version requirement

What changed:

• Only React 16+ is supported
• React 15 support has been removed

Action required:

• Upgrade to React 16 or higher before upgrading Recharts
• Replace unsafe lifecycle methods if you’re using custom components

Component lifecycle changes

Version 2.0.0 uses getDerivedStateFromProps to replace UNSAFE_componentWillReceiveProps for React 17 support.

If you’re using custom components with Recharts, ensure they’re compatible with React 16+ lifecycle methods.

D3 package upgrades

What changed:

• D3 packages (d3-scale, d3-shape, d3-interpolate) upgraded to version 2.x/3.x
• D3 7.x upgrade in version 2.1.12 may break some testing tools

Action required:

Jest configuration for D3 7.x (v2.1.12+)

If you’re using Jest for testing, you may need to update your configuration:

const path = require('path');
const d3Pkgs = [
  'd3',
  'd3-array',
  'd3-scale',
  'd3-shape',
  'd3-interpolate',
  // ... other d3 packages
];

module.exports = {
  transform: {
    '^.+\.m?[jt]sx?$': 'babel-jest',
  },
  transformIgnorePatterns: [
    `/node_modules/(?!${d3Pkgs.join('|')}|internmap|d3-delaunay|delaunator|robust-predicates)`,
  ],
};

Prop changes

Pie component

What changed:

• Deprecated valueKey prop removed

Action required:

• Use dataKey instead of valueKey

// Before
<Pie valueKey="value" />

// After
<Pie dataKey="value" />

Axis components

What changed:

• scale="utcTime" renamed to scale="utc"

Action required:

• Update scale prop values

// Before
<XAxis scale="utcTime" />

// After
<XAxis scale="utc" />

Stack offset changes

What changed:

• Fixed stackOffset="sign" behavior
• Added stackOffset="positive" option for positive-only stacking

Action required:

• Review your stacked charts with stackOffset="sign" to ensure they still display correctly
• Use stackOffset="positive" if you need the old behavior for positive values only

Type exports

What changed:

• Component props are now exported for TypeScript users

Action required:

• Update imports if you were defining types manually

// Before (manual types)
type CustomLineProps = {
  stroke?: string;
  // ...
};

// After (use exported types)
import { LineProps } from 'recharts';
type CustomLineProps = LineProps & {
  // your custom props
};

Version 1.0.0

Breaking changes from 0.x

Legend and Tooltip wrapperStyle

What changed:

• Removed wrapperStyle prop from DefaultTooltipContent

Action required:

• Use contentStyle prop instead for styling tooltip content

Axis scale values

What changed:

• Replaced axis scale value utcTime with utc

Action required:

• Update any XAxis or YAxis components using scale="utcTime"

Line and Area clipping

What changed:

• Dots in Line charts are now clipped by default

Action required:

• Verify that your line charts display as expected
• Adjust margins if needed to show dots at chart boundaries

Need help?

If you encounter issues during migration:

• Check the GitHub Issues for similar problems
• Review the full changelog for detailed changes
• Ask questions in GitHub Discussions
• Join the Recharts Slack community