animated butterfly chart icon Animated Butterfly Chart API and Samples

Learn how to configure and use Animated Butterfly Chart features and options with simple JavaScript code and HTML. All code samples use only plain HTML and JavaScript to show Animated Butterfly Charts, 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. The KyubitTimeCharts.js is the only dependency file you need to include on the page to work with all features of the Animated Butterfly Chart and other charts of Kyubit JavaScript Charts Library

A Quickstart Sample

To grasp the basic concepts and simplicity of setting up the Animated Butterfly Chart, take a look at this straightforward example of chart setup. Essentially, we're creating a config object that contains all the relevant data needed for the chart to be displayed. The values used by the chart could be included directly in the JavasScript config object or fetched from the external CSV file. We then invoke the showButterflyChart 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: "Sales", prefix: "$" }],
        groups: ["Store", "Online"],
        dataCSVURL: "ButterflySample01.csv"
    }

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

Animated Butterfly Chart Properties

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

Animated Butterfly 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 title 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 a dark background and light text and graphics.

groups

(array)
An array of that contains names of the two groups that are compared with the Animated Butterfly Chart. This property must contain two values.

Example...
groups: [ "Male","Female" ]

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 Butterfly Chart can display a single measure (for two compared groups). 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. The measure label is displayed for the X-axis.

Example...
measures: [ { title: "Sales ", prefix: "$", decimalPlaces: 2 } ]

data

(array)
An array of items to be displayed on the chart. Each item object includes the item (title), period, val, and val2 properties. 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 measure. Items in the data array should be ordered by the time periods in the ascending order. 

