Javascript ChartsBubble Series

javascript logo

A Bubble Series extends the Scatter Series by using the size of each marker to represent a third variable.

Simple Bubble

To create a Bubble Series use the 'bubble' series type, and provide a sizeKey for the variable that will determine the size of each bubble or marker.

series: [
    {
        type: 'bubble',
        xKey: 'height',
        yKey: 'weight',
        sizeKey: 'age',
        xName: 'Height',
        yName: 'Weight',
        sizeName: 'Age',
        title: 'Male',
    },
],

In this configuration:

  • xKey defines the numerical values for the x axis, and is mapped by default to a Number.
  • yKey provides the numerical values for the y axis, and is mapped by default to a Number Axis.
  • sizeKey provides the numerical values determining the size of each bubble.
  • xName, yName and sizeName are optional and configure display names, reflected in Tooltips.
  • title is optional and is used in the Tooltip Titles and Legend Items.

Markers

Size

The values defined by sizeKey are used to calculate the marker size domain for each series. Markers are sized proportionally between the lowest and highest values.

It is possible to use marker.size to set the minimum possible marker size, and marker.maxSize to set the maximum possible marker size.

To manually set the value domain used to calculate the size, use marker.domain. This is particularly useful when showing multiple Bubble Series in the same chart.

marker: {
    size: 10, //defaults to 7
    maxSize: 20, //defaults to 30
    domain: [0, 100], //defaults to the series data domain
}

Using the above configuration

  • The size domain is set to between 0 and 100.
  • A value of 0 will be represented by a marker of size 10.
  • A value of 100 will be represented by a marker of size 20.
  • A value of 50 will be represented by a marker the size of 15.

Customisation

It is possible to customise the fill, stroke and shape of the markers used in the Bubble Series.

marker: {
    shape: 'square',
    fill: '#e36f6ab5',
    stroke: '#9f4e4a',
},

In the above example, the 'females' series uses 'circle' markers and the 'male' series uses 'square' markers.

Please see the Series Markers page for more information or the API Reference for a list of all available marker options.

Labels

To show labels for a Bubble Series set the label.enabled config of a series to true and specify which key should be used to fetch the label values.

Bubble Series label placement is constrained so that:

  • Labels don't overlap any markers.
  • Labels don't overlap other labels.

If these constraints are not satisfied, a label is not placed.

Try opening the above example in a larger window to see that more labels are placed as the chart gets bigger. You can also try changing the size of the markers and the font size of the labels to see how that affects label placement.

Satisfying these constraints is computationally intensive and the complexity rises exponentially with increasing number of data points. Given that label placement might have to happen in real time, for example, when resizing a chart window, it is advised not to enable Bubble Series labels for data sets with more than a few hundred points.

API Reference