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

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

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

<ParamField path="xAxisId" type="AxisId" default="0">
  The ID of the X-axis. Defaults to `0` if not provided.
</ParamField>

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

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

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

<ParamField path="yAxisId" type="AxisId" default="0">
  The ID of the Y-axis. Defaults to `0` if not provided.
</ParamField>

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

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

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

<ParamField path="dataPoint" type="CartesianDataPoint" required>
  The data point with x and y values in data coordinates.
</ParamField>

<ParamField path="xAxisId" type="AxisId" default="0">
  The ID of the X-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="yAxisId" type="AxisId" default="0">
  The ID of the Y-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="Coordinate | undefined">
  Object with pixel x and y coordinates, or `undefined` if conversion is not possible.
</ParamField>

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

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

<ParamField path="xAxisId" type="AxisId" default="0">
  The ID of the X-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to data values, or `undefined`.
</ParamField>

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

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

<ParamField path="yAxisId" type="AxisId" default="0">
  The ID of the Y-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to data values, or `undefined`.
</ParamField>

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

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

<ParamField path="xAxisId" type="AxisId" default="0">
  The ID of the X-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to the closest data value, or `undefined`.
</ParamField>

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

<ParamField path="yAxisId" type="AxisId" default="0">
  The ID of the Y-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to the closest data value, or `undefined`.
</ParamField>

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

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

<ParamField path="xAxisId" type="AxisId" default="0">
  The ID of the X-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to the closest tick value, or `undefined`.
</ParamField>

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

<ParamField path="yAxisId" type="AxisId" default="0">
  The ID of the Y-axis. Defaults to `0` if not provided.
</ParamField>

<ParamField path="returns" type="InverseScaleFunction | undefined">
  An inverse scale function that maps pixel coordinates to the closest tick value, or `undefined`.
</ParamField>

**Since:** 3.8

## Types

### ScaleFunction

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

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

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

```typescript theme={null}
interface Coordinate {
  x: number;
  y: number;
}
```