npm / recharts
recharts
What changed in recharts 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
2 breaking4 deprecations45 new APIs and options5 performance11 behavior and defaults3 tooling71 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initrecharts 3141 changes
Breaking changes 2
The previous align prop is replaced by position and offset.
The previous verticalAlign prop is replaced by position and offset.
Deprecations 4
Cell is deprecated and will be removed in the next major version; migrate its usage to the shape prop of the respective chart elements.
Deprecates CartesianAxis.
Pie activeShape is deprecated; use shape and the isActive prop passed from its callback to create active Pie sectors.
Pie inactiveShape is deprecated in favor of the shape prop.
New APIs and options 45
Legend now supports offset for more convenient positioning.
Legend now supports position for more convenient positioning, replacing the previous align and verticalAlign props.
Sankey now supports the accessibilityLayer prop.
Sankey now supports the desc prop.
Sankey now supports the title prop.
XAxis supports height="auto" to size the axis to its tick labels.
Animations are now fully customizable, with new animation props and fixes to existing animation behavior.
The interpolate function is exported and documented for use with animations.
ResponsiveContainer now allows HTML attributes to be passed through.
Treemap adds nodeInset and nodeGap properties for layout control.
The hook is annotated as available since 3.9.
Chart layout hooks and layout types are exposed in the public API.
Adds the cursor prop type to BaseChartProps.
Area gains external generics.
Bar gains generic types.
The data prop supports generics, allowing chart data to be validated by TypeScript.
Chart props gain event throttling controls.
Graphical items and charts gain optional explicit generics.
Legend adds a label style prop.
A typed charts helper is added.
The new niceTIcks prop accepts 'none', 'auto', 'equidistant', or 'nice' to select tick behavior.
A new hook returns the current tooltip coordinate.
A new hook returns whether the tooltip is active.
The axis type can now be auto, which selects category for categorical axes and number for numeric axes.
Exports AxisInterval from the public API.
Enables ranged stacked bars.
Exports BarRectangleItem from the public API.
Adds a component for configuring settings, such as radius, for a whole stack of bars.
Exports DataKey from the public API.
Exports the type for the Pie shape function.
Adds
graphicalItemIdto the tooltip payload object.Exports TooltipIndex from the public API.
Exports TreemapNode from the public API.
Adds the
equidistantPreserveEndinterval option for XAxis and YAxis.The ActiveDotProps type is now exported for use in TypeScript code.
The DotItemDotProps type is now exported for use in TypeScript code.
Stacked charts now support reverseStackOrder, fixing a regression between Recharts 2 and 3.
Pie now accepts shape to customize sector shapes in line with other chart elements; use the isActive prop passed to the callback to create active sectors.
Exported DefaultZIndexes so it can be imported by developers.
Exported ZIndexLayer so it can be imported by developers.
Line adds a shape property for custom shape implementations.
Sankey supports left-aligned nodes through the align prop.
Sankey supports top-aligned nodes through the verticalAlign prop.
Many chart components now support z-index ordering, allowing Recharts elements to be positioned like CSS elements.
Add the responsive prop to any chart with a height and width, avoiding the need to wrap it in ResponsiveContainer.
Performance 5
Avoids exponential depth traversal on dense graphs, improving Sankey graph processing.
ScatterChart hover reduces re-renders from O(n) to O(1).
Tree-shaking improvements and removal of unnecessary loops reduce the final bundle size.
Pie charts skip minAngle redistribution when no segment needs it.
This release includes performance improvements, including optimizing SetTooltipEntrySettings to break an infinite rendering loop.
Behavior and default changes 11
PieChart adds dataKey to the Legend payload.
Updates tick calculation and domain extension.
Bar supports CSS transitions.
Primitive animations are automatically disabled based on user system preferences.
Tooltip closes on blur.
Bar stack radius is now applied to active bars.
The offset prop now accepts a Coordinate object.
The Tooltip activeLabel type is now string | number; this may break code that relied on it being a string.
The immutable check is disabled in production, removing console warnings.
Stacked bar animations are improved.
ResponsiveContainer now shrinks only in the dimensions where shrinking is needed.
Tooling 3
The dataKey prop supports generics, allowing chart data to be validated by TypeScript.
Type definitions for LabelList and Area are enhanced.
Area.label now has a specific type instead of any.
Fixes and other changes 71
Tooltip search falls back to index-based search when label-based search returns undefined with allowDuplicatedCategory=false.
Pie passes computed innerRadius and outerRadius to Label children via PolarLabelContextProvider.
Keeps barGap correct when maxBarSize clamps the bar width.
Stale active bar layer state is cleared.
connectNulls no longer connects across stacked points where every series is null.
Floating-point tick gaps no longer cause getBandSizeOfAxis to collapse band size.
Controlled startIndex and endIndex no longer cause the brush to snap back on mouseup or be lost on data updates.
Custom label content now receives computed position attributes.
The Legend type is fixed.
Tooltip now finds the active sector in the angle-axis wrap-around gap.
The legend icon aria-label omits empty values.
Fixes the formatter prop for individual graphical items.
Removes a trailing duplicate tick when allowDecimals is false.
Sankey nodes no longer overlap links that skip depths.
Explicit ticks render when a non-literal domain cannot resolve on empty data.
Tooltip dispatch in Bar now uses originalDataIndex.
Stacked bars now render when all values are zero.
Prevents a NaN coordinate layout crash when all values are zero.
Legend no longer overlaps the chart when the container is resized.
Fixes an erroneous console warning during initialization.
Prevents NaN node positions when link values sum to zero.
Tooltips now preserve valid falsy custom names such as 0 and the empty string.
Axis padding is no longer ignored by the clipping mask when allowDataOverflow is enabled with a restricted domain.
Uses entry.value for the aria-label when a formatter returns a React element.
Restores arrow key navigation when the active index is outside the zoomed range.
Resolves keyboard navigation and tooltip issues for Pie charts.
Fixes a double padding gap when a data item has value 0.
Updates the ticks prop type for PolarRadiusAxis.
Prevents tooltip flicker with syncMethod="value" when data arrays have mismatched lengths.
Prevents crashes when payload entries are sparse or undefined.
Prevents stackOffset="expand" from overriding the numerical XAxis domain.
Elements no longer disappear during dynamic zIndex transitions.
Active bar highlighting works with missing or null data.
Prevents animated line flicker with round or square strokeLinecap.
Mouse event typing is fixed.
Charts no longer error when onMouseEnter or onMouseLeave is undefined.
Tooltip and legend colors now synchronize with per-sector fill.
Event types for Pie and RadialBar are fixed.
Pie event handler types are fixed.
Tooltip synchronization is enabled for PieChart.
PolarAngleAxis event types are fixed.
XAxis and YAxis now respect a user-provided textAnchor prop.
Tooltip payload typing is corrected from any.
Event types for XAxis and YAxis are updated.
Fixes stackOffset=sign for charts with three or more positive values in one series.
A new type fixes the TypeScript type for Bar.shape.
Fixes a circular dependency that occurred when building with Vite.
Fixes BarStack clipPath in charts using stackOffset=sign.
The tick type is now explicit instead of any.
Rounds numbers before putting them to the DOM.
Fixes a crash when a Label is passed as content to LabelList.
Fixes duplicated or unrelated tooltip payload data when multiple Scatter elements are used in one ScatterChart.
Stores refs instead of IDs to unblock shadow DOM use cases.
The accidental eslint dependency was removed from main dependencies, so it should no longer be installed with recharts.
The Pie shape prop includes the Sector index, enabling customization of specific slices similar to activeIndex in 2.x.
In multi-Pie PieCharts with shared dataKeys, only the hovered Sector is marked active, preventing cross-Pie highlighting.
Recharts ZIndex SVG portal g tags receive tabIndex -1 to prevent extraneous focusable surfaces.
ErrorBar no longer emits a duplicate key warning when an error range has identical values.
A Legend with a portal no longer adjusts the chart margin and leaves empty space.
Line animation now works correctly when interrupted by changes unrelated to data.
Active dots no longer appear outside the graph.
Overlapping 0 and 360 ticks are prevented.
Fixes a regression that prevented Area event handlers from firing correctly.
Fixes stacked bar charts with a brush removing elements from the wrong side of the chart.
Fixes Funnel label positioning issues from the previous release.
Fixes Funnel margin calculations.
Label now allows overwriting the textAnchor prop.
Label and Text types are corrected to include only what they can actually render.
Fixes a unique key error in Sankey.
Fixes animation stutters in Treemap.
The width="auto" oscillation detection now applies only when the difference is greater than 1 pixel.