Scale hooks

Hooks for converting between data values and pixel coordinates.

useXAxisScale

Returns a function to convert data values to pixel coordinates for an X-axis.

Useful for positioning annotations, custom shapes, or other elements at specific data points on the chart.

import { useXAxisScale } from 'recharts';

function CustomAnnotation() {
  const xScale = useXAxisScale();
  
  if (!xScale) return null;
  
  const pixelX = xScale('Page A');
  
  if (pixelX == null) return null;
  
  return (
    <line x1={pixelX} y1={0} x2={pixelX} y2={300} stroke="red" />
  );
}

xAxisId · AxisId · default: "0"

The ID of the X-axis. Defaults to 0 if not provided.

returns · ScaleFunction | undefined

A scale function that maps data values to pixel coordinates, or undefined if used outside a chart context or if the axis doesn’t exist.

Since: 3.8

useYAxisScale

Returns a function to convert data values to pixel coordinates for a Y-axis.

Useful for positioning annotations, custom shapes, or other elements at specific data points on the chart.

import { useYAxisScale } from 'recharts';

function CustomAnnotation() {
  const yScale = useYAxisScale();
  
  if (!yScale) return null;
  
  const pixelY = yScale(1500);
  
  if (pixelY == null) return null;
  
  return (
    <line x1={0} y1={pixelY} x2={600} y2={pixelY} stroke="blue" />
  );
}

yAxisId · AxisId · default: "0"

The ID of the Y-axis. Defaults to 0 if not provided.

returns · ScaleFunction | undefined

A scale function that maps data values to pixel coordinates, or undefined if used outside a chart context or if the axis doesn’t exist.

Since: 3.8

useCartesianScale

Converts a data point (in data coordinates) to pixel coordinates.

This is a convenience hook that combines useXAxisScale and useYAxisScale together in a single call.

import { useCartesianScale } from 'recharts';

function CustomMarker() {
  const pixelCoords = useCartesianScale({ x: 'Page C', y: 2500 });
  
  if (!pixelCoords) return null;
  
  return (
    <g>
      <circle cx={pixelCoords.x} cy={pixelCoords.y} r={5} fill="red" />
      <text x={pixelCoords.x + 10} y={pixelCoords.y}>
        Important point
      </text>
    </g>
  );
}

dataPoint · CartesianDataPoint · required

The data point with x and y values in data coordinates.

xAxisId · AxisId · default: "0"

The ID of the X-axis. Defaults to 0 if not provided.

yAxisId · AxisId · default: "0"

The ID of the Y-axis. Defaults to 0 if not provided.

returns · Coordinate | undefined

Object with pixel x and y coordinates, or undefined if conversion is not possible.

Since: 3.8

Inverse scale hooks

Convert pixel coordinates back to data values.

useXAxisInverseScale

Returns a function to convert pixel coordinates back to data values for an X-axis.

Useful for implementing interactions like click-to-add-annotation, drag interactions, or tooltips that need to determine what data point corresponds to a mouse position.

import { useXAxisInverseScale } from 'recharts';

function CustomComponent() {
  const xInverseScale = useXAxisInverseScale();
  
  const handleClick = (e: React.MouseEvent) => {
    if (!xInverseScale) return;
    
    const dataValue = xInverseScale(e.clientX);
    console.log('Clicked on data value:', dataValue);
  };
  
  return <rect width="100%" height="100%" fill="transparent" onClick={handleClick} />;
}

xAxisId · AxisId · default: "0"

The ID of the X-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to data values, or undefined.

Since: 3.8

Behavior:

• For continuous (numerical) scales: returns an interpolated value
• For categorical scales: returns the closest category in the domain (same as useXAxisInverseDataSnapScale)

useYAxisInverseScale

Returns a function to convert pixel coordinates back to data values for a Y-axis.

import { useYAxisInverseScale } from 'recharts';

function CustomComponent() {
  const yInverseScale = useYAxisInverseScale();
  
  if (!yInverseScale) return null;
  
  const dataValue = yInverseScale(200);
  console.log('Data value at y=200:', dataValue);
  
  return null;
}

yAxisId · AxisId · default: "0"

The ID of the Y-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to data values, or undefined.

Since: 3.8

Snap scale hooks

Snap to the closest data point or tick instead of interpolating.

useXAxisInverseDataSnapScale

Returns a function to convert pixel coordinates back to data values, snapping to the closest data point.

Similar to useXAxisInverseScale, but instead of returning the exact data value at the pixel position (interpolation), it returns the value of the closest data point.

import { useXAxisInverseDataSnapScale } from 'recharts';

function SnapToDataPoint() {
  const xSnapScale = useXAxisInverseDataSnapScale();
  
  const handleClick = (e: React.MouseEvent) => {
    if (!xSnapScale) return;
    
    const closestDataValue = xSnapScale(e.clientX);
    console.log('Closest data point:', closestDataValue);
  };
  
  return <rect width="100%" height="100%" fill="transparent" onClick={handleClick} />;
}

xAxisId · AxisId · default: "0"

The ID of the X-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to the closest data value, or undefined.

Since: 3.8

useYAxisInverseDataSnapScale

Returns a function to convert pixel coordinates back to data values for a Y-axis, snapping to the closest data point.

yAxisId · AxisId · default: "0"

The ID of the Y-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to the closest data value, or undefined.

Since: 3.8

useXAxisInverseTickSnapScale

Returns a function to convert pixel coordinates back to data values, snapping to the closest axis tick.

Similar to useXAxisInverseScale, but instead of returning the exact data value at the pixel position (interpolation), it returns the value of the closest tick.

import { useXAxisInverseTickSnapScale } from 'recharts';

function SnapToTick() {
  const xTickSnapScale = useXAxisInverseTickSnapScale();
  
  const handleClick = (e: React.MouseEvent) => {
    if (!xTickSnapScale) return;
    
    const closestTickValue = xTickSnapScale(e.clientX);
    console.log('Closest tick:', closestTickValue);
  };
  
  return <rect width="100%" height="100%" fill="transparent" onClick={handleClick} />;
}

xAxisId · AxisId · default: "0"

The ID of the X-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to the closest tick value, or undefined.

Since: 3.8

useYAxisInverseTickSnapScale

Returns a function to convert pixel coordinates back to data values for a Y-axis, snapping to the closest axis tick.

yAxisId · AxisId · default: "0"

The ID of the Y-axis. Defaults to 0 if not provided.

returns · InverseScaleFunction | undefined

An inverse scale function that maps pixel coordinates to the closest tick value, or undefined.

Since: 3.8

Types

ScaleFunction

type ScaleFunction = (
  value: unknown, 
  options?: { position?: BandPosition }
) => number | undefined;

A function that converts data values to pixel coordinates.

• value - The data value to convert (number, string, or category)
• options.position - Position within a band: ‘start’, ‘middle’, or ‘end’
• Returns the pixel coordinate, or undefined if the value is not in the domain

InverseScaleFunction

type InverseScaleFunction = (pixelValue: number) => unknown;

A function that converts pixel coordinates back to data values.

• pixelValue - The pixel coordinate to convert
• Returns the closest data value in the domain

CartesianDataPoint

type CartesianDataPoint = {
  x: number | string;
  y: number | string;
};

Data point with x and y values that can be converted to pixel coordinates. The x and y values should be in the same format as your chart data.

Coordinate

interface Coordinate {
  x: number;
  y: number;
}