Flexible axis system supporting linear, logarithmic, datetime, and category axes with extensive customization for labels, ticks, plot lines, and scaling.
The Axis class manages chart axes including scaling, ticks, labels, and visual elements.
class Axis {
/** Axis options configuration */
options: AxisOptions;
/** Chart that contains this axis */
chart: Chart;
/** Whether this is a horizontal axis */
horiz: boolean;
/** Whether this is the opposite axis */
opposite: boolean;
/** Axis minimum value */
min: number;
/** Axis maximum value */
max: number;
/** Axis data minimum */
dataMin: number;
/** Axis data maximum */
dataMax: number;
/** Array of axis tick positions */
tickPositions: Array<number>;
/** Axis length in pixels */
len: number;
/** Axis translation ratio */
transA: number;
/** Axis translation base */
transB: number;
/** Series associated with this axis */
series: Array<Series>;
/** Axis categories */
categories: Array<string>;
/** Axis names */
names: Array<string>;
}Methods for controlling axis range and extremes.
class Axis {
/**
* Set axis extremes (min/max values)
* @param min - Minimum value (null for auto)
* @param max - Maximum value (null for auto)
* @param redraw - Whether to redraw chart immediately
* @param animation - Animation options
* @param eventArguments - Custom event data
*/
setExtremes(min?: number | null, max?: number | null, redraw?: boolean, animation?: boolean | AnimationOptionsObject, eventArguments?: any): void;
/**
* Get current axis extremes
* @returns Object with min, max, dataMin, dataMax
*/
getExtremes(): AxisExtremesObject;
/**
* Update axis options
* @param options - New axis options
* @param redraw - Whether to redraw chart immediately
*/
update(options: AxisOptions, redraw?: boolean): void;
/**
* Set axis categories
* @param categories - Array of category names
* @param redraw - Whether to redraw chart immediately
*/
setCategories(categories: Array<string>, redraw?: boolean): void;
/**
* Set axis title
* @param title - New axis title options
* @param redraw - Whether to redraw chart immediately
*/
setTitle(title: AxisTitleOptions, redraw?: boolean): void;
}Methods for adding reference lines and highlighted regions to axes.
class Axis {
/**
* Add a plot line (vertical or horizontal reference line)
* @param options - Plot line configuration
* @returns PlotLineOrBand instance
*/
addPlotLine(options: AxisPlotLinesOptions): PlotLineOrBand;
/**
* Add a plot band (highlighted region)
* @param options - Plot band configuration
* @returns PlotLineOrBand instance
*/
addPlotBand(options: AxisPlotBandsOptions): PlotLineOrBand;
/**
* Remove a plot line by ID
* @param id - Plot line ID
*/
removePlotLine(id: string): void;
/**
* Remove a plot band by ID
* @param id - Plot band ID
*/
removePlotBand(id: string): void;
}class PlotLineOrBand {
/**
* Remove this plot line or band
*/
destroy(): void;
/** SVG element for the plot line/band */
svgElem: SVGElement;
/** Configuration options */
options: AxisPlotLinesOptions | AxisPlotBandsOptions;
/** Parent axis */
axis: Axis;
}Methods for converting between data values and pixel coordinates.
class Axis {
/**
* Convert data value to pixel coordinate
* @param value - Data value
* @param paneCoordinates - Whether to use pane coordinates
* @returns Pixel coordinate
*/
toPixels(value: number, paneCoordinates?: boolean): number;
/**
* Convert pixel coordinate to data value
* @param pixel - Pixel coordinate
* @param paneCoordinates - Whether pixel is in pane coordinates
* @returns Data value
*/
toValue(pixel: number, paneCoordinates?: boolean): number;
/**
* Get point position for given value
* @param value - Data value
* @param inside - Whether to constrain to axis length
* @returns Pixel position
*/
getPixelPadding(value: number, inside?: boolean): number;
}Configuration options for horizontal (x) axes.
interface XAxisOptions {
/** Axis type */
type?: AxisTypeValue; // 'linear' | 'logarithmic' | 'datetime' | 'category' | 'treegrid'
/** Axis categories for category axis */
categories?: Array<string>;
/** Axis title */
title?: XAxisTitleOptions;
/** Axis labels */
labels?: XAxisLabelsOptions;
/** Axis line configuration */
lineColor?: ColorString;
lineWidth?: number;
/** Axis minimum value */
min?: number;
/** Axis maximum value */
max?: number;
/** Tick interval */
tickInterval?: number;
/** Minor tick interval */
minorTickInterval?: number | string;
/** Tick positions */
tickPositions?: Array<number>;
/** Tick width */
tickWidth?: number;
/** Tick length */
tickLength?: number;
/** Tick color */
tickColor?: ColorString;
/** Grid line configuration */
gridLineColor?: ColorString;
gridLineWidth?: number;
gridLineDashStyle?: DashStyleValue;
/** Minor grid line configuration */
minorGridLineColor?: ColorString;
minorGridLineWidth?: number;
minorGridLineDashStyle?: DashStyleValue;
/** Plot lines */
plotLines?: Array<XAxisPlotLinesOptions>;
/** Plot bands */
plotBands?: Array<XAxisPlotBandsOptions>;
/** Axis events */
events?: AxisEventsOptions;
/** Whether to reverse axis */
reversed?: boolean;
/** Whether axis is opposite */
opposite?: boolean;
/** Axis offset */
offset?: number;
/** Start on tick */
startOnTick?: boolean;
/** End on tick */
endOnTick?: boolean;
/** Show first label */
showFirstLabel?: boolean;
/** Show last label */
showLastLabel?: boolean;
/** Crosshair configuration */
crosshair?: boolean | AxisCrosshairOptions;
}Configuration options for vertical (y) axes.
interface YAxisOptions {
/** Axis type */
type?: AxisTypeValue;
/** Axis title */
title?: YAxisTitleOptions;
/** Axis labels */
labels?: YAxisLabelsOptions;
/** Stack labels configuration */
stackLabels?: YAxisStackLabelsOptions;
/** Axis minimum value */
min?: number;
/** Axis maximum value */
max?: number;
/** Soft minimum (suggestion) */
softMin?: number;
/** Soft maximum (suggestion) */
softMax?: number;
/** Floor value (absolute minimum) */
floor?: number;
/** Ceiling value (absolute maximum) */
ceiling?: number;
/** Tick interval */
tickInterval?: number;
/** Minor tick interval */
minorTickInterval?: number | string;
/** Axis line configuration */
lineColor?: ColorString;
lineWidth?: number;
/** Grid line configuration */
gridLineColor?: ColorString;
gridLineWidth?: number;
gridLineDashStyle?: DashStyleValue;
gridLineInterpolation?: string;
/** Plot lines */
plotLines?: Array<YAxisPlotLinesOptions>;
/** Plot bands */
plotBands?: Array<YAxisPlotBandsOptions>;
/** Whether to reverse axis */
reversed?: boolean;
/** Whether axis is opposite */
opposite?: boolean;
/** Axis events */
events?: AxisEventsOptions;
/** Breaks in axis */
breaks?: Array<AxisBreaksOptions>;
}Configuration for axis plot lines (reference lines).
interface AxisPlotLinesOptions {
/** Plot line ID */
id?: string;
/** Plot line value */
value?: number;
/** Plot line width */
width?: number;
/** Plot line color */
color?: ColorString;
/** Plot line dash style */
dashStyle?: DashStyleValue;
/** Plot line z-index */
zIndex?: number;
/** Plot line label */
label?: AxisPlotLinesLabelOptions;
/** Plot line events */
events?: AxisPlotLineEventsOptions;
/** Plot line class name */
className?: string;
}
interface AxisPlotLinesLabelOptions {
/** Label text */
text?: string;
/** Label style */
style?: CSSObject;
/** Label alignment */
align?: AlignValue;
/** Label rotation */
rotation?: number;
/** Label x offset */
x?: number;
/** Label y offset */
y?: number;
/** Use HTML for label */
useHTML?: boolean;
}Configuration for axis plot bands (highlighted regions).
interface AxisPlotBandsOptions {
/** Plot band ID */
id?: string;
/** Plot band start value */
from?: number;
/** Plot band end value */
to?: number;
/** Plot band color */
color?: ColorType;
/** Plot band border color */
borderColor?: ColorString;
/** Plot band border width */
borderWidth?: number;
/** Plot band z-index */
zIndex?: number;
/** Plot band label */
label?: AxisPlotBandsLabelOptions;
/** Plot band events */
events?: AxisPlotBandEventsOptions;
/** Plot band class name */
className?: string;
}Event handlers for axis interactions and changes.
interface AxisEventsOptions {
/**
* Fired when axis extremes are set
* @param event - Event object with min, max, trigger properties
*/
setExtremes?: AxisSetExtremesEventCallbackFunction;
/**
* Fired after axis extremes are set
* @param event - Event object
*/
afterSetExtremes?: AxisEventCallbackFunction;
/**
* Fired when point breaks axis
* @param event - Event object
*/
pointBreak?: AxisPointBreakEventCallbackFunction;
/**
* Fired when point falls in axis break
* @param event - Event object
*/
pointInBreak?: AxisEventCallbackFunction;
}
type AxisSetExtremesEventCallbackFunction = (this: Axis, evt: AxisSetExtremesEventObject) => void;
type AxisEventCallbackFunction = (this: Axis) => void;
type AxisPointBreakEventCallbackFunction = (this: Axis, evt: AxisPointBreakEventObject) => void;
interface AxisSetExtremesEventObject {
/** New minimum value */
min: number;
/** New maximum value */
max: number;
/** What triggered the change */
trigger: AxisExtremesTriggerValue;
/** Prevent default behavior */
preventDefault(): void;
}Specialized axis for time-based data with automatic tick positioning and formatting.
interface DatetimeAxisOptions extends AxisOptions {
type: 'datetime';
/** Date/time formatting options */
dateTimeLabelFormats?: AxisDateTimeLabelFormatsOptions;
/** Tick pixel interval */
tickPixelInterval?: number;
/** Units for tick intervals */
units?: Array<Array<string | Array<number>>>;
}
interface AxisDateTimeLabelFormatsOptions {
millisecond?: string;
second?: string;
minute?: string;
hour?: string;
day?: string;
week?: string;
month?: string;
year?: string;
}Axis with logarithmic scaling for data spanning multiple orders of magnitude.
interface LogarithmicAxisOptions extends AxisOptions {
type: 'logarithmic';
/** Whether to allow negative values */
allowNegativeLog?: boolean;
/** Logarithmic base */
log?: number;
}Discrete axis for categorical data with string labels.
interface CategoryAxisOptions extends AxisOptions {
type: 'category';
/** Array of category names */
categories?: Array<string>;
/** Unique names array */
uniqueNames?: boolean;
}Usage Examples:
// Basic axis configuration
const chart = Highcharts.chart('container', {
xAxis: {
type: 'category',
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
title: { text: 'Month' }
},
yAxis: {
type: 'linear',
title: { text: 'Sales ($)' },
min: 0
},
series: [{ data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0] }]
});
// Dynamic axis manipulation
chart.xAxis[0].setExtremes(1, 4); // Show only Feb-May
chart.yAxis[0].update({ max: 200 });
// Add plot lines and bands
chart.yAxis[0].addPlotLine({
value: 100,
color: '#ff0000',
width: 2,
id: 'target-line',
label: { text: 'Target', align: 'right' }
});
chart.yAxis[0].addPlotBand({
from: 90,
to: 110,
color: 'rgba(255, 0, 0, 0.1)',
id: 'target-band'
});
// Multiple axes
const multiAxisChart = Highcharts.chart('container', {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr']
},
yAxis: [{
title: { text: 'Temperature (°C)' }
}, {
title: { text: 'Humidity (%)' },
opposite: true
}],
series: [{
name: 'Temperature',
data: [20, 22, 25, 27],
yAxis: 0
}, {
name: 'Humidity',
data: [65, 70, 80, 75],
yAxis: 1
}]
});
// Datetime axis
const timeChart = Highcharts.chart('container', {
xAxis: {
type: 'datetime',
dateTimeLabelFormats: {
month: '%b %Y',
year: '%Y'
}
},
series: [{
data: [
[Date.UTC(2023, 0, 1), 29.9],
[Date.UTC(2023, 1, 1), 71.5],
[Date.UTC(2023, 2, 1), 106.4]
]
}]
});