Axes and grids

Configure axes and grids for precise control over your charts

Axes define how your data maps to visual space. This guide covers XAxis, YAxis, and CartesianGrid configuration.

Axis basics

XAxis configuration

The X-axis typically represents categories or time:

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

const data = [
  { month: 'Jan', value: 400 },
  { month: 'Feb', value: 300 },
  { month: 'Mar', value: 600 },
];

<LineChart width={600} height={300} data={data}>
  <XAxis dataKey="month" />
  <YAxis />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

YAxis configuration

The Y-axis typically represents values:

<YAxis />

No dataKey is needed for Y-axis—it automatically uses the data from your Line, Bar, or Area components.

Axis types

Axes can handle different data types:

Category axis

Treats data as distinct values with equal spacing:

<XAxis dataKey="month" type="category" />

Use for: text labels, discrete categories, ordered lists.

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:51-62

Number axis

Treats data as continuous numeric range:

<YAxis type="number" />

Use for: numeric values, measurements, quantities.

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:62-74

Auto type

Infers the type based on chart layout:

<XAxis type="auto" />  {/* category for horizontal layout */}
<YAxis type="auto" />  {/* number for horizontal layout */}

This is the default behavior.

Axis domains

Control the range of values displayed on an axis.

Auto domain

Let Recharts calculate the domain from your data:

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

Fixed domain

Set explicit min and max values:

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

Data-based domain

Use data min/max values:

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

{/* Start from 0, max from data */}
<YAxis domain={[0, 'dataMax']} />

Domain with padding

Add padding to data min/max:

{/* Add 20% padding to both ends */}
<YAxis domain={['dataMin - 100', 'dataMax + 100']} />

{/* Percentage-based padding */}
<YAxis domain={['dataMin * 0.9', 'dataMax * 1.1']} />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:76-108

Function-based domain

Calculate domain dynamically:

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

{/* Symmetric domain around zero */}
<YAxis
  domain={([dataMin, dataMax]) => {
    const absMax = Math.max(Math.abs(dataMin), Math.abs(dataMax));
    return [-absMax, absMax];
  }}
/>

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:105-107

Allow data overflow

Prevent clipping when data exceeds domain:

<YAxis domain={[0, 100]} allowDataOverflow={true} />

Axis ticks

Custom tick count

Suggest the number of ticks:

<YAxis tickCount={5} />

This is a suggestion—Recharts may adjust it for nice round numbers.

Custom tick values

Specify exact tick positions:

<YAxis ticks={[0, 25, 50, 75, 100]} />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:148-153

Tick formatting

Customize tick labels:

<YAxis
  tickFormatter={(value) => `$${value.toLocaleString()}`}
/>

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

Nice ticks algorithm

Control how Recharts calculates “nice” tick values:

{/* Auto (default) - Uses d3's nice algorithm */}
<YAxis niceTicks="auto" />

{/* None - Use raw calculated ticks */}
<YAxis niceTicks="none" />

{/* Adaptive - Smart algorithm for better spacing */}
<YAxis niceTicks="adaptive" />

{/* Snap to 1-2-5 pattern */}
<YAxis niceTicks="snap125" />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:205-214

Tick interval

Control which ticks are shown:

{/* Show all ticks */}
<XAxis interval={0} />

{/* Show every other tick */}
<XAxis interval={1} />

{/* Preserve end ticks (default) */}
<XAxis interval="preserveEnd" />

{/* Preserve start ticks */}
<XAxis interval="preserveStart" />

{/* Preserve both */}
<XAxis interval="preserveStartEnd" />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:167-170

Min tick gap

Minimum spacing between tick labels:

<XAxis minTickGap={5} />  {/* Default */}
<XAxis minTickGap={20} /> {/* More space between ticks */}

Use this to prevent overlapping labels.

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:160-165

Axis styling

Axis size

Control axis dimensions:

{/* Fixed height for XAxis */}
<XAxis height={30} />  {/* Default */}
<XAxis height={60} />  {/* Taller for rotated labels */}

{/* Fixed or auto width for YAxis */}
<YAxis width={60} />   {/* Default */}
<YAxis width="auto" /> {/* Adjust to content */}

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:72-76, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:150-156

Axis line

Customize the axis line:

{/* Hide axis line */}
<XAxis axisLine={false} />

{/* Custom axis line style */}
<XAxis axisLine={{ stroke: '#333', strokeWidth: 2 }} />

Tick line

Control tick marks:

{/* Hide tick lines */}
<XAxis tickLine={false} />

{/* Custom tick line style */}
<XAxis tickLine={{ stroke: '#666' }} />

Tick label styling

Style tick text:

<XAxis
  tick={{ fill: '#666', fontSize: 12 }}
  angle={-45}
  textAnchor="end"
/>

Props:

