Chart

Chart

new Chart()

Description:
  • Main chart class.

    • Note: Instantiated via bb.generate().
Source:
See:
Example
var chart = bb.generate({
 data: {
   columns: [
       ["x", "2015-11-02", "2015-12-01", "2016-01-01", "2016-02-01", "2016-03-01"],
       ["count1", 11, 8, 7, 6, 5 ],
       ["count2", 9, 3, 6, 2, 8 ]
  ]}
}

Members

(static) $ :object

Description:
  • Access instance's primary node elements

Source:
Properties:
Name Type Description
$ object

Access instance's primary node elements

Properties
Name Type Description
chart d3.selection

Wrapper element

svg d3.selection

Main svg element

defs d3.selection

Definition element

main d3.selection

Main grouping element

needle d3.selection

Needle element

  • NOTE:
    • The element will have bb-needle as class name.
    • Will provide speical helper .updateHelper(value: number, updateConfig: boolean) method to facilitate needle position update.
tooltip d3.selection

Tooltip element

legend d3.selection

Legend element

title d3.selection

Title element

grid d3.selection

Grid element

arc d3.selection

Arc element

circles d3.selection

Data point circle elements

bar object

Bar element object

Properties
Name Type Description
bars d3.selection

Bar elements

candlestick d3.selection

Candlestick elements

line object

Line element object

Properties
Name Type Description
lines d3.selection

Line elements

areas d3.selection

Areas elements

text object

Text element object

Properties
Name Type Description
texts d3.selection

Data label text elements

Access instance's primary node elements

Type:
  • object
Examples
const chart = bb.generate({ ... });

chart.$.chart; // wrapper element
chart.$.line.circles;  // all data point circle elements
// Update arc needle position
const chart = bb.generate({
  data: {
    type: "donut"
  },
  arc: {
    needle: {
      show: true,
      ...
    }
  }
});

chart.$.needle.updateHelper(70);  // update needle position to point value 70.

// update needle position to point value 70 and the config value.
// NOTE: updating config value, will update needle pointer initial value too.
chart.$.needle.updateHelper(70, true);

// update needle point position every 1 second
let i = 0;
setInterval(() => {
  chart.$.needle.updateHelper(i += 10);
}, 1000)

(static) plugins :Array

Description:
  • Plugin instance array

Source:

Plugin instance array

Type:
  • Array
Example
var chart = bb.generate({
    ...
    plugins: [
       new bb.plugin.stanford({ ... }),
       new PluginA()
    ]
 });

 chart.plugins; // [Stanford, PluginA] - instance array

Methods

axis․labels(labels) → {object|undefined}

Description:
  • Get and set axis labels.

    • NOTE: Only applicable for chart types which has x and y axes.
Source:
Example
// Update axis' label
chart.axis.labels({
  x: "New X Axis Label",
  y: "New Y Axis Label",
  y2: "New Y2 Axis Label"
});

chart.axis.labels();
// --> {
//  x: "New X Axis Label",
//  y: "New Y Axis Label",
//  y2: "New Y2 Axis Label"
// }
Parameters:
Name Type Description
labels object

specified axis' label to be updated.

Properties
Name Type Attributes Description
x string <optional>

x Axis string

y string <optional>

y Axis string

y2 string <optional>

y2 Axis string

Returns:

axis labels text object

Type
object | undefined

axis․max(max) → {object|undefined}

Description:
  • Get and set axis max value.

    • NOTE: Only applicable for chart types which has x and y axes.
Source:
Example
// Update axis' label
chart.axis.max({
   x: 100,
   y: 1000,
   y2: 10000
});

// To unset specific axis max, set false to each of them.
chart.axis.max({
  x: false,
  y: false,
  y2: false
});

// shorthand (only affects y and y2 axis)
chart.axis.max(10);
chart.axis.max(false);
Parameters:
Name Type Description
max object

If max is given, specified axis' max value will be updated.
If no argument is given, the max values set on generating option for each axis will be returned. If not set any max values on generation, it will return undefined.
To unset specific axis max, set false to each of them.

Returns:
Type
object | undefined

axis․min(min) → {object|undefined}

Description:
  • Get and set axis min value.

    • NOTE: Only applicable for chart types which has x and y axes.
Source:
Example
// Update axis' min
chart.axis.min({
  x: -10,
  y: 1000,
  y2: 100
});

// To unset specific axis min, set false to each of them.
chart.axis.min({
  x: false,
  y: false,
  y2: false
});

// shorthand (only affects y and y2 axis)
chart.axis.min(-50);
chart.axis.min(false);
Parameters:
Name Type Description
min object

If min is given, specified axis' min value will be updated.
If no argument is given, the min values set on generating option for each axis will be returned. If not set any min values on generation, it will return undefined.
To unset specific axis max, set false to each of them.

Returns:
Type
object | undefined

axis․range(range) → {object|undefined}

Description:
  • Get and set axis min and max value.

    • NOTE: Only applicable for chart types which has x and y axes.
Source:
Example
// Update axis' label
chart.axis.range({
  min: {
    x: -10,
    y: -1000,
    y2: -10000
  },
  max: {
    x: 100,
    y: 1000,
    y2: 10000
  },
});

// To unset specific axis max, set false to each of them.
chart.axis.range({
  min: {
    x: false,
    y: false,
    y2: false
  },
  max: {
    x: false,
    y: false,
    y2: false
  },
});

// shorthand (only affects y and y2 axis)
chart.axis.range({ min: -50, max: 1000 });
chart.axis.range({ min: false, max: false });
Parameters:
Name Type Description
range object

If range is given, specified axis' min and max value will be updated. If no argument is given, the current min and max values for each axis will be returned.
To unset specific axis max, set false to each of them.

Returns:
Type
object | undefined

categories(categories) → {Array}

Description:
  • Set or get category names on category axis.

Source:
Example
chart.categories([
     "Category 1", "Category 2", ...
]);
Parameters:
Name Type Description
categories Array

This must be an array that includes category names in string. If category names are included in the date by data.x option, this is not required.

Returns:
Type
Array

category(i, category) → {string}

Description:
  • Set specified category name on category axis.

Source:
Example
chart.category(2, "Category 3");
Parameters:
Name Type Description
i number

index of category to be changed

category string

category value to be changed

Returns:
Type
string

color(id) → {string}

Description:
  • Get the color

Source:
Example
chart.color("data1");
Parameters:
Name Type Description
id string

id to get the color

Returns:
Type
string

config(name, valueopt, redrawopt) → {*}

Description:
  • Get or set config option value.

    • NOTE
    • The option key name must be specified as the last level.
    • when no argument is given, will return all specified generation options object only. (will exclude any other options not specified at the initialization)
Source:
Example
// Getter
chart.config("gauge.max");

// Getter specified with top level key name will not work.
// The option key name must be specified as the last level.
// chart.config("gauge"); // will not work

// without any arguments, it returns generation config object
chart.config();  // {data: { ... }, axis: { ... }, ...}

// Setter
chart.config("gauge.max", 100);

// Setter specified with top level key name will not work.
// The option key name must be specified as the last level.
// chart.config("gauge", {min: 10, max: 20}); // will not work

// Setter & redraw with the new option
chart.config("gauge.max", 100, true);
Parameters:
Name Type Attributes Description
name string

The option key name.

value * <optional>

The value accepted for indicated option.

redraw boolean <optional>

Set to redraw with the new option changes.

  • NOTE: Doesn't guarantee work in all circumstances. It can be applied for limited options only.
Returns:
Type
*

data(targetIds) → {Array}

Description:
  • Get data loaded in the chart.

Source:
Example
// Get only data1 data
chart.data("data1");
// --> [{id: "data1", id_org: "data1", values: Array(6)}, ...]

// Get data1 and data2 data
chart.data(["data1", "data2"]);

// Get all data
chart.data();
Parameters:
Name Type Description
targetIds string | Array

If this argument is given, this API returns the specified target data. If this argument is not given, all of data will be returned.

Returns:

Data objects

Type
Array

data․axes(axes) → {object}

Description:
  • Get and set axes of the data loaded in the chart.

    • NOTE: If all data is related to one of the axes, the domain of axis without related data will be replaced by the domain from the axis with related data
Source:
Example
// Get current axes
chart.data.axes();
// --> {data1: "y"}

// Update axes
chart.data.axes({
 data1: "y",
 data2: "y2"
});
Parameters:
Name Type Description
axes object

If this argument is given, the axes of data will be updated. If not given, the current axes will be returned. The format of this argument is the same as

Returns:

Corresponding axes value for data, if specified axes value.

Type
object

data․colors(colors) → {object}

Description:
  • Get and set colors of the data loaded in the chart.

Source:
Example
// Get current colors
chart.data.colors();
// --> {data1: "#00c73c", data2: "#fa7171"}

// Update colors
chart.data.colors({
 data1: "#FFFFFF",
 data2: "#000000"
});
Parameters:
Name Type Description
colors object

If this argument is given, the colors of data will be updated. If not given, the current colors will be returned. The format of this argument is the same as data.colors.

Returns:

Corresponding data color value according its key value.

Type
object

data․max() → {Array}

Description:
  • Get the maximum data value bound to the chart

Source:
Example
// Get current axes
chart.data.max();
// --> [{x: 3, value: 400, id: "data1", index: 3}, ...]
Returns:

Data objects

Type
Array

data․min() → {Array}

Description:
  • Get the minimum data value bound to the chart

Source:
Example
// Get current axes
chart.data.min();
// --> [{x: 0, value: 30, id: "data1", index: 0}, ...]
Returns:

Data objects

Type
Array

data․names(names) → {object}

Description:
  • Get and set names of the data loaded in the chart.

Source:
Example
// Get current names
chart.data.names();
// --> {data1: "test1", data2: "test2"}

// Update names
chart.data.names({
 data1: "New Name 1",
 data2: "New Name 2"
});
Parameters:
Name Type Description
names object

If this argument is given, the names of data will be updated. If not given, the current names will be returned. The format of this argument is the same as data.names.

Returns:

Corresponding names according its key value, if specified names values.

Type
object

data․shown(targetIds) → {Array}

Description:
  • Get data shown in the chart.

Source:
Example
// Get shown data by filtering to include only data1 data
chart.data.shown("data1");
// --> [{id: "data1", id_org: "data1", values: Array(6)}, ...]

// Get shown data by filtering to include data1 and data2 data
chart.data.shown(["data1", "data2"]);

// Get all shown data
chart.data.shown();
Parameters:
Name Type Description
targetIds string | Array

If this argument is given, this API filters the data with specified target ids. If this argument is not given, all shown data will be returned.

Returns:

Data objects

Type
Array

data․values(targetIds, flatopt) → {Array}

Description:
  • Get values of the data loaded in the chart.

Source:
Example
// Get data1 values
chart.data.values("data1");
// --> [10, 20, 30, 40]
Parameters:
Name Type Attributes Default Description
targetIds string | Array | null

This API returns the values of specified target. If this argument is not given, null will be retruned

flat boolean <optional>
true

Get flatten values

Returns:

Data values

Type
Array

defocus(targetIdsValue)

Description:
  • This API fades out specified targets and reverts the others.

    You can specify multiple targets by giving an array that includes id as String. If no argument is given, all of targets will be faded out.

Source:
Example
// data1 will be faded out and the others will be reverted.
chart.defocus("data1");

// data1 and data2 will be faded out and the others will be reverted.
chart.defocus(["data1", "data2"]);

// all targets will be faded out.
chart.defocus();
Parameters:
Name Type Description
targetIdsValue string | Array

Target ids to be faded out.

destroy() → {null}

Description:
  • Reset the chart object and remove element and events completely.

Source:
Example
chart.destroy();
Returns:
Type
null

export(option, callbackopt) → {string}

Description:
  • Export chart as an image.

    • NOTE:
      • IE11 and below not work properly due to the lack of the feature(foreignObject) support
      • Every style applied to the chart & the basic CSS file(ex. billboard.css) should be at same domain as API call context to get correct styled export image.
Source:
Example
chart.export();
 // --> "data:image/svg+xml;base64,PHN..."

 // Initialize the download automatically
 chart.export({mimeType: "image/png"}, dataUrl => {
    const link = document.createElement("a");

    link.download = `${Date.now()}.png`;
    link.href = dataUrl;
    link.innerHTML = "Download chart as image";

    document.body.appendChild(link);
 });

 // Resize the exported image
 chart.export(
   {
     width: 800,
     height: 600,
     preserveAspectRatio: false,
     preserveFontStyle: false,
     mimeType: "image/png"
   },
   dataUrl => { ... }
 );
Parameters:
Name Type Attributes Description
option object

Export option

Properties
Name Type Attributes Default Description
mimeType string <optional>
"image/png"

The desired output image format. (ex. 'image/png' for png, 'image/jpeg' for jpeg format)

width number <optional>
{currentWidth}

width

height number <optional>
{currentHeigth}

height

preserveAspectRatio boolean <optional>
true

Preserve aspect ratio on given size

preserveFontStyle boolean <optional>
false

Preserve font style(font-family).
NOTE:

  • This option is useful when outlink web font style's font-family are applied to chart's text element.
  • Text element's position(especially "transformed") can't be preserved correctly according the page's layout condition.
  • If need to preserve accurate text position, embed the web font data within to the page and set preserveFontStyle=false.
callback function <optional>

The callback to be invoked when export is ready.

Returns:

dataURI

Type
string

flow(args)

Description:
  • Flow data to the chart.

    By this API, you can append new data points to the chart.

Source:
Example
// 2 data points will be apprended to the tail and popped from the head.
// After that, 4 data points will be appended and no data points will be poppoed.
chart.flow({
 columns: [
   ["x", "2018-01-11", "2018-01-21"],
   ["data1", 500, 200],
   ["data2", 100, 300],
   ["data3", 200, 120]
 ],
 to: "2013-01-11",
 done: function () {
   chart.flow({
     columns: [
       ["x", "2018-02-11", "2018-02-12", "2018-02-13", "2018-02-14"],
       ["data1", 200, 300, 100, 250],
       ["data2", 100, 90, 40, 120],
       ["data3", 100, 100, 300, 500]
     ],
     length: 2,
     duration: 1500
   });
 }
});
Parameters:
Name Type Description
args object

The object can consist with following members:

Key Type Description
json Object Data as JSON format (@see data․json)
rows Array Data in array as row format (@see data․rows)
columns Array Data in array as column format (@see data․columns)
to String The lower x edge will move to that point. If not given, the lower x edge will move by the number of given data points
length Number The lower x edge will move by the number of this argument
duration Number The duration of the transition will be specified value. If not given, transition.duration will be used as default
done Function The specified function will be called when flow ends
  • NOTE:
    • If json, rows and columns given, the data will be loaded.
    • If data that has the same target id is given, the chart will be appended.
    • Otherwise, new target will be added. One of these is required when calling.
    • If json specified, keys is required as well as data.json.
      • If tab isn't visible(by evaluating document.hidden), will not be executed to prevent unnecessary work.

flush(softopt)

Description:
  • Force to redraw.

    • NOTE: When zoom/subchart is used, the zoomed state will be resetted.
Source:
Example
chart.flush();

// for soft redraw
chart.flush(true);
Parameters:
Name Type Attributes Description
soft boolean <optional>

For soft redraw.

focus(targetIdsValue)

Description:
  • This API highlights specified targets and fade out the others.

    You can specify multiple targets by giving an array that includes id as String. If no argument is given, all of targets will be highlighted.

Source:
Example
// data1 will be highlighted and the others will be faded out
 chart.focus("data1");

// data1 and data2 will be highlighted and the others will be faded out
chart.focus(["data1", "data2"]);

// all targets will be highlighted
chart.focus();
Parameters:
Name Type Description
targetIdsValue string | Array

Target ids to be highlighted.

groups(groups) → {Array}

Description:
  • Update groups for the targets.

Source:
Example
// data1 and data2 will be a new group.
 chart.groups([
    ["data1", "data2"]
 ]);
Parameters:
Name Type Description
groups Array

This argument needs to be an Array that includes one or more Array that includes target ids to be grouped.

Returns:

Grouped data names array

Type
Array

hide(targetIdsValueopt, optionsopt)

Description:
  • Hide data series from chart

Source:
Example
// hide 'data1'
chart.hide("data1");

// hide 'data1' and 'data3'
chart.hide(["data1", "data3"]);
Parameters:
Name Type Attributes Description
targetIdsValue string | Array <optional>

The target id value.

options object <optional>

The object can consist with following members:

Key Type default Description
withLegend boolean false whether or not display legend

legend․hide(targetIds)

Description:
  • Hide legend for each target.

Source:
Example
// Hide legend for data1.
chart.legend.hide("data1");

// Hide legend for data1 and data2.
chart.legend.hide(["data1", "data2"]);

// Hide all legend.
chart.legend.hide();
Parameters:
Name Type Description
targetIds string | Array
  • If targetIds is given, specified target's legend will be hidden.
  • If only one target is the candidate, String can be passed.
  • If no argument is given, all of target's legend will be hidden.

legend․show(targetIds)

Description:
  • Show legend for each target.

    • NOTE: Legend APIs aren't supported for treemap type.
Source:
Example
// Show legend for data1.
chart.legend.show("data1");

// Show legend for data1 and data2.
chart.legend.show(["data1", "data2"]);

// Show all legend.
chart.legend.show();
Parameters:
Name Type Description
targetIds string | Array
  • If targetIds is given, specified target's legend will be shown.
  • If only one target is the candidate, String can be passed.
  • If no argument is given, all of target's legend will be shown.

load(args)

Description:
  • Load data to the chart.

    You can specify multiple targets by giving an array that includes id as String. If no argument is given, all of targets will be toggles.

    • Note:
      • unload should be used if some data needs to be unloaded simultaneously. If you call unload API soon after/before load instead of unload param, chart will not be rendered properly because of cancel of animation.
      • done will be called after data loaded, but it's not after rendering. It's because rendering will finish after some transition and there is some time lag between loading and rendering
Source:
See:
Examples
// Load data1 and unload data2 and data3
chart.load({
    columns: [
       ["data1", 100, 200, 150, ...],
       ...
   ],
   unload: ["data2", "data3"],
   url: "...",
   done: function() { ... }
   resizeAfter: true  // will resize after load
});
const chart = bb.generate({
  data: {
    columns: [
      ["data1", 20, 30, 40]
    ]
  }
});

chart.load({
   columns: [
       // with 'append' option, the 'data1' will have `[20,30,40,50,60]`.
       ["data1", 50, 60]
   ],
   append: true
});
const chart = bb.generate({
  data: {
    x: "x",
    xFormat: "%Y-%m-%dT%H:%M:%S",
    columns: [
      ["x", "2021-01-03T03:00:00", "2021-01-04T12:00:00", "2021-01-05T21:00:00"],
      ["data1", 36, 30, 24]
    ]
  },
  axis: {
    x: {
      type: "timeseries"
    }
  }
};

chart.load({
  columns: [
    // when existing chart has `x` value, should provide correponding 'x' value.
    // with 'append' option, the 'data1' will have `[36,30,24,37]`.
    ["x", "2021-02-01T08:00:00"],
    ["data1", 37]
  ],
  append: true
});
// myAPI.json
// {
//   "data1": [220, 240, 270, 250, 280],
//   "data2": [180, 150, 300, 70, 120]
// }

chart.load({
    url: './data/myAPI.json',
    mimeType: "json",

    // set request header if is needed
    headers: {
      "Content-Type": "text/json"
    }
});
chart.load({
    data: [
      // equivalent as: columns: [["data1", 30, 200, 100]]
      {"data1": 30}, {"data1": 200}, {"data1": 100}

      // or
      // equivalent as: columns: [["data1", 10, 20], ["data2", 13, 30]]
      // {"data1": 10, "data2": 13}, {"data1": 20, "data2": 30}}
    ]
});
chart.load({
    json: [
         {name: "www.site1.com", upload: 800, download: 500, total: 400},
    ],
    keys: {
        x: "name",
        value: ["upload", "download"]
    }
});
chart.load({
  json: {
      data1:[30, 20, 50, 40, 60, 50],
      data2:[200, 130, 90, 240, 130, 220],
  }
});
Parameters:
Name Type Description
args object

The object can consist with following members:

Key Type Description
columns Array The columns data will be loaded. If data that has the same target id is given, the chart will be updated. Otherwise, new target will be added
json Array The json data will be loaded. If data that has the same target id is given, the chart will be updated. Otherwise, new target will be added
rows Array The rows data will be loaded. If data that has the same target id is given, the chart will be updated. Otherwise, new target will be added
url string The data from url will be loaded. If data that has the same target id is given, the chart will be updated. Otherwise, new target will be added
 
append boolean Load data appending it to the current dataseries.
If the existing chart hasx value, should provide with corresponding x value for newly loaded data.
axes Object The axes specified by data.axes will be updated. axes must be Object that has target id as keys.
categories Array The categories specified by axis.x.categories or data.x will be updated. categories must be Array.
classes Object The classes specified by data.classes will be updated. classes must be Object that has target id as keys.
colors Object The colors specified by data.colors will be updated. colors must be Object that has target id as keys.
data Obejct Data objects to be loaded. Checkout the example.
done Function The specified function will be called after data loaded.
headers string Set request header if loading via data.url.
@see data․headers
keys Object Choose which JSON objects keys correspond to desired data.
NOTE: Only for JSON object given as array.
@see data․keys
mimeType string Set 'json' if loading JSON via url.
@see data․mimeType
names Object Same as data.names()
resizeAfter boolean Resize after the load. Default value is false.
- This option won't call onresize neither onresized.
- When set to 'true', will call .flush(true) at the end of load.
type string The type of targets will be updated.
types Object The types of targets will be updated.
unload Array Specify the data will be unloaded before loading new data. If true given, all of data will be unloaded. If target ids given as String or Array, specified targets will be unloaded. If absent or false given, unload will not occur.
xs string Same as data.xs option

regions(regions) → {Array}

Description:
  • Update regions.

Source:
Example
// Show 2 regions
chart.regions([
   {axis: "x", start: 5, class: "regionX"},
   {
     axis: "y", end: 50, class: "regionY",
     label: {
     	text: "Region Text",
     	x: 5,  // position relative of the initial x coordinate
     	y: 5,  // position relative of the initial y coordinate
     	color: "red",  // color string
     	rotated: true  // make text to show in vertical or horizontal
     }
   }
]);
Parameters:
Name Type Description
regions Array

Regions will be replaced with this argument. The format of this argument is the same as regions.

Returns:

regions

Type
Array

regions․add(regions) → {Array}

Description:
  • Add new region.

    This API adds new region instead of replacing like regions.

Source:
Example
// Add a new region
chart.regions.add(
   {
     axis: "x", start: 5, class: "regionX",
     label: {
     	text: "Region Text",
     	color: "red"  // color string
     }
   }
);

// Add new regions
chart.regions.add([
   {axis: "x", start: 5, class: "regionX"},
   {
     axis: "y", end: 50, class: "regionY",
     label: {
     	text: "Region Text",
     	x: 5,  // position relative of the initial x coordinate
     	y: 5,  // position relative of the initial y coordinate
     	color: "red",  // color string
     	rotated: true  // make text to show in vertical or horizontal
     }
   }
]);
Parameters:
Name Type Description
regions Array | object

New region will be added. The format of this argument is the same as regions and it's possible to give an Object if only one region will be added.

Returns:

regions

Type
Array

regions․remove(optionsValue) → {Array}

Description:
  • Remove regions.

    This API removes regions.

Source:
Example
// regions that have 'region-A' or 'region-B' will be removed.
chart.regions.remove({
  classes: [
    "region-A", "region-B"
  ]
});

// all of regions will be removed.
chart.regions.remove();
Parameters:
Name Type Description
optionsValue object

This argument should include classes. If classes is given, the regions that have one of the specified classes will be removed. If args is not given, all of regions will be removed.

Returns:

regions Removed regions

Type
Array

resize(size)

Description:
  • Resize the chart.

Source:
Example
// Resize to 640x480
chart.resize({
   width: 640,
   height: 480
});
Parameters:
Name Type Description
size object

This argument should include width and height in pixels.

Properties
Name Type Attributes Description
width number <optional>

width value

height number <optional>

height value

revert(targetIdsValue)

Description:
  • Revert focused or defocused state to initial state.

    You can specify multiple targets by giving an array that includes id as string. If no argument is given, all of targets will be reverted.

Source:
Example
// 'data1' will be reverted.
chart.revert("data1");

// 'data1' and 'data2' will be reverted.
chart.revert(["data1", "data2"]);

// all targets will be reverted.
chart.revert();
Parameters:
Name Type Description
targetIdsValue string | Array

Target ids to be reverted

select(idsopt, indicesopt, resetOtheropt)

Description:
Source:
Example
// select all data points
 chart.select();

 // select all from 'data2'
 chart.select("data2");

 // select all from 'data1' and 'data2'
 chart.select(["data1", "data2"]);

 // select from 'data1', indices 2 and unselect others selected
 chart.select("data1", [2], true);

 // select from 'data1', indices 0, 3 and 5
 chart.select("data1", [0, 3, 5]);
Parameters:
Name Type Attributes Description
ids string | Array <optional>

id value to get selected.

indices Array <optional>

The index array of data points. If falsy value given, will select all data points.

resetOther boolean <optional>

Unselect already selected.

selected(targetIdopt) → {Array}

Description:
  • Get selected data points.

    By this API, you can get selected data points information. To use this API, data.selection.enabled needs to be set true.

Source:
Example
// all selected data points will be returned.
 chart.selected();
 // --> ex.) [{x: 1, value: 200, id: "data1", index: 1, name: "data1"}, ... ]

 // all selected data points of data1 will be returned.
 chart.selected("data1");
Parameters:
Name Type Attributes Description
targetId string <optional>

You can filter the result by giving target id that you want to get. If not given, all of data points will be returned.

Returns:

dataPoint Array of the data points.
ex.) [{x: 1, value: 200, id: "data1", index: 1, name: "data1"}, ...]

Type
Array

show(targetIdsValueopt, optionsopt)

Description:
  • Show data series on chart

Source:
Example
// show 'data1'
chart.show("data1");

// show 'data1' and 'data3'
chart.show(["data1", "data3"]);
Parameters:
Name Type Attributes Description
targetIdsValue string | Array <optional>

The target id value.

options object <optional>

The object can consist with following members:

Key Type default Description
withLegend boolean false whether or not display legend

subchart(domainValue) → {Array}

Description:
  • Select subchart by giving x domain range.

    • ℹ️ NOTE:
    • Due to the limitations of floating point precision, domain value may not be exact returning approximately values.
Source:
Example
// Specify domain for subchart selection
 chart.subchart([1, 2]);

 // Get the current subchart selection domain range
 // Domain value may not be exact returning approximately values.
 chart.subchart();
Parameters:
Name Type Description
domainValue Array

If domain range is given, the subchart will be seleted to the given domain. If no argument is given, the current subchart selection domain will be returned.

Returns:

domain value in array

Type
Array

subchart․hide()

Description:
  • Hide generated subchart

    • NOTE: for ESM imports, needs to import 'subchart' exports and instantiate it by calling subchart().
Source:
Example
chart.subchart.hide();

subchart․reset()

Description:
  • Reset subchart selection

Source:
Example
// Reset subchart selection
chart.subchart.reset();

subchart․show()

Description:
  • Show subchart

    • NOTE: for ESM imports, needs to import 'subchart' exports and instantiate it by calling subchart().
Source:
Example
// for ESM imports, needs to import 'subchart' and must be instantiated first to enable subchart's API.
import {subchart} from "billboard.js";

const chart = bb.generate({
  ...
  subchart: {
     // need to be instantiated by calling 'subchart()'
     enabled: subchart()

     // in case don't want subchart to be shown at initialization, instantiate with '!subchart()'
     enabled: !subchart()
  }
});

chart.subchart.show();

subchart․toggle()

Description:
  • Toggle the visiblity of subchart

    • NOTE: for ESM imports, needs to import 'subchart' exports and instantiate it by calling subchart().
Source:
Example
// When subchart is hidden, will be shown
// When subchart is shown, will be hidden
chart.subchart.toggle();

toggle(targetIdsopt, optionsopt)

Description:
  • Toggle data series on chart. When target data is hidden, it will show. If is shown, it will hide in vice versa.

Source:
Example
// toggle 'data1'
chart.toggle("data1");

// toggle 'data1' and 'data3'
chart.toggle(["data1", "data3"]);
Parameters:
Name Type Attributes Description
targetIds string | Array <optional>

The target id value.

options object <optional>

The object can consist with following members:

Key Type default Description
withLegend boolean false whether or not display legend

tooltip․hide()

Description:
  • Hide tooltip

Source:

tooltip․show(args)

Description:
  • Show tooltip

Source:
Example
// show the 2nd x Axis coordinate tooltip
 // for Arc(gauge, donut & pie) and radar type, approch showing tooltip by using "index" number.
 chart.tooltip.show({
   index: 1
 });

 // show tooltip for the 3rd x Axis in x:50 and y:100 coordinate of '.bb-event-rect' of the x Axis.
 chart.tooltip.show({
   x: 2,
   mouse: [50, 100]
 });

 // show tooltip for timeseries x axis
 chart.tooltip.show({
   x: new Date("2018-01-02 00:00")
 });

 // treemap type can be shown by using "id" only.
 chart.tooltip.show({
   data: {
       id: "data1"  // data id
   }
 });

 // for Arc types, specify 'id' or 'index'
 chart.tooltip.show({ data: { id: "data2" }});
 chart.tooltip.show({ data: { index: 2 }});

 // when data.xs is used
 chart.tooltip.show({
   data: {
       x: 3,  // x Axis value
       id: "data1",  // data id
       value: 500  // data value
   }
 });

 // when data.xs isn't used, but tooltip.grouped=false is set
 chart.tooltip.show({
   data: {
       index: 3,  // or 'x' key value
       id: "data1",  // data id
       value: 500  // data value
   }
 });
Parameters:
Name Type Description
args object

The object can consist with following members:

Key Type Description
index Number Determine focus by index
x Number | Date Determine focus by x Axis index
mouse Array Determine x and y coordinate value relative the targeted '.bb-event-rect' x Axis.
It should be used along with data, index or x value. The default value is set as [0,0]
data Object When data.xs option is used or tooltip.grouped set to 'false', should be used giving this param.

Key:
- x {number | Date}: x Axis value
- index {number}: x Axis index (useless for data.xs)
- id {string}: data id
- value {number}: The corresponding value for tooltip.

unload(argsValue)

Description:
  • Unload data to the chart.

    You can specify multiple targets by giving an array that includes id as String. If no argument is given, all of targets will be toggles.

    • Note: If you call load API soon after/before unload, unload param of load should be used. Otherwise chart will not be rendered properly because of cancel of animation.
      done will be called after data loaded, but it's not after rendering. It's because rendering will finish after some transition and there is some time lag between loading and rendering.
Source:
Example
// Unload data2 and data3
 chart.unload({
   ids: ["data2", "data3"],
   done: function() {
      // called after the unloaded
   },
   resizeAfter: true  // will resize after unload
 });
Parameters:
Name Type Description
argsValue object
key Type Description
ids String | Array Target id data to be unloaded. If not given, all data will be unloaded.
done Fuction Callback after data is unloaded.
resizeAfter boolean Resize after the unload. Default value is false.
- This option won't call onresize neither onresized.
- When set to 'true', will call .flush(true) at the end of unload.

unselect(idsopt, indicesopt)

Description:
  • Set data points to be un-selected.

Source:
Example
// unselect all data points
 chart.unselect();

 // unselect all from 'data1'
 chart.unselect("data1");

 // unselect from 'data1', indices 2
 chart.unselect("data1", [2]);
Parameters:
Name Type Attributes Description
ids string | Array <optional>

id value to be unselected.

indices Array <optional>

The index array of data points. If falsy value given, will select all data points.

unzoom()

Description:
  • Unzoom zoomed area

    • NOTE: Calling .unzoom() will not trigger zoom events.
Source:
Example
chart.unzoom();

x(x) → {object}

Description:
  • Get and set x values for the chart.

Source:
Example
// Get current x values
 chart.x();

 // Update x values for all targets
 chart.x([100, 200, 300, 400, ...]);
Parameters:
Name Type Description
x Array

If x is given, x values of every target will be updated. If no argument is given, current x values will be returned as an Object whose keys are the target ids.

Returns:

xs

Type
object

xgrids(grids) → {Array}

Description:
  • Update x grid lines.

Source:
Example
// Show 2 x grid lines
chart.xgrids([
   {value: 1, text: "Label 1"},
   {value: 4, text: "Label 4"}
]);
// --> Returns: [{value: 1, text: "Label 1"}, {value: 4, text: "Label 4"}]
Parameters:
Name Type Description
grids Array

X grid lines will be replaced with this argument. The format of this argument is the same as grid.x.lines.

Returns:
Type
Array

xgrids․add(grids) → {Array}

Description:
  • Add x grid lines.
    This API adds new x grid lines instead of replacing like xgrids.

Source:
Example
// Add a new x grid line
chart.xgrids.add(
  {value: 4, text: "Label 4"}
);

// Add new x grid lines
chart.xgrids.add([
  {value: 2, text: "Label 2"},
  {value: 4, text: "Label 4"}
]);
Parameters:
Name Type Description
grids Array | object

New x grid lines will be added. The format of this argument is the same as grid.x.lines and it's possible to give an Object if only one line will be added.

Returns:
Type
Array

xgrids․remove(grids) → {void}

Description:
  • Remove x grid lines.
    This API removes x grid lines.

Source:
Example
// x grid line on x = 2 will be removed
chart.xgrids.remove({value: 2});

// x grid lines that have 'grid-A' will be removed
chart.xgrids.remove({
  class: "grid-A"
});

// all of x grid lines will be removed
chart.xgrids.remove();
Parameters:
Name Type Description
grids object

This argument should include value or class. If value is given, the x grid lines that have specified x value will be removed. If class is given, the x grid lines that have specified class will be removed. If args is not given, all of x grid lines will be removed.

Properties
Name Type Attributes Description
value number <optional>

target value

class string <optional>

target class

Returns:
Type
void

xs(xs) → {object}

Description:
  • Get and set x values for the chart.

Source:
Example
// Get current x values
 chart.xs();

 // Update x values for all targets
 chart.xs({
   data1: [10, 20, 30, 40, ...],
   data2: [100, 200, 300, 400, ...]
 });
Parameters:
Name Type Description
xs Array

If xs is given, specified target's x values will be updated. If no argument is given, current x values will be returned as an Object whose keys are the target ids.

Returns:

xs

Type
object

ygrids(grids) → {object}

Description:
  • Update y grid lines.

Source:
Example
// Show 2 y grid lines
chart.ygrids([
   {value: 100, text: "Label 1"},
   {value: 400, text: "Label 4"}
]);
// --> Returns: [{value: 100, text: "Label 1"}, {value: 400, text: "Label 4"}]
Parameters:
Name Type Description
grids Array

Y grid lines will be replaced with this argument. The format of this argument is the same as grid.y.lines.

Returns:
Type
object

ygrids․add(grids) → {object}

Description:
  • Add y grid lines.
    This API adds new y grid lines instead of replacing like ygrids.

Source:
Example
// Add a new x grid line
chart.ygrids.add(
  {value: 400, text: "Label 4"}
);

// Add new x grid lines
chart.ygrids.add([
  {value: 200, text: "Label 2"},
  {value: 400, text: "Label 4"}
]);
Parameters:
Name Type Description
grids Array | object

New y grid lines will be added. The format of this argument is the same as grid.y.lines and it's possible to give an Object if only one line will be added.

Returns:
Type
object

ygrids․remove(grids) → {void}

Description:
  • Remove y grid lines.
    This API removes x grid lines.

Source:
Example
// y grid line on y = 200 will be removed
chart.ygrids.remove({value: 200});

// y grid lines that have 'grid-A' will be removed
chart.ygrids.remove({
  class: "grid-A"
});

// all of y grid lines will be removed
chart.ygrids.remove();
Parameters:
Name Type Description
grids object

This argument should include value or class. If value is given, the y grid lines that have specified y value will be removed. If class is given, the y grid lines that have specified class will be removed. If args is not given, all of y grid lines will be removed.

Properties
Name Type Attributes Description
value number <optional>

target value

class string <optional>

target class

Returns:
Type
void

zoom(domainValue) → {Array}

Description:
  • Zoom by giving x domain range.

    • ℹ️ NOTE:
    • For wheel type zoom, the minimum zoom range will be set as the given domain range. To get the initial state, .unzoom() should be called.
    • To be used zoom.enabled option should be set as truthy.
    • When x axis type is category, domain range should be specified as index numbers.
    • Due to the limitations of floating point precision, domain value may not be exact returning approximately values.
Source:
Example
// Zoom to specified domain range
 chart.zoom([10, 20]);

 // For timeseries x axis, the domain value can be string, but the format should match with the 'data.xFormat' option.
 chart.zoom(["2021-02-03", "2021-02-08"]);

 // For category x axis, the domain value should be index number.
 chart.zoom([0, 3]);

 // Get the current zoomed domain range
 // Domain value may not be exact returning approximately values.
 chart.zoom();
Parameters:
Name Type Description
domainValue Array

If domain range is given, the chart will be zoomed to the given domain. If no argument is given, the current zoomed domain will be returned.

Returns:

domain value in array

Type
Array

zoom․enable(enabled)

Description:
  • Enable and disable zooming.

Source:
Example
// Enable zooming using the mouse wheel
 chart.zoom.enable(true);
 // Or
 chart.zoom.enable("wheel");

 // Enable zooming by dragging
 chart.zoom.enable("drag");

 // Disable zooming
 chart.zoom.enable(false);
Parameters:
Name Type Description
enabled string | boolean

Possible string values are "wheel" or "drag". If enabled is true, "wheel" will be used. If false is given, zooming will be disabled.
When set to false, the current zooming status will be reset.

zoom․max(maxopt) → {number}

Description:
  • Set or get x Axis maximum zoom range value

Source:
Example
// Set maximum range value
 chart.zoom.max(20);
Parameters:
Name Type Attributes Description
max number <optional>

maximum value to set for zoom

Returns:

zoom max value

Type
number

zoom․min(minopt) → {number}

Description:
  • Set or get x Axis minimum zoom range value

Source:
Example
// Set minimum range value
 chart.zoom.min(-1);
Parameters:
Name Type Attributes Description
min number <optional>

minimum value to set for zoom

Returns:

zoom min value

Type
number

zoom․range(rangeopt) → {object}

Description:
  • Set zoom range

Source:
Example
chart.zoom.range({
     min: 10,
     max: 100
 });
Parameters:
Name Type Attributes Description
range object <optional>

zoom range

Returns:

zoom range value { min: 0, max: 100 }

Type
object