Bubble Chart

<wa-bubble-chart>

Pro

Included with Web Awesome Pro

Stable

Bubble charts add a third dimension to scatter plots by varying the size of each data point. They are useful for visualizing relationships where a third variable adds meaning beyond a simple x/y correlation.

Get Bubble Chart with Web Awesome Pro!

Subscribing to Web Awesome Pro gives you every Pro component, plus premium themes, color tools, team collaboration, and more.

Pro Components
Native Styles
CSS + Layout Utilities
Ever-Growing Pattern Library
Unlimited Hosted Projects
Pre-Built Pro Themes
Pro Theme Builder
Pro Color Tools
Official Figma Design Kit
WA Pro Perpetual License
Actual Human™ Support

Get Web Awesome Pro + Bubble Chart!

Already have Pro? Log in

<wa-bubble-chart
  label="City Comparison"
  description="A bubble chart comparing cities by cost of living, quality of life, and population"
>
  <script type="application/json">
    {
      "data": {
        "datasets": [
          {
            "label": "North America",
            "data": [
              { "x": 65, "y": 7.8, "r": 18 },
              { "x": 50, "y": 7.0, "r": 12 },
              { "x": 55, "y": 7.5, "r": 14 }
            ]
          },
          {
            "label": "Europe",
            "data": [
              { "x": 40, "y": 8.2, "r": 16 },
              { "x": 30, "y": 7.6, "r": 10 },
              { "x": 45, "y": 8.0, "r": 13 }
            ]
          }
        ]
      }
    }
  </script>
</wa-bubble-chart>

Unlike bar or line charts, bubble data is an array of {x, y, r} point objects:

Property	Description
`x`	Position along the x-axis
`y`	Position along the y-axis
`r`	Bubble radius in pixels, fixed and not scaled to the axes

See <wa-chart> for advanced configuration, custom plugins, and direct Chart.js access.

Examples

Link to This Section

Providing Data with JSON

Link to This Section

Place a <script type="application/json"> tag inside the component. Each data point is an object with x, y, and r properties. The JSON follows the Chart.js configuration format.

<wa-bubble-chart
  label="Product Analysis"
  description="A bubble chart showing products by price, rating, and sales volume"
>
  <script type="application/json">
    {
      "data": {
        "datasets": [
          {
            "label": "Products",
            "data": [
              { "x": 30, "y": 4.2, "r": 18 },
              { "x": 50, "y": 4.5, "r": 14 },
              { "x": 25, "y": 3.9, "r": 22 },
              { "x": 55, "y": 4.7, "r": 10 },
              { "x": 40, "y": 4.0, "r": 16 }
            ]
          }
        ]
      }
    }
  </script>
</wa-bubble-chart>

Providing Data with JavaScript

Link to This Section

Set the config property from JavaScript when your data comes from code rather than static markup. The chart re-renders automatically each time you assign it. For data that updates at runtime, try the live controls in Accessing the Chart.js Instance.

<wa-bubble-chart
  id="bubble-js-example"
  label="Product Analysis"
  description="A bubble chart of products by price, rating, and volume"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-js-example');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Products',
          data: [
            { x: 30, y: 4.2, r: 18 },
            { x: 50, y: 4.5, r: 14 },
            { x: 25, y: 3.9, r: 22 },
            { x: 55, y: 4.7, r: 10 },
            { x: 40, y: 4.0, r: 16 },
          ],
        },
      ],
    },
  };
</script>

config is shallowly reactive.
If you mutate the object in place, reassign it to trigger a re-render.

Custom Tooltips

Link to This Section

Bubble tooltips show raw x, y, r values by default. Attach a property to each data point and read it in a tooltip callback to name points and spell out what the bubble size means.

<wa-bubble-chart
  id="bubble-tooltips"
  x-label="Price"
  y-label="Rating"
  label="Menu Performance"
  description="A bubble chart whose tooltips name each drink and its sales instead of showing raw coordinates"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-tooltips');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Menu Items',
          data: [
            { x: 3.25, y: 4.3, r: 12, name: 'Drip Coffee' },
            { x: 4.25, y: 4.5, r: 18, name: 'Espresso' },
            { x: 4.75, y: 4.6, r: 22, name: 'Latte' },
            { x: 5.0, y: 4.7, r: 10, name: 'Cold Brew' },
          ],
        },
      ],
    },
    options: {
      plugins: {
        tooltip: {
          callbacks: {
            label: context => {
              const { name, x, y, r } = context.raw;
              return `${name}: $${x}, ${y}★, ${r} sold`;
            },
          },
        },
      },
    },
  };
</script>

Bubble Sizes

Link to This Section

The r property on each data point sets the bubble radius in pixels. Unlike x and y, this value is absolute and not mapped to a chart scale. Use larger values to represent greater magnitude.

