animated bubble chart icon Animated Bubble Chart API and Samples

Learn how to set up and use Animated Bubble Chart features and options with simple JavaScript code and HTML. All code samples use only plain HTML and JavaScript to show Animated Bubble Chart, and no other third-party technologies/libraries are involved. The only dependency file is, of course, the Kyubit Charts Library, so the first thing is to include KyubitTimeCharts.js in the HTML script section.

A Quickstart Sample

To understand the fundamental concepts and simplicity of setting up the Animated Bubble Chart, take a look at this straightforward example of chart configuration. In essence, we're creating a config object that contains all the crucial data needed for the chart to be displayed. The values for the chart could be included directly in the JavasScript config object or fetched from the external CSV file. We then invoke the showBubbleChart library function to render the chart on a specific DIV element. In this instance, the chart's data is kept in a separate CSV file. Additional methods for providing data to the chart are discussed in subsequent API examples. 

function showChart() {
    let config = {
        title: "Quickstart Sample 01",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        dataCSVURL: "Sample01.csv"
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

Animated Bubble Chart Properties

A list of all chart properties with descriptions of their usage, types, and default values.

Animated Bubble Chart Event Handlers

A list of all chart event handlers.


Properties

title

(string)
Defines the chart title which is always visible in the chart's left upper corner.

description

(string)
Defines the description text that is visible when moving the mouse over the title text.

width/height

(numeric)
Chart properties width and height expect numeric input that presents number of pixels used for chart rendering size on the web page. If the "width" and "height" properties are not provided, chart width and height will depend on the parent DIV element size.

fontFamily

(string, default: "Arial")
Defines the preferred font for chart text with the fontFamiliy attribute, otherwise the Arial font will be used.

fontSizeIncrease

(numeric, default: 0)
Font size is auto-calculated based on the chart width and height (for best results). Still, it is possible to influence the final font size by setting the "fontSizeIncrease" property to values between -3 and 3. For example, to slightly increase the font, set the value to 1. To decrease the font size, set the value to -1.

darkMode

(boolean, default: false)
Display the chart in the mode with the dark background and light text and graphics.

measures

(array)
An array of measures that define the measure features. Actual values are defined in the Data property, while here in the "measures" property we define the measure attributes. Each measure object includes a title, and optional decimalPlaces, prefix, suffix, and description attributes. The Animated Bubble Chart must contain 2 or 3 measures. The Prefix controls if any sign or text is to be displayed in front of each value related to the measure. The Suffix controls if any sign or text is to be displayed after each value related to the measure. The description of the measure is displayed while moving the mouse over the measure label. Measure labels are displayed on each of the chart axes.

measures: [
      { title: "Measure1 Title ", prefix: "$" },
      { title: "Measure2 Title ", prefix: "$", decimalPlaces: 2 },
      { title: "Measure3 Title ", decimalPlaces: 2 }
]

data

(array)
An array of items to be displayed on the chart. Each item objects include item (title), period, val, val2, and (optionally) val3 attributes. In this example, there is no CSV data. All data with values are defined directly in the config object, data array. Decimal places are defined for the 3rd measure. Items in the data array should be ordered by the time periods in the ascending order. 

function showChart() {
    let config = {
        title: "Quickstart sample 02",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Avg. num of employees", decimalPlaces: 1 }
        ],
        data: [
            { item: "Company A", period: "2020", val: 1000000, val2: 100000, val3: 8.341 },
            { item: "Company B", period: "2020", val: 450000, val2: 80000, val3: 6.431 },
            { item: "Company C", period: "2020", val: 650000, val2: 200000, val3: 14.123 },
            { item: "Company A", period: "2021", val: 1300000, val2: 134000, val3: 19.65 },
            { item: "Company B", period: "2021", val: 80000, val2: 180000, val3: 14.23 },
            { item: "Company C", period: "2021", val: 950000, val2: 250000, val3: 76.123 },
            { item: "Company A", period: "2022", val: 1550000, val2: 195000, val3: 56.567 },
            { item: "Company B", period: "2022", val: 800000, val2: 110000, val3: 4.1 },
            { item: "Company C", period: "2022", val: 1500000, val2: 300000, val3: 220.23 },
            { item: "Company A", period: "2023", val: 2230000, val2: 220000, val3: 90.47 },
            { item: "Company B", period: "2023", val: 1300000, val2: 125000, val3: 5.98 },
            { item: "Company C", period: "2023", val: 2800000, val2: 280000, val3: 385.76 },
        ]
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

dataCSVURL

(string)
Defines the URL for data items to be fetched from the external CSV file (as presented in Sample 01).

csvType

(string, default: "inline")
Defines the structure of values in the CSV data. It could be defined as 'inline' (default), 'rowItems', or 'columnItems'. Various available CSV structures exist to make it easy for users to prepare CSV data depending on their data sources. These examples illustrate the CSV data structure. Learn more about expected data structures on the data structure samples page.

inline
Data items are defined one by one, where each item has a definition of the time period and values for all measures. Items must be sorted by the period in the ascending order.

rowItems
Items are defined on rows, while time periods are defined on columns. Columns must be sorted by the period in the ascending order. A separate set of rows for each of the chart measures has to be provided one below another.

columnItems
Items are defined on columns, while time periods are defined on rows. Rows must be sorted by the period in the ascending order. A separate set of rows for each of the chart measures has to be provided one below another. 

Item;Period;Measure;Measure;Measure
Company A;2020;1000000;100000;8
Company B;2020;450000;80000;6
Company C;2020;650000;200000;14
Company A;2021;1300000;134000;19
Company B;2021;80000;180000;14
Company C;2021;950000;250000;76
Company A;2022;1550000;195000;56
Company B;2022;800000;110000;4
Company C;2022;1500000;300000;220
Company A;2023;2230000;220000;90
Company B;2023;1300000;125000;5
Company C;2023;2800000;280000;385

dataCSV

(string)
Provides the CSV data directly to the chart config object (not as an external file). The structure of data and values in the CSV file could be 'inline' (default), 'rowItems', or 'columnItems' (as explained above). 

function showChart() {
    let config = {
        title: "Quickstart sample 03",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        csvType: 'rowItems',
        dataCSV: `Item;2020;2021;2022;2023
                Company A; 1000000; 1300000; 1550000; 2230000
                Company B; 450000; 80000; 800000; 1300000
                Company C; 650000; 950000; 1500000; 2800000
                Company A; 100000; 134000; 195000; 220000
                Company B; 80000; 180000; 110000; 125000
                Company C; 200000; 250000; 300000; 280000
                Company A; 8; 19; 56; 90
                Company B; 6; 14; 4; 5
                Company C; 14; 76; 220; 385`
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

decimalSeparator

(string, default: ".")
Defines the decimal separator in the CSV file values.

thousandsSeparator

(string, default: ",")
Defines the thousands separator in the CSV file values.

showPlayControls

(boolean, default: true)
Defines if play/pause and time axis will be displayed to control animation and transition changes.

autoPlay

(boolean, default: false)
Sets if the chart should immediately start with animation upon data load.

transitionTime

(numeric, default: 4)
This property controls the duration of transition between time periods during the chart animations (in seconds)

showLastPeriod

(boolean, default: false)
If enabled this property will set the initial display of the chart to the last period (otherwise, it will start from the first period).

labelsDisplay

(numeric, default: 0)
The property controls the display of bubble labels. The Animated Bubble Chart can display many items (bubbles). In these situations, it would not be convenient to show labels for all items as many would overlap and create a visual mess on the chart.
The default option "0" - Show All(No overlap) displays all items that do not overlap.
The option "1" - Show All forces the chart to display all labels for all items.
The option "2" - Show Leaders will display only the leaders (items with the highest values) for all 2 or 3 measures on the chart.
The option "3" - Show Leaders (Top 3) will display only the top 3 leaders (items with the highest values) for all 2 or 3 measures on the chart.

A user can change this option while using the chart.

animScaleX, animScaleY

(boolean, default: true)
Controls if the chart axes scales will be dynamic (animated), changing the axis scale min/max values to the currently displayed values. If the axis scale is not dynamically animated, it will display the maximum value related to all data points all the time of the animation. If the chart employs logarithmic scale or autoMinMax scale options, the animScale is automatically disabled.

logarithmicXaxis, logarithmicYaxis

(boolean, default: true)
If enabled, the chart axis will be displayed with the logarithmic scale. In this case, dynamic axis scale property is automatically disabled.
In the following example, the X axis uses a logarithmic scale and is not animated, while the Y axis still uses a linear scale and is animated. 

 function showChart(){
    let config = {
        title: "Sample 04",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        logarithmicXaxis: true,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Avg. num of employees", decimalPlaces: 1 }
        ],
        data: [
            { item: "Company A", period: "2020", val: 1000000000, val2: 100000, val3: 8.341 },
            { item: "Company B", period: "2020", val: 450000, val2: 80000, val3: 6.431 },
            { item: "Company C", period: "2020", val: 650000000000, val2: 200000, val3: 14.123 },
            { item: "Company A", period: "2021", val: 1300000000, val2: 134000, val3: 19.65 },
            { item: "Company B", period: "2021", val: 80000, val2: 180000, val3: 14.23 },
            { item: "Company C", period: "2021", val: 9500000000000, val2: 250000, val3: 76.123 },
            { item: "Company A", period: "2022", val: 1550000000, val2: 195000, val3: 56.567 },
            { item: "Company B", period: "2022", val: 800000, val2: 110000, val3: 4.1 },
            { item: "Company C", period: "2022", val: 15000000000000, val2: 300000, val3: 220.23 },
            { item: "Company A", period: "2023", val: 2230000000, val2: 220000, val3: 90.47 },
            { item: "Company B", period: "2023", val: 1300000, val2: 125000, val3: 5.98 },
            { item: "Company C", period: "2023", val: 28000000000000, val2: 280000, val3: 385.76 },
        ]
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

autoMinMaxX, autoMinMaxY

(boolean, default: true)
Controls if the axis scale will be automatically trimmed to focus on the data values provided. When disabled the chart axis displays a scale from 0 to max value. When enabled the axis scale will start from the value related to the minimum value of all items. When enabled the dynamic axis scale property is automatically disabled. 

function showChart(){
    let config = {
        title: "Quickstart sample 05",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        autoMinMaxY: true,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Avg. num of employees", decimalPlaces: 1 }
        ],
        data: [
            { item: "Company A", period: "2020", val: 1000000, val2: 100000, val3: 8.341 },
            { item: "Company B", period: "2020", val: 450000, val2: 180000, val3: 6.431 },
            { item: "Company C", period: "2020", val: 650000, val2: 200000, val3: 14.123 },
            { item: "Company A", period: "2021", val: 1300000, val2: 134000, val3: 19.65 },
            { item: "Company B", period: "2021", val: 80000, val2: 180000, val3: 14.23 },
            { item: "Company C", period: "2021", val: 950000, val2: 190000, val3: 76.123 },
            { item: "Company A", period: "2022", val: 1550000, val2: 195000, val3: 56.567 },
            { item: "Company B", period: "2022", val: 800000, val2: 150000, val3: 4.1 },
            { item: "Company C", period: "2022", val: 1500000, val2: 190000, val3: 220.23 },
            { item: "Company A", period: "2023", val: 2230000, val2: 220000, val3: 90.47 },
            { item: "Company B", period: "2023", val: 1300000, val2: 125000, val3: 5.98 },
            { item: "Company C", period: "2023", val: 2800000, val2: 210000, val3: 385.76 },
        ]
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

colorPalette

(string, default: "Standard")
Defines the preferred color palette used by the Animated Bubble Chart. Available options are Warm, Cold, Strong, and (default) Standard.

Example...
colorPalette: "Warm"

customPaletteColors

(string)
Defines the custom palette colors to be used by the Animated Bubble Chart. Hexadecimal color codes separated with an empty space. If defined, it will override the colorPalette definition.

Example...
customPaletteColors: "#5B9BD5 #4472C4"

legend (groups)

(string, default: "TopRight")
If the chart is using groups (grouping of items), then those groups could be displayed on the chart legend. Available values for the chart legend are TopRight, TopLeft, BottomRight, BottomLeft, and None.

Groups
The group should be defined in the second column of CSV inline data. Using groups with CSV data is supported only when csvType is inline (default). If data items are defined directly in the config object, the item should simply have the group property (for example, { item: "Company A", group: "US", period: "2020", val: 1000000, val2: 100000, val3: 8.341 }). The sample with groups is provided below.

markers

(array)
Defines the custom horizontal and vertical lines that mark some important fixed value (threshold) of significance to compare with other chart values during the chart animation and analysis. The chart can include multiple marker lines. Marker lines are defined as objects with title, color, valX/valX, and opacity. If the marker line is about to be drawn on the X-axis, set the valX to the required value. For the Y-axis marker, set the valY value.

The following example is using groups, custom colors, legend position and markers. 

function showChart() {
    let config = {
        title: "Sample 06",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        customPaletteColors: "#5B9BD5 red #4472C4 #255E91 #636363 #264478 #84B4DF #B7B7B7 #698ED0",
        legend: "TopRight",
        markers: [
            { "title": "Threshold X", "color": "gray", "valX": 800000, "opacity": 0.9 },
            { "title": "Marker Y", "color": "red", "valY": 60000, "opacity": 0.9 }
        ],
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        dataCSVURL: "Sample06.csv"
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

itemDefinitions (item images)

(array)
Defines the item image to be rendered instead of the bubble (circle) by setting the image URL. Items are represented by the images which are resized during the animation to match the third measure value proportions (using the same principles for a bubble resize). The items without images will be displayed as a bubble. The image could be available on a relative or an abosulute URL path. 

function showChart() {
    let config = {
        title: "Sample 07",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        itemDefinitions: [
            { item: "Company A", imageURL: "img/apple.png" },
            { item: "Company B", imageURL: "img/google.png" },
            { item: "Company C", imageURL: "img/microsoft.png" },
            { item: "Company D", imageURL: "img/tesla.png" }
        ],
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        dataCSVURL: "Sample06.csv"
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

countryFlags

(boolean, default: false)
If the items on the chart are countries, use this setting to quickly set country flag images to be displayed instead of the bubbles. The item name that needs to match the country name (in English) or two-letter country code (ISO 3166). Items are represented by the images which are resized during the animation to match the third measure value proportions (using the same principles for a bubble resize). The items that do not match any country will be displayed as a bubble. 

function showChart() {
    let config = {
        title: "Sample 07",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        countryFlags: true,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        dataCSVURL: "Sample07.csv"
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

showNegativeX, showNegativeY

(boolean)
If the data include negative values, the chart will display a negative and a positive axis scale. In cases you wish to show only positive values and disregard the display of the negative axis scale set the showNegativeX or showNegativeY to false. 

function showChart() {
    let config = {
        title: "Sample 08",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Avg. num of employees", decimalPlaces: 1 }
        ],
        showNegativeY: true,
        data: [
            { item: "Company A", period: "2020", val: 1000000, val2: 100000, val3: 8.341 },
            { item: "Company B", period: "2020", val: 450000, val2: 80000, val3: 6.431 },
            { item: "Company C", period: "2020", val: 650000, val2: 200000, val3: 14.123 },
            { item: "Company A", period: "2021", val: 1300000, val2: 134000, val3: 19.65 },
            { item: "Company B", period: "2021", val: 80000, val2: -30000, val3: 14.23 },
            { item: "Company C", period: "2021", val: 950000, val2: 250000, val3: 76.123 },
            { item: "Company A", period: "2022", val: 1550000, val2: 195000, val3: 56.567 },
            { item: "Company B", period: "2022", val: 800000, val2: -50000, val3: 4.1 },
            { item: "Company C", period: "2022", val: 1500000, val2: 300000, val3: 220.23 },
            { item: "Company A", period: "2023", val: 2230000, val2: 220000, val3: 90.47 },
            { item: "Company B", period: "2023", val: 1300000, val2: 20000, val3: 5.98 },
            { item: "Company C", period: "2023", val: 2800000, val2: 280000, val3: 385.76 },
        ]
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

Event Handlers

onItemClick

{ e, item }
To catch the event when a user clicks on the chart item (bubble) use onItemClick event handler. It will pass 2 arguments, event object and item object. Item object contains all information about the clicked item. 

function showChart() {
    let config = {
        title: "Sample 09",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        onItemClick: clickItemHandler,
        measures: [
            { title: "Revenue", prefix: "$" },
            { title: "Profit", prefix: "$" },
            { title: "Number of employees" }
        ],
        dataCSVURL: "Sample06.csv"
    }

    kyubitTimeCharts.showBubbleChart("chartDiv", config);
}

function clickItemHandler(e)
{
    const item = e.item;
    alert(item.item + " is clicked. Measure 2 value is " + item.val2);
}

onSelectionReset

{ chartDivID }
The event is raised when the chart items are unselected. It passes the DIV id attribute of the related chart as an argument.

Get started with Kyubit Charts Library

JavaScript Charts Library Download Begin your journey with the Kyubit Charts Library. Download it now and evaluate the charts using your own data. Seamlessly integrate the Kyubit JavaScript library into your website or web application—it's as simple as adding a single JavaScript file to your page. Get started with stunning chart visualizations! 🚀