> ## 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.

# 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.

```tsx theme={null}
import { ZIndexLayer } from 'recharts';

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

<ParamField path="zIndex" type="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.
</ParamField>

<ParamField path="children" type="ReactNode">
  The content to render inside this z-index layer.
</ParamField>

**Since:** 3.4

### Usage

The `ZIndexLayer` component must be used inside a chart component:

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

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

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

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

<ParamField path="grid" type="-100">
  CartesianGrid and PolarGrid
</ParamField>

<ParamField path="barBackground" type="-50">
  Background of Bar and RadialBar. Not visible by default but can be enabled with `background={true}`.
</ParamField>

#### Default layer

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

#### Chart elements (positive z-index)

<ParamField path="area" type="100">
  Area, Pie, Radar, and ReferenceArea
</ParamField>

<ParamField path="cursorRectangle" type="200">
  Cursor rectangle in bar charts. Renders below bars so it doesn't hide other bars in stacked charts.
</ParamField>

<ParamField path="bar" type="300">
  Bar and RadialBar
</ParamField>

<ParamField path="line" type="400">
  Line, ReferenceLine, and ErrorBar
</ParamField>

<ParamField path="axis" type="500">
  XAxis, YAxis, PolarAngleAxis, and PolarRadiusAxis (ticks, lines, and children)
</ParamField>

<ParamField path="scatter" type="600">
  Scatter, ReferenceDot, and dots on Line/Area/Radar when `dot={true}`
</ParamField>

#### Interactive layers (high z-index)

<ParamField path="activeBar" type="1000">
  Highlight rectangle when hovering over a Bar or RadialBar
</ParamField>

<ParamField path="cursorLine" type="1100">
  Cursor line in Line, Area, Scatter, and Radar charts. Also applies to radial cursor in RadialBarChart.
</ParamField>

<ParamField path="activeDot" type="1200">
  Highlight dot when hovering over a point in Line, Area, Scatter, or Radar
</ParamField>

<ParamField path="label" type="2000">
  LabelList and Label components, including axis labels
</ParamField>

### Example usage

```tsx theme={null}
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](https://recharts.github.io/en-US/guide/zIndex/).

## 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:

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