Axis Configuration

Learn how to configure and customize X-axis, Y-axis, and multiple axes in Highcharts for precise data visualization.

Axis Configuration

Axes are fundamental components of Highcharts that define the scale and position of data. Understanding axis configuration is essential for creating effective and accurate visualizations.

Axis Basics

Most Highcharts charts have two axes: the X-axis (horizontal) and Y-axis (vertical). Each axis can be configured independently.

Highcharts.chart('container', {
    xAxis: {
        categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
        title: {
            text: 'Month'
        }
    },
    yAxis: {
        title: {
            text: 'Temperature (°C)'
        },
        min: 0
    },
    series: [{
        data: [7.0, 6.9, 9.5, 14.5, 18.2]
    }]
});

Axis Configuration Options

Basic Properties

Core axis options from AxisOptions.ts:

interface AxisOptions {
    type?: 'linear' | 'logarithmic' | 'datetime' | 'category';
    title?: AxisTitleOptions;
    categories?: Array<string>;
    min?: number;
    max?: number;
    startOnTick?: boolean;
    endOnTick?: boolean;
    tickInterval?: number;
    minorTickInterval?: number | 'auto';
    reversed?: boolean;
    opposite?: boolean;
    visible?: boolean;
}

Example:

xAxis: {
    type: 'datetime',
    min: Date.UTC(2024, 0, 1),
    max: Date.UTC(2024, 11, 31),
    reversed: false,
    opposite: false
}

Labels & Formatting

Customize axis labels and their appearance:

xAxis: {
    labels: {
        enabled: true,
        formatter: function() {
            return this.value + '°';
        },
        rotation: -45,
        align: 'right',
        style: {
            fontSize: '12px',
            color: '#333'
        },
        overflow: 'justify'
    }
}

Date/Time Formatting:

xAxis: {
    type: 'datetime',
    labels: {
        format: '{value:%Y-%m-%d}',
        rotation: -45
    },
    dateTimeLabelFormats: {
        day: '%e %b',
        week: '%e %b',
        month: '%b \'%y',
        year: '%Y'
    }
}

Grid & Tick Marks

Control the visual appearance of axis grid lines and ticks:

yAxis: {
    gridLineWidth: 1,
    gridLineColor: '#e6e6e6',
    gridLineDashStyle: 'Dash',
    minorGridLineWidth: 0,
    minorGridLineColor: '#f2f2f2',
    
    tickWidth: 1,
    tickLength: 10,
    tickColor: '#ccc',
    tickPosition: 'outside',
    
    minorTickInterval: 'auto',
    minorTickWidth: 1,
    minorTickLength: 5
}

Plot Bands & Lines

Add visual markers to highlight specific ranges or values:

yAxis: {
    plotBands: [{
        from: 0,
        to: 10,
        color: 'rgba(68, 170, 213, 0.1)',
        label: {
            text: 'Low Range',
            align: 'center'
        }
    }, {
        from: 10,
        to: 20,
        color: 'rgba(255, 200, 0, 0.1)',
        label: {
            text: 'Medium Range'
        }
    }],
    plotLines: [{
        value: 15,
        color: 'red',
        dashStyle: 'ShortDash',
        width: 2,
        label: {
            text: 'Target',
            align: 'right'
        }
    }]
}

Axis Types

Highcharts supports four primary axis types:

Linear

Default numeric axis with linear scale

{ type: 'linear' }

Logarithmic

Logarithmic scale for exponential data

{ type: 'logarithmic' }

DateTime

Time-based axis for temporal data

{ type: 'datetime' }

Category

Categorical axis for discrete values

{ type: 'category', categories: ['A', 'B', 'C'] }

Multiple Axes

Charts can have multiple X or Y axes to display different scales:

Dual Y-Axes

Highcharts.chart('container', {
    title: {
        text: 'Temperature and Rainfall'
    },
    xAxis: {
        categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May']
    },
    yAxis: [{
        // Primary Y-axis
        title: {
            text: 'Temperature (°C)'
        },
        labels: {
            format: '{value}°C'
        }
    }, {
        // Secondary Y-axis
        title: {
            text: 'Rainfall (mm)'
        },
        labels: {
            format: '{value} mm'
        },
        opposite: true
    }],
    series: [{
        name: 'Temperature',
        type: 'column',
        yAxis: 0,
        data: [7.0, 6.9, 9.5, 14.5, 18.2]
    }, {
        name: 'Rainfall',
        type: 'spline',
        yAxis: 1,
        data: [49.9, 71.5, 106.4, 129.2, 144.0]
    }]
});

Axis Methods

Manipulate axes dynamically after chart creation:

Extremes

// Set axis extremes
chart.xAxis[0].setExtremes(0, 100);

// Get current extremes
const extremes = chart.xAxis[0].getExtremes();
console.log(extremes.min, extremes.max);

// Set with animation
chart.yAxis[0].setExtremes(0, 200, true, true);

// Auto-calculate extremes
chart.xAxis[0].setExtremes(null, null);

Update Axis

// Update axis configuration
chart.xAxis[0].update({
    title: {
        text: 'Updated Title'
    },
    gridLineWidth: 1
});

