Configuration Options

Comprehensive guide to Highcharts global options, setOptions, and configuration patterns for customizing charts.

Configuration Options

Highcharts provides a powerful and flexible options system that allows you to customize every aspect of your charts. Understanding how to structure and apply options is key to creating professional visualizations.

Options Structure

Highcharts options are organized hierarchically in a configuration object:

Highcharts.chart('container', {
    // Chart-level options
    chart: { /* chart configuration */ },
    title: { /* title configuration */ },
    subtitle: { /* subtitle configuration */ },
    
    // Axes
    xAxis: { /* x-axis configuration */ },
    yAxis: { /* y-axis configuration */ },
    
    // Series data
    series: [{ /* series configuration */ }],
    
    // Feature modules
    tooltip: { /* tooltip configuration */ },
    legend: { /* legend configuration */ },
    plotOptions: { /* series type defaults */ },
    
    // Accessibility
    accessibility: { /* accessibility options */ },
    
    // Export/print
    exporting: { /* export configuration */ },
    
    // Responsive
    responsive: { /* responsive rules */ }
});

Global Options

Set global options that apply to all charts using Highcharts.setOptions():

Basic Usage

// Set global options once
Highcharts.setOptions({
    lang: {
        loading: 'Loading...',
        months: ['January', 'February', 'March', 'April', 'May', 'June',
                 'July', 'August', 'September', 'October', 'November', 'December'],
        weekdays: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 
                   'Thursday', 'Friday', 'Saturday'],
        numericSymbols: ['k', 'M', 'G', 'T', 'P', 'E']
    },
    colors: ['#058DC7', '#50B432', '#ED561B', '#DDDF00', '#24CBE5',
             '#64E572', '#FF9655', '#FFF263', '#6AF9C4'],
    chart: {
        backgroundColor: '#f9f9f9',
        style: {
            fontFamily: 'Arial, sans-serif'
        }
    },
    credits: {
        enabled: false
    }
});

// All charts created after will use these defaults
Highcharts.chart('container1', { /* ... */ });
Highcharts.chart('container2', { /* ... */ });

Language Options

Highcharts.setOptions({
    lang: {
        // Localization
        locale: 'en-US',
        
        // Date/time
        months: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio',
                 'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'],
        shortMonths: ['Ene', 'Feb', 'Mar', 'Abr', 'May', 'Jun',
                      'Jul', 'Ago', 'Sep', 'Oct', 'Nov', 'Dic'],
        weekdays: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 
                   'Jueves', 'Viernes', 'Sábado'],
        
        // UI strings
        loading: 'Cargando...',
        resetZoom: 'Restablecer zoom',
        resetZoomTitle: 'Restablecer nivel de zoom 1:1',
        
        // Number formatting
        decimalPoint: ',',
        thousandsSep: '.',
        numericSymbols: ['k', 'M', 'G', 'T', 'P', 'E'],
        numericSymbolMagnitude: 1000
    }
});

Global Theme

// Custom theme
Highcharts.setOptions({
    colors: ['#2b908f', '#90ee7e', '#f45b5b', '#7798BF', 
             '#aaeeee', '#ff0066', '#eeaaee', '#55BF3B',
             '#DF5353', '#7798BF', '#aaeeee'],
    chart: {
        backgroundColor: {
            linearGradient: { x1: 0, y1: 0, x2: 1, y2: 1 },
            stops: [
                [0, '#2a2a2b'],
                [1, '#3e3e40']
            ]
        },
        style: {
            fontFamily: '\'Unica One\', sans-serif'
        },
        plotBorderColor: '#606063'
    },
    title: {
        style: {
            color: '#E0E0E3',
            fontSize: '20px'
        }
    },
    xAxis: {
        gridLineColor: '#707073',
        labels: {
            style: {
                color: '#E0E0E3'
            }
        },
        lineColor: '#707073',
        tickColor: '#707073',
        title: {
            style: {
                color: '#A0A0A3'
            }
        }
    },
    yAxis: {
        gridLineColor: '#707073',
        labels: {
            style: {
                color: '#E0E0E3'
            }
        },
        lineColor: '#707073',
        tickColor: '#707073',
        title: {
            style: {
                color: '#A0A0A3'
            }
        }
    },
    legend: {
        backgroundColor: 'rgba(0, 0, 0, 0.5)',
        itemStyle: {
            color: '#E0E0E3'
        }
    }
});

PlotOptions

Define default options for each series type using plotOptions:

