JavaScript ChartsBubble Series

Version 14.3.0

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

Simple Bubble Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  BubbleSeriesModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { femaleHeightWeight, maleHeightWeight } from "./height-weight-data";

ModuleRegistry.registerModules([
  BubbleSeriesModule,
  LegendModule,
  NumberAxisModule,
]);

const options: AgChartOptions = {
  title: {
    text: "Weight vs Height",
  },
  subtitle: {
    text: "by gender",
  },
  series: [
    {
      type: "bubble",
      title: "Male",
      data: maleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      sizeKey: "age",
      sizeName: "Age",
    },
    {
      type: "bubble",
      title: "Female",
      data: femaleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      sizeKey: "age",
      sizeName: "Age",
    },
  ],
  axes: {
    x: {
      type: "number",
      title: {
        text: "Height",
      },
      label: {
        formatter: (params) => {
          return params.value + "cm";
        },
      },
    },
    y: {
      type: "number",
      title: {
        text: "Weight",
      },
      label: {
        formatter: (params) => {
          return params.value + "kg";
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

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.

Size Copy Link

main.ts

import {
  AgBubbleSeriesOptions,
  AgCartesianChartOptions,
  AgCharts,
  AgMarkerSizeMode,
  BubbleSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

ModuleRegistry.registerModules([BubbleSeriesModule, NumberAxisModule]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "Store Performance",
  },
  subtitle: {
    text: "Bubble size shows annual revenue",
  },
  series: [
    {
      type: "bubble",
      xKey: "footfall",
      xName: "Weekly Footfall",
      yKey: "conversion",
      yName: "Conversion Rate",
      sizeKey: "revenue",
      sizeName: "Revenue",
      labelKey: "store",
      sizeMode: "diameter",
      minSize: 4,
      maxSize: 60,
      sizeDomain: [0, 250],
      label: {
        enabled: true,
        placement: ["inside", "top", "bottom"],
        truncate: false,
        formatter: ({ datum }) => `$${datum.revenue}m`,
      },
    },
  ],
  axes: {
    x: {
      type: "number",
      title: {
        text: "Weekly Footfall",
      },
    },
    y: {
      type: "number",
      title: {
        text: "Conversion Rate",
      },
    },
  },
  formatter: {
    x: "#{~f}k",
    y: "#{~f}%",
    size: "$#{~f}m",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function setSizeMode(event: Event) {
  (options.series![0] as AgBubbleSeriesOptions).sizeMode = (
    event.target as HTMLInputElement
  ).value as AgMarkerSizeMode;

  chart.update(options);
}

function setMinSize(event: Event) {
  const value = Number((event.target as HTMLInputElement).value);
  (options.series![0] as AgBubbleSeriesOptions).minSize = value;

  document.getElementById("minSizeValue")!.innerHTML = String(value);
  chart.update(options);
}

function setMaxSize(event: Event) {
  const value = Number((event.target as HTMLInputElement).value);
  (options.series![0] as AgBubbleSeriesOptions).maxSize = value;

  document.getElementById("maxSizeValue")!.innerHTML = String(value);
  chart.update(options);
}

function setSizeDomain(event: Event) {
  const value = (event.target as HTMLInputElement).value;
  (options.series![0] as AgBubbleSeriesOptions).sizeDomain =
    value === "data"
      ? undefined
      : (value.split(",").map(Number) as [number, number]);

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setSizeMode = setSizeMode;
  (<any>window).setMinSize = setMinSize;
  (<any>window).setMaxSize = setMaxSize;
  (<any>window).setSizeDomain = setSizeDomain;
}

The values defined by sizeKey set the size domain for each series. Marker sizes are interpolated linearly from minSize for the lowest value to maxSize for the highest.

{
    series: [
        {
            type: 'bubble',
            // ...
            sizeKey: 'revenue',
            sizeName: 'Revenue',
            sizeMode: 'diameter', // defaults to 'diameter'
            minSize: 4, // defaults to 7
            maxSize: 60, // defaults to 30
            sizeDomain: [0, 250], // defaults to the series data domain
        },
    ],
}

In the above example:

sizeKey provides the numerical values determining the size of each bubble.
sizeName is optional and configures the display name reflected in Tooltips.
minSize sets the size of the marker for the lowest value and maxSize sets the size of the marker for the highest value.
sizeMode sets how values determine marker sizes. See Size Mode for more details.
sizeDomain sets the value domain to between 0 and 250. See Size Domain for more details.

Size Mode Copy Link

With the default 'diameter' size mode, the marker diameter grows with the value. With 'area', the marker area grows instead. The area is only strictly proportional to the value when minSize is 0 and sizeDomain starts at 0.

Size Domain Copy Link

By default, the size domain is the range of sizeKey values in the series data. Use sizeDomain to set it manually, for example to keep bubble sizes comparable across multiple Bubble Series in the same chart. Values outside the domain are clamped to minSize or maxSize.

To reverse the mapping so that larger values produce smaller markers, reverse the sizeDomain bounds, for example sizeDomain: [100, 0].

Customisation Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  BubbleSeriesModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { femaleHeightWeight, maleHeightWeight } from "./height-weight-data";

ModuleRegistry.registerModules([
  BubbleSeriesModule,
  LegendModule,
  NumberAxisModule,
]);

const options: AgChartOptions = {
  title: {
    text: "Weight vs Height",
  },
  subtitle: {
    text: "by Gender",
  },
  series: [
    {
      type: "bubble",
      title: "Male",
      data: maleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      sizeKey: "age",
      sizeName: "Age",
      shape: "square",
      fill: "#e36f6ab5",
      stroke: "#9f4e4a",
    },
    {
      type: "bubble",
      title: "Female",
      data: femaleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      sizeKey: "age",
      sizeName: "Age",
      shape: "circle", // default
      fill: "#7b91deb5",
      stroke: "#56659b",
    },
  ],
  axes: {
    x: {
      type: "number",
      title: {
        text: "Height",
      },
      label: {
        formatter: (params) => {
          return params.value + "cm";
        },
      },
    },
    y: {
      type: "number",
      title: {
        text: "Weight",
      },
      label: {
        formatter: (params) => {
          return params.value + "kg";
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

Customise the fill, stroke and shape of the markers used in the Bubble Series.

{
    series: [
        {
            //...
            shape: 'square',
            fill: '#e36f6ab5',
            stroke: '#9f4e4a',
        },
    ],
}

In the above example, the 'Female' 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 Copy Link

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

main.ts

import {
  AgBubbleSeriesOptions,
  AgCartesianChartOptions,
  AgCharts,
  BubbleSeriesModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { femaleHeightWeight, maleHeightWeight } from "./height-weight-data";

ModuleRegistry.registerModules([
  BubbleSeriesModule,
  LegendModule,
  NumberAxisModule,
]);

const options: AgCartesianChartOptions = {
  title: {
    text: "Weight vs Height",
  },
  subtitle: {
    text: "With Name Labels",
  },
  series: [
    {
      type: "bubble",
      title: "Male",
      data: maleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      sizeKey: "age",
      sizeName: "Age",
      labelKey: "name",
      labelName: "Name",
      shape: "square",
      fill: "#e36f6ab5",
      stroke: "#9f4e4a",
      label: { enabled: true },
    },
    {
      type: "bubble",
      title: "Female",
      data: femaleHeightWeight,
      xKey: "height",
      xName: "Height",
      yKey: "weight",
      yName: "Weight",
      labelName: "Name",
      sizeKey: "age",
      sizeName: "Age",
      labelKey: "name",
      fill: "#7b91deb5",
      stroke: "#56659b",
      label: {
        enabled: true,
      },
    },
  ],
  axes: {
    x: {
      type: "number",
      title: {
        text: "Height",
      },
      label: {
        formatter: (params) => {
          return params.value + "cm";
        },
      },
    },
    y: {
      type: "number",
      title: {
        text: "Weight",
      },
      label: {
        formatter: (params) => {
          return params.value + "kg";
        },
      },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function updateFontSize(event: any) {
  const value = Number(event.target.value);
  (options.series![0] as AgBubbleSeriesOptions).label!.fontSize = value;
  (options.series![1] as AgBubbleSeriesOptions).label!.fontSize = value;

  document.getElementById("fontSizeSliderValue")!.innerHTML = String(value);
  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).updateFontSize = updateFontSize;
}

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 font size of the labels to see how that affects label placement.

See Series Labels: Collision Avoidance for more details.

Colour Scale Copy Link

Supply a colorKey to colour each marker by a data value, and customise the colouring via colorScale.

main.ts

import {
  AgCartesianChartOptions,
  AgCharts,
  BubbleSeriesModule,
  GradientLegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  BubbleSeriesModule,
  GradientLegendModule,
  NumberAxisModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "Product Portfolio",
  },
  subtitle: {
    text: "Bubble size shows annual revenue, colour shows profit margin",
  },
  series: [
    {
      type: "bubble",
      xKey: "marketShare",
      xName: "Market Share",
      yKey: "growth",
      yName: "Revenue Growth",
      sizeKey: "revenue",
      sizeName: "Revenue",
      colorKey: "margin",
      colorName: "Profit Margin",
      fillOpacity: 0.9,
      colorScale: {
        fills: [{ color: "#dd3497" }, { color: "#1d91c0" }],
      },
      strokeWidth: 0,
      minSize: 8,
      maxSize: 40,
    },
  ],
  axes: {
    x: {
      type: "number",
      title: {
        text: "Market Share",
      },
    },
    y: {
      type: "number",
      title: {
        text: "Revenue Growth",
      },
    },
  },
  gradientLegend: {
    position: {
      placement: "right",
      yOffset: -55,
    },
    gradient: {
      preferredLength: 240,
    },
    scale: {
      padding: 6,
      interval: {
        step: 5,
      },
    },
  },
  formatter: {
    x: "#{~f}%",
    y: "#{~f}%",
    size: "$#{,.0f}m",
    color: "#{~f}%",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

See the Colour Scale page for the full configuration reference including custom fills, discrete bins, and the Gradient Legend.

Large Datasets Copy Link

By default, a maximum of 2000 markers per series are rendered. Items beyond this limit are aggregated to improve performance whilst maintaining the same visual appearance. Use maxRenderedItems to increase this limit if needed.

See Large Dataset Interactivity for more details.

Bubble Chart Examples Copy Link

See more Bubble Chart examples in the AG Charts Gallery.

Bubble Chart Example

Multiple Bubble Series Chart Example

Bubble Chart With Categories Example

Bubble Chart With Images Example

Bubble Chart With Patterns Example

Bubble Chart With Custom SVG Patterns Example

API Reference Copy Link

Properties available on the AgBubbleSeriesOptions interface.

type required 'bubble': Configuration for Bubble Series.
xKey required DatumKey: The key to use to retrieve x-values from the data.
yKey required DatumKey: The key to use to retrieve y-values from the data.
sizeKey required DatumKey: The key to use to retrieve size values from the data, used to control the size of the markers.
id string default: auto-generated value: Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
context ContextDefault: Context object to use in callbacks.
data DatumDefault[]: The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean: Whether to display the series.
focusIndex number: Position of the series in the keyboard focus order within other series. Series with a lower value are focused first, instead of the declared order in the `series` array.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
selection AgSelectionOptions: Configuration for data selection.
nodeClickRange InteractionRange: Range from a node that a click triggers the listener.
showInLegend boolean: Whether to include the series in the legend.
listeners AgSeriesListeners: A map of event names to event listeners.
xKeyAxis string default: 'x': The key of the x-axis to which this series is bound.
yKeyAxis string default: 'y': The key of the y-axis to which this series is bound.
sizeDomain [AgNumericValue, AgNumericValue]: Explicitly specifies the extent of the domain of `sizeKey` values to map onto the `[minSize, maxSize]` range. Reverse the bounds (e.g. `[100, 0]`) to invert the mapping so that larger values produce smaller markers.
minSize PixelSize default: 7: Determines the smallest size a marker can be in pixels. `sizeKey` values at the lower end of `sizeDomain` map to this size.
maxSize PixelSize default: 30: Determines the largest size a marker can be in pixels. `sizeKey` values at the upper end of `sizeDomain` map to this size.
sizeMode AgMarkerSizeMode default: 'diameter': Determines if the marker diameter or area grows with the `sizeKey` values. In `'area'` mode the area is only strictly proportional to the value when `minSize` is `0` and `sizeDomain` starts at `0`.
maxRenderedItems number default: 2000: Determines the largest number of items that can be rendered at once. If there are more items, they will be aggregated to resemble similar visual appearance.
title string: The title to use for the series. Defaults to `yName` if it exists, or `yKey` if not.
label AgBubbleSeriesLabel: Configuration for the labels shown on top of data points.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
styler Styler: Function used to return formatting for entire series, based on the given parameters.
itemStyler Styler: Function used to return formatting for individual markers, based on the supplied information.
highlight AgMultiSeriesHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
colorScale AgColorScale: Configuration for colour scale with fills, domain, and mode.
shape AgMarkerShape: The shape to use for the markers. You can also supply a custom marker by providing a `AgMarkerShapeFn` function.
fill AgColorType: The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
fillOpacity Opacity: The opacity of the fill colour.
stroke AgCssColorOrRef: The colour for the stroke.
strokeWidth PixelSize: The width of the stroke in pixels.
strokeOpacity Opacity: The opacity of the stroke colour.
lineDash PixelSize[]: An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize: The initial offset of the dashed line in pixels.
showInMiniChart boolean: Whether to include the series in the Mini Chart.
labelKey DatumKey: The key to use to retrieve values from the data to use as labels for the markers.
colorKey DatumKey: The key to use to retrieve colour values from the data. This value (along with `colorScale` config) will be used to determine the marker colour.
xName string: A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yName string: A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
sizeName string: A human-readable description of the size values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
labelName string: A human-readable description of the label values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
colorName string: A human-readable description of the colour values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
legendItemName string: The text to display in the legend for this series. If supplied, matching items with the same value will be toggled together.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsBubble Series

Simple Bubble Copy Link

Size Copy Link

Size Mode Copy Link

Size Domain Copy Link

Customisation Copy Link

Labels Copy Link

Colour Scale Copy Link

Large Datasets Copy Link

Bubble Chart Examples Copy Link

API Reference Copy Link