Class: Series

Highcharts. Series

new Series(chart, options)

This is the base series prototype that all other series types inherit from. A new series is initialized either through the series option structure, or after the chart is initialized, through Highcharts.Chart#addSeries.

The object can be accessed in a number of ways. All series and point event handlers give a reference to the series object. The chart object has a series property that is a collection of all the chart's series. The point objects and axis objects also have the same reference.

Another way to reference the series programmatically is by id. Add an id in the series configuration options, and get the series object by Highcharts.Chart#get.

Configuration options for the series are given in three levels. Options for all series in a chart are given in the plotOptions.series object. Then options for all series of a specific type are given in the plotOptions of that type, for example plotOptions.line. Next, options for one single series are given in the series array, or as arguments to chart.addSeries.

The data in the series is stored in various arrays.

  • First, series.options.data contains all the original config options for each point whether added by options or methods like series.addPoint.

  • Next, series.data contains those values converted to points, but in case the series data length exceeds the cropThreshold, or if the data is grouped, series.data doesn't contain all the points. It only contains the points that have been created on demand.

  • Then there's series.points that contains all currently visible point objects. In case of cropping, the cropped-away points are not part of this array. The series.points array starts at series.cropStart compared to series.data and series.options.data. If however the series data is grouped, these can't be correlated one to one.

  • series.xData and series.processedXData contain clean x values, equivalent to series.data and series.points.

  • series.yData and series.processedYData contain clean y values, equivalent to series.data and series.points.

Parameters:
Name Type Description
chart Highcharts.Chart

The chart instance.

options Highcharts.SeriesOptionsType | object

The series options.

Members

area :Highcharts.SVGElement|undefined

SVG element of area-based charts. Can be used for styling purposes. If zones are configured, this element will be hidden and replaced by multiple zone areas, accessible via series['zone-area-x'] (where x is a number, starting with 0).

Type:

chart :Highcharts.Chart

Read only. The chart that the series belongs to.

Type:

data :Array.<Highcharts.Point>

Read only. An array containing those values converted to points. In case the series data length exceeds the cropThreshold, or if the data is grouped, series.data doesn't contain all the points. Also, in case a series is hidden, the data array may be empty. To access raw values, series.options.data will always be up to date. Series.data only contains the points that have been created on demand. To modify the data, use Highcharts.Series#setData or Highcharts.Point#update.

Type:
See also:
  • Highcharts.Series.points

graph :Highcharts.SVGElement|undefined

SVG element of line-based charts. Can be used for styling purposes. If zones are configured, this element will be hidden and replaced by multiple zone lines, accessible via series['zone-graph-x'] (where x is a number, starting with 0).

Type:

name :string

The series name as given in the options. Defaults to "Series {n}".

Type:
  • string

options :Highcharts.SeriesOptionsType

Read only. The series' current options. To update, use Highcharts.Series#update.

Type:
  • Highcharts.SeriesOptionsType

points :Array.<Highcharts.Point>

An array containing all currently visible point objects. In case of cropping, the cropped-away points are not part of this array. The series.points array starts at series.cropStart compared to series.data and series.options.data. If however the series data is grouped, these can't be correlated one to one. To modify the data, use Highcharts.Series#setData or Highcharts.Point#update.

Type:

selected :boolean

Read only. The series' selected state as set by Highcharts.Series#select.

Type:
  • boolean

type :string

Read only. The series' type, like "line", "area", "column" etc. The type in the series options anc can be altered using Highcharts.Series#update.

Type:
  • string

visible :boolean

Read only. The series' visibility state as set by Highcharts.Series#show, Highcharts.Series#hide, or in the initial configuration.

Type:
  • boolean

xAxis :Highcharts.Axis

Read only. The unique xAxis object associated with the series.

Type:

yAxis :Highcharts.Axis

Read only. The unique yAxis object associated with the series.

Type:

Methods

addPoint(options [, redraw] [, shift] [, animation] [, withEvent])

Add a point to the series after render time. The point can be added at the end, or by giving it an X value, to the start or in the middle of the series.

