0
# @visx/axis
1
2
@visx/axis provides React components for creating data visualization axes with full D3 scale integration. It offers pre-built axis components for all four orientations (left, right, top, bottom) and a flexible base component for custom configurations, enabling the creation of professional charts with properly positioned ticks, labels, and axis lines.
3
4
## Package Information
5
6
- **Package Name**: @visx/axis
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @visx/axis`
10
11
## Core Imports
12
13
```typescript
14
import {
15
Axis,
16
AxisLeft,
17
AxisRight,
18
AxisTop,
19
AxisBottom,
20
Orientation,
21
SharedAxisProps,
22
AxisProps,
23
AxisRightProps,
24
AxisTopProps,
25
leftTickLabelProps,
26
rightTickLabelProps,
27
topTickLabelProps,
28
bottomTickLabelProps
29
} from "@visx/axis";
30
```
31
32
For CommonJS:
33
34
```javascript
35
const { Axis, AxisLeft, AxisRight, AxisTop, AxisBottom, Orientation } = require("@visx/axis");
36
```
37
38
## Basic Usage
39
40
```typescript
41
import React from 'react';
42
import { scaleLinear } from '@visx/scale';
43
import { AxisLeft, AxisBottom } from '@visx/axis';
44
45
// Create scales
46
const xScale = scaleLinear({
47
range: [0, 400],
48
domain: [0, 100],
49
});
50
51
const yScale = scaleLinear({
52
range: [300, 0],
53
domain: [0, 50],
54
});
55
56
function Chart() {
57
return (
58
<svg width={500} height={400}>
59
<AxisLeft
60
scale={yScale}
61
left={40}
62
label="Y Values"
63
stroke="#1b1a1e"
64
tickStroke="#1b1a1e"
65
tickLabelProps={{
66
fill: '#1b1a1e',
67
fontSize: 11,
68
textAnchor: 'end',
69
}}
70
/>
71
<AxisBottom
72
scale={xScale}
73
top={300}
74
left={40}
75
label="X Values"
76
stroke="#1b1a1e"
77
tickStroke="#1b1a1e"
78
tickLabelProps={{
79
fill: '#1b1a1e',
80
fontSize: 11,
81
textAnchor: 'middle',
82
}}
83
/>
84
</svg>
85
);
86
}
87
```
88
89
## Architecture
90
91
@visx/axis is built around several key components:
92
93
- **Base Axis Component**: The flexible `Axis` component that can be oriented in any direction
94
- **Oriented Components**: Pre-configured components (`AxisLeft`, `AxisRight`, `AxisTop`, `AxisBottom`) with orientation-specific defaults
95
- **Scale Integration**: Full compatibility with D3 and @visx/scale functions
96
- **Tick System**: Automatic tick positioning, formatting, and rendering with customization options
97
- **Type Safety**: Complete TypeScript definitions for all components and props
98
99
## Capabilities
100
101
### Pre-built Axis Components
102
103
Ready-to-use axis components with orientation-specific styling and positioning. Perfect for standard chart layouts without configuration overhead.
104
105
```typescript { .api }
106
function AxisLeft<Scale extends AxisScale>(props: SharedAxisProps<Scale>): JSX.Element;
107
function AxisRight<Scale extends AxisScale>(props: SharedAxisProps<Scale>): JSX.Element;
108
function AxisTop<Scale extends AxisScale>(props: SharedAxisProps<Scale>): JSX.Element;
109
function AxisBottom<Scale extends AxisScale>(props: SharedAxisProps<Scale>): JSX.Element;
110
```
111
112
[Pre-built Axis Components](./prebuilt-axes.md)
113
114
### Base Axis Component
115
116
Flexible axis component with full customization control. Ideal for custom orientations, complex styling, or when you need complete control over axis behavior.
117
118
```typescript { .api }
119
function Axis<Scale extends AxisScale>(props: AxisProps<Scale>): JSX.Element;
120
121
interface AxisProps<Scale extends AxisScale> extends SharedAxisProps<Scale> {
122
orientation?: OrientationType;
123
}
124
```
125
126
[Base Axis Component](./base-axis.md)
127
128
### Orientation Constants
129
130
Orientation constants for axis positioning and validation.
131
132
```typescript { .api }
133
const Orientation: {
134
readonly top: "top";
135
readonly left: "left";
136
readonly right: "right";
137
readonly bottom: "bottom";
138
};
139
140
type OrientationType = "top" | "left" | "right" | "bottom";
141
```
142
143
### Default Styling Constants
144
145
Exported default styling objects for each axis orientation:
146
147
```typescript { .api }
148
const leftTickLabelProps: {
149
readonly dx: "-0.25em";
150
readonly dy: "0.25em";
151
readonly fill: "#222";
152
readonly fontFamily: "Arial";
153
readonly fontSize: 10;
154
readonly textAnchor: "end";
155
};
156
157
const rightTickLabelProps: {
158
readonly dx: "0.25em";
159
readonly dy: "0.25em";
160
readonly fill: "#222";
161
readonly fontFamily: "Arial";
162
readonly fontSize: 10;
163
readonly textAnchor: "start";
164
};
165
166
const topTickLabelProps: {
167
readonly dy: "-0.75em";
168
readonly fill: "#222";
169
readonly fontFamily: "Arial";
170
readonly fontSize: 10;
171
readonly textAnchor: "middle";
172
};
173
174
const bottomTickLabelProps: {
175
readonly dy: "0.25em";
176
readonly fill: "#222";
177
readonly fontFamily: "Arial";
178
readonly fontSize: 10;
179
readonly textAnchor: "middle";
180
};
181
```
182
183
## Core Types
184
185
External types referenced in the API come from:
186
- `TextProps`: From `@visx/text` - properties for text rendering
187
- `ReactNode`, `Ref`, `SVGProps`: From React - standard React types
188
- `D3Scale`, `ScaleInput`, `NumberLike`: From `@visx/scale` - scale-related types
189
190
```typescript { .api }
191
type AxisScale<Output extends AxisScaleOutput = AxisScaleOutput> = D3Scale<Output, any, any>;
192
type AxisScaleOutput = number | NumberLike | undefined;
193
194
interface SharedAxisProps<Scale extends AxisScale> {
195
// Position
196
left?: number;
197
top?: number;
198
199
// Scale (required)
200
scale: Scale;
201
202
// Ticks
203
numTicks?: number;
204
tickValues?: ScaleInput<Scale>[];
205
tickFormat?: TickFormatter<ScaleInput<Scale>>;
206
tickLength?: number;
207
hideTicks?: boolean;
208
hideZero?: boolean;
209
210
// Axis line
211
hideAxisLine?: boolean;
212
axisLineClassName?: string;
213
stroke?: string;
214
strokeWidth?: number | string;
215
strokeDasharray?: string;
216
217
// Labels
218
label?: string;
219
labelOffset?: number;
220
labelProps?: Partial<TextProps>;
221
labelClassName?: string;
222
223
// Styling
224
axisClassName?: string;
225
tickClassName?: string;
226
tickStroke?: string;
227
tickLabelProps?: TickLabelProps<ScaleInput<Scale>>;
228
tickLineProps?: Omit<SVGProps<SVGLineElement>, 'to' | 'from' | 'ref'>;
229
230
// Advanced
231
rangePadding?: number | { start?: number; end?: number };
232
tickTransform?: string;
233
tickComponent?: (tickRendererProps: TickRendererProps) => ReactNode;
234
ticksComponent?: (tickRendererProps: TicksRendererProps<Scale>) => ReactNode;
235
innerRef?: Ref<SVGGElement>;
236
children?: (renderProps: AxisRendererProps<Scale>) => ReactNode;
237
}
238
239
type TickFormatter<T> = (
240
value: T,
241
index: number,
242
values: { value: T; index: number }[]
243
) => string | undefined;
244
245
type TickLabelProps<T> =
246
| Partial<TextProps>
247
| ((value: T, index: number, values: { value: T; index: number }[]) => Partial<TextProps>);
248
249
interface TickRendererProps extends Partial<TextProps> {
250
x: number;
251
y: number;
252
formattedValue: string | undefined;
253
}
254
255
interface TicksRendererProps<Scale extends AxisScale> {
256
tickLabelProps: Partial<TextProps>[];
257
hideTicks?: boolean;
258
horizontal: boolean;
259
orientation: OrientationType;
260
scale: Scale;
261
tickClassName?: string;
262
tickComponent?: (tickRendererProps: TickRendererProps) => ReactNode;
263
tickStroke?: string;
264
tickTransform?: string;
265
ticks: ComputedTick<Scale>[];
266
strokeWidth?: number | string;
267
tickLineProps?: Omit<SVGProps<SVGLineElement>, 'to' | 'from' | 'ref'>;
268
}
269
270
interface AxisRendererProps<Scale extends AxisScale> extends SharedAxisProps<Scale> {
271
axisFromPoint: { x: number; y: number };
272
axisToPoint: { x: number; y: number };
273
horizontal: boolean;
274
scale: Scale;
275
tickPosition: (value: ScaleInput<Scale>) => AxisScaleOutput;
276
tickSign: 1 | -1;
277
ticks: ComputedTick<Scale>[];
278
}
279
280
interface ComputedTick<Scale extends AxisScale> {
281
value: ScaleInput<Scale>;
282
index: number;
283
from: { x: number; y: number };
284
to: { x: number; y: number };
285
formattedValue: string | undefined;
286
}
287
```