Data and layout

Recharts uses a declarative approach to map data to visual elements. Understanding how data flows through the chart and how layouts determine coordinate systems is essential for building effective visualizations.

Data structure

Recharts works with plain JavaScript arrays of objects. Each object represents a data point.

Basic data format

const data = [
  { name: 'Jan', revenue: 4000, expenses: 2400 },
  { name: 'Feb', revenue: 3000, expenses: 1398 },
  { name: 'Mar', revenue: 2000, expenses: 9800 },
  { name: 'Apr', revenue: 2780, expenses: 3908 },
];

Each object can have any number of properties. Recharts accesses these properties using the dataKey prop.

Nested data

Data can include nested objects:

const data = [
  { 
    month: 'Jan', 
    sales: { actual: 4000, target: 3500 },
    region: { north: 1200, south: 2800 }
  },
  { 
    month: 'Feb', 
    sales: { actual: 3000, target: 3200 },
    region: { north: 1500, south: 1500 }
  },
];

// Access nested data with dot notation
<Line dataKey="sales.actual" stroke="#8884d8" />
<Line dataKey="sales.target" stroke="#82ca9d" />

Array data

For scatter plots or bubble charts, data points can be coordinate pairs:

const data = [
  { x: 100, y: 200, z: 200 },
  { x: 120, y: 100, z: 260 },
  { x: 170, y: 300, z: 400 },
];

<ScatterChart width={600} height={300}>
  <XAxis dataKey="x" type="number" />
  <YAxis dataKey="y" type="number" />
  <Scatter data={data} fill="#8884d8" />
</ScatterChart>

The dataKey prop

The dataKey prop is the primary mechanism for connecting data to visual elements. It specifies which property to extract from each data object.

String dataKey

Most common usage - a string property name:

const data = [
  { month: 'Jan', value: 100 },
  { month: 'Feb', value: 200 },
];

<XAxis dataKey="month" />
<Line dataKey="value" stroke="#8884d8" />

Function dataKey

For complex data transformations, use a function:

const data = [
  { date: '2024-01-01', revenue: 4000, costs: 2400 },
  { date: '2024-02-01', revenue: 3000, costs: 1398 },
];

<Line 
  dataKey={(item) => item.revenue - item.costs} 
  stroke="#8884d8" 
  name="Profit"
/>

<XAxis 
  dataKey="date" 
  tickFormatter={(date) => new Date(date).toLocaleDateString()}
/>

Function dataKey receives the entire data point object and should return a value that can be plotted.

Nested dataKey with dot notation

const data = [
  { 
    date: '2024-01', 
    metrics: { 
      sales: { value: 1000, growth: 0.15 },
      users: { value: 5000, growth: 0.22 }
    }
  },
];

<Line dataKey="metrics.sales.value" stroke="#8884d8" />
<Line dataKey="metrics.users.value" stroke="#82ca9d" />

Layout prop

The layout prop determines the orientation of the chart and how axes are mapped to data.

Horizontal layout (default)

In horizontal layout:

XAxis represents the category (discrete values)
YAxis represents the value (continuous values)
Bars/lines grow vertically

<BarChart 
  width={600} 
  height={300} 
  data={data}
  layout="horizontal"  // default, can be omitted
>
  <XAxis dataKey="name" type="category" />
  <YAxis type="number" />
  <Bar dataKey="value" fill="#8884d8" />
</BarChart>

Vertical layout

In vertical layout:

XAxis represents the value (continuous values)
YAxis represents the category (discrete values)
Bars/lines grow horizontally

<BarChart 
  width={600} 
  height={300} 
  data={data}
  layout="vertical"
>
  <XAxis type="number" />
  <YAxis dataKey="name" type="category" />
  <Bar dataKey="value" fill="#8884d8" />
</BarChart>

Horizontal (default)
Vertical

const data = [
  { category: 'A', value: 100 },
  { category: 'B', value: 200 },
];

<BarChart layout="horizontal" data={data}>
  <XAxis dataKey="category" />  {/* Categories on X */}
  <YAxis />                       {/* Values on Y */}
  <Bar dataKey="value" />
</BarChart>

const data = [
  { category: 'A', value: 100 },
  { category: 'B', value: 200 },
];

<BarChart layout="vertical" data={data}>
  <XAxis type="number" />         {/* Values on X */}
  <YAxis dataKey="category" type="category" />  {/* Categories on Y */}
  <Bar dataKey="value" />
</BarChart>

Polar layouts

Polar charts use different layout values:

// PieChart uses 'centric' layout
<PieChart layout="centric">
  <Pie data={data} dataKey="value" />
