Z-Index utilities

Recharts provides a z-index system for controlling the layering of chart elements. Since SVG doesn’t support CSS z-index, Recharts uses portals to render elements in the correct order.

ZIndexLayer

A component that renders its children into a portal corresponding to the given z-index.

import { ZIndexLayer } from 'recharts';

function CustomComponent() {
  return (
    <ZIndexLayer zIndex={1000}>
      <circle cx={100} cy={100} r={50} fill="red" />
    </ZIndexLayer>
  );
}

zIndex · number | undefined

Numeric z-index value. Higher values render on top of lower values. If undefined or 0, content renders in the default layer without portals.

children · ReactNode

The content to render inside this z-index layer.

Since: 3.4

Usage

The ZIndexLayer component must be used inside a chart component:

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

function CustomAnnotation() {
  return (
    <ZIndexLayer zIndex={2000}>
      <text x={100} y={50} fill="red" fontSize={20}>
        High Priority Label
      </text>
    </ZIndexLayer>
  );
}

function Chart() {
  return (
    <LineChart width={600} height={300} data={data}>
      <XAxis dataKey="name" />
      <YAxis />
      <Line dataKey="value" />
      <CustomAnnotation />
    </LineChart>
  );
}

ZIndexable

Interface for components that support the zIndex prop.

interface ZIndexable {
  /**
   * Z-Index of this component and its children.
   * The higher the value, the more on top it will be rendered.
   * If undefined or 0, the content is rendered in the default layer.
   */
  zIndex?: number;
}

Since: 3.4

Components with zIndex support

Many Recharts components accept a zIndex prop:

import { Line, Area, Bar, ReferenceLine } from 'recharts';

<Line dataKey="value" zIndex={400} />
<Area dataKey="area" zIndex={100} />
<Bar dataKey="bar" zIndex={300} />
<ReferenceLine y={100} zIndex={500} />

DefaultZIndexes

A collection of all default z-index values used by Recharts. You can reuse these or define your own.

const DefaultZIndexes = {
  grid: -100,
  barBackground: -50,
  area: 100,
  cursorRectangle: 200,
  bar: 300,
  line: 400,
  axis: 500,
  scatter: 600,
  activeBar: 1000,
  cursorLine: 1100,
  activeDot: 1200,
  label: 2000,
} as const;

Default z-index layers

Background layers (negative z-index)

grid · -100

CartesianGrid and PolarGrid

barBackground · -50

Background of Bar and RadialBar. Not visible by default but can be enabled with background={true}.

Default layer

Elements without a specific zIndex prop render at zIndex: 0 (the default layer).

Chart elements (positive z-index)

area · 100

Area, Pie, Radar, and ReferenceArea

cursorRectangle · 200

Cursor rectangle in bar charts. Renders below bars so it doesn’t hide other bars in stacked charts.

bar · 300

Bar and RadialBar

line · 400

Line, ReferenceLine, and ErrorBar

axis · 500

XAxis, YAxis, PolarAngleAxis, and PolarRadiusAxis (ticks, lines, and children)

scatter · 600

Scatter, ReferenceDot, and dots on Line/Area/Radar when dot={true}

Interactive layers (high z-index)

activeBar · 1000

Highlight rectangle when hovering over a Bar or RadialBar

cursorLine · 1100

Cursor line in Line, Area, Scatter, and Radar charts. Also applies to radial cursor in RadialBarChart.

activeDot · 1200

Highlight dot when hovering over a point in Line, Area, Scatter, or Radar

label · 2000

LabelList and Label components, including axis labels

Example usage

import { DefaultZIndexes, ZIndexLayer } from 'recharts';

function CustomWatermark() {
  // Render below the grid
  return (
    <ZIndexLayer zIndex={DefaultZIndexes.grid - 100}>
      <text x={10} y={20} fill="#ccc" fontSize={40} opacity={0.3}>
        DRAFT
      </text>
    </ZIndexLayer>
  );
}

function CustomHighlight() {
  // Render above everything else
  return (
    <ZIndexLayer zIndex={DefaultZIndexes.label + 100}>
      <circle cx={100} cy={100} r={30} fill="yellow" opacity={0.5} />
    </ZIndexLayer>
  );
}

Z-Index guide

For a comprehensive guide on using z-index in Recharts, see the Z-Index and layers guide.

How it works

1. Portal-based rendering: Since SVG doesn’t support CSS z-index, Recharts creates separate SVG <g> elements for each z-index layer.

2. Dynamic registration: Z-index layers are registered dynamically. When you use a zIndex prop or ZIndexLayer, Recharts creates the corresponding portal automatically.

3. Rendering order: SVG elements are rendered in the order they appear in the DOM. Recharts organizes layers from lowest to highest z-index:

   • Negative z-index layers (e.g., grid at -100)
   • Default layer (z-index 0)
   • Positive z-index layers (e.g., labels at 2000)

4. No performance overhead: If you don’t use z-index features, there’s no performance impact. Portals are only created for the z-index values you actually use.

TypeScript

Full type definitions are available:

import { ZIndexLayer, ZIndexable, DefaultZIndexes } from 'recharts';

// ZIndexLayer component
const layer: JSX.Element = (
  <ZIndexLayer zIndex={100}>
    <circle r={5} />
  </ZIndexLayer>
);

// DefaultZIndexes constants
const gridZIndex: number = DefaultZIndexes.grid; // -100
const labelZIndex: number = DefaultZIndexes.label; // 2000

// ZIndexable interface
interface CustomComponentProps extends ZIndexable {
  data: any[];
}