Highcharts Angular

Official minimal Highcharts integration for Angular.

Table of Contents

1. Getting Started
   1. General Prerequisites
   2. Installing
   3. Usage
   4. SSR Support
   5. Angular Elements and useHTML
   6. Upgrade to v5
2. Options Details
3. Chart Instance
4. Highcharts Partial Loading on the Component Level
   1. Loading a Module
   2. Loading a Map for Highcharts Maps
   3. Loading a Map for Highcharts Stock
   4. Loading a Wrapper
5. Demo App
   1. Play with the App
   2. Files to Modify
6. Online Examples
7. Release
8. Help and FAQ

---

Getting Started

General Prerequisites

Ensure that Node.js, npm, and Angular are installed and up to date. Refer to the compatibility table below for the required versions:

Highcharts Angular Version	Node.js	Angular	Highcharts	Documentation
5.0.0	>=18.19	>=19.0.0	>=12.2.0	README
4.0.0	>=16.14	>=16.0.0	>=11.0.0	README
3.1.2	>=14.13	>=15.0.0	>=10.3.3	README
3.0.0	>=14.13	>=9.0.0	>=8.0.0	README
<2.10.0	>=6.10.2	>=6.0.0	>=6.0.0	README

---

Installing

Install the highcharts-angular package along with the highcharts dependency:

npm install highcharts-angular highcharts --save

Then, provide Highcharts with minimal configuration in your app.config.ts file:

import { provideHighcharts } from 'highcharts-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHighcharts(),
    // Other providers here ...
  ]
};

Or, alternatively, provide global configuration for all charts within your project:

import { provideHighcharts } from 'highcharts-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHighcharts({
      // Optional: Define the Highcharts instance dynamically
      instance: () => import('highcharts'),

      // Global chart options applied across all charts
      options: {
        title: {
          style: {
            color: 'tomato'
          }
        },
        legend: {
          enabled: false
        }
      },

      // Include Highcharts additional modules (e.g., exporting, accessibility) or custom themes
      modules: () => {
        return [
          import('highcharts/esm/modules/accessibility'),
          import('highcharts/esm/modules/exporting'),
          import('highcharts/esm/themes/sunset')
        ]
      }
    }),
    // Other providers here ...
  ]
};

Usage

You can use Highcharts in your Angular application either as a Component or a Directive. Below are the usage examples for both approaches:

---

1. Using the Component

In your app.component.ts, import the required HighchartsChartComponent and other relevant types at the top of the file:

import { Component } from '@angular/core';
import { HighchartsChartComponent, ChartConstructorType } from 'highcharts-angular';

@Component({
  template: `
    <highcharts-chart
      [constructorType]="chartConstructor"
      [options]="chartOptions"
      [(update)]="updateFlag"
      [oneToOne]="oneToOneFlag"
      class="chart"
    />
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartComponent]
})
export class AppComponent {
  chartOptions: Highcharts.Options = { ... }; // Required
  chartConstructor: ChartConstructorType = 'chart'; // Optional, defaults to 'chart'
  updateFlag: boolean = false; // Optional
  oneToOneFlag: boolean = true; // Optional, defaults to false
}

2. Using the Directive

In your app.component.ts, import the HighchartsChartDirective and other relevant types at the top of the file:

import {Component} from '@angular/core';
import { HighchartsChartDirective, ChartConstructorType } from 'highcharts-angular';

@Component({
  template: `
    <div
      highchartsChart
      [constructorType]="chartConstructor"
      [options]="chartOptions"
      [(update)]="updateFlag"
      [oneToOne]="oneToOneFlag"
      class="chart"
    ></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective]
})
export class AppComponent {
  chartOptions: Highcharts.Options = { ... }; // Required
  chartConstructor: ChartConstructorType = 'chart'; // Optional, defaults to 'chart'
  updateFlag: boolean = false; // Optional
  oneToOneFlag: boolean = true; // Optional, defaults to false
}

3. Example

This is the minimum example you can start with:

import { Component } from '@angular/core';
import { HighchartsChartDirective } from 'highcharts-angular';

