Axis Configuration Options

Complete reference for Highcharts axis configuration options

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

type · string · default: "linear"

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

categories · Array<string>

Category names for categorical axes

xAxis: {
  categories: ['Apples', 'Bananas', 'Oranges', 'Grapes']
}

title

title · object

Axis title configuration

yAxis: {
  title: {
    text: 'Temperature (°C)',
    align: 'high',
    rotation: 0,
    offset: 0,
    y: -10,
    style: {
      fontSize: '14px',
      fontWeight: 'bold',
      color: '#333'
    }
  }
}

Source: Referenced in ts/Core/Axis/AxisOptions.ts:30

Scale Options

min

min · number | null

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

max · number | null

Maximum value of the axis. If null, automatically calculated.

yAxis: {
  max: 100  // Force axis to end at 100
}

minPadding

minPadding · number · default: "0.01"

Padding below the minimum value (fraction of axis range)

yAxis: {
  minPadding: 0.05  // 5% padding below min
}

maxPadding

maxPadding · number · default: "0.01"

Padding above the maximum value (fraction of axis range)

yAxis: {
  maxPadding: 0.1  // 10% padding above max
}

startOnTick

startOnTick · boolean · default: "true"

Whether to force the axis to start on a tick

yAxis: {
  startOnTick: false,
  min: 5  // Will start exactly at 5
}

endOnTick

endOnTick · boolean · default: "true"

Whether to force the axis to end on a tick

yAxis: {
  endOnTick: false,
  max: 95  // Will end exactly at 95
}

tickInterval

tickInterval · number

The interval between ticks

xAxis: {
  tickInterval: 24 * 3600 * 1000  // One day for datetime axis
}

yAxis: {
  tickInterval: 10  // Ticks every 10 units
}

tickAmount

tickAmount · number

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

lineWidth · number · default: "1"

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

gridLineWidth · number · default: "1"

Width of the grid lines

gridLineDashStyle

gridLineDashStyle · string · default: "Solid"

Dash style of the grid lines

yAxis: {
  gridLineDashStyle: 'Dash'  // 'Solid', 'Dot', 'Dash', etc.
}

minorGridLineColor

minorGridLineColor · ColorType · default: "#f2f2f2"

Color of minor grid lines

minorGridLineWidth

minorGridLineWidth · number · default: "1"

Width of minor grid lines

minorTickInterval

minorTickInterval · number | 'auto'

Interval for minor ticks

yAxis: {
  minorTickInterval: 'auto',
  minorGridLineWidth: 1,
  minorGridLineColor: '#f0f0f0'
}

Label Options

labels

labels · object

Axis label configuration

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'
  }
}

Source: Referenced in ts/Core/Axis/AxisOptions.ts:26-27

Tick Options

tickColor

tickColor · ColorType · default: "#ccd6eb"

Color of the tick marks

tickWidth

tickWidth · number · default: "1"

Width of the tick marks in pixels

tickLength

tickLength · number · default: "10"

Length of the tick marks in pixels

tickPosition

tickPosition · string · default: "outside"

Position of tick marks: ‘inside’ or ‘outside’

xAxis: {
  tickColor: '#333',
  tickWidth: 2,
  tickLength: 5,
  tickPosition: 'inside'
}

tickPositions

tickPositions · Array<number>

Explicit tick positions

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}'
    }
  }
}

Source: Referenced in ts/Core/Axis/AxisOptions.ts:25

Plot Lines & Bands

plotLines

plotLines · Array<object>

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

plotBands · Array<object>

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

opposite · boolean · default: "false"

Whether to display the axis on the opposite side

yAxis: [{
  title: { text: 'Primary' }
}, {
  title: { text: 'Secondary' },
  opposite: true  // Right side for Y axis
}]

offset

offset · number · default: "0"

Distance in pixels to offset the axis from the default position

yAxis: {
  offset: 20  // Move 20px away from plot area
}

width

width · number | string

Width of the axis in pixels or percentage

xAxis: [{
  width: '48%',
  offset: 0
}, {
  width: '48%',
  left: '52%'
}]

height

height · number | string

Height of the axis in pixels or percentage

yAxis: [{
  height: '48%'
}, {
  height: '48%',
  top: '52%'
}]

left

left · number | string

Left position of the axis

top

top · number | string

Top position of the axis

Breaks

breaks

breaks · Array<object>

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

events · object

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);
    }
  }
}

Source: Referenced in chart events

Datetime Options

dateTimeLabelFormats

dateTimeLabelFormats · object

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

minRange · number

Minimum range to display (prevents zooming too far in)

xAxis: {
  type: 'datetime',
  minRange: 24 * 3600 * 1000  // At least one day
}

Advanced Options

reversed

reversed · boolean · default: "false"

Whether to reverse the axis direction

yAxis: {
  reversed: true  // High values at bottom
}

alignTicks

alignTicks · boolean · default: "true"

Whether to align ticks with other axes

allowDecimals

allowDecimals · boolean · default: "true"

Whether to allow decimals in the axis values

yAxis: {
  allowDecimals: false  // Integer values only
}

softMin / softMax

softMin · number

Soft minimum - only applied if no data is below this value

softMax · number

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

visible · boolean · default: "true"

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

• Axis Class API - Axis methods and properties
• Chart Options - Chart configuration
• Plot Options - Series defaults
• Events API - Axis events