0
# Hooks and Utilities
1

2
React hooks for accessing chart state and utility functions for custom chart development. These tools provide access to chart layout information, tooltip data, and helper functions for advanced chart customization.
3

4
## Capabilities
5

6
### Chart State Hooks
7

8
#### useActiveTooltipLabel
9

10
Hook for accessing the currently active tooltip label from chart data.
11

12
```typescript { .api }
13
/**
14
 * Returns the active tooltip label from chart interactions
15
 * @returns Currently active tooltip label or undefined if no interaction
16
 */
17
function useActiveTooltipLabel(): string | undefined;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { useActiveTooltipLabel } from 'recharts';
24

25
function CustomTooltipComponent() {
26
  const activeLabel = useActiveTooltipLabel();
27
  
28
  return (
29
    <div>
30
      {activeLabel && <p>Current Label: {activeLabel}</p>}
31
    </div>
32
  );
33
}
34
```
35

36
#### useActiveTooltipDataPoints
37

38
Hook for accessing the currently active data points being displayed in the tooltip.
39

40
```typescript { .api }
41
/**
42
 * Returns the currently active data points visible in tooltip
43
 * @returns Array of data points currently visible in tooltip, or undefined if no interaction
44
 */
45
function useActiveTooltipDataPoints<T = unknown>(): ReadonlyArray<T> | undefined;
46
```
47

48
**Usage Example:**
49

50
```typescript
51
import { useActiveTooltipDataPoints } from 'recharts';
52

53
function CustomTooltipComponent() {
54
  const dataPoints = useActiveTooltipDataPoints();
55
  
56
  return (
57
    <div>
58
      {dataPoints?.map((point, index) => (
59
        <div key={index}>Value: {point.value}</div>
60
      ))}
61
    </div>
62
  );
63
}
64
```
65

66
### Layout Information Hooks
67

68
#### useOffset
69

70
Hook for accessing chart offset information (distances between chart edges and plot area).
71

72
```typescript { .api }
73
/**
74
 * Returns chart offset defining blank space between chart and plot area
75
 * @returns Chart offset in pixels, or undefined if used outside chart context
76
 */
77
function useOffset(): ChartOffset | undefined;
78
```
79

80
**Usage Example:**
81

82
```typescript
83
import { useOffset } from 'recharts';
84

85
function CustomChartComponent() {
86
  const offset = useOffset();
87
  
88
  if (offset) {
89
    console.log(`Chart margins: top=${offset.top}, right=${offset.right}, bottom=${offset.bottom}, left=${offset.left}`);
90
  }
91
  
92
  return <div>Custom component with offset info</div>;
93
}
94
```
95

96
#### usePlotArea
97

98
Hook for accessing plot area dimensions and position where actual chart data is rendered.
99

100
```typescript { .api }
101
/**
102
 * Returns plot area dimensions and position for data rendering area
103
 * @returns Plot area coordinates and dimensions, or undefined if used outside chart context
104
 */
105
function usePlotArea(): PlotArea | undefined;
106
```
107

108
**Usage Example:**
109

110
```typescript
111
import { usePlotArea } from 'recharts';
112

113
function CustomOverlay() {
114
  const plotArea = usePlotArea();
115
  
116
  if (!plotArea) return null;
117
  
118
  return (
119
    <rect
120
      x={plotArea.x}
121
      y={plotArea.y}
122
      width={plotArea.width}
123
      height={plotArea.height}
124
      fill="transparent"
125
      stroke="#ddd"
126
      strokeDasharray="5,5"
127
    />
128
  );
129
}
130
```
131

132
#### useChartWidth
133

134
Hook for accessing the current chart width in pixels.
135

136
```typescript { .api }
137
/**
138
 * Returns the width of the chart container in pixels
139
 * @returns Chart width in pixels, or undefined if used outside chart context
140
 */
141
function useChartWidth(): number | undefined;
142
```
143

144
#### useChartHeight
145

146
Hook for accessing the current chart height in pixels.
147

148
```typescript { .api }
149
/**
150
 * Returns the height of the chart container in pixels
151
 * @returns Chart height in pixels, or undefined if used outside chart context
152
 */
153
function useChartHeight(): number | undefined;
154
```
155

156
**Usage Example:**
157

158
```typescript
159
import { useChartWidth, useChartHeight } from 'recharts';
160

161
function ResponsiveCustomComponent() {
162
  const width = useChartWidth();
163
  const height = useChartHeight();
164
  
165
  return (
166
    <text x={width ? width / 2 : 0} y={height ? height / 2 : 0} textAnchor="middle">
167
      Chart Size: {width} × {height}
168
    </text>
169
  );
170
}
171
```
172

173
## Utility Functions
174

175
### getNiceTickValues
176

177
Utility function for calculating aesthetically pleasing tick values for chart axes.
178

179
```typescript { .api }
180
/**
181
 * Calculates nice tick values for axis scales
182
 * @param domain - Data domain [min, max]
183
 * @param tickCount - Desired number of ticks
184
 * @param allowDecimals - Whether to allow decimal tick values
185
 * @returns Array of nice tick values
186
 */
187
function getNiceTickValues(
188
  domain: [number, number], 
189
  tickCount?: number, 
190
  allowDecimals?: boolean
191
): number[];
192
```
193

194
**Usage Example:**
195

196
```typescript
197
import { getNiceTickValues } from 'recharts';
198

199
// Calculate nice tick values for a domain
200
const domain: [number, number] = [0, 847];
201
const ticks = getNiceTickValues(domain, 5, true);
202
// Result might be: [0, 200, 400, 600, 800, 1000]
203

204
// Use in custom axis
205
<YAxis 
206
  domain={domain}
207
  ticks={ticks}
208
  tickCount={ticks.length}
209
/>
210
```
211

