> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/recharts/recharts/llms.txt
> Use this file to discover all available pages before exploring further.

# Data and layout

> How Recharts transforms your data into visual coordinates

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

```tsx theme={null}
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 },
];
```

<Note>
  Each object can have any number of properties. Recharts accesses these properties using the `dataKey` prop.
</Note>

### Nested data

Data can include nested objects:

```tsx theme={null}
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:

```tsx theme={null}
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:

```tsx theme={null}
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:

```tsx theme={null}
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()}
/>
```

<Info>
  Function `dataKey` receives the entire data point object and should return a value that can be plotted.
</Info>

### Nested dataKey with dot notation

```tsx theme={null}
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

```tsx theme={null}
<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

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

<Tabs>
  <Tab title="Horizontal (default)">
    ```tsx theme={null}
    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>
    ```
  </Tab>

  <Tab title="Vertical">
    ```tsx theme={null}
    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>
    ```
  </Tab>
</Tabs>

### Polar layouts

Polar charts use different layout values:

```tsx theme={null}
// 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:

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

The transformation involves:

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

```tsx theme={null}
<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>
```

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

### Polar coordinate system

Polar charts use angles and radii:

```tsx theme={null}
// 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:

```tsx theme={null}
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>
```

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

### Number axis

For continuous numeric values:

```tsx theme={null}
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>
```

<Info>
  Number axes scale proportionally. A value of 25 appears halfway between 0 and 50.
</Info>

## Domain configuration

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

### Auto domain (default)

Recharts automatically calculates domain from data:

```tsx theme={null}
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:

```tsx theme={null}
<YAxis domain={[0, 1000]} />
```

### Dynamic domain

Use special keywords:

```tsx theme={null}
<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:

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

<Tabs>
  <Tab title="Zero baseline">
    Always start from zero for better comparison:

    ```tsx theme={null}
    <YAxis domain={[0, 'auto']} />
    ```
  </Tab>

  <Tab title="Data range">
    Focus on data range for better detail:

    ```tsx theme={null}
    <YAxis domain={['dataMin', 'dataMax']} />
    ```
  </Tab>

  <Tab title="Symmetric">
    Center around zero for diverging data:

    ```tsx theme={null}
    <YAxis 
      domain={[
        (dataMin) => Math.min(dataMin, -Math.abs(dataMax)),
        (dataMax) => Math.max(dataMax, Math.abs(dataMin)),
      ]}
    />
    ```
  </Tab>
</Tabs>

## Data transformations

### Stacking data

Multiple bars or areas with the same `stackId` are stacked:

```tsx theme={null}
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%:

```tsx theme={null}
<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:

```tsx theme={null}
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>
  );
}
```

<Info>
  Charts with the same `syncId` synchronize their tooltip positions and active states.
</Info>

## Data point coordinates

Access computed coordinates in custom components:

```tsx theme={null}
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`