angular-highcharts

An Angular wrapper for Highcharts, providing easy integration of Highcharts, Highstock, Highmaps, and Highcharts Gantt charts into your Angular applications.

Table of Contents

• Requirements
• Installation
• Usage
• API Documentation
• Using Highcharts Modules
• Troubleshooting
• Demo
• Contributing
• License

Requirements

| Package | Version | |---------|---------| | Angular | >=21.0.0 | | Highcharts | >=11.0.0 |

Installation

Install both angular-highcharts and highcharts:

npm

npm install --save angular-highcharts highcharts

yarn

yarn add angular-highcharts highcharts

pnpm

pnpm add angular-highcharts highcharts

Usage

Step 1: Import the Module

Import ChartModule in your Angular module:

// app.module.ts
import { ChartModule } from 'angular-highcharts';

@NgModule({
  imports: [
    ChartModule // Add ChartModule to your imports
  ]
})
export class AppModule {}

Step 2: Create a Chart Component

// chart.component.ts
import { Component } from '@angular/core';
import { Chart } from 'angular-highcharts';

@Component({
  selector: 'app-chart',
  template: `
    <button (click)="add()">Add Point</button>
    <div [chart]="chart"></div>
  `
})
export class ChartComponent {
  chart = new Chart({
    chart: {
      type: 'line'
    },
    title: {
      text: 'Line Chart Example'
    },
    credits: {
      enabled: false
    },
    series: [{
      name: 'Line 1',
      data: [1, 2, 3],
      type: 'line'
    }]
  });

  // Add a point to the chart series
  add() {
    this.chart.addPoint(Math.floor(Math.random() * 10));
  }
}

Working with Chart Reference

Use the ref$ observable to access the Highcharts chart instance:

import { Component, OnInit } from '@angular/core';
import { Chart } from 'angular-highcharts';

export class ChartComponent implements OnInit {
  chart = new Chart({
    // ... chart options
  });

  ngOnInit() {
    this.chart.ref$.subscribe(chart => {
      // Access the Highcharts.Chart instance
      console.log(chart);
      
      // Use Highcharts API methods
      chart.setTitle({ text: 'Updated Title' });
    });
  }
}

API Documentation

Chart

Standard Highcharts chart for line, bar, pie, and other basic chart types.

Type: class

Constructor

new Chart(options: Highcharts.Options)

Properties

ref$: Observable<Highcharts.Chart>

Observable that emits the initialized Highcharts.Chart instance. Use this to access the chart API.

See Official Highcharts API Docs

chart.ref$.subscribe(chartInstance => {
  // Work with the chart
  chartInstance.setTitle({ text: 'New Title' });
});

ref: Highcharts.Chart ⚠️ Deprecated

Direct reference to the chart. Deprecated - use ref$ observable instead.

Methods

addPoint(point: number | [number, number] | Highcharts.PointOptionsObject, serieIndex?: number, redraw?: boolean, shift?: boolean): void

Adds a point to a series.

Parameters:

• point - The point to add (number, tuple, or object)
• serieIndex - Index of the series (default: 0)
• redraw - Whether to redraw the chart (default: true)
• shift - Whether to shift the first point off (default: false)

Example:

this.chart.addPoint(10);
this.chart.addPoint([Date.now(), 25], 0, true, false);

removePoint(pointIndex: number, serieIndex?: number, redraw?: boolean, shift?: boolean): void

Removes a point from a series.

Parameters:

• pointIndex - Index of the point to remove
• serieIndex - Index of the series (default: 0)
• redraw - Whether to redraw the chart (default: true)
• shift - Whether to shift (default: false)

addSeries(series: Highcharts.SeriesOptionsType): void

Adds a new series to the chart.

Example:

this.chart.addSeries({
  name: 'New Series',
  data: [1, 2, 3, 4],
  type: 'line'
});

removeSeries(seriesIndex: number): void

Removes a series from the chart by index.

init(el: ElementRef): void

Initializes the chart. Called automatically by the directive.

destroy(): void

Destroys the chart and cleans up resources.

StockChart

Highstock chart for financial and time-series data with advanced features like range selectors and navigator.

Type: class

Constructor

new StockChart(options: Highcharts.Options)

Properties

ref$: Observable<Highcharts.Chart>

Observable that emits the initialized Highstock chart instance.

ref: Highcharts.Chart ⚠️ Deprecated

Direct reference to the chart. Deprecated - use ref$ observable instead.

Example

import { StockChart } from 'angular-highcharts';

stockChart = new StockChart({
  rangeSelector: {
    selected: 1
  },
  series: [{
    name: 'Stock Price',
    data: [[Date.UTC(2023, 0, 1), 100], [Date.UTC(2023, 0, 2), 105]],
    type: 'line'
  }]
});

MapChart

Highmaps chart for geographical data visualization.

Type: class

Constructor

new MapChart(options: Highcharts.Options)

Properties

