Highcharts Angular

Official minimal Highcharts wrapper for Angular

Table of Contents

1. Getting started
   1. General prerequisites
   2. Installing
   3. Hello world demo
2. Options details
3. Chart instance
4. Highcharts instance details
   1. Core
   2. To load a module
   3. To load a plugin
   4. To load a map for Highmaps
   5. To load a wrapper
   6. To use setOptions
5. Demo app
   1. Play with the app
   2. Files to play with
6. Changing the Component
7. Help and FAQ

Getting started

General prerequisites

Make sure you have node, NPM and Angular up to date. Tested and required versions:

• node 6.10.2+
• npm 4.6.1+
• @angular/cli 6.0.0+

Installing

Get package from NPM in your Angular app:

npm install highcharts-angular --save

In your app.module.ts add the HighchartsChartModule:

...
import { HighchartsChartModule } from 'highcharts-angular';

@NgModule({
  imports: [
    ...
    HighchartsChartModule

In a component that will be building your Highcharts charts you will need to import Highcharts first, so in system console, while in your Angular app:

npm install highcharts --save

Next, in the app.component.ts, in top lines where other imports are add another one for Highcharts:

import * as Highcharts from 'highcharts';

In the same file (app.component.ts) add to the template Highcharts-angular component selector highcharts-chart:

<highcharts-chart 
  [Highcharts]="Highcharts"

  [constructorType]="chartConstructor"
  [options]="chartOptions"
  [callbackFunction]="chartCallback"

  [(update)]="updateFlag"
  [oneToOne]="oneToOneFlag"
  [runOutsideAngular]="runOutsideAngularFlag"

  style="width: 100%; height: 400px; display: block;"
></highcharts-chart>

Right side names, in double quotes, are just names of variables you are going to set next, so you could name them whatever you like. Style at the bottom of the selector is optional, but browsers do not know how to display <highcharts-chart>, so you should set some styles.

In the same file (app.component.ts) all variables should be set in export class AppComponent { like:

export class AppComponent {
  Highcharts: typeof Highcharts = Highcharts; // required
  chartConstructor: string = 'chart'; // optional string, defaults to 'chart'
  chartOptions: Highcharts.Options = { ... }; // required
  chartCallback: Highcharts.ChartCallbackFunction = function (chart) { ... } // optional function, defaults to null
  updateFlag: boolean = false; // optional boolean
  oneToOneFlag: boolean = true; // optional boolean, defaults to false
  runOutsideAngular: boolean = false; // optional boolean, defaults to false
  ...

Used options are explained below.

Hello world demo

To create a simple demo start with installing.

Next for app.component.ts's HTML template use:

<highcharts-chart 
  [Highcharts]="Highcharts"
  [options]="chartOptions"

  style="width: 100%; height: 400px; display: block;"
></highcharts-chart>

and export variables:

export class AppComponent {
  Highcharts: typeof Highcharts = Highcharts;
  chartOptions: Highcharts.Options = {
    series: [{
      data: [1, 2, 3],
      type: 'line'
    }]
  };
  ...

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

Options details

1. [Highcharts]="Highcharts"

The option is required. This is a Highcharts instance with required core and optional modules, plugin, maps, wrappers and set global options using setOptions. More detail for the option in the next documentation section.

2. [constructorType]="chartConstructor"

The option is optional. This is a string for constructor method. Possible values:

• 'chart' - for standard Highcharts® constructor - for any Highcharts instance, this is default value

• 'stockChart' - for Highstock® constructor - Highstock or Stock module is required

• 'mapChart' - for Highmaps® constructor - Highmaps or Map module is required

• 'ganttChart' - for Highcharts® Gantt constructor - Highcharts® Gantt or Gantt module is required

3. [options]="chartOptions"

The option is required. Possible chart options could be found in Highcharts API reference. Minimal working object that could be set for basic testing is { series:[{ data:[1, 2] }] }.

4. [callbackFunction]="chartCallback"

The option is optional. A callback function for the created chart. First argument for the function will hold the created chart. Default this in the function points to the chart.

5. [(update)]="updateFlag"

The option is optional. A boolean to trigger update on a chart as Angular is not detecting nested changes in a object passed to a component. Set corresponding variable (updateFlag in the example) to true and after update on a chart is done it will be changed asynchronously to false by Highcharts-angular component.

6. [oneToOne]="oneToOneFlag"

The option is optional, defaults to false. The oneToOne parameter for updates. When true, the series, xAxis and yAxis collections will be updated one to one, and items will be either added or removed to match the new updated options. For example, if the chart has two series and we call chart.update (and this is called on each chart's data change or if updateFlag is set to true) with a configuration containing three series, one will be added. If we call chart.update with one series, one will be removed. Setting an empty series array will remove all series, but leaving out the series property will leave all series untouched. If the series have id's, the new series options will be matched by id, and the remaining ones removed.

The options is presented in the demo in the first chart - try setting new chart options with different amounts of series in the textarea input to see this options in action.

7. [runOutsideAngular]="runOutsideAngularFlag"

The option is optional, defaults to false. When this option is set to true chart is created and updated outside of Angular's zone and Highcharts events do not trigger Angular change-detection. Details about runOutsideAngular are available in Angular documentation. This options is more useful for bigger, more complex application (see discussion).

The option is presented in this demo.

Chart instance

A chart instance could be obtained using:

• chart's callback function - chart is provided as first argument (see demo app and first hcCallback function)
• chart's events - context of all chart's events functions is the chart instance
• component output chartInstance - emitted after chart is created (see demo app and logChartInstance function)

Notice: If you are getting chart instance from chart's load event or chart's callback funciton and will be supporting exporting, then this function runs again when the chart is exported, because a chart for export is being created. To distinguish when the function is called for the chart and when it's called for the for-export chart you could check chart.renderer.forExport. If will be set to true for the for-export chart and undefined for the main chart.

Highcharts instance details

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

Notice: The Highcharts instance is shared through components in an Angular app, so loaded modules will affect all charts.

Core

As core you could load Highcharts, Highstock, Highmaps or Highcharts Gantt (v. 6.2.0+).

• For Highcharts:

import * as Highcharts from 'highcharts';

• For Highstock:

import * as Highcharts from 'highcharts/highstock';

or as Highcharts with stock module:

import * as Highcharts from 'highcharts';
import HC_stock from 'highcharts/modules/stock';
HC_stock(Highcharts);

• For Highmaps:

import * as Highcharts from 'highcharts/highmaps';

or as Highcharts with map module:

import * as Highcharts from 'highcharts';
import HC_map from 'highcharts/modules/map';
HC_map(Highcharts);

• For Highcharts Gantt:

import * as Highcharts from 'highcharts/highcharts-gantt';

or as Highcharts with gantt module:

import * as Highcharts from 'highcharts';
import HC_gantt from 'highcharts/modules/gantt';
HC_gantt(Highcharts);

To load a module

A module is a Highcharts official addon - including Highstock Technical Indicators, style themes, specialized series types (e.g. Bullet, Venn). After Highcharts is imported using Highcharts, Highstock or Highmaps use import and initialize each module on the Highcharts variable.

import * as Highcharts from 'highcharts';
import HC_exporting from 'highcharts/modules/exporting';
HC_exporting(Highcharts);

Alternatively, this could be done with require, but usually (depends on your app configuration) additional declaration declare var require: any; is needed at the top of the TypeScript file in which the modules are loaded.

import * as Highcharts from 'highcharts';
require('highcharts/modules/exporting')(Highcharts);

To load a plugin

A plugin is a third party/community made Highcharts addon (plugins are listed in the Highcharts plugin registry). First, make sure that a plugin support loading over NPM and load the required files. In example Custom-Events supports NPM loading, so after installing the package you could initialize it like:

import * as Highcharts from 'highcharts';
import * as HC_customEvents from 'highcharts-custom-events';
HC_customEvents(Highcharts);

If a plugin doesn't support loading through NPM you could treat it as a wrapper - see instructions below.

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

To load a map for Highmaps

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

To load a wrapper

A wrapper is a custom extension for Highcharts. To load a wrapper the same way as a module you could save it as a Javascript file and edit it by adding below code to beginning and end of a 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 you should add in tsconfig.json in your app allowJs: true:

...
"compilerOptions": {
    "allowJs": true,
    ...

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

import * as Highcharts from 'highcharts';
require('./relative-path-to-the-wrapper-file/wrapper-file-name')(Highcharts);

Where relative-path-to-the-wrapper-file should be relative (for the module importing the wrapper) path to the wrapper file and wrapper-file-name should be the name of the wrapper file.

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

To use setOptions

The best place to use setOptions is after your Highcharts instance is ready and before Highcharts variable is set in the main component. Example:

import * as Highcharts from 'highcharts/highstock';

...

Highcharts.setOptions({
  title: {
    style: {
      color: 'orange'
    }
  }
});

...

export class AppComponent {
  Highcharts: typeof Highcharts = Highcharts;

Demo app

Download (or clone) the contents of the highcharts-angular GitHub repository.

In system console, in main repo folder run:

npm install
npm start

This opens http://localhost:4200/ in your default browser with the app.

To open on a different port, for example 12345, use:

npm start -- --port 12345

Play with the app

Keep the console running and change some files - after a save the app will rebuild and refresh the localhost preview.

Files to play with

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

Contains Angular main component that uses the chart component.

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

Contains the chart component that creates Highcharts chart.

Changing the Component

Using Angular CLI v6, 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.component.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).

See https://github.com/angular/angular-cli/wiki/stories-create-library for details on library builds.

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.