// Update multiple properties
chart.yAxis[0].update({
    min: 0,
    max: 100,
    tickInterval: 10
});

Plot Bands/Lines

// Add plot band
chart.xAxis[0].addPlotBand({
    from: 5,
    to: 10,
    color: 'rgba(255, 0, 0, 0.1)',
    id: 'highlight'
});

// Remove plot band
chart.xAxis[0].removePlotBand('highlight');

// Add plot line
chart.yAxis[0].addPlotLine({
    value: 50,
    color: 'red',
    width: 2,
    id: 'threshold'
});

// Remove plot line
chart.yAxis[0].removePlotLine('threshold');

Add/Remove Axes

// Add new axis
chart.addAxis({
    title: {
        text: 'New Y-Axis'
    },
    opposite: true
}, false); // false = Y-axis, true = X-axis

// Remove axis
chart.yAxis[1].remove();

Crosshair Configuration

Crosshairs help users identify exact values:

xAxis: {
    crosshair: {
        width: 2,
        color: 'gray',
        dashStyle: 'ShortDash',
        snap: true,
        label: {
            enabled: true,
            format: '{value}'
        }
    }
},
yAxis: {
    crosshair: {
        color: 'green',
        width: 1,
        label: {
            enabled: true,
            backgroundColor: '#fff',
            borderColor: '#000',
            borderRadius: 3
        }
    }
}

Real-World Examples

Category Axis

Highcharts.chart('container', {
    chart: {
        type: 'column'
    },
    title: {
        text: 'Production by Country'
    },
    xAxis: {
        type: 'category',
        categories: ['USA', 'China', 'Brazil', 'EU', 'Argentina', 'India'],
        crosshair: true,
        labels: {
            rotation: -45,
            style: {
                fontSize: '13px'
            }
        }
    },
    yAxis: {
        min: 0,
        title: {
            text: '1000 metric tons (MT)'
        },
        gridLineWidth: 1,
        gridLineDashStyle: 'Dot'
    },
    series: [{
        name: 'Production',
        data: [387749, 280000, 129000, 64300, 54000, 34300]
    }]
});

Axis Options Reference

type · string · default: "linear"

The type of axis: 'linear', 'logarithmic', 'datetime', or 'category'.

categories · string[]

Array of category names for a category axis. Automatically sets type to 'category'.

min · number

The minimum value of the axis. If null, the min value is automatically calculated.

max · number

The maximum value of the axis. If null, the max value is automatically calculated.

reversed · boolean · default: false

Whether to reverse the axis so that the highest number is closest to the origin.

opposite · boolean · default: false

Whether to display the axis on the opposite side of the normal. The normal is on the left for vertical axes and bottom for horizontal axes.

tickInterval · number

The interval of the tick marks in axis units. When null, the tick interval is computed to approximately follow the tickPixelInterval.

gridLineWidth · number · default: 0

The width of the grid lines extending from the axis across the gradient or plot area.

labels · AxisLabelsOptions

Configuration for the axis labels, including formatting, rotation, and styling.

title · AxisTitleOptions

The axis title, displayed next to the axis line.

crosshair · AxisCrosshairOptions | boolean

Configure a crosshair that follows the mouse pointer along the axis.

TypeScript Interface

Key axis interfaces from AxisOptions.ts:

interface AxisOptions {
    type?: 'linear' | 'logarithmic' | 'datetime' | 'category';
    categories?: Array<string>;
    min?: number;
    max?: number;
    startOnTick?: boolean;
    endOnTick?: boolean;
    tickInterval?: number;
    minorTickInterval?: number | 'auto';
    reversed?: boolean;
    opposite?: boolean;
    visible?: boolean;
    labels?: AxisLabelsOptions;
    title?: AxisTitleOptions;
    gridLineWidth?: number;
    gridLineColor?: ColorType;
    gridLineDashStyle?: DashStyleValue;
    plotBands?: Array<AxisPlotBandsOptions>;
    plotLines?: Array<AxisPlotLinesOptions>;
    crosshair?: boolean | AxisCrosshairOptions;
}

interface AxisCrosshairLabelOptions {
    align?: AlignValue;
    backgroundColor?: ColorType;
    borderColor?: ColorType;
    borderRadius?: number;
    borderWidth?: number;
    enabled?: boolean;
    format?: string;
    formatter?: FormatterCallback<Axis>;
}

Best Practices

When using multiple Y-axes, set opposite: true on secondary axes to position them on the right side for better clarity.

1. Clarity - Always include descriptive axis titles
2. Range - Set appropriate min and max values to avoid misleading visualizations
3. Labels - Rotate labels when they overlap, or use staggerLines for alternating positions
4. Performance - For datetime axes with large datasets, set tickPixelInterval to reduce tick count
5. Accessibility - Use contrasting colors for grid lines and ensure labels are readable

Logarithmic axes cannot display zero or negative values. Ensure your data contains only positive numbers when using type: 'logarithmic'.

Next Steps

Data Handling

Learn about data formats and loading

Series Configuration

Configure data series

Responsive Charts

Make axes responsive to screen size

API Reference

Complete axis API documentation