Composable architecture

Recharts follows a composable architecture where charts are built by combining small, focused components. This design provides flexibility and reusability while maintaining a declarative API.

Chart composition model

Every Recharts chart is composed of three types of components:

Chart containers - The top-level component that defines the chart type
Graphical items - Components that render data (Line, Bar, Area, etc.)
Supporting components - Axes, grids, tooltips, legends, and labels

import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip } from 'recharts';

function MyChart() {
  return (
    <LineChart width={600} height={300} data={data}>
      {/* Supporting component - grid */}
      <CartesianGrid strokeDasharray="3 3" />
      
      {/* Supporting components - axes */}
      <XAxis dataKey="name" />
      <YAxis />
      
      {/* Graphical item - renders the data */}
      <Line type="monotone" dataKey="value" stroke="#8884d8" />
      
      {/* Supporting component - tooltip */}
      <Tooltip />
    </LineChart>
  );
}

Chart containers

Chart containers provide the coordinate system and manage the rendering context for child components.

Cartesian charts

Cartesian charts use X and Y axes:

import { LineChart, BarChart, AreaChart, ScatterChart, ComposedChart } from 'recharts';

// All cartesian charts share common props
<LineChart 
  width={600} 
  height={300} 
  data={data}
  margin={{ top: 5, right: 30, left: 20, bottom: 5 }}
>
  {/* Children components */}
</LineChart>

Cartesian charts automatically manage coordinate transformations and provide contexts consumed by XAxis, YAxis, and graphical items like Line, Bar, and Area.

Polar charts

Polar charts use angular and radial coordinates:

import { PieChart, RadarChart, RadialBarChart } from 'recharts';

<PieChart width={400} height={400}>
  {/* Pie, PolarGrid, PolarAngleAxis, etc. */}
</PieChart>

<RadarChart width={500} height={500} data={data}>
  {/* Radar, PolarGrid, PolarAngleAxis, PolarRadiusAxis */}
</RadarChart>

Graphical items

Graphical items render your data. They consume the chart context and axes to transform data into visual elements.

Line component

Renders data as connected points:

import { LineChart, Line } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line 
    type="monotone" 
    dataKey="revenue" 
    stroke="#8884d8" 
    strokeWidth={2}
    dot={{ fill: '#8884d8', r: 4 }}
    activeDot={{ r: 6 }}
  />
</LineChart>

Props
Source reference

dataKey: The key in data array to plot (required)
type: Curve interpolation (monotone, linear, step, etc.)
stroke: Line color
strokeWidth: Line thickness
dot: Show/customize dots at data points
activeDot: Customize active dot on hover

Implementation: src/cartesian/Line.tsx:14-29

Bar component

Renders data as rectangular bars:

import { BarChart, Bar } from 'recharts';

<BarChart width={600} height={300} data={data}>
  <Bar 
    dataKey="sales" 
    fill="#8884d8" 
    radius={[10, 10, 0, 0]}
    background={{ fill: '#eee' }}
  />
</BarChart>

Area component

Renders data as filled area under a line:

import { AreaChart, Area } from 'recharts';

<AreaChart width={600} height={300} data={data}>
  <Area 
    type="monotone" 
    dataKey="users" 
    stroke="#8884d8" 
    fill="#8884d8" 
    fillOpacity={0.6}
  />
</AreaChart>

Multiple graphical items

Combine multiple graphical items in one chart:

import { LineChart, Line, Area } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Area type="monotone" dataKey="range" fill="#8884d8" fillOpacity={0.3} />
  <Line type="monotone" dataKey="average" stroke="#8884d8" strokeWidth={2} />
  <Line type="monotone" dataKey="median" stroke="#82ca9d" strokeWidth={2} />
</LineChart>

Axes components

Axes define the scale and orientation for plotting data.

XAxis and YAxis

Cartesian axes for horizontal and vertical dimensions:

import { LineChart, Line, XAxis, YAxis } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <XAxis 
    dataKey="name" 
    stroke="#8884d8"
    tick={{ fill: '#8884d8' }}
    tickLine={{ stroke: '#8884d8' }}
  />
  <YAxis 
    stroke="#82ca9d"
    tickFormatter={(value) => `$${value}`}
  />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

