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

<static> types :Highcharts.Dictionary.<typeof_Highcharts.Series>

Registry of all available series types.

Type:
  • Highcharts.Dictionary.<typeof_Highcharts.Series>

center :Array.<number>

The series center position, read only. This applies only to circular chart types like pie and sunburst. It is an array of [centerX, centerY, diameter, innerDiameter].

Type:
  • Array.<number>

chart :Highcharts.Chart

Read only. The chart that the series belongs to.

Type:

color :Highcharts.ColorType|undefined

Series color as used by the legend and some series types.

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. In case of cropping, the data array may contain undefined values, instead of points. 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

<readonly> dataMax :number|undefined

Contains the maximum value of the series' data point. Some series types like networkgraph do not support this property as they lack a y-value.

Type:
  • number | undefined

<readonly> dataMin :number|undefined

Contains the minimum value of the series' data point. Some series types like networkgraph do not support this property as they lack a y-value.

Type:
  • number | undefined

<readonly> index :number

Contains the series' index in the Chart.series array.

Type:
  • number

legendItem :Highcharts.LegendItemObject|undefined

Legend data for the series.

Type:
Since:
  • 10.3.0

<readonly> linkedParent :Highcharts.Series

The parent series of the current series, if the current series has a linkedTo setting.

Type:

<readonly> linkedSeries :Array.<Highcharts.Series>

All child series that are linked to the current series through the linkedTo option.

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:

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

userOptions :Highcharts.SeriesOptionsType

Contains series options by the user without defaults.

Type:

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

<static> registerType(seriesType, SeriesClass)

Registers a series class to be accessible via Series.types.

Parameters:
Name Type Description
seriesType string

The series type as an identifier string in lower case.

SeriesClass function

The series class as a class pattern or a constructor function with prototype.

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 Highcharts.PointOptionsType

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 | Partial.<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.

Parameters:
Name Type Argument Description
init boolean <optional>

Initialize the animation.

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.

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.

groupData(xData, yData, groupPositions [, approximation])

Highcharts Stock only. Takes parallel arrays of x and y data and groups the data into intervals defined by groupPositions, a collection of starting x values for each group.

Parameters:
Name Type Argument Description
xData Array.<number>

Parallel array of x data.

yData Array.<(number|null|undefined)> | Array.<Array.<(number|null|undefined)>>

Parallel array of y data.

groupPositions Array.<number>

Group positions.

approximation string | function <optional>

Approximation to use.

Returns:

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

is(type)

Check whether the series item is itself or inherits from a certain series type.

Parameters:
Name Type Description
type string

The type of series to check for, can be either featured or custom series types. For example column, pie, ohlc etc.

Returns:
boolean .

True if this item is or inherits from the given type.

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 | Partial.<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 instantiated because it is outside the view or subject to Highcharts Stock 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 | Partial.<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

searchPoint(e [, compareX])

Find the nearest point from a pointer event. This applies to series that use k-d-trees to get the nearest point. Native pointer events must be normalized using Pointer.normalize, that adds chartX and chartY properties.

Parameters:
Name Type Argument Default Description
e Highcharts.PointerEvent

The normalized pointer event

compareX boolean <optional>
false

Search only by the X value, not Y

Returns:
Highcharts.Point | undefined .

The closest point to the pointer event

Try it

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

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.<Highcharts.PointOptionsType>

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 boolean | Partial.<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 Highcharts.SeriesStateValue | "" <optional>

The new state, can be either 'hover', 'inactive', 'select', or '' (an empty string), 'normal' 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( [onEnd])

Play a sonification of a series.

Parameters:
Name Type Argument Description
onEnd Highcharts.SonificationChartEventCallback <optional>

Callback to call after play completed

Requires:
  • module:modules/sonification

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