nuxt-highcharts

Highcharts for Nuxt

Setup

Add nuxt-highcharts dependency to your project

yarn add nuxt-highcharts # or npm install nuxt-highcharts

These are the module's required dependencies:
- highcharts - The charting library.
These are the module's optional dependencies:
- @highcharts/map-collection - Collection of maps to use with Highmap. Please be aware of their LICENSE. This module uses it strictly for demo purposes (and is non-profit, open-source).

NOTE: if you chose not to install the optional dependencies, you will most likely want to use webpack's ignorePlugin to ignore the missing dependency. Otherwise, you'll be faced with either build warnings or errors.

In nuxt.config, you would just need to add:

import webpack from 'webpack' // npm i -D webpack 

module.exports = {
  ...
  build: {
    plugins: [
      new webpack.IgnorePlugin({
        resourceRegExp: /\@highcharts\/map\-collection/
      })
    ],
  }
  ...
}

Add nuxt-highcharts to the modules section of nuxt.config.js

{
  modules: [
    // Simple usage
    'nuxt-highcharts',

    // With options
    ['nuxt-highcharts', { /* module options */ }]
  ],
  highcharts: {
    /* module options */
  }
}

Module Options

setOptions - [Object] options to use globally, that get sent to Highcharts.setOptions. Useful tip: import('highcharts/highcharts').Options to get intellisense suggestions
chartOptions - [Object] Default chart options to use for the highchart components. These get wired to Highcharts. Useful tip: import('highcharts/highcharts').Options to get intellisense suggestions
exporting - [Boolean] Enable/disable the exporting feature globally
mapChart - [Object] Default options for the Highmap chart
- mapName - [String] name to use for the mapChat, default: "myMapName"
- mapData - [Object|string] data to use for the map, default: world.geo.json. This can also be the JSON's url, which gets consumed by window.fetch

The above options can also be provided as props to the highcharts components. When provided as props, the props will be used instead. The demo passes most options, except exporting, as props since different components will have different requirements.Some options you may want to be applied globally however.

Usage

Module

The module adds a plugin which registers the following components:

highchart - The basic chart component (but still very powerful! see the demo)
highstock - The highstock chart component
highmap - The highmap chart component
sunburst - The sunburst chart

The highstock and highmap components are simply variants of the basic highchart component which accepts the following props:

highcharts - [Object] The Highcharts instance to use, default: Highcharts imported by the plugin (from node_modules/highcharts).
setOptions - [Object] the setOptions to use. Default: moduleOptions.setOptions.
options - [Object] The chartOptions to use, default: moduleOptions.chartOptions. (Heads up: Might get renamed to chartOptions someday)
redraw - [Boolean] Redraw option for Chart.update
oneToOne - [Boolean] One-to-One option for Chart.update
animation - [Object] Animation options Chart.update. This is where you can specify animation duration.
exporting - [Boolean] Enable / disable exporting. NOTE: the module options for exporting are applied to the default Highchart instance. If you wish to apply different exporting setting to a specific chart, this is a case where you'd have to pass in your own highcharts instance using the "highcharts" prop.
update - [Array] Contains an array of specific options to watch. Is extremely useful for speeding up the reactivity! Default: ["options"]. The following watchers are currently supported:
- "options": watch deep all the options' properties. Easy to use, but can impact performance.
- "options.caption"
- "options.series"
- "options.subtitle"
- "options.title"
- "options.yAxis"
- "options.xAxis"

The highmap component also adds the following prop:

mapChart - S/A module options

The plugin will also inject $highcharts into the current context, so that on any component, you can access the following properties:

$highcharts.chartTypes - various chart types
$highcharts.components - the components registered by the plugin
$highcharts.variants - the variant names for the components; probably extraneous, but is used by the demo to auto generate the navbar links.

Events

chartLoaded - emitted after successfully mounting any of the above components. It will provide an instance of the chart, so should you wish to use the Highchart API directly you can using that instance.

Examples:

For the impatient that "just need it to work", this is your easiest option!

<highchart :options="chartOptions" />

If you plan to only change the title and series data, this will update the chart faster than the previous example:

<highchart 
  :options="chartOptions" 
  :update="['options.title', 'options.series']" 
/>

Looking for more? The most up-to-date examples are in this git repo!. The demo uses this repo directly!

Beta features

As of v1.0.6: The "modules" prop - takes an array of strings that specify the highcharts modules to use. Specifically, this looks in node_modules/highcharts/modules/*.js for the modules to auto import, and then the modules prop just specifies them by name (as of 1.0.6 "map" is the only module with a supported data handler in nuxt-highcharts; others may be added if the issues arise). Some modules require extra data to be set, such as the map chart. When that is the case, nuxt-highcharts dynamically creates a prop for that module. So, the map module would also consume data passed to the "map" prop:

<highchart 
  :modules="['map']"
  :map="mapChart"
  :options="chartOptions" 
  :update="watchers"
/>

data() {
  return {
    title: 'Highmaps (Africa) basic demo',
    mapChart: {
      // It's important for mapName to match exactly
      // chartOptions.chart.map below 
      // (since that's where the library renders to)
      mapName: 'africa',
      mapData: AfricaMapData,
      // mapData: '/africa.geo.json' // Also works (if this is in static folder)
    },
    watchers: ['options.title']
  }
}

Deprecation of older features

It is possible that the "highstock", "highmap" and "sunburst" charts will become obsolete because the highchart component with the modules prop should create the exact same charts (and many more charts, now that all the highcharts modules get auto scanned)

Development

Clone this repository
Install dependencies using yarn install or npm install
Start development server using npm run dev

License

MIT License

vmas4u / nuxt-highcharts