Highcharts.chart('container', {
    plotOptions: {
        // Options for all series types
        series: {
            animation: true,
            dataLabels: {
                enabled: false
            },
            enableMouseTracking: true,
            events: {
                // Global series events
            }
        },
        
        // Options specific to line charts
        line: {
            lineWidth: 2,
            marker: {
                enabled: false
            },
            shadow: false
        },
        
        // Options specific to column charts
        column: {
            borderWidth: 0,
            pointPadding: 0.1,
            groupPadding: 0.1,
            dataLabels: {
                enabled: true
            }
        },
        
        // Options specific to pie charts
        pie: {
            allowPointSelect: true,
            cursor: 'pointer',
            dataLabels: {
                enabled: true,
                format: '{point.name}: {point.percentage:.1f}%'
            },
            showInLegend: true
        }
    },
    series: [{
        type: 'line',
        data: [1, 2, 3, 4, 5]
        // Inherits plotOptions.line and plotOptions.series
    }]
});

Options Hierarchy

Understand how options are merged and prioritized:

Priority Order

// 1. Global defaults (Highcharts.defaultOptions)
// 2. Global setOptions
Highcharts.setOptions({
    colors: ['#FF0000', '#00FF00']
});

// 3. Chart-level options
Highcharts.chart('container', {
    // 4. PlotOptions for series type
    plotOptions: {
        line: {
            color: '#0000FF'  // Overrides global colors for lines
        }
    },
    
    // 5. Individual series options (highest priority)
    series: [{
        type: 'line',
        color: '#FFFF00'  // Overrides plotOptions.line.color
    }]
});

Options Interface

TypeScript interface from Options.ts:

interface Options {
    chart?: ChartOptions;
    title?: TitleOptions;
    subtitle?: SubtitleOptions;
    xAxis?: XAxisOptions | Array<XAxisOptions>;
    yAxis?: YAxisOptions | Array<YAxisOptions>;
    series?: Array<SeriesTypeOptions>;
    plotOptions?: SeriesTypePlotOptions;
    tooltip?: TooltipOptions;
    legend?: LegendOptions;
    credits?: CreditsOptions;
    exporting?: ExportingOptions;
    navigation?: NavigationOptions;
    responsive?: ResponsiveOptions;
    lang?: LangOptions;
    colors?: Array<ColorString>;
    accessibility?: AccessibilityOptions;
}

interface GlobalOptions {
    buttonTheme?: ButtonThemeObject;
    timezone?: string;
    timezoneOffset?: number;
    useUTC?: boolean;
}

interface LangOptions {
    loading?: string;
    months?: Array<string>;
    shortMonths?: Array<string>;
    weekdays?: Array<string>;
    decimalPoint?: string;
    thousandsSep?: string;
    resetZoom?: string;
    resetZoomTitle?: string;
    numericSymbols?: Array<string>;
    numericSymbolMagnitude?: number;
    locale?: string;
}

Common Configuration Patterns

Color Customization

// Global color palette
Highcharts.setOptions({
    colors: ['#058DC7', '#50B432', '#ED561B', '#DDDF00', '#24CBE5']
});

// Per-chart colors
Highcharts.chart('container', {
    colors: ['#FF0000', '#00FF00', '#0000FF'],
    series: [{
        data: [1, 2, 3]
    }]
});

// Per-series color
series: [{
    color: '#FF6600',
    data: [1, 2, 3]
}]

// Per-point colors
series: [{
    data: [
        { y: 1, color: '#FF0000' },
        { y: 2, color: '#00FF00' },
        { y: 3, color: '#0000FF' }
    ]
}]

Tooltip Configuration

Highcharts.chart('container', {
    tooltip: {
        enabled: true,
        shared: true,
        crosshairs: true,
        backgroundColor: 'rgba(255, 255, 255, 0.85)',
        borderWidth: 1,
        borderColor: '#AAA',
        shadow: true,
        
        // Custom formatting
        formatter: function() {
            let s = '<b>' + this.x + '</b>';
            
            this.points.forEach(function(point) {
                s += '<br/>' + point.series.name + ': ' + point.y;
            });
            
            return s;
        },
        
        // Or use format string
        pointFormat: '<span style="color:{point.color}">●</span> {series.name}: <b>{point.y}</b><br/>',
        
        // Value formatting
        valueDecimals: 2,
        valuePrefix: '$',
        valueSuffix: ' USD'
    }
});

Legend Configuration

