Axis Configuration Options
Axis options control the behavior, appearance, and scale of chart axes (xAxis, yAxis, colorAxis, etc.).
Source: ts/Core/Axis/AxisOptions.ts
Basic Configuration
Highcharts.chart('container', {
xAxis: {
type: 'datetime',
title: { text: 'Time' }
},
yAxis: {
title: { text: 'Value' },
min: 0,
max: 100
}
});
Core Options
type
The axis type: ‘linear’, ‘logarithmic’, ‘datetime’, or ‘category’
xAxis: {
type: 'datetime' // For time series
}
yAxis: {
type: 'logarithmic' // For log scale
}
xAxis: {
type: 'category', // For categorical data
categories: ['Jan', 'Feb', 'Mar']
}
categories
Category names for categorical axes
xAxis: {
categories: ['Apples', 'Bananas', 'Oranges', 'Grapes']
}
title
yAxis: {
title: {
text: 'Temperature (°C)',
align: 'high',
rotation: 0,
offset: 0,
y: -10,
style: {
fontSize: '14px',
fontWeight: 'bold',
color: '#333'
}
}
}
ts/Core/Axis/AxisOptions.ts:30
Scale Options
min
Minimum value of the axis. If null, automatically calculated.
yAxis: {
min: 0 // Force axis to start at 0
}
xAxis: {
type: 'datetime',
min: Date.UTC(2024, 0, 1) // Start date
}
max
Maximum value of the axis. If null, automatically calculated.
yAxis: {
max: 100 // Force axis to end at 100
}
minPadding
Padding below the minimum value (fraction of axis range)
yAxis: {
minPadding: 0.05 // 5% padding below min
}
maxPadding
Padding above the maximum value (fraction of axis range)
yAxis: {
maxPadding: 0.1 // 10% padding above max
}
startOnTick
Whether to force the axis to start on a tick
yAxis: {
startOnTick: false,
min: 5 // Will start exactly at 5
}
endOnTick
Whether to force the axis to end on a tick
yAxis: {
endOnTick: false,
max: 95 // Will end exactly at 95
}
tickInterval
The interval between ticks
xAxis: {
tickInterval: 24 * 3600 * 1000 // One day for datetime axis
}
yAxis: {
tickInterval: 10 // Ticks every 10 units
}
tickAmount
Approximate number of ticks to show
yAxis: {
tickAmount: 6 // Aim for 6 ticks
}
Appearance Options
lineColor
lineColor
ColorType
default:"#ccd6eb"
Color of the axis line
xAxis: {
lineColor: '#333',
lineWidth: 2
}
lineWidth
Width of the axis line in pixels
gridLineColor
gridLineColor
ColorType
default:"#e6e6e6"
Color of the grid lines
yAxis: {
gridLineColor: '#e0e0e0',
gridLineWidth: 1,
gridLineDashStyle: 'Dot'
}
gridLineWidth
gridLineDashStyle
Dash style of the grid lines
yAxis: {
gridLineDashStyle: 'Dash' // 'Solid', 'Dot', 'Dash', etc.
}
minorGridLineColor
minorGridLineColor
ColorType
default:"#f2f2f2"
Color of minor grid lines
minorGridLineWidth
Width of minor grid lines
minorTickInterval
yAxis: {
minorTickInterval: 'auto',
minorGridLineWidth: 1,
minorGridLineColor: '#f0f0f0'
}
Label Options
labels
yAxis: {
labels: {
enabled: true,
align: 'right',
x: -10,
y: 5,
format: '{value} °C',
formatter: function() {
return this.value + ' units';
},
style: {
fontSize: '12px',
color: '#666'
},
rotation: 0,
overflow: 'justify'
}
}
xAxis: {
labels: {
format: '{value:%b %e}', // For datetime: "Jan 1"
rotation: -45,
align: 'right'
}
}
ts/Core/Axis/AxisOptions.ts:26-27
Tick Options
tickColor
tickColor
ColorType
default:"#ccd6eb"
Color of the tick marks
tickWidth
Width of the tick marks in pixels
tickLength
Length of the tick marks in pixels
tickPosition
Position of tick marks: ‘inside’ or ‘outside’
xAxis: {
tickColor: '#333',
tickWidth: 2,
tickLength: 5,
tickPosition: 'inside'
}
tickPositions
yAxis: {
tickPositions: [0, 25, 50, 75, 100] // Explicit ticks
}
Crosshair
crosshair
crosshair
boolean | object
default:"false"
Crosshair configuration for highlighting axis values
xAxis: {
crosshair: true // Simple crosshair
}
xAxis: {
crosshair: {
width: 2,
color: '#ff0000',
dashStyle: 'Dash',
snap: true,
label: {
enabled: true,
format: '{value:%b %e, %Y}'
}
}
}
ts/Core/Axis/AxisOptions.ts:25
Plot Lines & Bands
plotLines
Array of plot lines to draw on the axis
yAxis: {
plotLines: [{
value: 50,
color: 'red',
width: 2,
id: 'threshold',
dashStyle: 'Dash',
label: {
text: 'Threshold',
align: 'right',
style: {
color: 'red'
}
},
zIndex: 5
}]
}
plotBands
Array of plot bands to highlight ranges
xAxis: {
plotBands: [{
from: Date.UTC(2024, 0, 1),
to: Date.UTC(2024, 0, 7),
color: 'rgba(68, 170, 213, 0.2)',
id: 'week1',
label: {
text: 'Week 1',
align: 'center'
}
}]
}
yAxis: {
plotBands: [{
from: 20,
to: 80,
color: 'rgba(0, 255, 0, 0.1)',
label: { text: 'Normal Range' }
}]
}
Positioning
opposite
Whether to display the axis on the opposite side
yAxis: [{
title: { text: 'Primary' }
}, {
title: { text: 'Secondary' },
opposite: true // Right side for Y axis
}]
offset
Distance in pixels to offset the axis from the default position
yAxis: {
offset: 20 // Move 20px away from plot area
}
width
Width of the axis in pixels or percentage
xAxis: [{
width: '48%',
offset: 0
}, {
width: '48%',
left: '52%'
}]
height
Height of the axis in pixels or percentage
yAxis: [{
height: '48%'
}, {
height: '48%',
top: '52%'
}]
left
Left position of the axis
top
Breaks
breaks
Axis breaks for skipping ranges
xAxis: {
breaks: [{
from: Date.UTC(2024, 0, 5),
to: Date.UTC(2024, 0, 10),
breakSize: 0 // Gap size
}]
}
yAxis: {
breaks: [{
from: 5,
to: 10,
breakSize: 1
}, {
from: 20,
to: 30,
breakSize: 1
}]
}
Events
events
Event handlers for axis events
xAxis: {
events: {
afterSetExtremes: function(e) {
console.log('Extremes set:', e.min, e.max);
},
setExtremes: function(e) {
console.log('Setting extremes:', e.min, e.max);
// Return false to prevent
if (e.min < 0) return false;
},
afterBreaks: function() {
console.log('Breaks recalculated');
},
pointBreak: function(e) {
console.log('Point broken:', e.point.name);
}
}
}
Datetime Options
Format strings for datetime labels
xAxis: {
type: 'datetime',
dateTimeLabelFormats: {
millisecond: '%H:%M:%S.%L',
second: '%H:%M:%S',
minute: '%H:%M',
hour: '%H:%M',
day: '%e %b',
week: '%e %b',
month: '%b \'%y',
year: '%Y'
}
}
minRange
Minimum range to display (prevents zooming too far in)
xAxis: {
type: 'datetime',
minRange: 24 * 3600 * 1000 // At least one day
}
Advanced Options
reversed
Whether to reverse the axis direction
yAxis: {
reversed: true // High values at bottom
}
alignTicks
Whether to align ticks with other axes
allowDecimals
Whether to allow decimals in the axis values
yAxis: {
allowDecimals: false // Integer values only
}
softMin / softMax
Soft minimum - only applied if no data is below this value
Soft maximum - only applied if no data is above this value
yAxis: {
softMin: 0, // Prefer 0 as min if data allows
softMax: 100 // Prefer 100 as max if data allows
}
visible
Whether the axis is visible
xAxis: {
visible: false // Hide axis completely
}
Complete Example
Highcharts.chart('container', {
xAxis: {
// Type
type: 'datetime',
// Scale
min: Date.UTC(2024, 0, 1),
max: Date.UTC(2024, 11, 31),
minRange: 7 * 24 * 3600 * 1000, // One week
// Title
title: {
text: 'Time Period',
style: { fontSize: '14px' }
},
// Labels
labels: {
format: '{value:%b %e}',
rotation: -45,
align: 'right',
style: { fontSize: '11px' }
},
// Appearance
lineColor: '#333',
lineWidth: 1,
gridLineWidth: 1,
gridLineColor: '#e6e6e6',
// Ticks
tickInterval: 30 * 24 * 3600 * 1000, // Monthly
tickWidth: 1,
tickLength: 5,
tickColor: '#333',
// Crosshair
crosshair: {
width: 1,
color: '#999',
dashStyle: 'Dash'
},
// Plot bands
plotBands: [{
from: Date.UTC(2024, 5, 1),
to: Date.UTC(2024, 7, 31),
color: 'rgba(255, 200, 0, 0.1)',
label: { text: 'Summer' }
}],
// Events
events: {
afterSetExtremes: function(e) {
console.log('Date range:',
new Date(e.min).toISOString(),
new Date(e.max).toISOString()
);
}
}
},
yAxis: {
// Scale
min: 0,
softMax: 100,
// Title
title: {
text: 'Temperature (°C)',
rotation: 0,
align: 'high',
offset: 0,
y: -10
},
// Labels
labels: {
format: '{value}°',
align: 'right',
x: -10
},
// Appearance
gridLineWidth: 1,
gridLineDashStyle: 'Dot',
// Minor ticks
minorTickInterval: 'auto',
minorGridLineWidth: 1,
// Plot lines
plotLines: [{
value: 32,
color: '#0000ff',
width: 2,
label: { text: 'Freezing Point' }
}]
},
series: [{
data: generateTimeSeriesData()
}]
});
See Also
