Coordinate Systems in Recharts

When working with Recharts, you'll encounter three different coordinate systems. Understanding when to use each one is essential for creating custom annotations, shapes, and interactive features.

Different Rechart components accept, or provide, coordinate from different systems.

Overview

1. Domain Coordinates

Domain coordinates are the most intuitive—they use values from your actual data. When you specify x="March" on a ReferenceLine, Recharts automatically converts that to the correct pixel position based on your XAxis and YAxis scale.

You can also optionally pass position prop. This is important for Bar charts, where the axis scale typically has bandwidth: meaning that a single data point spans multiple pixels. The position prop controls where within that bandwidth the element is placed (e.g., start, middle, end).

Other charts, like Line charts, have no bandwidth (each data point maps to a single pixel). In those cases, the position prop is ignored.

Components that use domain coordinates:

• ReferenceLine - horizontal or vertical lines at data values
• ReferenceDot - circles at specific data points
• ReferenceArea - rectangles spanning data ranges

Advantages:

• Automatically adjusts when chart size changes
• Responds to axis domain changes (zoom, brush filtering)
• Works with both categorical and numerical axes

2. Pixel/Chart-Range Coordinates

Pixel coordinates are positions measured in pixels from the top-left corner of the chart. Use the useOffset() hook to get the plot area dimensions, then position elements relative to that area.

Key hooks:

• useMargin - returns empty space around the chart
• useOffset - returns space taken by margin, and axes, and Brush and Legend
• usePlotArea - plot area is the drawable area inside margins and offsets
• useChartWidth + useChartHeight - returns the full chart dimensions

When to use:

• Annotations that should stay at fixed positions regardless of data
• Decorative elements like watermarks or logos
• Custom legend, tooltip, or label positioning

3. Mouse Event Coordinates

Mouse events from the browser provide coordinates in the browser's viewport. The getRelativeCoordinate function converts these to chart-relative coordinates, accounting for:

• Chart position on the page
• Scroll offset
• CSS transforms (scale, rotate)
• Browser zoom in or zoom out

Key function:

• getRelativeCoordinate - converts mouse event to {relativeX, relativeY} coordinates.

This function works with both HTML elements (like <div>) and SVG elements. The returned coordinates are relative to the top-left corner of the element that received the event.

Converting Between Coordinate Systems

Often you need to convert between coordinate systems. For example, you might want to position a custom marker at a specific data point, or determine which data point the user clicked on.

Data → Pixels:

• useXAxisScale - returns a function to convert X data values to pixel positions
• useYAxisScale - returns a function to convert Y data values to pixel positions
• useCartesianScale - convenience hook for converting both at once

Pixels → Data:

• useXAxisInverseScale - returns a function to convert pixel X to the closest data value
• useYAxisInverseScale - returns a function to convert pixel Y to the closest data value
• useXAxisInverseTickSnapScale - returns a function to convert pixel X to the closest axis tick
• useYAxisInverseTickSnapScale - returns a function to convert pixel Y to the closest axis tick

Accessing Ticks:

• useXAxisTicks - returns the calculated ticks of an X-axis
• useYAxisTicks - returns the calculated ticks of a Y-axis

Choosing the Right Coordinate System