@Component({
  template: `
    <div highchartsChart [options]="chartOptions" class="chart"></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective]
})
export class AppComponent {
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
}

Build and run your Angular app to see a basic line chart.

Used options are explained below.

SSR Support

Both the component and directive in this library are fully compatible with Angular Universal (SSR).

In SSR, the code runs twice: once on the server (in an environment without a window object) and once in the browser. Since Highcharts is tightly integrated with browser events, it should not run on the server-side. But don’t worry—we’ve already handled this case for you! 😉

Our showcase application includes an example of SSR integration. You can try it by running:

ng serve my-ssr-app --open

Angular Elements and useHTML

First, install angular elements:

npm install @angular/elements --save

Include in main.ts file your element tag inside allowedTags and element properties inside allowedAttributes:

if (Highcharts && Highcharts.AST) {
  Highcharts.AST.allowedTags.push('translation-element');
  Highcharts.AST.allowedAttributes.push('translation-key');
}

Define your element in the constructor of the component that will use it:

private defineTranslationElement() {
  if (isNil(customElements.get('translation-element'))) {
    const translationElement = createCustomElement(TranslationComponent, {injector: this.injector});
    customElements.define('translation-element', translationElement);
  }
}

Then, create the element, set properties and use it in the chart:

const translationEl: NgElement & WithProperties<TranslationComponent> = document.createElement(translationElementTag);
translationEl.setAttribute('translation-key', 'shared.title');      

const chartOptions: Highcharts.Options = {
  title: {
    text: translationEl.outerHTML,
    useHTML: true,
  },
  ...
}

For a more detailed view take a look at the Online Examples - Angular Elements and useHTML

Upgrade to v5

Version 5 introduces significant improvements and changes to align with modern Angular practices. Please review the following breaking changes before upgrading:

Breaking Changes

• Dropped HighchartsChartModule. Replace your usage of HighchartsChartModule with the new provideHighcharts() and the standalone HighchartsChartComponent or HighchartsChartDirective.
• Dropped callbackFunction. Replace your usage of [callbackFunction]="myFunction" with (chartInstance)="myFunction($event)".
• chartInstance will not emit at all during destruction anymore.

Options details

Parameter	Type	Required	Defaults	Description
[constructorType]	ChartConstructorType	No	'chart'	A string for the constructor method. Official constructors include: - 'chart' for Highcharts charts - 'stockChart' for Highcharts Stock - 'mapChart' for Highcharts Maps - 'ganttChart' for Highcharts Gantt Note that 'stockChart', 'mapChart', and 'ganttChart' require loading the appropriate package or module.
[options]	Object	Yes	-	The chart options as described in the Highcharts API reference. A minimal working object for basic testing is { series:[{ data:[1, 2] }] }.
[(update)]	Boolean	No	-	A boolean to trigger a chart update. Angular does not detect nested changes in objects passed to a component. Set the corresponding variable (updateFlag in the example) to true, and after the update is done, it will asynchronously change back to false by the Highcharts Angular component.
[oneToOne]	Boolean	No	false	The oneToOne parameter for updates. When true, the series, xAxis, and yAxis collections will be updated one to one, and items will be added or removed to match the updated options. For example, if a chart has two series, calling chart.update with a configuration containing three series will add one. Similarly, calling chart.update with one series will remove one. Setting an empty series array removes all series, while leaving out the series property leaves them untouched. If the series have ids, new series options will be matched by id, and the remaining ones will be removed. This option is demonstrated in the demo. Try setting new chart options with different numbers of series in the textarea input to see it in action.

Chart instance

A chart instance can be obtained using the following methods:

• Component output chartInstance - Emitted after the chart is created (see demo app and the logChartInstance function).
• Chart's events - The context of all chart's events functions is the chart instance.

Note: If you are obtaining the chart instance from the chart's load event, and you plan to support exporting, the function will run again when the chart is exported. This is because a separate chart is created for export. To distinguish between the main chart and the export chart, you can check chart.renderer.forExport. It will be set to true for the export chart and undefined for the main chart.

Highcharts Partial Loading on the Component Level

A Highcharts instance is optionally initialized with modules, maps, wrappers, and set global options using setOptions. The core is required.

Note: The Highcharts instance is shared across components in an Angular app, meaning that loaded modules will affect all charts.

Since highcharts-angular 5.0.0, you can provide extra modules on demand to your chart at the component level:

Example

To load a module

A module is a Highcharts official addon - including Highcharts Stock Technical Indicators, style themes, specialized series types (e.g. Bullet, Venn).

After importing Highcharts, Highcharts Stock, or Highcharts Maps, use providePartialHighcharts and initialize modules with an array of Highcharts factory functions.

If a lack of TypeScript definitions d.ts is showing as an error - see Solving problems section of Highcharts documentation for TypeScript usage.

import { Component } from '@angular/core';
import { HighchartsChartDirective } from 'highcharts-angular';

@Component({
  template: `
    <div highchartsChart [options]="chartOptions" class="chart"></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective],
  providers: [
    providePartialHighcharts({ 
      modules: () => {
        return [
          // Load Gantt Chart 
          import('highcharts/esm/modules/gantt'),
          // Load exporting module
          import('highcharts/esm/modules/exporting'),
        ]
      }
    })
  ],
})
export class GanttComponent {
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
}

To load a map for Highcharts Maps

Official map collection is published and here are basic instructions for loading a map. A full example can also be found in the demo app.

import { Component } from '@angular/core';
import { HighchartsChartDirective } from 'highcharts-angular';