Parameters:
Name Type Argument Default Description
options number | object | Array.<(number|string)> | null

The point options. If options is a single number, a point with that y value is appended to the series. If it is an array, it will be interpreted as x and y values respectively. If it is an object, advanced options as outlined under series.data are applied.

redraw boolean <optional>
true

Whether to redraw the chart after the point is added. When adding more than one point, it is highly recommended that the redraw option be set to false, and instead Highcharts.Chart#redraw is explicitly called after the adding of points is finished. Otherwise, the chart will redraw after adding each point.

shift boolean <optional>
false

If true, a point is shifted off the start of the series as one is appended to the end.

animation boolean | Highcharts.AnimationOptionsObject <optional>

Whether to apply animation, and optionally animation configuration.

withEvent boolean <optional>
true

Used internally, whether to fire the series addPoint event.

Fires:
  • Highcharts.Series#event:addPoint
Try it

animate(init)

Animate in the series. Called internally twice. First with the init parameter set to true, which sets up the initial state of the animation. Then when ready, it is called with the init parameter undefined, in order to perform the actual animation. After the second run, the function is removed.

Parameters:
Name Type Description
init boolean

Initialize the animation.

drawGraph()

Draw the graph. Called internally when rendering line-like series types. The first time it generates the series.graph item and optionally other series-wide items like series.area for area charts. On subsequent calls these items are updated with new positions and attributes.

drawPoints()

Draw the markers for line-like series types, and columns or other graphical representation for Highcharts.Point objects for other series types. The resulting element is typically stored as Highcharts.Point.graphic, and is created on the first call and updated and moved on subsequent calls.

getName()

Return series name in "Series {Number}" format or the one defined by a user. This method can be simply overridden as series name format can vary (e.g. technical indicators).

Returns:
string .

The series name.

getPlotBox()

Get the translation and scale for the plot area of this series.

Returns:

getValidPoints( [points] [, insideOnly] [, allowNull])

Return the series points with null points filtered out.

Parameters:
Name Type Argument Default Description
points Array.<Highcharts.Point> <optional>

The points to inspect, defaults to Highcharts.Series.points.

insideOnly boolean <optional>
false

Whether to inspect only the points that are inside the visible view.

allowNull boolean <optional>
false

Whether to allow null points to pass as valid points.

Returns:
Array.<Highcharts.Point> .

The valid points.

hide()

Hide the series if visible. If the chart.ignoreHiddenSeries option is true, the chart is redrawn without this series.

Fires:
  • Highcharts.Series#event:hide
Try it

markerAttribs(point [, state])

Get non-presentational attributes for a point. Used internally for both styled mode and classic. Can be overridden for different series types.

Parameters:
Name Type Argument Description
point Highcharts.Point

The Point to inspect.

state string <optional>

The state, can be either hover, select or undefined.

See also:
  • Highcharts.Series#pointAttribs
Returns:
Highcharts.SVGAttributes .

A hash containing those attributes that are not settable from CSS.

onMouseOut()

Runs on mouse out of the series graphical items.

Fires:
  • Highcharts.Series#event:mouseOut

onMouseOver()

Runs on mouse over the series graphical items.

Fires:
  • Highcharts.Series#event:mouseOver

remove( [redraw] [, animation] [, withEvent])

Remove a series and optionally redraw the chart.

Parameters:
Name Type Argument Default Description
redraw boolean <optional>
true

Whether to redraw the chart or wait for an explicit call to Highcharts.Chart#redraw.

animation boolean | Highcharts.AnimationOptionsObject <optional>

Whether to apply animation, and optionally animation configuration.

withEvent boolean <optional>
true

Used internally, whether to fire the series remove event.

Fires:
  • Highcharts.Series#event:remove
Try it

removePoint(i [, redraw] [, animation])

Remove a point from the series. Unlike the Highcharts.Point#remove method, this can also be done on a point that is not instanciated because it is outside the view or subject to Highstock data grouping.

Parameters:
Name Type Argument Default Description
i number

The index of the point in the data array.

redraw boolean <optional>
true