<wa-bubble-chart
  id="bubble-size-example"
  label="Investment Portfolio"
  description="A bubble chart where bubble size represents investment amount"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-size-example');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Investments',
          data: [
            { x: 4, y: 12, r: 28 },
            { x: 6, y: 8, r: 14 },
            { x: 7, y: 14, r: 22 },
            { x: 3, y: 7, r: 10 },
            { x: 8, y: 16, r: 18 },
          ],
        },
      ],
    },
  };
</script>

Multiple Datasets

Link to This Section

Use multiple datasets to compare groups of bubbles. Each group gets its own color.

<wa-bubble-chart
  id="bubble-multi"
  label="Industry Comparison"
  description="A bubble chart comparing metrics across two industry sectors"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-multi');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Technology',
          data: [
            { x: 70, y: 8.5, r: 18 },
            { x: 55, y: 7.8, r: 14 },
            { x: 65, y: 8.2, r: 12 },
          ],
        },
        {
          label: 'Healthcare',
          data: [
            { x: 40, y: 7.2, r: 16 },
            { x: 50, y: 7.6, r: 18 },
            { x: 35, y: 7.5, r: 12 },
          ],
        },
      ],
    },
  };
</script>

Colors

Link to This Section

Override the default color palette using the --fill-color-* and --border-color-* CSS custom properties on the component.

<wa-bubble-chart
  id="bubble-colors"
  label="Custom Colors"
  description="A bubble chart with custom colors"
  style="
    --fill-color-1: color-mix(in srgb, var(--wa-color-orange-60) 50%, transparent);
    --border-color-1: var(--wa-color-orange-60);
  "
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-colors');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Menu Items',
          data: [
            { x: 3.25, y: 4.3, r: 16 },
            { x: 4.75, y: 4.6, r: 22 },
            { x: 4.25, y: 4.5, r: 18 },
            { x: 5.0, y: 4.7, r: 14 },
          ],
        },
      ],
    },
  };
</script>

Legend

Link to This Section

Use the legend-position attribute to control where the legend appears. Add without-legend to hide it entirely.

<wa-bubble-chart
  id="bubble-legend"
  legend-position="bottom"
  label="Legend at Bottom"
  description="A bubble chart with the legend at the bottom"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-legend');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Paperbacks',
          data: [
            { x: 320, y: 4.2, r: 16 },
            { x: 280, y: 4.0, r: 14 },
          ],
        },
        {
          label: 'Hardcovers',
          data: [
            { x: 400, y: 4.4, r: 12 },
            { x: 448, y: 4.5, r: 18 },
          ],
        },
      ],
    },
  };
</script>

Grid Lines

Link to This Section

Use the grid attribute to control which axes show grid lines. Options are both (default), x, y, and none.

<wa-bubble-chart id="bubble-grid" grid="none" label="No Grid" description="A bubble chart with grid lines hidden">
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-grid');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Planets',
          data: [
            { x: 0.4, y: 167, r: 9 },
            { x: 0.7, y: 464, r: 21 },
            { x: 1.0, y: 15, r: 22 },
            { x: 1.5, y: -65, r: 12 },
          ],
        },
      ],
    },
  };
</script>

Axis Labels

Link to This Section

Use the x-label and y-label attributes to add descriptive labels to each axis.

<wa-bubble-chart
  id="bubble-axis"
  x-label="Cost Index"
  y-label="Quality Score"
  label="City Analysis"
  description="A bubble chart with labeled axes comparing city cost and quality"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-axis');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Cities',
          data: [
            { x: 40, y: 7.2, r: 16 },
            { x: 55, y: 8.2, r: 18 },
            { x: 50, y: 7.8, r: 12 },
            { x: 60, y: 7.6, r: 10 },
          ],
        },
      ],
    },
  };
</script>

Disabling Features

Link to This Section

Use without-tooltip to hide hover tooltips and without-animation to disable transitions.

<wa-bubble-chart
  id="bubble-disabled"
  without-tooltip
  without-animation
  label="Minimal"
  description="A bubble chart with tooltips and animations disabled"
>
</wa-bubble-chart>
<script type="module">
  const chart = document.querySelector('#bubble-disabled');

  chart.config = {
    data: {
      datasets: [
        {
          label: 'Trails',
          data: [
            { x: 3, y: 6, r: 10 },
            { x: 8, y: 20, r: 18 },
            { x: 5, y: 12, r: 14 },
          ],
        },
      ],
    },
  };
</script>

API

Link to This Section

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN

npm

Self-Hosted

React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/[email protected]/components/bubble-chart/bubble-chart.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/webawesome/dist/components/bubble-chart/bubble-chart.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/bubble-chart/bubble-chart.js';

To import this component for React 18 or below, use the following code:

import WaBubbleChart from '@awesome.me/webawesome/dist/react/bubble-chart/index.js';

