Tooltips and legends

Add interactive tooltips and legends to your charts

Tooltips and legends make your charts interactive and easier to understand. This guide covers configuration and customization.

Tooltip basics

The Tooltip component displays data values when users hover over or click chart elements.

Default tooltip

Add a tooltip with default styling:

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

function ChartWithTooltip() {
  return (
    <LineChart width={600} height={300} data={data}>
      <XAxis dataKey="month" />
      <YAxis />
      <Tooltip />
      <Line dataKey="revenue" stroke="#8884d8" />
    </LineChart>
  );
}

Tooltip trigger modes

Control when tooltips appear using the trigger prop:

{/* Show on hover (default) */}
<Tooltip trigger="hover" />

{/* Show on click and stay active */}
<Tooltip trigger="click" />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:230-235

Shared vs individual tooltips

The shared prop controls whether the tooltip shows data for all series or just one:

{/* Show all series at current axis position (default for line charts) */}
<Tooltip shared={true} />

{/* Show only the hovered data point */}
<Tooltip shared={false} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:216-227

Tooltip customization

Styling the tooltip

Customize appearance using style props:

<Tooltip
  contentStyle={{
    backgroundColor: '#f5f5f5',
    border: '1px solid #ccc',
    borderRadius: 8,
  }}
  itemStyle={{ color: '#8884d8' }}
  labelStyle={{ fontWeight: 'bold', marginBottom: 8 }}
/>

Available style props:

• contentStyle: Styles the tooltip container
• itemStyle: Styles each data item (<li> element)
• labelStyle: Styles the label (<p> element)
• wrapperStyle: Styles the outer wrapper div

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:120-243

Custom separator

Change the separator between name and value:

<Tooltip separator=" = " />
{/* Output: Revenue = 4000 */}

<Tooltip separator=": " />
{/* Output: Revenue: 4000 */}

Default is " : ".

Formatting values

Use the formatter prop to customize how values display:

<Tooltip
  formatter={(value, name, item, index, payload) => {
    // Return formatted value
    return `$${value.toLocaleString()}`;
    
    // Or return [value, name] to customize both
    return [`$${value.toLocaleString()}`, name.toUpperCase()];
  }}
/>

Formatter receives:

• value: The data value
• name: The series name
• item: The complete tooltip payload entry
• index: The item index
• payload: All tooltip data

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:139-148

Formatting labels

Customize the tooltip label (typically the x-axis value):

<Tooltip
  labelFormatter={(label, payload) => {
    return `Month: ${label}`;
  }}
/>

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:174-177

Custom tooltip content

Create a completely custom tooltip:

const CustomTooltip = ({ active, payload, label }) => {
  if (!active || !payload || !payload.length) {
    return null;
  }

  return (
    <div style={{
      backgroundColor: 'white',
      padding: '12px',
      border: '2px solid #8884d8',
      borderRadius: '8px',
    }}>
      <p style={{ fontWeight: 'bold', marginBottom: '8px' }}>
        {label}
      </p>
      {payload.map((entry, index) => (
        <div key={index} style={{ color: entry.color }}>
          {entry.name}: ${entry.value.toLocaleString()}
        </div>
      ))}
    </div>
  );
};

<Tooltip content={<CustomTooltip />} />

Custom content receives:

• active: Whether tooltip is active
• payload: Array of data for all visible series
• label: The axis label
• coordinate: Mouse position
• accessibilityLayer: Accessibility settings

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:108-119

Tooltip positioning

Offset

Control distance from cursor:

{/* Single number for both axes */}
<Tooltip offset={20} />

{/* Different offsets for x and y */}
<Tooltip offset={{ x: 10, y: 20 }} />

Default is 10.

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:184-190

Fixed position

Lock tooltip to a specific position:

<Tooltip position={{ x: 100, y: 50 }} />

You can also set just one coordinate:

{/* Fix x, let y follow cursor */}
<Tooltip position={{ x: 100 }} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:200-206