ref$: Observable<Highcharts.Chart>

Observable that emits the initialized Highmaps chart instance.

ref: Highcharts.Chart ⚠️ Deprecated

Direct reference to the chart. Deprecated - use ref$ observable instead.

Example

import { MapChart } from 'angular-highcharts';
import worldMap from '@highcharts/map-collection/custom/world.geo.json';

mapChart = new MapChart({
  chart: {
    map: worldMap
  },
  title: {
    text: 'World Map'
  },
  series: [{
    type: 'map',
    name: 'Countries',
    data: [/* map data */]
  }]
});

HighchartsGantt

Highcharts Gantt chart for project management and scheduling visualization.

Type: class

Constructor

new HighchartsGantt(options: Highcharts.Options)

Properties

ref$: Observable<Highcharts.Chart>

Observable that emits the initialized Gantt chart instance.

Example

import { HighchartsGantt } from 'angular-highcharts';

ganttChart = new HighchartsGantt({
  title: {
    text: 'Project Timeline'
  },
  series: [{
    type: 'gantt',
    name: 'Tasks',
    data: [/* gantt data */]
  }]
});

Using Highcharts Modules

Highcharts provides additional modules for extended functionality (exporting, 3D charts, annotations, etc.). To use these modules with angular-highcharts:

Important Notes

1. Use ESM imports: Import from highcharts/esm/ for proper tree-shaking and module resolution
2. Use .src suffix: Import modules with .src. in the path for AOT compatibility
3. Default imports: Use default imports (recommended) or namespace imports
4. Factory pattern: Provide modules using a factory function (required for AOT)
5. Location: Most modules are in highcharts/esm/modules/, except highcharts-more.src which is in the root

Available Modules

You can find available modules in your node_modules/highcharts/esm/modules/ directory:

ls -la node_modules/highcharts/esm/modules/

Popular modules include:

• exporting.src - Chart export functionality
• export-data.src - Export chart data to CSV/Excel
• accessibility.src - Accessibility features
• annotations.src - Chart annotations
• boost.src - Performance boost for large datasets
• drilldown.src - Drilldown functionality
• no-data-to-display.src - Message when no data available

Example

// app.module.ts
import { ChartModule, HIGHCHARTS_MODULES } from 'angular-highcharts';
import more from 'highcharts/esm/highcharts-more.src';
import exporting from 'highcharts/esm/modules/exporting.src';
import exportData from 'highcharts/esm/modules/export-data.src';
import accessibility from 'highcharts/esm/modules/accessibility.src';

@NgModule({
  imports: [ChartModule],
  providers: [
    { 
      provide: HIGHCHARTS_MODULES, 
      useFactory: () => [more, exporting, exportData, accessibility]
    }
  ]
})
export class AppModule { }

Module-Specific Usage

After registering modules, you can use their features in your chart options:

chart = new Chart({
  chart: { type: 'line' },
  exporting: {
    enabled: true,  // Enabled by exporting module
    buttons: {
      contextButton: {
        menuItems: ['downloadPNG', 'downloadJPEG', 'downloadPDF']
      }
    }
  },
  // ... other options
});

Troubleshooting

TypeScript Type Errors

If you encounter TypeScript errors when building or serving your Angular app, especially with specialized chart types like gauges or custom options:

// Cast options to any to bypass type checking
chart = new Chart({
  // gauge or custom options
} as any);

This is particularly useful for:

• Gauge charts
• Custom chart types
• Advanced configurations not fully typed in @types/highcharts

Module Import Errors

Problem: Cannot find module 'highcharts/modules/exporting.src'

Solution: Ensure you're using the .src suffix and default imports:

// ✅ Correct - ESM default import (recommended)
import exporting from 'highcharts/esm/modules/exporting.src';

// ✅ Also works - Namespace import (still supported)
import * as exporting from 'highcharts/esm/modules/exporting.src';

// ❌ Wrong - Missing .src suffix
import exporting from 'highcharts/esm/modules/exporting';

Note: This library uses ESM imports internally (highcharts/esm/...). Both default and namespace import styles work for module registration.

Chart Not Rendering

Common causes:

1. ChartModule not imported in your module
2. Chart container has no height - add CSS: div { height: 400px; }
3. Chart initialization happens before the view is ready - use ngAfterViewInit() or ref$ observable

Memory Leaks

Always destroy charts in ngOnDestroy():

ngOnDestroy() {
  this.chart.destroy();
}

More Help

• Official Highcharts Documentation
• Highcharts API Reference
• Installing from npm

Demo

• 🚀 Live Demo
• 💻 Source Code

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Coding standards and conventions
• Commit message guidelines
• Pull request process

Before submitting a PR, please:

1. Check existing issues and PRs
2. Follow the commit message format
3. Add tests for new features
4. Update documentation as needed

Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Ask a question

License

MIT © Felix Itzenplitz

Made with ❤️ for the Angular community