212
### Global Configuration
213

214
Global configuration object for library-wide settings.
215

216
```typescript { .api }
217
/**
218
 * Global configuration object with library settings
219
 */
220
interface Global {
221
  /** Server-side rendering detection flag */
222
  isSsr: boolean;
223
}
224

225
const Global: Global;
226
```
227

228
**Usage Example:**
229

230
```typescript
231
import { Global } from 'recharts';
232

233
// Check if running in server-side rendering environment
234
if (Global.isSsr) {
235
  console.log('Running in SSR environment');
236
}
237
```
238

239
## Hook Types and Interfaces
240

241
### ChartOffset
242

243
Interface defining the offset/margin space around the chart plot area.
244

245
```typescript { .api }
246
/**
247
 * Defines the blank space between the chart container and plot area
248
 */
249
interface ChartOffset {
250
  /** Distance from top edge of chart to top edge of plot area */
251
  readonly top: number;
252
  /** Distance from bottom edge of chart to bottom edge of plot area */
253
  readonly bottom: number;
254
  /** Distance from left edge of chart to left edge of plot area */
255
  readonly left: number;
256
  /** Distance from right edge of chart to right edge of plot area */
257
  readonly right: number;
258
}
259
```
260

261
### PlotArea
262

263
Interface defining the plot area where actual chart data is rendered.
264

265
```typescript { .api }
266
/**
267
 * Defines the area where actual chart data is rendered
268
 */
269
interface PlotArea {
270
  /** Width of the plot area */
271
  readonly width: number;
272
  /** Height of the plot area */
273
  readonly height: number;
274
  /** X coordinate of the top-left corner of plot area */
275
  readonly x: number;
276
  /** Y coordinate of the top-left corner of plot area */
277
  readonly y: number;
278
}
279
```
280

281
## Advanced Hook Usage Patterns
282

283
### Custom Tooltip with Hooks
284

285
```typescript
286
import { 
287
  useActiveTooltipLabel, 
288
  useActiveTooltipDataPoints, 
289
  usePlotArea 
290
} from 'recharts';
291

292
function AdvancedCustomTooltip() {
293
  const label = useActiveTooltipLabel();
294
  const dataPoints = useActiveTooltipDataPoints();
295
  const plotArea = usePlotArea();
296
  
297
  if (!label || !dataPoints || dataPoints.length === 0) {
298
    return null;
299
  }
300
  
301
  return (
302
    <div className="custom-tooltip" style={{
303
      position: 'absolute',
304
      background: 'white',
305
      border: '1px solid #ccc',
306
      padding: '10px',
307
      borderRadius: '4px'
308
    }}>
309
      <h4>{label}</h4>
310
      {dataPoints.map((point, index) => (
311
        <div key={index}>
312
          <span style={{ color: point.color }}>●</span>
313
          {point.name}: {point.value}
314
        </div>
315
      ))}
316
    </div>
317
  );
318
}
319
```
320

321
### Custom Chart Overlay with Layout Info
322

323
```typescript
324
import { useOffset, usePlotArea, useChartWidth, useChartHeight } from 'recharts';
325

326
function ChartOverlay() {
327
  const offset = useOffset();
328
  const plotArea = usePlotArea();
329
  const chartWidth = useChartWidth();
330
  const chartHeight = useChartHeight();
331
  
332
  if (!offset || !plotArea || !chartWidth || !chartHeight) {
333
    return null;
334
  }
335
  
336
  return (
337
    <g>
338
      {/* Plot area border */}
339
      <rect
340
        x={plotArea.x}
341
        y={plotArea.y}
342
        width={plotArea.width}
343
        height={plotArea.height}
344
        fill="none"
345
        stroke="#e0e0e0"
346
        strokeDasharray="2,2"
347
      />
348
      
349
      {/* Chart info text */}
350
      <text x={10} y={20} fontSize="12" fill="#666">
351
        Chart: {chartWidth}×{chartHeight} | Plot: {plotArea.width}×{plotArea.height}
352
      </text>
353
    </g>
354
  );
355
}
356
```
357

358
### Using Hooks in Custom Shapes
359

360
```typescript
361
import { usePlotArea } from 'recharts';
362

363
function CustomBackground() {
364
  const plotArea = usePlotArea();
365
  
366
  if (!plotArea) return null;
367
  
368
  // Create gradient background for plot area
369
  return (
370
    <defs>
371
      <linearGradient id="plotGradient" x1="0%" y1="0%" x2="0%" y2="100%">
372
        <stop offset="0%" stopColor="#f8f9fa" />
373
        <stop offset="100%" stopColor="#ffffff" />
374
      </linearGradient>
375
      <rect
376
        x={plotArea.x}
377
        y={plotArea.y}
378
        width={plotArea.width}
379
        height={plotArea.height}
380
        fill="url(#plotGradient)"
381
      />
382
    </defs>
383
  );
384
}
385
```
386

387
## Context Requirements
388

389
**Important**: All hooks must be used within a chart context (inside a chart component like LineChart, BarChart, etc.). Using these hooks outside of a chart context will return `undefined`.
390

391
```typescript
392
// ✅ Correct usage - inside chart
393
<LineChart data={data}>
394
  <CustomComponentUsingHooks />
395
</LineChart>
396

397
// ❌ Incorrect usage - outside chart context  
398
<div>
399
  <CustomComponentUsingHooks /> {/* Hooks will return undefined */}
400
</div>
401
```