Class: Axis

Highcharts. Axis

new Axis(chart, options)

Create a new axis object. Called internally when instanciating a new chart or adding axes by Highcharts.Chart#addAxis.

A chart can have from 0 axes (pie chart) to multiples. In a normal, single series cartesian chart, there is one X axis and one Y axis.

The X axis or axes are referenced by Highcharts.Chart.xAxis, which is an array of Axis objects. If there is only one axis, it can be referenced through chart.xAxis[0], and multiple axes have increasing indices. The same pattern goes for Y axes.

If you need to get the axes from a series object, use the series.xAxis and series.yAxis properties. These are not arrays, as one series can only be associated to one X and one Y axis.

A third way to reference the axis programmatically is by id. Add an id in the axis configuration options, and get the axis by Highcharts.Chart#get.

Configuration options for the axes are given in options.xAxis and options.yAxis.

Parameters:
Name Type Description
chart Highcharts.Chart

The Chart instance to apply the axis on.

options Highcharts.AxisOptions

Axis options.

Members

chart :Highcharts.Chart

The Chart that the axis belongs to.

Type:

coll :string

The collection where the axis belongs, for example xAxis, yAxis or colorAxis. Corresponds to properties on Chart, for example Highcharts.Chart.xAxis.

Type:
  • string

crosshair :boolean|Highcharts.AxisCrosshairOptions

The processed crosshair options.

Type:

defaultLeftAxisOptions :*|Array.<*>

The Z axis or depth axis for 3D plots.

See the Axis class for programmatic access to the axis.

Type:
  • * | Array.<*>
Since:
  • 5.0.0
Try it

defaultOptions :*|Array.<*>

The X axis or category axis. Normally this is the horizontal axis, though if the chart is inverted this is the vertical axis. In case of multiple axes, the xAxis node is an array of configuration objects.

See the Axis class for programmatic access to the axis.

Type:
  • * | Array.<*>

defaultYAxisOptions :*|Array.<*>

The Y axis or value axis. Normally this is the vertical axis, though if the chart is inverted this is the horizontal axis. In case of multiple axes, the yAxis node is an array of configuration objects.

See the Axis object for programmatic access to the axis.

Type:
  • * | Array.<*>

horiz :boolean

Whether the axis is horizontal.

Type:
  • boolean

isXAxis :boolean|undefined

Whether the axis is the x-axis.

Type:
  • boolean | undefined

max :number|null

The maximum value of the axis. In a logarithmic axis, this is the logarithm of the real value, and the real value can be obtained from Highcharts.Axis#getExtremes.

Type:
  • number | null

min :number|null

The minimum value of the axis. In a logarithmic axis, this is the logarithm of the real value, and the real value can be obtained from Highcharts.Axis#getExtremes.

Type:
  • number | null

reversed :boolean

Whether the axis is reversed. Based on the axis.reversed, option, but inverted charts have reversed xAxis by default.

Type:
  • boolean

series :Array.<Highcharts.Series>

All series associated to the axis.

Type:

side :number

The side on which the axis is rendered. 0 is top, 1 is right, 2 is bottom and 3 is left.

Type:
  • number

Methods

addPlotBand(options)

Add a plot band after render time.

Parameters:
Name Type Description
options Highcharts.AxisPlotBandsOptions

A configuration object for the plot band, as defined in xAxis.plotBands.

Returns:
Highcharts.PlotLineOrBand | undefined .

The added plot band.

Try it

addPlotLine(options)

Add a plot line after render time.

Parameters:
Name Type Description
options Highcharts.AxisPlotLinesOptions

A configuration object for the plot line, as defined in xAxis.plotLines.

Returns:
Highcharts.PlotLineOrBand | undefined .

The added plot line.

Try it

addTitle(display)

Adds the title defined in axis.options.title.

Parameters:
Name Type Description
display boolean

Whether or not to display the title.

drawCrosshair( [e] [, point])

Internal function to draw a crosshair.

Parameters:
Name Type Argument Description
e Highcharts.PointerEventObject <optional>

The event arguments from the modified pointer event, extended with chartX and chartY

point Highcharts.Point <optional>

The Point object if the crosshair snaps to points.

Fires:
  • Highcharts.Axis#event:afterDrawCrosshair
  • Highcharts.Axis#event:drawCrosshair

getExtremes()

Get the current extremes for the axis.

Returns:
Highcharts.ExtremesObject .

An object containing extremes information.

Try it

getLinearTickPositions(tickInterval, min, max)

Internal function to et the tick positions of a linear axis to round values like whole tens or every five.

Parameters:
Name Type Description
tickInterval number

The normalized tick interval.

min number

Axis minimum.

max number

Axis maximum.

Returns:
Array.<number> .

An array of axis values where ticks should be placed.

getLinePath(lineWidth)

Internal function to get the path for the axis line. Extended for polar charts.

Parameters:
Name Type Description
lineWidth number

The line width in pixels.

Returns:
Highcharts.SVGPathArray .

The SVG path definition in array form.

getMinorTickInterval()

Resolve the new minorTicks/minorTickInterval options into the legacy loosely typed minorTickInterval option.

Returns:

getMinorTickPositions()

Internal function to return the minor tick positions. For logarithmic axes, the same logic as for major ticks is reused.

Returns:
Array.<number> .

An array of axis values where ticks should be placed.

getPlotBandPath(from, to)

Internal function to create the SVG path definition for a plot band.

Parameters:
Name Type Description
from number

The axis value to start from.

to number

The axis value to end on.

Returns:
Highcharts.SVGPathArray .

The SVG path definition in array form.

getPlotLinePath(value [, lineWidth] [, old] [, force] [, translatedValue])