XAxis typically uses type="category" (discrete values) while YAxis uses type="number" (continuous values). These defaults are inferred from the chart layout.

Multiple axes

Use multiple axes for different data scales:

import { LineChart, Line, XAxis, YAxis } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <XAxis dataKey="name" />
  {/* Left Y-axis for revenue */}
  <YAxis yAxisId="left" orientation="left" stroke="#8884d8" />
  {/* Right Y-axis for percentage */}
  <YAxis yAxisId="right" orientation="right" stroke="#82ca9d" />
  
  <Line yAxisId="left" dataKey="revenue" stroke="#8884d8" />
  <Line yAxisId="right" dataKey="growthRate" stroke="#82ca9d" />
</LineChart>

PolarAngleAxis and PolarRadiusAxis

Axes for polar coordinate systems:

import { RadarChart, Radar, PolarGrid, PolarAngleAxis, PolarRadiusAxis } from 'recharts';

<RadarChart width={500} height={500} data={data}>
  <PolarGrid />
  <PolarAngleAxis dataKey="category" />
  <PolarRadiusAxis angle={90} domain={[0, 100]} />
  <Radar dataKey="value" fill="#8884d8" fillOpacity={0.6} />
</RadarChart>

Grid components

Grids add visual guides to help read values.

CartesianGrid

import { LineChart, Line, CartesianGrid } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <CartesianGrid 
    strokeDasharray="3 3" 
    vertical={true}
    horizontal={true}
  />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

PolarGrid

import { RadarChart, Radar, PolarGrid } from 'recharts';

<RadarChart width={500} height={500} data={data}>
  <PolarGrid gridType="polygon" />
  <Radar dataKey="value" fill="#8884d8" />
</RadarChart>

Interactive components

Display data on hover:

import { LineChart, Line, Tooltip } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line dataKey="value" stroke="#8884d8" />
  <Tooltip 
    contentStyle={{ backgroundColor: '#fff', border: '1px solid #ccc' }}
    labelStyle={{ fontWeight: 'bold' }}
    formatter={(value) => `$${value.toLocaleString()}`}
  />
</LineChart>

The Tooltip component automatically detects the tooltip event type based on the chart. LineChart and AreaChart default to axis tooltips, while PieChart defaults to item tooltips.

Legend

Display a legend for multiple data series:

import { LineChart, Line, Legend } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line name="Revenue" dataKey="revenue" stroke="#8884d8" />
  <Line name="Expenses" dataKey="expenses" stroke="#82ca9d" />
  <Legend 
    verticalAlign="top" 
    height={36}
    iconType="circle"
  />
</LineChart>

Cursor

Customize the cursor shown on hover:

import { LineChart, Line, Tooltip } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line dataKey="value" stroke="#8884d8" />
  <Tooltip cursor={{ stroke: '#8884d8', strokeWidth: 2, strokeDasharray: '5 5' }} />
</LineChart>

Label components

Label

Add labels to axes, lines, or specific points:

import { LineChart, Line, XAxis, Label } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <XAxis dataKey="name">
    <Label value="Month" offset={0} position="insideBottom" />
  </XAxis>
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

LabelList

Add labels to all data points:

import { BarChart, Bar, LabelList } from 'recharts';

<BarChart width={600} height={300} data={data}>
  <Bar dataKey="value" fill="#8884d8">
    <LabelList dataKey="value" position="top" />
  </Bar>
</BarChart>

Customization components

Cell

Customize individual segments in Pie charts or bars:

import { PieChart, Pie, Cell } from 'recharts';

const COLORS = ['#0088FE', '#00C49F', '#FFBB28', '#FF8042'];

<PieChart width={400} height={400}>
  <Pie data={data} dataKey="value">
    {data.map((entry, index) => (
      <Cell key={`cell-${index}`} fill={COLORS[index % COLORS.length]} />
    ))}
  </Pie>
</PieChart>

Customized

Render custom SVG content within the chart:

import { LineChart, Line, Customized } from 'recharts';