Highcharts.chart('container', {
    legend: {
        enabled: true,
        align: 'right',
        verticalAlign: 'middle',
        layout: 'vertical',
        
        backgroundColor: '#FCFFC5',
        borderColor: '#C98657',
        borderWidth: 1,
        borderRadius: 5,
        
        itemStyle: {
            fontSize: '12px',
            fontWeight: 'bold',
            color: '#333'
        },
        
        itemHoverStyle: {
            color: '#000'
        },
        
        itemHiddenStyle: {
            color: '#CCC'
        },
        
        // Custom symbol
        symbolHeight: 12,
        symbolWidth: 12,
        symbolRadius: 6,
        
        // Navigation for long legends
        navigation: {
            enabled: true,
            activeColor: '#3E576F',
            inactiveColor: '#CCC'
        }
    }
});

Credits & Exporting

Highcharts.chart('container', {
    // Disable Highcharts.com link
    credits: {
        enabled: false
        // Or customize:
        // text: 'My Company',
        // href: 'https://example.com'
    },
    
    // Export configuration
    exporting: {
        enabled: true,
        buttons: {
            contextButton: {
                menuItems: [
                    'viewFullscreen',
                    'printChart',
                    'separator',
                    'downloadPNG',
                    'downloadJPEG',
                    'downloadPDF',
                    'downloadSVG',
                    'separator',
                    'downloadCSV',
                    'downloadXLS'
                ]
            }
        },
        filename: 'my-chart',
        chartOptions: {
            // Options for exported chart
            title: {
                text: 'Exported Chart'
            }
        }
    }
});

Option Parameters Reference

colors · string[]

Default colors for the chart’s series. Array of color strings (hex, rgb, rgba).

lang · LangOptions

Language strings and settings for localization.

plotOptions · SeriesTypePlotOptions

Default plotting options for all series types and specific series types.

tooltip · TooltipOptions

Options for the tooltip that appears when the user hovers over a series or point.

legend · LegendOptions

The legend is a box containing a symbol and name for each series item or point item in the chart.

credits · CreditsOptions

Highcharts by default puts a credits label in the lower right corner of the chart.

exporting · ExportingOptions

Options for the exporting module. Requires the exporting module to be loaded.

Real-World Examples

Corporate Theme

Highcharts.setOptions({
    colors: ['#004990', '#0072CE', '#00A4E4', '#41B6E6', '#7ED3F7'],
    chart: {
        backgroundColor: '#FFFFFF',
        style: {
            fontFamily: 'Roboto, sans-serif'
        },
        borderRadius: 8,
        plotBorderWidth: 1,
        plotBorderColor: '#E5E5E5'
    },
    title: {
        style: {
            color: '#333333',
            fontSize: '18px',
            fontWeight: '600'
        },
        align: 'left'
    },
    subtitle: {
        style: {
            color: '#666666',
            fontSize: '14px'
        },
        align: 'left'
    },
    legend: {
        itemStyle: {
            fontSize: '12px',
            color: '#333333'
        },
        itemHoverStyle: {
            color: '#004990'
        }
    },
    credits: {
        enabled: false
    },
    plotOptions: {
        series: {
            animation: {
                duration: 1000
            },
            dataLabels: {
                style: {
                    fontSize: '11px',
                    fontWeight: '400'
                }
            }
        }
    }
});

Dynamic Options Updates

Update chart options after initialization:

const chart = Highcharts.chart('container', { /* initial options */ });

// Update entire chart configuration
chart.update({
    title: {
        text: 'Updated Title'
    },
    colors: ['#FF0000', '#00FF00']
});

// Update with specific merge behavior
chart.update({
    plotOptions: {
        series: {
            animation: false
        }
    }
}, true, true, false);
// (options, redraw, oneToOne, animation)

Best Practices

Use Highcharts.setOptions() for options that should apply to all charts in your application. This ensures consistency and reduces code duplication.

1. Global Defaults - Set common options globally with setOptions()
2. Type Safety - Use TypeScript interfaces for better IDE support
3. Performance - Disable animations for charts with frequent updates
4. Accessibility - Always include accessibility options for better UX
5. Theming - Create reusable themes with setOptions()

Be careful when using Highcharts.setOptions() as it affects all charts created after the call. If you need chart-specific options, pass them in the chart constructor instead.

Next Steps

Chart Configuration

Learn about chart-specific options

Responsive Charts

Make charts adapt to screen size

Themes

Explore pre-built themes

API Reference

Complete options API documentation