</PieChart>

// RadarChart uses 'centric' layout
<RadarChart layout="centric">
  <PolarAngleAxis dataKey="subject" />
  <Radar dataKey="value" />
</RadarChart>

// RadialBarChart uses 'radial' layout
<RadialBarChart layout="radial">
  <RadialBar dataKey="value" />
</RadialBarChart>

Coordinate systems

Recharts transforms your data through coordinate systems to determine pixel positions.

Cartesian coordinate system

Cartesian charts use X and Y coordinates:

// Data point: { name: 'A', value: 100 }
// Transforms to: { x: 50, y: 200 } (in pixels)

The transformation involves:

Domain: The range of your data values (e.g., 0 to 1000)
Range: The pixel range available (e.g., 0 to 400)
Scale: The function that maps domain to range

<LineChart width={600} height={300} data={data}>
  <XAxis 
    dataKey="name" 
    // Domain: all unique 'name' values
    // Range: 0 to chart width
  />
  <YAxis 
    domain={[0, 1000]}  // Explicit domain
    // Range: chart height to 0 (inverted for SVG)
  />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

In SVG, the Y-axis increases downward. Recharts automatically inverts it so higher values appear at the top.

Polar coordinate system

Polar charts use angles and radii:

// Data point: { category: 'A', value: 80 }
// Transforms to: { angle: 45°, radius: 120px }

<RadarChart width={500} height={500} data={data}>
  <PolarAngleAxis 
    dataKey="category" 
    // Maps categories to angles (0° to 360°)
  />
  <PolarRadiusAxis 
    domain={[0, 100]}
    // Maps values to radii (center to edge)
  />
  <Radar dataKey="value" fill="#8884d8" />
</RadarChart>

Axis types

Recharts supports different axis types that determine how data is scaled.

Category axis

For discrete, non-numeric values:

const data = [
  { product: 'iPhone', sales: 1000 },
  { product: 'iPad', sales: 800 },
  { product: 'MacBook', sales: 600 },
];

<BarChart data={data}>
  <XAxis dataKey="product" type="category" />
  <YAxis type="number" />
  <Bar dataKey="sales" fill="#8884d8" />
</BarChart>

Category axes distribute items evenly regardless of their actual values. Each category gets equal spacing.

Number axis

For continuous numeric values:

const data = [
  { time: 0, position: 0 },
  { time: 10, position: 50 },
  { time: 25, position: 75 },
  { time: 100, position: 100 },
];

<LineChart data={data}>
  <XAxis dataKey="time" type="number" domain={[0, 100]} />
  <YAxis dataKey="position" type="number" />
  <Line dataKey="position" stroke="#8884d8" />
</LineChart>

Number axes scale proportionally. A value of 25 appears halfway between 0 and 50.

Domain configuration

The domain prop controls the range of values displayed on an axis.

Auto domain (default)

Recharts automatically calculates domain from data:

const data = [
  { x: 10, y: 100 },
  { x: 50, y: 500 },
];

<LineChart data={data}>
  <XAxis dataKey="x" />  {/* domain: [10, 50] */}
  <YAxis />               {/* domain: [100, 500] */}
  <Line dataKey="y" stroke="#8884d8" />
</LineChart>

Fixed domain

Explicitly set min and max:

<YAxis domain={[0, 1000]} />

Dynamic domain

Use special keywords:

<YAxis domain={['auto', 'auto']} />          {/* Auto-calculated */}
<YAxis domain={['dataMin', 'dataMax']} />    {/* Min/max from data */}
<YAxis domain={[0, 'dataMax']} />            {/* Start at 0, max from data */}
<YAxis domain={['dataMin - 100', 'dataMax + 100']} />  {/* Add padding */}

Function domain

Calculate domain dynamically:

<YAxis 
  domain={[
    (dataMin) => Math.floor(dataMin / 100) * 100,
    (dataMax) => Math.ceil(dataMax / 100) * 100,
  ]}
/>

Zero baseline
Data range
Symmetric

Always start from zero for better comparison:

<YAxis domain={[0, 'auto']} />

Focus on data range for better detail:

<YAxis domain={['dataMin', 'dataMax']} />

Center around zero for diverging data:

<YAxis 
  domain={[
    (dataMin) => Math.min(dataMin, -Math.abs(dataMax)),
    (dataMax) => Math.max(dataMax, Math.abs(dataMin)),
  ]}
/>

Data transformations

Stacking data

Multiple bars or areas with the same stackId are stacked:

const data = [
  { month: 'Jan', productA: 100, productB: 200, productC: 150 },
  { month: 'Feb', productA: 150, productB: 250, productC: 100 },
];

<BarChart data={data}>
  <XAxis dataKey="month" />
  <YAxis />
  <Bar dataKey="productA" stackId="stack" fill="#8884d8" />
  <Bar dataKey="productB" stackId="stack" fill="#82ca9d" />
  <Bar dataKey="productC" stackId="stack" fill="#ffc658" />
</BarChart>

Stacking behavior:

First bar starts from baseline (0 or domain min)
Second bar starts where first bar ends
Third bar starts where second bar ends

Percentage stacking

Normalize stacks to 100%:

<BarChart data={data}>
  <XAxis dataKey="month" />
  <YAxis />
  <Bar dataKey="productA" stackId="stack" fill="#8884d8" />
  <Bar dataKey="productB" stackId="stack" fill="#82ca9d" />
  <Bar dataKey="productC" stackId="stack" fill="#ffc658" />
  {/* Each stack totals to 100% of available height */}
</BarChart>

// To show percentage labels:
<Bar dataKey="productA" stackId="stack">
  <LabelList 
    dataKey="productA" 
    formatter={(value, entry) => {
      const total = entry.productA + entry.productB + entry.productC;
      return `${((value / total) * 100).toFixed(1)}%`;
    }}
  />
</Bar>

Synchronized charts

Share interactions across multiple charts:

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

function SynchronizedCharts() {
  return (
    <div>
      <LineChart 
        width={600} 
        height={200} 
        data={data1}
        syncId="charts"  // Same syncId = synchronized
      >
        <XAxis dataKey="time" />
        <YAxis />
        <Tooltip />
        <Line dataKey="temperature" stroke="#8884d8" />
      </LineChart>

      <LineChart 
        width={600} 
        height={200} 
        data={data2}
        syncId="charts"  // Shares hover state with chart above
      >
        <XAxis dataKey="time" />
        <YAxis />
        <Tooltip />
        <Line dataKey="humidity" stroke="#82ca9d" />
      </LineChart>
    </div>
  );
}

Charts with the same syncId synchronize their tooltip positions and active states.

Data point coordinates

Access computed coordinates in custom components:

const CustomDot = (props) => {
  const { cx, cy, payload } = props;
  // cx, cy are pixel coordinates
  // payload is the original data point
  
  return (
    <circle 
      cx={cx} 
      cy={cy} 
      r={payload.value > 100 ? 6 : 3} 
      fill={payload.value > 100 ? 'red' : '#8884d8'}
    />
  );
};

<Line dataKey="value" dot={<CustomDot />} />

Coordinate props available:

cx, cy: Center coordinates (for dots, scatter points)
x, y: Top-left coordinates (for bars, rectangles)
width, height: Dimensions (for bars, rectangles)
payload: Original data object
value: The plotted value from dataKey

Get Started

Core Concepts

Guides

Examples

Data structure

Basic data format

Nested data

Array data

The dataKey prop

String dataKey

Function dataKey

Nested dataKey with dot notation

Layout prop

Horizontal layout (default)

Vertical layout

Polar layouts

Coordinate systems

Cartesian coordinate system

Polar coordinate system

Axis types

Category axis

Number axis

Domain configuration

Auto domain (default)

Fixed domain

Dynamic domain

Function domain

Data transformations

Stacking data

Percentage stacking

Synchronized charts

Data point coordinates

Get Started

Core Concepts

Guides

Examples

Documentation Index

​Data structure

​Basic data format

​Nested data

​Array data

​The dataKey prop

​String dataKey

​Function dataKey

​Nested dataKey with dot notation

​Layout prop

​Horizontal layout (default)

​Vertical layout

​Polar layouts

​Coordinate systems

​Cartesian coordinate system

​Polar coordinate system

​Axis types

​Category axis

​Number axis

​Domain configuration

​Auto domain (default)

​Fixed domain

​Dynamic domain

​Function domain

​Data transformations

​Stacking data

​Percentage stacking

​Synchronized charts

​Data point coordinates

Data structure

Basic data format

Nested data

Array data

The dataKey prop

String dataKey

Function dataKey

Nested dataKey with dot notation

Layout prop

Horizontal layout (default)

Vertical layout

Polar layouts

Coordinate systems

Cartesian coordinate system

Polar coordinate system

Axis types

Category axis

Number axis

Domain configuration

Auto domain (default)

Fixed domain

Dynamic domain

Function domain

Data transformations

Stacking data

Percentage stacking

Synchronized charts

Data point coordinates