function showChart() {
    let config = {
        title: "Sample 02",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [{ title: "Sales", prefix: "$" }],
        groups: ["US", "Europe"],
        data: [
            { item: "Company A", period: "2020", val: 1000000, val2: 800000 },
            { item: "Company B", period: "2020", val: 450000, val2: 550000 },
            { item: "Company C", period: "2020", val: 650000, val2: 750000 },
            { item: "Company A", period: "2021", val: 1300000, val2: 900000 },
            { item: "Company B", period: "2021", val: 80000, val2: 120000 },
            { item: "Company C", period: "2021", val: 950000, val2: 1950000 },
            { item: "Company A", period: "2022", val: 1550000, val2: 1250000 },
            { item: "Company B", period: "2022", val: 800000, val2: 700000 },
            { item: "Company C", period: "2022", val: 1500000, val2: 2500000 },
            { item: "Company A", period: "2023", val: 2230000, val2: 3230000 },
            { item: "Company B", period: "2023", val: 1300000, val2: 4300000 },
            { item: "Company C", period: "2023", val: 2800000, val2: 3800000 },
        ]
    }

    kyubitTimeCharts.showButterflyChart("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 the value for both measure groups. 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.

columnItems
Items are defined on columns, while time periods are defined on rows. Rows must be sorted by the period in the ascending order. 

Item;Period;Measure;Measure
Company A;2020;1000000;800000
Company B;2020;450000;550000
Company C;2020;650000;320000
Company A;2021;1300000;1200000
Company B;2021;80000;70000
Company C;2021;950000;850000
Company A;2022;1550000;1250000
Company B;2022;1800000;1750000
Company C;2022;1500000;1250000
Company A;2023;2230000;1850000
Company B;2023;2300000;2800000
Company C;2023;1800000;550000

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: "Sample 03",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        measures: [{ title: "Sales", prefix: "$" }],
        groups: ["Services", "Products"],
        dataCSV: `Item;Period;Measure;Measure
                Company A;2020;1000000;80000
                Company B;2020;450000;55000
                Company C;2020;650000;32000
                Company A;2021;1300000;120000
                Company B;2021;80000;7000
                Company C;2021;950000;85000
                Company A;2022;1550000;125000
                Company B;2022;1800000;175000
                Company C;2022;1500000;125000
                Company A;2023;2230000;185000
                Company B;2023;2300000;280000
                Company C;2023;1800000;55000`
    }

    kyubitTimeCharts.showButterflyChart("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).

logarithmicXaxis

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

 function showChart(){
    let config = {
        title: "Sample 04",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        logarithmicXaxis: true,
        measures: [{ title: "Revenue", prefix: "$" }],
        groups: ["Reseller", "Internet"],
        data: [
            { item: "Company A", period: "2020", val: 100000000, val2: 800000000 },
            { item: "Company B", period: "2020", val: 450000, val2: 550000 },
            { item: "Company C", period: "2020", val: 650, val2: 750 },
            { item: "Company A", period: "2021", val: 1300000000, val2: 900000000 },
            { item: "Company B", period: "2021", val: 80000, val2: 120000 },
            { item: "Company C", period: "2021", val: 950, val2: 1950 },
            { item: "Company A", period: "2022", val: 1550000000, val2: 1250000000 },
            { item: "Company B", period: "2022", val: 800000, val2: 700000 },
            { item: "Company C", period: "2022", val: 1500, val2: 2500 },
            { item: "Company A", period: "2023", val: 2230000000, val2: 3230000000 },
            { item: "Company B", period: "2023", val: 1300000, val2: 4300000 },
            { item: "Company C", period: "2023", val: 2800, val2: 3800 },
        ]
    }

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

showHighest

(boolean, default: false)
Sets if the chart will display the record (highest) value for an item during the chart animation. In this way, a user can observe not only the value for the current period but also can see what was the highest value for the item during the chart animation progress. 

function showChart(){
    let config = {
        title: "Sample 05",
        width: "800",
        height: "600",
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        showHighest: true,
        measures: [{ title: "Sales", prefix: "$" }],
        groups: ["Male", "Female"],
        data: [
            { item: "Company A", period: "2020", val: 212000, val2: 252000 },
            { item: "Company B", period: "2020", val: 165000, val2: 145000 },
            { item: "Company C", period: "2020", val: 106000, val2: 96000 },
            { item: "Company A", period: "2021", val: 183000, val2: 193000 },
            { item: "Company B", period: "2021", val: 158000, val2: 128000 },
            { item: "Company C", period: "2021", val: 110000, val2: 110000 },
            { item: "Company A", period: "2022", val: 105000, val2: 100000 },
            { item: "Company B", period: "2022", val: 98000, val2: 188000 },
            { item: "Company C", period: "2022", val: 115000, val2: 105000 },
            { item: "Company A", period: "2023", val: 83000, val2: 73000 },
            { item: "Company B", period: "2023", val: 55000, val2: 65000 },
            { item: "Company C", period: "2023", val: 35000, val2: 42000 },
        ]
    }

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

colorPalette

(string, default: "Standard")
Defines the preferred color palette used by the Animated Butterfly Chart items (bar). 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 Butterfly Chart items (bars). Two Hexadecimal color codes are separated with an empty space. If defined, it will override the colorPalette definition.

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

itemDefinitions (item images)

(array)
Defines the item image to be rendered on the Y-axis instead of the item text. The image could be available on a relative or an absolute URL path. 

function showChart() {
    let config = {
        title: "Sample 06",
        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: "Sales", prefix: "$" }],
        groups: ["Female Customers", "Male Customers"],
        dataCSVURL: "ButterflySample06.csv"
    }

    kyubitTimeCharts.showButterflyChart("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 between the bars. The item name needs to match the country name (in English) or two-letter country code (ISO 3166). 

function showChart() {
     let config = {
        title: "Sample 07",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        countryFlags: true,
        measures: [{ title: "Sales", prefix: "$" }],
        groups: ["Products", "Services"],
        dataCSVURL: "ButterflySample07.csv"
    }

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

Multilingual Options

To display the text of the chart user interface (mostly visible in the chart menu) in a language other than English, utilize the provided properties that allow you to modify specific phrases. This enables you to input your preferred phrases in any language, including English, that best suits your needs. For your convenience, we have provided sets of translated phrases in Spanish, German, French, and Portuguese. You can easily copy these sets into your code for a quick translation of the user interface texts. 

function showChart() {
     let config = {
        title: "Sample 08",
        width: "800",
        height: "600",
        darkMode: true,
        thousandsSeparator: ".",
        decimalSeparator: ",",
        transitionTime: 4,
        countryFlags: true,
        measures: [{ title: "Sales", prefix: "$" }],
        groups: ["Products", "Services"],
        dataCSVURL: "ButterflySample07.csv",
        txtOptions: "Opciones",
        txtSpeed: "Velocidad",
        txtImageDownload: "Descarga de imagen",
        txtChartDownload: "Descarga de gráficos",
        txtResetVisuals: "Restablecer",
        txtDownload: "Descargar",
        txtFullscreen: "Pantalla completa",
        txtExitFullscreen: "Salir de pantalla completa",
        txtScale: "Escala",
        txtLogarithmic: "Logarítmico",
        txtAbout: "Acerca de"
    }

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

txtOptions: "Optionen",
txtSpeed: "Geschwindigkeit",
txtImageDownload: "Bild-Download",
txtChartDownload: "Chart-Download",
txtResetVisuals: "Zurücksetzen",
txtDownload: "Herunterladen",
txtFullscreen: "Vollbild",
txtExitFullscreen: "Vollbild beenden",
txtScale: "Skalierung",
txtLogarithmic: "Logarithmisch",
txtAbout: "Über"

Event Handlers

onItemClick

{ e, item }
To catch the event when a user clicks on the chart item (bar) use the 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: "Sales", prefix: "$" }],
        groups: ["Married", "Single"],
        dataCSVURL: "ButterflySample06.csv"
    }

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

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

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! 🚀