Whether to redraw the chart after the point is added. When removing more than one point, it is highly recommended that the redraw option be set to false, and instead Highcharts.Chart#redraw is explicitly called after the adding of points is finished.

animation boolean | Highcharts.AnimationOptionsObject <optional>

Whether and optionally how the series should be animated.

Fires:
  • Highcharts.Point#event:remove
Try it

render()

Render the graph and markers. Called internally when first rendering and later when redrawing the chart. This function can be extended in plugins, but normally shouldn't be called directly.

Fires:
  • Highcharts.Series#event:afterRender

select( [selected])

Select or unselect the series. This means its selected property is set, the checkbox in the legend is toggled and when selected, the series is returned by the Highcharts.Chart#getSelectedSeries function.

Parameters:
Name Type Argument Description
selected boolean <optional>

True to select the series, false to unselect. If undefined, the selection state is toggled.

Fires:
  • Highcharts.Series#event:select
  • Highcharts.Series#event:unselect
Try it

setCompare(compare)

Highstock only. Set the compare mode of the series after render time. In most cases it is more useful running Highcharts.Axis#setCompare on the X axis to update all its series.

Parameters:
Name Type Description
compare string

Can be one of null, "percent" or "value".

setData(data [, redraw] [, animation] [, updatePoints])

Apply a new set of data to the series and optionally redraw it. The new data array is passed by reference (except in case of updatePoints), and may later be mutated when updating the chart data.

Note the difference in behaviour when setting the same amount of points, or a different amount of points, as handled by the updatePoints parameter.

Parameters:
Name Type Argument Default Description
data Array.<*>

Takes an array of data in the same format as described under series.{type}.data for the given series type, for example a line series would take data in the form described under series.line.data.

redraw boolean <optional>
true

Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call Highcharts.Chart#redraw after.

animation Highcharts.AnimationOptionsObject <optional>

When the updated data is the same length as the existing data, points will be updated by default, and animation visualizes how the points are changed. Set false to disable animation, or a configuration object to set duration or easing.

updatePoints boolean <optional>
true

When this is true, points will be updated instead of replaced whenever possible. This occurs a) when the updated data is the same length as the existing data, b) when points are matched by their id's, or c) when points can be matched by X values. This allows updating with animation and performs better. In this case, the original array is not passed by reference. Set false to prevent.

Try it

setState( [state] [, inherit])

Set the state of the series. Called internally on mouse interaction operations, but it can also be called directly to visually highlight a series.

Parameters:
Name Type Argument Description
state string <optional>

Can be either hover or undefined to set to normal state.

inherit boolean <optional>

Determines if state should be inherited by points too.

setVisible( [visible] [, redraw])

Show or hide the series.

Parameters:
Name Type Argument Default Description
visible boolean <optional>

True to show the series, false to hide. If undefined, the visibility is toggled.

redraw boolean <optional>
true

Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call chart.redraw() after.

Fires:
  • Highcharts.Series#event:hide
  • Highcharts.Series#event:show

show()

Show the series if hidden.

Fires:
  • Highcharts.Series#event:show
Try it

sonify(options)

Sonify a series.

Parameters:
Name Type Description
options Highcharts.SonifySeriesOptionsObject

The options for sonifying this series.

Requires:
  • module:modules/sonification
Try it

translate()

Translate data points from raw data values to chart specific positioning data needed later in the drawPoints and drawGraph functions. This function can be overridden in plugins and custom series type implementations.

Fires:
  • Highcharts.Series#events:translate

update(options [, redraw])

Update the series with a new set of options. For a clean and precise handling of new options, all methods and elements from the series are removed, and it is initialized from scratch. Therefore, this method is more performance expensive than some other utility methods like Highcharts.Series#setData or Highcharts.Series#setVisible.

Note that Series.update may mutate the passed data options.

Parameters:
Name Type Argument Default Description
options Highcharts.SeriesOptionsType

New options that will be merged with the series' existing options.

redraw boolean <optional>
true

Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call Highcharts.Chart#redraw after.

Fires:
  • Highcharts.Series#event:update
  • Highcharts.Series#event:afterUpdate
Try it