Allow escape viewbox

Let tooltip extend beyond chart boundaries:

<Tooltip
  allowEscapeViewBox={{ x: true, y: true }}
/>

Default is { x: false, y: false }.

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:80-85

Advanced tooltip features

Filter null values

Hide entries with null values:

<Tooltip filterNull={true} />  {/* Default */}

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:134-137

Include hidden series

Show data from hidden series:

<Tooltip includeHidden={true} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:150-156

Portal rendering

Render tooltip outside the chart container to avoid clipping:

const tooltipPortal = document.getElementById('tooltip-container');

<Tooltip portal={tooltipPortal} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:192-198

Cursor customization

Customize or disable the cursor shown on hover:

{/* Disable cursor */}
<Tooltip cursor={false} />

{/* Custom cursor style */}
<Tooltip cursor={{ stroke: 'red', strokeWidth: 2 }} />

{/* Custom cursor component */}
<Tooltip cursor={<CustomCursor />} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Tooltip.tsx:126-131

Legend basics

The Legend component shows labels for each data series.

Default legend

import { LineChart, Line, Legend } from 'recharts';

<LineChart width={600} height={300} data={data}>
  <Line dataKey="revenue" stroke="#8884d8" name="Revenue" />
  <Line dataKey="profit" stroke="#82ca9d" name="Profit" />
  <Legend />
</LineChart>

Legend alignment

Control vertical and horizontal positioning:

{/* Position below chart (default) */}
<Legend verticalAlign="bottom" align="center" />

{/* Position at top right */}
<Legend verticalAlign="top" align="right" />

{/* Position in middle left */}
<Legend verticalAlign="middle" align="left" />

Options:

• verticalAlign: "top", "middle", "bottom"
• align: "left", "center", "right"

Source: https://github.com/recharts/recharts/blob/main/src/component/Legend.tsx:147-156

Legend layout

Control how legend items are arranged:

{/* Horizontal layout (default) */}
<Legend layout="horizontal" />

{/* Vertical layout */}
<Legend layout="vertical" />

Source: https://github.com/recharts/recharts/blob/main/src/component/DefaultLegendContent.tsx

Legend customization

Styling

Customize legend appearance:

<Legend
  wrapperStyle={{
    paddingTop: '20px',
    borderTop: '1px solid #ccc',
  }}
  iconSize={18}
/>

Source: https://github.com/recharts/recharts/blob/main/src/component/Legend.tsx:111-114

Custom content

Create a custom legend:

const CustomLegend = ({ payload }) => {
  return (
    <ul style={{ listStyle: 'none', display: 'flex', gap: '20px' }}>
      {payload.map((entry, index) => (
        <li key={index} style={{ color: entry.color }}>
          <span style={{
            display: 'inline-block',
            width: '12px',
            height: '12px',
            backgroundColor: entry.color,
            marginRight: '8px',
          }} />
          {entry.value}
        </li>
      ))}
    </ul>
  );
};

<Legend content={<CustomLegend />} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Legend.tsx:98-110

Sorting legend items

Control the order of legend items:

{/* Sort alphabetically by value (default) */}
<Legend itemSorter="value" />

{/* Sort by dataKey */}
<Legend itemSorter="dataKey" />

{/* Custom sort function */}
<Legend itemSorter={(item) => -item.value} />

{/* No sorting */}
<Legend itemSorter={null} />

Source: https://github.com/recharts/recharts/blob/main/src/component/Legend.tsx:136-145

Best practices

Name your data series

Always provide a name prop for better tooltips and legends:

<Line dataKey="revenue" name="Monthly Revenue" stroke="#8884d8" />

Tooltip animations

By default, tooltips respect the user’s prefers-reduced-motion setting. Set isAnimationActive={false} to disable animations completely.

Portal rendering limitations

When using a custom portal, tooltip positioning is calculated relative to the portal element, not the chart.