const CustomShape = (props) => {
  const { x, y, width, height } = props;
  return (
    <rect x={x} y={y} width={width} height={height} fill="rgba(255, 0, 0, 0.1)" />
  );
};

<LineChart width={600} height={300} data={data}>
  <Customized component={CustomShape} />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

Reference components

Add reference lines, areas, or dots to highlight specific values:

import { LineChart, Line, ReferenceLine, ReferenceArea, ReferenceDot } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line dataKey="value" stroke="#8884d8" />
  
  {/* Horizontal line at y=100 */}
  <ReferenceLine y={100} stroke="red" label="Target" />
  
  {/* Vertical line at x="Feb" */}
  <ReferenceLine x="Feb" stroke="green" label="Launch" />
  
  {/* Highlight a region */}
  <ReferenceArea x1="Jan" x2="Mar" y1={0} y2={150} fill="#82ca9d" fillOpacity={0.3} />
  
  {/* Mark a specific point */}
  <ReferenceDot x="Apr" y={120} r={10} fill="red" stroke="none" />
</LineChart>

Component hierarchy

The order of components matters for rendering and interactivity:

<LineChart>
  {/* 1. Grid and reference components (background) */}
  <CartesianGrid />
  <ReferenceArea />
  
  {/* 2. Axes */}
  <XAxis />
  <YAxis />
  
  {/* 3. Graphical items (data visualization) */}
  <Line />
  <Area />
  
  {/* 4. Interactive overlays */}
  <Tooltip />
  <Legend />
  
  {/* 5. Custom decorations (foreground) */}
  <Customized />
</LineChart>

Components are rendered in the order they appear in JSX. Place background elements first and interactive elements last for proper layering.

Context providers

Recharts uses React context internally to share state between components:

CartesianChartContext: Provides chart dimensions, layout, and data to XAxis, YAxis, and cartesian graphical items
PolarChartContext: Provides polar coordinate system to PolarAngleAxis, PolarRadiusAxis, and polar graphical items
ResponsiveContainerContext: Provides responsive dimensions to chart containers

// From src/chart/LineChart.tsx:14-29
export const LineChart = forwardRef<SVGSVGElement, CartesianChartProps<unknown>>(
  (props: CartesianChartProps<unknown>, ref) => {
    return (
      <CartesianChart
        chartName="LineChart"
        defaultTooltipEventType="axis"
        validateTooltipEventTypes={allowedTooltipTypes}
        tooltipPayloadSearcher={arrayTooltipSearcher}
        categoricalChartProps={props}
        ref={ref}
      />
    );
  },
);

You don’t need to interact with contexts directly. They’re managed automatically when you compose chart components.

Get Started

Core Concepts

Guides

Examples

Composable architecture

Chart composition model

Chart containers

Cartesian charts

Polar charts

Graphical items

Line component

Bar component

Area component

Multiple graphical items

Axes components

XAxis and YAxis

Multiple axes

PolarAngleAxis and PolarRadiusAxis

Grid components

CartesianGrid

PolarGrid

Interactive components

Tooltip

Legend

Cursor

Label components

Label

LabelList

Customization components

Cell

Customized

Reference components

Component hierarchy

Context providers

Get Started

Core Concepts

Guides

Examples

Documentation Index

​Chart composition model

​Chart containers

​Cartesian charts

​Polar charts

​Graphical items

​Line component

​Bar component

​Area component

​Multiple graphical items

​Axes components

​XAxis and YAxis

​Multiple axes

​PolarAngleAxis and PolarRadiusAxis

​Grid components

​CartesianGrid

​PolarGrid

​Interactive components

​Tooltip

​Legend

​Cursor

​Label components

​Label

​LabelList

​Customization components

​Cell

​Customized

​Reference components

​Component hierarchy

​Context providers

Chart composition model

Chart containers

Cartesian charts

Polar charts

Graphical items

Line component

Bar component

Area component

Multiple graphical items

Axes components

XAxis and YAxis

Multiple axes

PolarAngleAxis and PolarRadiusAxis

Grid components

CartesianGrid

PolarGrid

Interactive components

Tooltip

Legend

Cursor

Label components

Label

LabelList

Customization components

Cell

Customized

Reference components

Component hierarchy

Context providers