Slots

Link to This Section

Learn more about using slots.

Name	Description
(default)	An optional `<script type="application/json">` element containing the Chart.js configuration object.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name	Description	Reflects
`config`	The Chart.js configuration object. Setting this property will automatically re-render the chart. Type `ChartJS['config']`
`description` `description`	A description of the chart, used for accessibility. Type `string \| null` Default `null`
`grid` `grid`	Which axes to show grid lines on. Type `'x' \| 'y' \| 'both' \| 'none'` Default `'both'`
`indexAxis` `index-axis`	The base axis of the dataset. 'x' for vertical bars and 'y' for horizontal bars. Type `'x' \| 'y'` Default `'x'`
`label` `label`	A label for the chart, used for accessibility. Type `string \| null` Default `null`
`legendPosition` `legend-position`	The position of the legend relative to the chart. Type `LayoutPosition \| 'start' \| 'end'` Default `'top'`
`max` `max`	The maximum value for the value axis. Type `number \| null` Default `null`
`min` `min`	The minimum value for the value axis. Type `number \| null` Default `null`
`plugins` `plugins`	Additional Chart.js plugins to register for this chart instance. Type `array` Default `[]`
`stacked` `stacked`	Stacks datasets on top of each other along the value axis. Type `boolean` Default `false`
`type` `type`	The type of chart to render. Valid types include `bar`, `line`, `pie`, `doughnut`, `polarArea`, `radar`, `scatter`, and `bubble`. Type `ChartType` Default `'bubble'`
`withoutAnimation` `without-animation`	Disables chart animations Type `boolean` Default `false`
`withoutLegend` `without-legend`	Hides the legend Type `boolean` Default `false`
`withoutTooltip` `without-tooltip`	Hides tooltips over data points Type `boolean` Default `false`
`xLabel` `x-label`	A label for the x-axis. Type `string \| null` Default `null`
`yLabel` `y-label`	A label for the y-axis. Type `string \| null` Default `null`

CSS Custom Properties

Link to This Section

Learn more about CSS custom properties.

Name	Description
`--border-color-1`	Border color for the first dataset. Default `var(--wa-color-blue-60)`
`--border-color-2`	Border color for the second dataset. Default `var(--wa-color-pink-60)`
`--border-color-3`	Border color for the third dataset. Default `var(--wa-color-green-60)`
`--border-color-4`	Border color for the fourth dataset. Default `var(--wa-color-yellow-60)`
`--border-color-5`	Border color for the fifth dataset. Default `var(--wa-color-purple-60)`
`--border-color-6`	Border color for the sixth dataset. Default `var(--wa-color-orange-60)`
`--border-radius`	Border radius for bar charts. Default `var(--wa-border-radius-s)`
`--border-width`	Border width for bars and arcs. Default `var(--wa-border-width-s)`
`--fill-color-1`	Fill color for the first dataset. Default `color-mix(in srgb, var(--wa-color-blue-60) 40%, transparent)`
`--fill-color-2`	Fill color for the second dataset. Default `color-mix(in srgb, var(--wa-color-pink-60) 40%, transparent)`
`--fill-color-3`	Fill color for the third dataset. Default `color-mix(in srgb, var(--wa-color-green-60) 40%, transparent)`
`--fill-color-4`	Fill color for the fourth dataset. Default `color-mix(in srgb, var(--wa-color-yellow-60) 40%, transparent)`
`--fill-color-5`	Fill color for the fifth dataset. Default `color-mix(in srgb, var(--wa-color-purple-60) 40%, transparent)`
`--fill-color-6`	Fill color for the sixth dataset. Default `color-mix(in srgb, var(--wa-color-orange-60) 40%, transparent)`
`--grid-border-width`	Border width for chart grid lines and axis borders. Default `var(--wa-border-width-s)`
`--grid-color`	Color of the chart grid lines and axis borders. Default `var(--wa-color-neutral-border-quiet)`
`--line-border-width`	Border width for line and radar charts. Default `var(--wa-border-width-m)`
`--point-radius`	Radius of data point dots. Default `var(--wa-border-width-m)`

Need a hand?

Report a bug

Ask for help

Bubble Chart

Examples

Providing Data with JSON

Providing Data with JavaScript

Custom Tooltips

Bubble Sizes

Multiple Datasets

Colors

Legend

Grid Lines

Axis Labels

Disabling Features

API

Importing

Slots

Attributes & Properties

CSS Custom Properties

Quick Links

Recent Searches

Bubble Chart

Examples

Providing Data with JSON

Providing Data with JavaScript

Custom Tooltips

Bubble Sizes

Multiple Datasets

Colors

Legend

Grid Lines

Axis Labels

Disabling Features

API

Importing

Slots

Attributes & Properties

CSS Custom Properties

Quick Links

Recent Searches

We Have Cookies…