angular-highcharts

!Build Status

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:

$3

``bash
npm install --save angular-highcharts highcharts
`

$3

`bash
yarn add angular-highcharts highcharts
`

$3

`bash
pnpm add angular-highcharts highcharts
`

Usage

$3

Import ChartModule in your Angular module:

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

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

$3

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

@Component({
selector: 'app-chart',
template:
Add Point

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

$3

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

`typescript
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

$3

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

Type: class

#### Constructor

`typescript
new Chart(options: Highcharts.Options)
`

#### Properties

##### ref$: Observable

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

See Official Highcharts API Docs

`typescript
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:
`typescript
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:
`typescript
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.

$3

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

Type: class

#### Constructor

`typescript
new StockChart(options: Highcharts.Options)
`

#### Properties

##### ref$: Observable

Observable that emits the initialized Highstock chart instance.

##### ref: Highcharts.Chart ⚠️ Deprecated

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

#### Example

`typescript
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'
}]
});
`

$3

Highmaps chart for geographical data visualization.

Type: class

#### Constructor

`typescript
new MapChart(options: Highcharts.Options)
`

#### Properties

##### ref$: Observable

Observable that emits the initialized Highmaps chart instance.

##### ref: Highcharts.Chart ⚠️ Deprecated

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

#### Example

`typescript
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 /]
}]
});
`

$3

Highcharts Gantt chart for project management and scheduling visualization.

Type: class

#### Constructor

`typescript
new HighchartsGantt(options: Highcharts.Options)
`

#### Properties

##### ref$: Observable

Observable that emits the initialized Gantt chart instance.

#### Example

`typescript
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:

$3

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

$3

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

`bash
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

$3

`typescript
// 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 { }
`

$3

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

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

Troubleshooting

$3

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

`typescript
// 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

$3

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

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

`typescript
// ✅ 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.

$3

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

$3

Always destroy charts in ngOnDestroy():

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

$3

- 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