@Component({
  template: `
    <div highchartsChart [options]="chartOptions" class="chart"></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective],
  providers: [providePartialHighcharts({ modules: () => [import('highcharts/esm/modules/map')] })],
})
export class MapComponent {
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
}

To load a stock for Highcharts

import { Component } from '@angular/core';
import { HighchartsChartDirective } from 'highcharts-angular';

@Component({
  template: `
    <div highchartsChart [options]="chartOptions" class="chart"></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective],
  providers: [providePartialHighcharts({ modules: () => [import('highcharts/esm/modules/stock')] })],
})
export class StockComponent {
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
}

To load a wrapper

A wrapper is a custom extension for Highcharts. To load a wrapper in the same way as a module, save it as a JavaScript file and add the following code to the beginning and end of the file:

(function (factory) {
  if (typeof module === 'object' && module.exports) {
    module.exports = factory;
  } else {
    factory(Highcharts);
  }
}(function (Highcharts) {

...
/* wrapper code */
...

}));

Next, you will be loading a local .js file, so add allowJs: true to the tsconfig.json in your app:

{
  "compilerOptions": {
    "allowJs": true
  }
}

The wrapper is now ready to be imported into your app. Use require instead of import to prevent TS5055 errors:

import { Component } from '@angular/core';
import { HighchartsChartDirective } from 'highcharts-angular';


@Component({
  template: `
    <div highchartsChart [options]="chartOptions" class="chart"></div>
  `,
  styles: [`.chart { width: 100%; height: 400px; display: block; }`],
  imports: [HighchartsChartDirective],
  providers: [providePartialHighcharts({ modules: () => [import('./relative-path-to-the-wrapper-file/wrapper-file-name')] })],
})
export class StockComponent {
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
}

Where relative-path-to-the-wrapper-file is the relative path (from the module importing the wrapper) to the wrapper file, and wrapper-file-name is the name of the wrapper file.

If TypeScript definitions (d.ts) are missing and causing errors, see the Solving problems section of the Highcharts documentation for TypeScript usage.

Demo app

Download (or clone) the contents of the highcharts-angular GitHub repository.
The demo app does not rely on external dependencies but instead builds the highcharts-angular package, so it's necessary to run npm start to generate this package.

In your system console, in the main repo folder, run:

npm install

1. Start Default:

npm start

2. Start with SSR:

npm start:ssr

The command npm start will launch the default app, while npm start:ssr will start the server-side rendering (SSR) version. Both versions can be accessed at http://localhost:4200/ in your default browser.

To open the app on a different port (e.g., 12345), use:

npm start -- --port 12345

Play with the app

Keep the console running, and modify files — after saving, the app will automatically rebuild and refresh in the localhost preview.

Files to play with

• app.component.ts (located in src\app)

This file contains the main Angular component, which utilizes different components like line-chart, gantt-chart, map-chart, and stock-chart.

Online examples

• Basic line
• Stock
• Stock + indicators
• Stock + GUI
• Map
• Gantt
• Map + mapppoints with lat/lon
• Map + mapppoints with proj4
• Optimal way to update
• Data from the service
• Property XXX does not exist on type YYY
• Using portals to render an angular component within a chart
• Angular Elements and useHTML

Release

Using Angular CLI v19, the library must be manually rebuilt on each change in order to reflect in the demo app.

Run the following command on each change to the highcharts-chart.directive.ts file:

npm run build

If you are running the demo app in another terminal window when you rebuild the library, the changes should be reflected in your browser (note: you may need to refresh the browser a second time after the live reload in order to see the change).

For CHANGELOG.md update use :

npm run release

Help and FAQ

For technical support please contact Highcharts technical support.

For TypeScript problems with Highcharts first see Highcharts documentation for TypeScript usage.

FAQ:

How to add and use indicators?

Add indicators as any other module. Live demo

How to add and use themes?

Add themes as any other module. See the demo app in this repository for an example.

More info about custom themes in Highcharts general documentation.

I have a general issue with Highcharts and TypeScript

The correct repository to report such issues is main Highcharts repository.

Synchronized Charts Angular demo

Based on original Highcharts demo for Synchronized charts.

Additionally added class based sync between charts - demo.

Property XXX does not exist on type YYY

It is happening when you are trying to use non-existing property or one of our internal properties that are not publicly available for example axis.dataMin. To fix that you need to create your own type that will extend the default Highcharts one with the new properties. Then all you need to do is to cast the selected option / to the extended type - demo.

How to use Highcharts Maps with the proj4?

Install the proj4 library and its types @types/proj4. Then pass it to chartOptions.chart.proj4 property. See the demo app in this repository or live demo example.

I want to render angular component in the tooltip/axis formatter

To render angular component within the chart you can use the angular portals - demo