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.SeriesOptions | object

The series options.

Members

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

name :string

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

Type:
  • string

options :Highcharts.PlotSeriesOptions

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

Type:
  • Highcharts.PlotSeriesOptions

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])

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.

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.

getColor()

Get the series' color based on either the options or pulled from global options.

getExtremes( [yData])

Calculate Y extremes for the visible data. The result is set as dataMin and dataMax on the Series item.

Parameters:
Name Type Argument Description
yData Array.<number> <optional>

The data to inspect. Defaults to the current data within the visible range.

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:

getSymbol()

Get the series' symbol based on either the options or pulled from global options.

getValidPoints( [points] [, insideOnly])

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.

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

setOptions(itemOptions)

Set the series options by merging from the options tree. Called internally on initiating and updating series. This function will not redraw the series. For API usage, use Highcharts.Series#update.

Parameters:
Name Type Description
itemOptions Highcharts.PlotSeriesOptions

The series options.

Fires:
  • Highcharts.Series#event:afterSetOptions
Returns:

setState( [state])

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.

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 initiated from scratch. Therefore, this method is more performance expensive than some other utility methods like Highcharts.Series#setData or Highcharts.Series#setVisible.

Parameters:
Name Type Argument Default Description
options Highcharts.SeriesOptions

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:afterUpdate
Try it