Create the path for a plot line that goes from the given value on this axis, across the plot to the opposite side. Also used internally for grid lines and crosshairs.

Parameters:
Name Type Argument Default Description
value number

Axis value.

lineWidth number <optional>
1

Used for calculation crisp line coordinates.

old boolean <optional>
false

Use old coordinates (for resizing and rescaling).

force boolean | string <optional>
false

If false, the function will return null when it falls outside the axis bounds. If true, the function will return a path aligned to the plot area sides if it falls outside. If pass, it will return a path outside.

translatedValue number <optional>

If given, return the plot line path of a pixel position on the axis.

Returns:
Array.<(string|number)> .

The SVG path definition for the plot line.

getThreshold(threshold)

Get the zero plane either based on zero or on the min or max value. Used in bar and area plots.

Parameters:
Name Type Description
threshold number

The threshold in axis values.

Returns:
number .

The translated threshold position in terms of pixels, and corrected to stay within the axis bounds.

hasData()

Return true if the axis has associated data.

Returns:
boolean .

True if the axis has associated visible series and those series have either valid data points or explicit min and max settings.

hideCrosshair()

Hide the crosshair if visible.

init(chart, userOptions)

Overrideable function to initialize the axis.

Parameters:
Name Type Description
chart Highcharts.Chart
userOptions Highcharts.Options
See also:
Fires:
  • Highcharts.Axis#event:afterInit
  • Highcharts.Axis#event:init

remove( [redraw])

Remove the axis from the chart.

Parameters:
Name Type Argument Default Description
redraw boolean <optional>
true

Whether to redraw the chart following the remove.

Try it

removePlotBand(id)

Remove a plot band by its id.

Parameters:
Name Type Description
id string

The plot band's id as given in the original configuration object or in the addPlotBand option.

Try it

removePlotLine(id)

Remove a plot line by its id.

Parameters:
Name Type Description
id string

The plot line's id as given in the original configuration object or in the addPlotLine option.

Try it

renderLine()

Render the axis line. Called internally when rendering and redrawing the axis.

renderMinorTick(pos)

Render a minor tick into the given position. If a minor tick already exists in this position, move it.

Parameters:
Name Type Description
pos number

The position in axis values.

renderTick(pos, i)

Render a major tick into the given position. If a tick already exists in this position, move it.

Parameters:
Name Type Description
pos number

The position in axis values.

i number

The tick index.

setCategories(categories [, redraw])

Set new axis categories and optionally redraw.

Parameters:
Name Type Argument Default Description
categories Array.<string>

The new categories.

redraw boolean <optional>
true

Whether to redraw the chart.

Try it

setCompare(compare [, redraw])

Highstock only. Set the compare mode on all series belonging to an Y axis after render time.

Parameters:
Name Type Argument Default Description
compare string

The compare mode. Can be one of null, "value" or "percent".

redraw boolean <optional>
true

Whether to redraw the chart or to wait for a later call to Highcharts.Chart#redraw.

See also:
Try it

setDataGrouping( [dataGrouping] [, redraw])

Highstock only. Force data grouping on all the axis' series.

Parameters:
Name Type Argument Default Description
dataGrouping boolean | Highcharts.PlotSeriesDataGroupingOptions <optional>

A dataGrouping configuration. Use false to disable data grouping dynamically.

redraw boolean <optional>
true

Whether to redraw the chart or wait for a later call to Highcharts.Chart#redraw.

setExtremes( [newMin] [, newMax] [, redraw] [, animation] [, eventArguments])

Set the minimum and maximum of the axes after render time. If the startOnTick and endOnTick options are true, the minimum and maximum values are rounded off to the nearest tick. To prevent this, these options can be set to false before calling setExtremes. Also, setExtremes will not allow a range lower than the minRange option, which by default is the range of five points.

Parameters:
Name Type Argument Default Description
newMin number <optional>

The new minimum value.

newMax number <optional>

The new maximum value.

redraw boolean <optional>
true

Whether to redraw the chart or wait for an explicit call to Highcharts.Chart#redraw

animation boolean | Highcharts.AnimationOptionsObject <optional>
true

Enable or modify animations.

eventArguments * <optional>

Arguments to be accessed in event handler.

Fires:
  • Highcharts.Axis#event:setExtremes
Try it

setTickPositions()

Now we have computed the normalized tickInterval, get the tick positions

Fires:
  • Highcharts.Axis#event:afterSetTickPositions

setTitle(titleOptions [, redraw])

Update the axis title by options after render time.

Parameters:
Name Type Argument Default Description
titleOptions Highcharts.XAxisTitleOptions | Highcharts.YAxisTitleOptions | Highcharts.ZAxisTitleOptions

The additional title options.

redraw boolean <optional>
true

Whether to redraw the chart after setting the title.

Try it

toPixels(value, paneCoordinates)

Translate a value in terms of axis units into pixels within the chart.

Parameters:
Name Type Description
value number

A value in terms of axis units.

paneCoordinates boolean

Whether to return the pixel coordinate relative to the chart or just the axis/pane itself.

Returns:
number .

Pixel position of the value on the chart or axis.

toValue(pixel, paneCoordiantes)

Translate a pixel position along the axis to a value in terms of axis units.

Parameters:
Name Type Description
pixel number

The pixel value coordinate.

paneCoordiantes boolean

Whether the input pixel is relative to the chart or just the axis/pane itself.

Returns:
number .

The axis value.

update(options)

Update an axis object with a new set of options. The options are merged with the existing options, so only new or altered options need to be specified.

Parameters:
Name Type Description
options Highcharts.XAxisOptions | Highcharts.YAxisOptions | Highcharts.ZAxisOptions

The new options that will be merged in with existing options on the axis.

Try it