• tick: Tick text properties (or false to hide)
• angle: Rotation angle in degrees
• textAnchor: Text alignment
• fontSize: Font size
• letterSpacing: Letter spacing for width calculation

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:133-146, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:176-204

Tick margin

Space between tick line and label:

<XAxis tickMargin={5} />  {/* Default */}
<XAxis tickMargin={15} /> {/* More space */}

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:186-189

Advanced axis features

Multiple axes

Use multiple axes for different data scales:

const data = [
  { month: 'Jan', sales: 4000, growth: 24 },
  { month: 'Feb', sales: 3000, growth: 18 },
];

<LineChart width={600} height={300} data={data}>
  <XAxis dataKey="month" />
  <YAxis yAxisId="left" />
  <YAxis yAxisId="right" orientation="right" />
  
  <Line yAxisId="left" dataKey="sales" stroke="#8884d8" />
  <Line yAxisId="right" dataKey="growth" stroke="#82ca9d" />
</LineChart>

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:64-71, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:120-126

Axis orientation

Flip axis position:

{/* XAxis on bottom (default) or top */}
<XAxis orientation="bottom" />
<XAxis orientation="top" />

{/* YAxis on left (default) or right */}
<YAxis orientation="left" />
<YAxis orientation="right" />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:83-86, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:162-166

Reversed axis

Reverse the direction:

<XAxis reversed={true} />
<YAxis reversed={true} />

Mirror axis

Flip labels to inside the chart:

<XAxis mirror={true} />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:78-81

Axis padding

Add padding at axis edges:

<XAxis padding={{ left: 20, right: 20 }} />
<YAxis padding={{ top: 20, bottom: 20 }} />

Default is { left: 0, right: 0 } for XAxis and { top: 0, bottom: 0 } for YAxis.

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:155-159, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:167-172

Scale type

Use different scale functions:

{/* Linear scale (default) */}
<YAxis scale="auto" />

{/* Logarithmic scale */}
<YAxis scale="log" />

{/* Custom D3 scale */}
import { scaleLog } from 'd3-scale';
const customScale = scaleLog().base(Math.E);
<YAxis scale={customScale} />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/XAxis.tsx:111-131, https://github.com/recharts/recharts/blob/main/src/cartesian/YAxis.tsx:99-119

Hide axis

Hide the entire axis:

<XAxis hide={true} />

CartesianGrid

Add background grid lines to your chart.

Basic grid

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

<LineChart width={600} height={300} data={data}>
  <CartesianGrid strokeDasharray="3 3" />
  <XAxis dataKey="month" />
  <YAxis />
  <Line dataKey="value" stroke="#8884d8" />
</LineChart>

Grid customization

{/* Solid grid lines */}
<CartesianGrid stroke="#ccc" />

{/* Dashed grid lines */}
<CartesianGrid strokeDasharray="3 3" />
<CartesianGrid strokeDasharray="5 5 1 5" />
<CartesianGrid strokeDasharray={[5, 5, 1, 5]} />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:181-188

Grid visibility

Control which grid lines show:

{/* Show both (default) */}
<CartesianGrid horizontal={true} vertical={true} />

{/* Only horizontal lines */}
<CartesianGrid vertical={false} />

{/* Only vertical lines */}
<CartesianGrid horizontal={false} />

{/* Custom grid line component */}
<CartesianGrid
  horizontal={{ stroke: 'red', strokeWidth: 2 }}
  vertical={{ stroke: 'blue', strokeWidth: 1 }}
/>

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:92-103

Grid fill

Add background colors:

{/* Solid background */}
<CartesianGrid fill="#f5f5f5" fillOpacity={0.5} />

{/* Alternating stripes */}
<CartesianGrid
  horizontalFill={['#f5f5f5', '#ffffff']}
  fillOpacity={0.6}
/>

<CartesianGrid
  verticalFill={['#f0f0f0', '#ffffff']}
  fillOpacity={0.4}
/>

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:119-161

Custom grid points

Specify exact grid line positions:

<CartesianGrid
  horizontalPoints={[50, 100, 150, 200]}
  verticalPoints={[100, 200, 300]}
/>

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:105-117

Sync with ticks

Align grid lines with axis ticks:

<CartesianGrid syncWithTicks={true} />

Default is false.

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:163-169

Multiple axes

Specify which axis the grid follows:

<CartesianGrid xAxisId={0} yAxisId="left" />

Source: https://github.com/recharts/recharts/blob/main/src/cartesian/CartesianGrid.tsx:190-198

Best practices

Choose appropriate domains

For percentage data, use domain={[0, 100]}. For data that can be negative, use domain={['auto', 'auto']} or calculate a symmetric domain.

Overlapping tick labels

If labels overlap, try:

• Increasing minTickGap
• Rotating labels with angle={-45}
• Using tickFormatter to shorten labels
• Increasing axis height or width

YAxis auto width

Set width="auto" on YAxis to automatically adjust based on the widest tick label. This is useful for dynamic data ranges.