Options

Options

new Options()

Source:
See:
  • bb.generate to use these options on generating the chart

Class to set options on generating chart.

  • It's instantiated internally, not exposed for public.

Members

(static) area :object

Source:
See:
Properties:
Name Type Description
area object

Area object

Properties
Name Type Attributes Default Description
above boolean <optional>
 false

Set background area above the data chart line.
front boolean <optional>
 true

Set area node to be positioned over line node.
linearGradient boolean | object <optional>
 false

Set the linear gradient on area.

Or customize by giving below object value:

  • x {Array}: x1, x2 value
  • y {Array}: y1, y2 value
  • stops {Array}: Each item should be having [offset, stop-color, stop-opacity] values.
zerobased boolean <optional>
 true

Set if min or max value will be 0 on area chart.

Set area options

Type:
  • object
Example
area: {
     above: true,
     zerobased: false,

     // <g class='bb-areas'> will be positioned behind the line <g class='bb-lines'> in stacking order
     front: false,

     // will generate follwing linearGradient:
     // <linearGradient x1="0" x2="0" y1="0" y2="1">
     //    <stop offset="0" stop-color="$DATA_COLOR" stop-opacity="1"></stop>
     //    <stop offset="1" stop-color="$DATA_COLOR" stop-opacity="0"></stop>
     // </linearGradient>
     linearGradient: true,

     // Or customized gradient
     linearGradient: {
     	x: [0, 0],  // x1, x2 attributes
     	y: [0, 0],  // y1, y2 attributes
     	stops: [
     	  // offset, stop-color, stop-opacity
     	  [0, "#7cb5ec", 1],

     	  // setting 'null' for stop-color, will set its original data color
     	  [0.5, null, 0],

     	  // setting 'function' for stop-color, will pass data id as argument.
     	  // It should return color string or null value
     	  [1, function(id) { return id === "data1" ? "red" : "blue"; }, 0],
     	]
     }
 }

(static) axis․rotated :boolean

Source:
Default Value:
  • false

Switch x and y axis position.

Type:
  • boolean
Example
axis: {
  rotated: true
}

(static) axis․x․axes :Array

Source:
See:

Set additional axes for x Axis.

  • NOTE: Axis' scale is based on x Axis value if domain option isn't set.

Each axis object should consist with following options:

Name Type Default Description
domain Array - Set the domain value
tick.outer boolean true Show outer tick
tick.format Function - Set formatter for tick text
tick.count Number - Set the number of y axis ticks
tick.values Array - Set tick values manually
Type:
  • Array
Example
x: {
   axes: [
     {
       // if set, will not be correlated with the main x Axis domain value
       domain: [0, 1000],
       tick: {
         outer: false,
         format: function(x) {
            return x + "%";
         },
         count: 2,
         values: [10, 20, 30]
       }
     },
     ...
   ]
}

(static) axis․x․categories :Array

Source:
Default Value:
  • []

Set category names on category axis. 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.

Type:
  • Array
Example
axis: {
  x: {
    categories: ["Category 1", "Category 2", ...]
  }
}

(static) axis․x․clipPath :boolean

Source:
Default Value:
  • true
See:

Set clip-path attribute for x axis element

Type:
  • boolean
Example
// don't set 'clip-path' attribute
clipPath: false

(static) axis․x․extent :Array|function

Source:
Default Value:
  • undefined

Set default extent for subchart and zoom. This can be an array or function that returns an array.

Type:
  • Array | function
Example
axis: {
  x: {
    // extent range as a pixel value
    extent: [0, 200],

    // when axis is 'timeseries', parsable datetime string
    extent: ["2019-03-01", "2019-03-05"],

    // return extent value
    extent: function(domain, scale) {
   	 var extent = domain.map(function(v) {
    	    return scale(v);
    	 });

  	 // it should return a format of array
  	 // ex) [0, 584]
    	 return extent;
    }
  }
}

(static) axis․x․height :number

Source:
Default Value:
  • undefined

Set height of x axis.

The height of x axis can be set manually by this option. If you need more space for x axis, please use this option for that. The unit is pixel.

Type:
  • number
Example
axis: {
  x: {
    height: 20
  }
}

(static) axis․x․label :string|object

Source:
Default Value:
  • undefined

Set label on x axis.

You can set x axis label and change its position by this option. string and object can be passed and we can change the poisiton by passing object that has position key.
Available position differs according to the axis direction (vertical or horizontal). If string set, the position will be the default.

  • If it's horizontal axis:
    • inner-right [default]
    • inner-center
    • inner-left
    • outer-right
    • outer-center
    • outer-left
  • If it's vertical axis:
    • inner-top [default]
    • inner-middle
    • inner-bottom
    • outer-top
    • outer-middle
    • outer-bottom
Type:
  • string | object
Example
axis: {
  x: {
    label: "Your X Axis"
  }
}

axis: {
  x: {
    label: {
       text: "Your X Axis",
       position: "outer-center"
    }
  }
}

(static) axis․x․localtime :boolean

Source:
Default Value:
  • true

Set how to treat the timezone of x values.
If true, treat x value as localtime. If false, convert to UTC internally.

Type:
  • boolean
Example
axis: {
  x: {
    localtime: false
  }
}

(static) axis․x․max

Source:
Properties:
Name Type Description
max number

Set the max value

Properties
Name Type Attributes Default Description
fit boolean <optional>
 false

When specified max.value is greater than the bound data value, setting true will make x axis max to be fitted to the bound data max value.

  • NOTE: If the bound data max value is greater than the max.value, the x axis max will be limited as the given max.value.
value number <optional>

Set the max value

Set max value of x axis range.

Example
axis: {
  x: {
    max: 100,

    max: {
      // 'fit=true' will make x axis max to be limited as the bound data value max when 'max.value' is greater.
      // - when bound data max is '10' and max.value: '100' ==>  x axis max will be '10'
      // - when bound data max is '1000' and max.value: '100' ==> x axis max will be '100'
      fit: true,
      value: 100
    }
  }
}

(static) axis․x․min

Source:
Properties:
Name Type Description
min number

Set the min value

Properties
Name Type Attributes Default Description
fit boolean <optional>
 false

When specified min.value is lower than the bound data value, setting true will make x axis min to be fitted to the bound data min value.

  • NOTE: If the bound data min value is lower than the min.value, the x axis min will be limited as the given min.value.
value number <optional>

Set the min value

Set min value of x axis range.

Example
axis: {
  x: {
    min: -100,

    min: {
      // 'fit=true' will make x axis min to be limited as the bound data value min when 'min.value' is lower.
      // - when bound data min is '-10' and min.value: '-100' ==>  x axis min will be '-10'
      // - when bound data min is '-1000' and min.value: '-100' ==> x axis min will be '-100'
      fit: true,
      value: -100
    }
  }
}

(static) axis․x․padding :object|number

Source:
Default Value:
  • {}

Set padding for x axis.

If this option is set, the range of x axis will increase/decrease according to the values. If no padding is needed in the rage of x axis, 0 should be set. By default, left/right padding are set depending on x axis type or chart types.

  • NOTE:
    • The meaning of padding values, differs according axis types:
      • category/indexed: The unit of tick value ex. the given value 1, is same as the width of 1 tick width
      • timeseries: Numeric time value ex. the given value 1000*60*60*24, which is numeric time equivalent of a day, is same as the width of 1 tick width
    • If want values to be treated as pixels, specify unit:"px".
      • The pixel value will be convered based on the scale values. Hence can not reflect accurate padding result.
Type:
  • object | number
Example
axis: {
  x: {
    padding: {
      // when axis type is 'category'
      left: 1,  // set left padding width of equivalent value of a tick's width
      right: 0.5  // set right padding width as half of equivalent value of tick's width

      // when axis type is 'timeseries'
      left: 1000*60*60*24,  // set left padding width of equivalent value of a day tick's width
      right: 1000*60*60*12   // set right padding width as half of equivalent value of a day tick's width
    },

    // or set both values at once.
    padding: 10,

    // or set padding values as pixel unit.
    padding: {
      left: 100,
      right: 50,
      unit: "px"
    },
  }
}

(static) axis․x․show :boolean

Source:
Default Value:
  • true

Show or hide x axis.

Type:
  • boolean
Example
axis: {
  x: {
    show: false
  }
}

(static) axis․x․tick․autorotate :boolean

Source:
Default Value:
  • false
See:

Rotate x axis tick text if there is not enough space for 'category' and 'timeseries' type axis.

  • NOTE: The conditions where autorotate is enabled are:
    • axis.x.type='category' or 'timeseries
    • axis.x.tick.multiline=false
    • axis.x.tick.culling=false
    • axis.x.tick.fit=true
  • NOTE: axis.x.tick.clippath=false is necessary for calculating the overflow padding between the end of x axis and the width of the SVG
Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      rotate: 15,
      autorotate: true,
      multiline: false,
      culling: false,
      fit: true
    },
    clipPath: false
  }
}

(static) axis․x․tick․centered :boolean

Source:
Default Value:
  • false

centerize ticks on category axis.

Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      centered: true
    }
  }
}

(static) axis․x․tick․count :number

Source:
Default Value:
  • undefined

The number of x axis ticks to show.

This option hides tick lines together with tick text. If this option is used on timeseries axis, the ticks position will be determined precisely and not nicely positioned (e.g. it will have rough second value).

Type:
  • number
Example
axis: {
  x: {
    tick: {
      count: 5
    }
  }
}

(static) axis․x․tick․culling :boolean

Source:
Default Value:
  • `true` for indexed axis and timeseries axis, `false` for category axis

Setting for culling ticks.

  • true: the ticks will be culled, then only limited tick text will be shown.
    This option does not hide the tick lines by default, if want to hide tick lines, set axis.x.tick.culling.lines=false.
  • false: all of ticks will be shown.

    The number of ticks to be shown can be chaned by axis.x.tick.culling.max.
Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      culling: false
    }
  }
}

(static) axis․x․tick․culling․lines :boolean

Source:
Default Value:
  • true

Control visibility of tick lines within culling option, along with tick text.

Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      culling: {
          lines: false,
      }
    }
  }
}

(static) axis․x․tick․culling․max :number

Source:
Default Value:
  • 10

The number of tick texts will be adjusted to less than this value.

Type:
  • number
Example
axis: {
  x: {
    tick: {
      culling: {
          max: 5
      }
    }
  }
}

(static) axis․x․tick․fit :boolean

Source:
Default Value:
  • true
See:

Fit x axis ticks.

  • true: ticks will be shown according to x value of the data points.
  • false: ticks will be shown as to have same intervals.
Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      fit: false
    }
  }
}

(static) axis․x․tick․format :function|string

Source:
Default Value:
  • undefined
See:

A function to format tick value. Format string is also available for timeseries data.

Type:
  • function | string
Example
axis: {
  x: {
    tick: {
       // for timeseries, a 'datetime' object is given as parameter
      format: function(x) {
          return x.getFullYear();
      }

      // for category, index(Number) and categoryName(String) are given as parameter
      format: function(index, categoryName) {
          return categoryName.substr(0, 10);
      },

       // for timeseries format specifier
       format: "%Y-%m-%d %H:%M:%S"
    }
  }
}

(static) axis․x․tick․multiline :boolean

Source:
Default Value:
  • true
See:

Set tick text to be multiline

  • NOTE:

When x tick text contains \n, it's used as line break and 'axis.x.tick.width' option is ignored.

Type:
  • boolean
Examples
axis: {
  x: {
    tick: {
      multiline: false
    }
  }
}
// example of line break with '\n'
// In this case, 'axis.x.tick.width' is ignored
data: {
   x: "x",
   columns: [
       ["x", "long\ntext", "Another\nLong\nText"],
       ...
   ],
}

(static) axis․x․tick․outer :boolean

Source:
Default Value:
  • true

Show x axis outer tick.

Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      outer: false
    }
  }
}

(static) axis․x․tick․rotate :number

Source:
Default Value:
  • 0
See:

Rotate x axis tick text.

  • If you set negative value, it will rotate to opposite direction.
  • Applied when axis.rotated option is false.
  • As long as axis_x_tick_fit is set to true it will calculate an overflow for the y2 axis and add this value to the right padding.
Type:
  • number
Example
axis: {
  x: {
    tick: {
      rotate: 60
    }
  }
}

(static) axis․x․tick․show :boolean

Source:
Default Value:
  • true
See:

Show or hide x axis tick line.

Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      show: false
    }
  }
}

(static) axis․x․tick․text․position :object

Source:
Default Value:
  • {x: 0, y:0}

Set the x Axis tick text's position relatively its original position

Type:
  • object
Example
axis: {
  x: {
    tick: {
      text: {
        position: {
          x: 10,
          y: 10
        }
      }
    }
  }
}

(static) axis․x․tick․text․show :boolean

Source:
Default Value:
  • true
See:

Show or hide x axis tick text.

Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      text: {
          show: false
      }
    }
  }
}

(static) axis․x․tick․tooltip :boolean

Source:
Default Value:
  • false

Set to display system tooltip(via 'title' attribute) for tick text

  • NOTE: Only available for category axis type (axis.x.type='category')
Type:
  • boolean
Example
axis: {
  x: {
    tick: {
      tooltip: true
    }
  }
}

(static) axis․x․tick․values :Array|function

Source:
Default Value:
  • null

Set the x values of ticks manually.

If this option is provided, the position of the ticks will be determined based on those values.
This option works with timeseries data and the x values will be parsed accoding to the type of the value and data.xFormat option.

Type:
  • Array | function
Example
axis: {
  x: {
    tick: {
      values: [1, 2, 4, 8, 16, 32, ...],

      // an Array value should be returned
      values: function() {
      	return [ ... ];
      }
    }
  }
}

(static) axis․x․tick․width :number

Source:
Default Value:
  • null

Set tick width

  • NOTE:

When x tick text contains \n, this option is ignored.

Type:
  • number
Example
axis: {
  x: {
    tick: {
      width: 50
    }
  }
}

(static) axis․x․type :string

Source:
Default Value:
  • indexed
See:

Set type of x axis.

Available Values:

  • category
  • indexed
  • log
  • timeseries

NOTE:

  • log type:
    • the x values specified by data.x(or by any equivalent option), must be exclusively-positive.
    • x axis min value should be >= 0.
Type:
  • string
Example
axis: {
  x: {
    type: "timeseries"
  }
}

(static) axis․y2․axes :Array

Source:
See:

Set additional axes for y2 Axis.

  • NOTE: Axis' scale is based on y2 Axis value if domain option isn't set.

Each axis object should consist with following options:

Name Type Default Description
domain Array - Set the domain value
tick.outer boolean true Show outer tick
tick.format Function - Set formatter for tick text
tick.count Number - Set the number of y axis ticks
tick.values Array - Set tick values manually
Type:
  • Array
Example
y2: {
   axes: [
     {
       // if set, will not be correlated with the main y2 Axis domain value
       domain: [0, 1000],
       tick: {
         outer: false,
         format: function(x) {
            return x + "%";
         },
         count: 2,
         values: [10, 20, 30]
       }
     },
     ...
   ]
}

(static) axis․y2․center :number

Source:
Default Value:
  • undefined

Set center value of y2 axis.

Type:
  • number
Example
axis: {
  y2: {
    center: 0
  }
}

(static) axis․y2․default :Array

Source:
Default Value:
  • undefined

Set default range of y2 axis.

This option set the default value for y2 axis when there is no data on init.

Type:
  • Array
Example
axis: {
  y2: {
    default: [0, 1000]
  }
}

(static) axis․y2․inner :boolean

Source:
Default Value:
  • false

Show y2 axis inside of the chart.

Type:
  • boolean
Example
axis: {
  y2: {
    inner: true
  }
}

(static) axis․y2․inverted :boolean

Source:
Default Value:
  • false

Change the direction of y2 axis.

If true set, the direction will be from the top to the bottom.

Type:
  • boolean
Example
axis: {
  y2: {
    inverted: true
  }
}

(static) axis․y2․label :string|object

Source:
Default Value:
  • {}
See:

Set label on y2 axis.

You can set y2 axis label and change its position by this option. This option works in the same way as axis.x.label.

Type:
  • string | object
Example
axis: {
  y2: {
    label: "Your Y2 Axis"
  }
}

axis: {
  y2: {
    label: {
       text: "Your Y2 Axis",
       position: "outer-middle"
    }
  }
}

(static) axis․y2․max :number

Source:
Default Value:
  • undefined

Set max value of y2 axis.

Type:
  • number
Example
axis: {
  y2: {
    max: 1000
  }
}

(static) axis․y2․min :number

Source:
Default Value:
  • undefined

Set min value of y2 axis.

Type:
  • number
Example
axis: {
  y2: {
    min: -1000
  }
}

(static) axis․y2․padding :object|number

Source:
Default Value:
  • {}

Set padding for y2 axis.

You can set padding for y2 axis to create more space on the edge of the axis. This option accepts object and it can include top and bottom. top, bottom will be treated as pixels.

  • NOTE:
    • Given values are translated relative to the y2 Axis domain value for padding
    • For area and bar type charts, area.zerobased or bar.zerobased options should be set to 'false` to get padded bottom.
Type:
  • object | number
Example
axis: {
  y2: {
    padding: {
      top: 100,
      bottom: 100
    }

    // or set both values at once.
    padding: 10
}

(static) axis․y2․show :boolean

Source:
Default Value:
  • false

Show or hide y2 axis.

  • NOTE:
    • When set to false will not generate y2 axis node. In this case, all 'y2' axis related functionality won't work properly.
    • If need to use 'y2' related options while y2 isn't visible, set the value true and control visibility by css display property.
Type:
  • boolean
Example
axis: {
  y2: {
    show: true
  }
}

(static) axis․y2․tick․count :number

Source:
Default Value:
  • undefined

Set the number of y2 axis ticks.

  • NOTE: This works in the same way as axis.y.tick.count.
Type:
  • number
Example
axis: {
  y2: {
    tick: {
      count: 5
    }
  }
}

(static) axis․y2․tick․culling :boolean

Source:
Default Value:
  • false

Setting for culling ticks.

  • true: the ticks will be culled, then only limited tick text will be shown.
    This option does not hide the tick lines by default, if want to hide tick lines, set axis.y2.tick.culling.lines=false.
  • false: all of ticks will be shown.

    The number of ticks to be shown can be chaned by axis.y2.tick.culling.max.
Type:
  • boolean
Example
axis: {
  y2: {
    tick: {
      culling: false
    }
  }
}

(static) axis․y2․tick․culling․lines :boolean

Source:
Default Value:
  • true

Control visibility of tick lines within culling option, along with tick text.

Type:
  • boolean
Example
axis: {
  y2: {
    tick: {
      culling: {
          lines: false,
      }
    }
  }
}

(static) axis․y2․tick․culling․max :number

Source:
Default Value:
  • 5

The number of tick texts will be adjusted to less than this value.

Type:
  • number
Example
axis: {
  y2: {
    tick: {
      culling: {
          max: 5
      }
    }
  }
}

(static) axis․y2․tick․format :function

Source:
Default Value:
  • undefined

Set formatter for y2 axis tick text.

This option works in the same way as axis.y.format.

Type:
  • function
Example
axis: {
  y2: {
    tick: {
      format: d3.format("$,")
      //or format: function(d) { return "$" + d; }
    }
  }
}

(static) axis․y2․tick․outer :boolean

Source:
Default Value:
  • true

Show or hide y2 axis outer tick.

Type:
  • boolean
Example
axis: {
  y2: {
    tick: {
      outer: false
    }
  }
}

(static) axis․y2․tick․rotate :number

Source:
Default Value:
  • 0

Rotate y2 axis tick text.

  • If you set negative value, it will rotate to opposite direction.
  • Applied when axis.rotated option is true.
Type:
  • number
Example
axis: {
  y2: {
    tick: {
      rotate: 60
    }
  }
}

(static) axis․y2․tick․show :boolean

Source:
Default Value:
  • true
See:

Show or hide y2 axis tick line.

Type:
  • boolean
Example
axis: {
  y2: {
    tick: {
      show: false
    }
  }
}

(static) axis․y2․tick․stepSize :number

Source:
See:

Set axis tick step(interval) size.

  • NOTE: Will be ignored if axis.y2.tick.count or axis.y2.tick.values options are set.
Type:
  • number
Example
axis: {
  y2: {
    tick: {
      // tick value will step as indicated interval value.
      // ex) 'stepSize=15' ==> [0, 15, 30, 45, 60]
      stepSize: 15
    }
  }
}

(static) axis․y2․tick․text․position :object

Source:
Default Value:
  • {x: 0, y:0}

Set the y2 Axis tick text's position relatively its original position

Type:
  • object
Example
axis: {
  y2: {
    tick: {
      text: {
        position: {
          x: 10,
          y: 10
        }
      }
    }
  }
}

(static) axis․y2․tick․text․show :boolean

Source:
Default Value:
  • true
See:

Show or hide y2 axis tick text.

Type:
  • boolean
Example
axis: {
  y2: {
    tick: {
      text: {
          show: false
      }
    }
  }
}

(static) axis․y2․tick․values :Array|function

Source:
Default Value:
  • null

Set y2 axis tick values manually.

Type:
  • Array | function
Example
axis: {
  y2: {
    tick: {
      values: [100, 1000, 10000],

      // an Array value should be returned
      values: function() {
      	return [ ... ];
      }
    }
  }
}

(static) axis․y2․type :string

Source:
Default Value:
  • "indexed"
See:

Set type of y2 axis.

Available Values:

  • indexed
  • log
  • timeseries

NOTE:

  • log type:
    • the bound data values must be exclusively-positive.
    • y2 axis min value should be >= 0.
    • data.groups(stacked data) option aren't supported.
Type:
  • string
Example
axis: {
  y2: {
    type: "indexed"
  }
}

(static) axis․y․axes :Array

Source:
See:

Set additional axes for y Axis.

  • NOTE: Axis' scale is based on y Axis value if domain option isn't set.

Each axis object should consist with following options:

Name Type Default Description
domain Array - Set the domain value
tick.outer boolean true Show outer tick
tick.format Function - Set formatter for tick text
tick.count Number - Set the number of y axis ticks
tick.values Array - Set tick values manually
Type:
  • Array
Example
y: {
   axes: [
     {
       // if set, will not be correlated with the main y Axis domain value
       domain: [0, 1000],
       tick: {
         outer: false,
         format: function(x) {
            return x + "%";
         },
         count: 2,
         values: [10, 20, 30]
       }
     },
     ...
   ]
}

(static) axis․y․center :number

Source:
Default Value:
  • undefined

Set center value of y axis.

Type:
  • number
Example
axis: {
  y: {
    center: 0
  }
}

(static) axis․y․clipPath :boolean

Source:
Default Value:
  • true

Set clip-path attribute for y axis element

  • NOTE: clip-path attribute for y Axis is set only when axis.y.inner option is true.
Type:
  • boolean
Example
// don't set 'clip-path' attribute
clipPath: false

(static) axis․y․default :Array

Source:
Default Value:
  • undefined

Set default range of y axis.

This option set the default value for y axis when there is no data on init.

Type:
  • Array
Example
axis: {
  y: {
    default: [0, 1000]
  }
}

(static) axis․y․inner :boolean

Source:
Default Value:
  • false

Show y axis inside of the chart.

Type:
  • boolean
Example
axis: {
  y: {
    inner: true
  }
}

(static) axis․y․inverted :boolean

Source:
Default Value:
  • false

Change the direction of y axis.

If true set, the direction will be from the top to the bottom.

Type:
  • boolean
Example
axis: {
  y: {
    inverted: true
  }
}

(static) axis․y․label :string|object

Source:
Default Value:
  • {}
See:

Set label on y axis.

You can set y axis label and change its position by this option. This option works in the same way as axis.x.label.

Type:
  • string | object
Example
axis: {
  y: {
    label: "Your Y Axis"
  }
}

axis: {
  y: {
    label: {
       text: "Your Y Axis",
       position: "outer-middle"
    }
  }
}

(static) axis․y․max :number

Source:
Default Value:
  • undefined

Set max value of y axis.

  • NOTE: Padding will be added based on this value, so if you don't need the padding, please set axis.y.padding to disable it (e.g. axis.y.padding = 0).
Type:
  • number
Example
axis: {
  y: {
    max: 1000
  }
}

(static) axis․y․min :number

Source:
Default Value:
  • undefined

Set min value of y axis.

  • NOTE: Padding will be added based on this value, so if you don't need the padding, please set axis.y.padding to disable it (e.g. axis.y.padding = 0).
Type:
  • number
Example
axis: {
  y: {
    min: 1000
  }
}

(static) axis․y․padding :object|number

Source:
Default Value:
  • {}

Set padding for y axis.

You can set padding for y axis to create more space on the edge of the axis. This option accepts object and it can include top and bottom. top, bottom will be treated as pixels.

  • NOTE:
    • Given values are translated relative to the y Axis domain value for padding
    • For area and bar type charts, area.zerobased or bar.zerobased options should be set to 'false` to get padded bottom.
Type:
  • object | number
Example
axis: {
  y: {
    padding: {
      top: 0,
      bottom: 0
    },

    // or set both values at once.
    padding: 10
  }
}

(static) axis․y․show :boolean

Source:
Default Value:
  • true

Show or hide y axis.

Type:
  • boolean
Example
axis: {
  y: {
    show: false
  }
}

(static) axis․y․tick․count :number

Source:
Default Value:
  • undefined

Set the number of y axis ticks.

  • NOTE: The position of the ticks will be calculated precisely, so the values on the ticks will not be rounded nicely. In the case, axis.y.tick.format or axis.y.tick.values will be helpful.
Type:
  • number
Example
axis: {
  y: {
    tick: {
      count: 5
    }
  }
}

(static) axis․y․tick․culling :boolean

Source:
Default Value:
  • false

Setting for culling ticks.

  • true: the ticks will be culled, then only limited tick text will be shown.
    This option does not hide the tick lines by default, if want to hide tick lines, set axis.y.tick.culling.lines=false.
  • false: all of ticks will be shown.

    The number of ticks to be shown can be chaned by axis.y.tick.culling.max.
Type:
  • boolean
Example
axis: {
  y: {
    tick: {
      culling: false
    }
  }
}

(static) axis․y․tick․culling․lines :boolean

Source:
Default Value:
  • true

Control visibility of tick lines within culling option, along with tick text.

Type:
  • boolean
Example
axis: {
  y: {
    tick: {
      culling: {
          lines: false,
      }
    }
  }
}

(static) axis․y․tick․culling․max :number

Source:
Default Value:
  • 5

The number of tick texts will be adjusted to less than this value.

Type:
  • number
Example
axis: {
  y: {
    tick: {
      culling: {
          max: 5
      }
    }
  }
}

(static) axis․y․tick․format :function

Source:
Default Value:
  • undefined

Set formatter for y axis tick text.

This option accepts d3.format object as well as a function you define.

Type:
  • function
Example
axis: {
  y: {
    tick: {
      format: function(x) {
          return x.getFullYear();
      }
    }
  }
}

(static) axis․y․tick․outer :boolean

Source:
Default Value:
  • true

Show y axis outer tick.

Type:
  • boolean
Example
axis: {
  y: {
    tick: {
      outer: false
    }
  }
}

(static) axis․y․tick․rotate :number

Source:
Default Value:
  • 0

Rotate y axis tick text.

  • If you set negative value, it will rotate to opposite direction.
  • Applied when axis.rotated option is true.
Type:
  • number
Example
axis: {
  y: {
    tick: {
      rotate: 60
    }
  }
}

(static) axis․y․tick․show :boolean

Source:
Default Value:
  • true
See:

Show or hide y axis tick line.

Type:
  • boolean
Example
axis: {
  y: {
    tick: {
      show: false
    }
  }
}

(static) axis․y․tick․stepSize :number

Source:
See:

Set axis tick step(interval) size.

  • NOTE: Will be ignored if axis.y.tick.count or axis.y.tick.values options are set.
Type:
  • number
Example
axis: {
  y: {
    tick: {
      // tick value will step as indicated interval value.
      // ex) 'stepSize=15' ==> [0, 15, 30, 45, 60]
      stepSize: 15
    }
  }
}

(static) axis․y․tick․text․position :object

Source:
Default Value:
  • {x: 0, y:0}

Set the y Axis tick text's position relatively its original position

Type:
  • object
Example
axis: {
  y: {
    tick: {
      text: {
        position: {
          x: 10,
          y: 10
        }
      }
    }
  }
}

(static) axis․y․tick․text․show :boolean

Source:
Default Value:
  • true
See:

Show or hide y axis tick text.

Type:
  • boolean
Example
axis: {
  y: {
    tick: {
      text: {
          show: false
      }
    }
  }
}

(static) axis․y․tick․values :Array|function

Source:
Default Value:
  • null

Set y axis tick values manually.

Type:
  • Array | function
Example
axis: {
  y: {
    tick: {
      values: [100, 1000, 10000],

      // an Array value should be returned
      values: function() {
      	return [ ... ];
      }
    }
  }
}

(static) axis․y․type :string

Source:
Default Value:
  • "indexed"
See:

Set type of y axis.

Available Values:

  • indexed
  • log
  • timeseries

NOTE:

  • log type:
    • the bound data values must be exclusively-positive.
    • y axis min value should be >= 0.
    • data.groups(stacked data) option aren't supported.
Type:
  • string
Example
axis: {
  y: {
    type: "log"
  }
}

(static) background

Source:
See:
Properties:
Name Type Description
background object

background object

Properties
Name Type Description
class string

Specify the class name for background element.
color string

Specify the fill color for background element.
NOTE: Will be ignored if imgUrl option is set.
imgUrl string

Specify the image url string for background.

Set chart background.

Example
background: {
   class: "myClass",
   color: "red",

   // Set image url for background.
   // If specified, 'color' option will be ignored.
   imgUrl: "https://naver.github.io/billboard.js/img/logo/billboard.js.svg",
}

(static) bar :object

Source:
See:
Properties:
Name Type Description
bar object

Bar object

Properties
Name Type Attributes Default Description
indices.removeNull number <optional>
 false

Remove nullish data on bar indices positions.
label.threshold number <optional>
 0

Set threshold ratio to show/hide labels.
padding number <optional>
 0

The padding pixel value between each bar.
radius number <optional>

Set the radius of bar edge in pixel.

Properties
Name Type Attributes Description
ratio number <optional>

Set the radius ratio of bar edge in relative the bar's width.
sensitivity number <optional>
 2

The senstivity offset value for interaction boundary.
width number <optional>

Change the width of bar chart.

Properties
Name Type Attributes Default Description
ratio number <optional>
 0.6

Change the width of bar chart by ratio.
max number <optional>

The maximum width value for ratio.
dataname number <optional>

Change the width of bar for indicated dataset only.

  • NOTE:
    • Works only for non-stacked bar
    • Bars are centered accoding its total width value
Properties
Name Type Attributes Default Description
ratio number <optional>
 0.6

Change the width of bar chart by ratio.
max number <optional>

The maximum width value for ratio.
zerobased boolean <optional>
 true

Set if min or max value will be 0 on bar chart.

Set bar options

Type:
  • object
Example
bar: {
     // remove nullish data on bar indices postions
     indices: {
         removeNull: true
     },

     padding: 1,

     // bar radius
     radius: 10,
     // or
     radius: {
         ratio: 0.5
     }

     label: {
         // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the y Axis domain range value.
         // if data value is below than 0.1, text label will be hidden.
         threshold: 0.1,
     },

     // will not have offset between each bar elements for interaction
     sensitivity: 0,

     width: 10,

     // or
     width: {
         ratio: 0.2,
         max: 20
     },

     // or specify width per dataset
     width: {
         data1: 20,
         data2: {
             ratio: 0.2,
             max: 20
         }
     },

     zerobased: false
 }

(static) bindto

Source:
Default Value:
  • #chart
Properties:
Name Type Attributes Default Description
bindto string | HTMLElement | d3.selection | object <optional>
 "#chart"

Specify the element where chart will be drawn.

Properties
Name Type Attributes Default Description
element string | HTMLElement | d3.selection "#chart"

Specify the element where chart will be drawn.
classname string <optional>
 bb

Specify the class name of bind element.
NOTE: When class name isn't bb, then you also need to update the default CSS to be rendered correctly.

Specify the CSS selector or the element which the chart will be set to. D3 selection object can be specified also.
If other chart is set already, it will be replaced with the new one (only one chart can be set in one element).

  • NOTE: In case of element doesn't exist or not specified, will add a <div> element to the body.
Example
bindto: "#myContainer"

// or HTMLElement
bindto: document.getElementById("myContainer")

// or D3 selection object
bindto: d3.select("#myContainer")

// or to change default classname
bindto: {
   element: "#chart",
   classname: "bill-board"  // ex) <div id='chart' class='bill-board'>
}

(static) bubble :object

Source:
Properties:
Name Type Description
bubble object

bubble object

Properties
Name Type Attributes Default Description
maxR number | function <optional>
 35

Set the max bubble radius value
zerobased boolean <optional>
 false

Set if min or max value will be 0 on bubble chart.

Set bubble options

Type:
  • object
Example
bubble: {
     // ex) If 100 is the highest value among data bound, the representation bubble of 100 will have radius of 50.
     // And the lesser will have radius relatively from tha max value.
     maxR: 50,

     // or set radius callback
     maxR: function(d) {
         // ex. of d param - {x: Fri Oct 06 2017 00:00:00 GMT+0900, value: 80, id: "data2", index: 5}
         ...
         return Math.sqrt(d.value * 2);
     },
     zerobased: false
 }

(static) candlestick :object

Source:
See:
Properties:
Name Type Description
candlestick object

Candlestick object

Properties
Name Type Attributes Description
width number <optional>

Change the width.

Properties
Name Type Attributes Default Description
ratio number <optional>
 0.6

Change the width by ratio.
max number <optional>

The maximum width value for ratio.
dataname number <optional>

Change the width for indicated dataset only.

Properties
Name Type Attributes Default Description
ratio number <optional>
 0.6

Change the width of bar chart by ratio.
max number <optional>

The maximum width value for ratio.
color object <optional>

Color setting.

Properties
Name Type Attributes Description
down string | object <optional>

Change down(bearish) value color.

Properties
Name Type Attributes Description
dataname string <optional>

Change down value color for indicated dataset only.

Set candlestick options

Type:
  • object
Example
candlestick: {
     width: 10,

     // or
     width: {
        	ratio: 0.2,
        	max: 20
     },

     // or specify width per dataset
     width: {
        	data1: 20,
        	data2: {
        	    ratio: 0.2,
        		max: 20
        	}
     },
     color: {
 	  	// spcify bearish color
 	  	down: "red",

 	  	// or specify color per dataset
 	  	down: {
 	  		data1: "red",
 	  		data2: "blue",
 	  	}
     }
 }

(static) clipPath :boolean

Source:
Default Value:
  • true
See:

Set 'clip-path' attribute for chart element

  • NOTE:

When is false, chart node element is positioned after the axis node in DOM tree hierarchy. Is to make chart element positioned over axis element.

Type:
  • boolean
Example
// don't set 'clip-path' attribute
clipPath: false

(static) color :object

Source:
Properties:
Name Type Description
color object

color object

Properties
Name Type Attributes Default Description
onover string | object | function <optional>

Set the color value for each data point when mouse/touch onover event occurs.
pattern Array | null <optional>
 []

Set custom color pattern. Passing null will not set a color for these elements, which requires the usage of custom CSS-based theming to work.
tiles function <optional>

if defined, allows use svg's patterns to fill data area. It should return an array of SVGPatternElement.

  • NOTE: The pattern element's id will be defined as bb-colorize-pattern-$COLOR-VALUE.
    ex. When color pattern value is ['red', '#fff'] and defined 2 patterns,then ids for pattern elements are:
    • bb-colorize-pattern-red
    • bb-colorize-pattern-fff
threshold object <optional>

color threshold for gauge and tooltip color

Properties
Name Type Attributes Default Description
unit string <optional>

If set to value, the threshold will be based on the data value. Otherwise it'll be based on equation of the threshold.max option value.
values Array <optional>

Threshold values for each steps
max number <optional>
 100

The base value to determine threshold step value condition. When the given value is 15 and max 10, then the value for threshold is 15*100/10.

Set color of the data values

Type:
  • object
Example
color: {
     pattern: ["#1f77b4", "#aec7e8", ...],

     // Set colors' patterns
     // it should return an array of SVGPatternElement
     tiles: function() {
        var pattern = document.createElementNS("http://www.w3.org/2000/svg", "pattern");
        var g = document.createElementNS("http://www.w3.org/2000/svg", "g");
        var circle1 = document.createElementNS("http://www.w3.org/2000/svg", "circle");

        pattern.setAttribute("patternUnits", "userSpaceOnUse");
        pattern.setAttribute("width", "32");
        pattern.setAttribute("height", "32");

        g.style.fill = "#000";
        g.style.opacity = "0.2";

        circle1.setAttribute("cx", "3");
        circle1.setAttribute("cy", "3");
        circle1.setAttribute("r", "3");

        g.appendChild(circle1);
        pattern.appendChild(g);

        return [pattern];
     },

     // for threshold usage, pattern values should be set for each steps
     pattern: ["grey", "green", "yellow", "orange", "red"],
     threshold: {
         unit: "value",

         // when value is 20 => 'green', value is 40 => 'orange' will be set.
         values: [10, 20, 30, 40, 50],

         // the equation for max:
         // - unit == 'value': max => 30
         // - unit != 'value': max => value*100/30
         max: 30
     },

     // set all data to 'red'
     onover: "red",

     // set different color for data
     onover: {
         data1: "red",
         data2: "yellow"
     },

     // will pass data object to the callback
     onover: function(d) {
         return d.id === "data1" ? "red" : "green";
     }
 }

(static) data․axes :object

Source:
Default Value:
  • {}

Set y axis the data related to. y and y2 can be used.

  • 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
Type:
  • object
Example
data: {
  axes: {
    data1: "y",
    data2: "y2"
  }
}

(static) data․classes :object

Source:
Default Value:
  • {}

Set custom data class.

If this option is specified, the element g for the data has an additional class that has the prefix 'bb-target-' (eg. bb-target-additional-data1-class).

Type:
  • object
Example
data: {
  classes: {
    data1: "additional-data1-class",
    data2: "additional-data2-class"
  }
}

(static) data․color :function

Source:
Default Value:
  • undefined
See:

Set color converter function.

This option should a function and the specified function receives color (e.g. '#ff0000') and d that has data parameters like id, value, index, etc. And it must return a string that represents color (e.g. '#00ff00').

Type:
  • function
Example
data: {
  color: function(color, d) { ... }
}

(static) data․colors :object

Source:
Default Value:
  • {}

Set color for each data.

Type:
  • object
Example
data: {
  colors: {
    data1: "#ff0000",
    data2: function(d) {
       return "#000";
    }
    ...
  }
}

(static) data․columns :Array

Source:
Default Value:
  • undefined
See:

Load data from a multidimensional array, with each element containing an array consisting of a datum name and associated data values.

Type:
  • Array
Example
data: {
  columns: [
     ["data1", 30, 20, 50, 40, 60, 50],
     ["data2", 200, 130, 90, 240, 130, 220],
     ["data3", 300, 200, 160, 400, 250, 250]
  ]
}

// for 'bar' type, data can contain:
// - an array of [start, end] data following the order
data: {
  columns: [
    ["data1", -100, 50, [100, 200], [200, 300]],
    ["data2", -200, 300, [-100, 100], [-50, -30]],
  ],
  type: "bar"
}

// for 'range' types('area-line-range' or 'area-spline-range'), data should contain:
// - an array of [high, mid, low] data following the order
// - or an object with 'high', 'mid' and 'low' key value
data: {
  columns: [
     ["data1",
         [150, 140, 110],  // or {high:150, mid: 140, low: 110}
         [150, 140, 110],
         [150, 140, 110]
     ]
  ],
  type: "area-line-range"
}

// for 'bubble' type, data can contain dimension value:
// - an array of [y, z] data following the order
// - or an object with 'y' and 'z' key value
// 'y' is for y axis coordination and 'z' is the bubble radius value
data: {
  columns: [
     ["data1",
         [10, 140],  // or {y:10, z: 140}
         [100, 30],
         [50, 100]
     ]
  ],
  type: "bubble"
}

// for 'canlestick' type, data should contain:
// - an array of [open, high, low, close, volume(optional)] data following the order
// - or an object with 'open', 'high', 'low', 'close' and 'value'(optional) key value
data: {
  columns: [
     ["data1",
         [1000, 1100, 850, 870, 100],  // or {open:1000, high: 1100, low: 870, volume: 100}
         [870, 1250, 830, 1200]  // 'volume' can be omitted
     ]
  ],
  type: "candlestick"
}

(static) data․empty․label․text :string

Source:
Default Value:
  • ""

Set text label to be displayed when there's no data to show.

  • ex. Toggling all visible data to not be shown, unloading all current data, etc.
Type:
  • string
Example
data: {
  empty: {
    label: {
      text: "No Data"
    }
  }
}

(static) data․filter :function

Source:
Default Value:
  • undefined
See:

Filter values to be shown The data value is the same as the returned by .data().

Type:
  • function
Example
data: {
  // filter for id value
  filter: function(v) {
     // v: [{id: "data1", id_org: "data1", values: [
     //      {x: 0, value: 130, id: "data2", index: 0}, ...]
     //    }, ...]
     return v.id !== "data1";
  }

(static) data․groups :Array

Source:
Default Value:
  • []

Set groups for the data for stacking.

Type:
  • Array
Example
data: {
  groups: [
    ["data1", "data2"],
    ["data3"]
  ]
}

(static) data․headers :string

Source:
Default Value:
  • undefined
See:

XHR header value

  • NOTE: Should be used with data.url option
Type:
  • string
Example
data: {
    url: "/data/test.csv",
    headers: {
       "Content-Type": "text/xml",
       ...
    }
}

(static) data․hide :boolean|Array

Source:
Default Value:
  • false

Hide each data when the chart appears.

If true specified, all of data will be hidden. If multiple ids specified as an array, those will be hidden.

Type:
  • boolean | Array
Example
data: {
  // all of data will be hidden
  hide: true

  // specified data will be hidden
  hide: ["data1", ...]
}

(static) data․idConverter :function

Source:
Default Value:
  • function(id) { return id; }

Converts data id value

Type:
  • function
Example
data: {
   idConverter: function(id) {
      // when id is 'data1', converts to be 'data2'
      // 'data2' should be given as the initial data value
      if (id === "data1") {
         return "data2";
      } else {
         return id;
      }
   }
}

(static) data․json :Array

Source:
Default Value:
  • undefined
See:

Parse a JSON object for data. See also data.keys.

Type:
  • Array
Example
data: {
    json: [
      {name: "www.site1.com", upload: 200, download: 200, total: 400},
      {name: "www.site2.com", upload: 100, download: 300, total: 400},
      {name: "www.site3.com", upload: 300, download: 200, total: 500},
      {name: "www.site4.com", upload: 400, download: 100, total: 500}
    ],
    keys: {
      // x: "name", // it's possible to specify 'x' when category axis
      value: ["upload", "download"]
    }
}

(static) data․keys :string

Source:
Default Value:
  • undefined

Choose which JSON object keys correspond to desired data.

  • NOTE: Only for JSON object given as array.
Type:
  • string
Example
data: {
    json: [
      {name: "www.site1.com", upload: 200, download: 200, total: 400},
      {name: "www.site2.com", upload: 100, download: 300, total: 400},
      {name: "www.site3.com", upload: 300, download: 200, total: 500},
      {name: "www.site4.com", upload: 400, download: 100, total: 500}
    ],
    keys: {
      // x: "name", // it's possible to specify 'x' when category axis
      value: ["upload", "download"]
    }
}

(static) data․labels :object

Source:
Default Value:
  • {}
See:
Properties:
Name Type Description
data object

Data object

Properties
Name Type Attributes Default Description
labels boolean <optional>
 false

Show or hide labels on each data points

Properties
Name Type Attributes Default Description
centered boolean <optional>
 false

Centerize labels on bar shape. (NOTE: works only for 'bar' type)
format function <optional>

Set formatter function for data labels.
The formatter function receives 4 arguments such as v, id, i, j and it must return a string(\n character will be used as line break) that will be shown as the label.

The arguments are:

  • v is the value of the data point where the label is shown.
  • id is the id of the data where the label is shown.
  • i is the index of the data series point where the label is shown.
  • texts is the array of whole corresponding data series' text labels.

    Formatter function can be defined for each data by specifying as an object and D3 formatter function can be set (ex. d3.format('$'))
backgroundColors string | object <optional>

Set label text background colors.
colors string | object | function <optional>

Set label text colors.
position object <optional>

Set each dataset position, relative the original.

Properties
Name Type Attributes Default Description
x number <optional>
 0

x coordinate position, relative the original.
y number <optional>
 0

y coordinate position, relative the original.

Set labels options

Type:
  • object
Example
data: {
  labels: true,

  // or set specific options
  labels: {
    format: function(v, id, i, j) {
        ...
        // to multiline, return with '\n' character
        return "Line1\nLine2";
    },

    // it's possible to set for each data
    format: {
        data1: function(v, id, i, texts) { ... },
        ...
    },

    // align text to center of the 'bar' shape (works only for 'bar' type)
    centered: true,

    // apply backgound color for label texts
    backgroundColors: "red",

    // set differenct backround colors per dataset
    backgroundColors: {
         data1: "green",
         data2: "yellow"
    }

    // apply for all label texts
    colors: "red",

    // set different colors per dataset
    // for not specified dataset, will have the default color value
    colors: {
       data1: "yellow",
       data3: "green"
    },

    // call back for label text color
    colors: function(color, d) {
        // color: the default data label color string
        // data: ex) {x: 0, value: 200, id: "data3", index: 0}
        ....
        return d.value > 200 ? "cyan" : color;
    },

    // set x, y coordinate position
    position: {
       x: -10,
       y: 10
    },

    // or set x, y coordinate position by each dataset
    position: {
       data1: {x: 5, y: 5},
       data2: {x: 10, y: -20}
    }
  }
}

(static) data․mimeType :string

Source:
Default Value:
  • csv

Used if loading JSON via data.url.

  • Available Values:
    • json
    • csv
    • tsv
Type:
  • string
Example
data: {
    mimeType: "json"
}

(static) data․names :object

Source:
Default Value:
  • {}
See:

Set custom data name.

Type:
  • object
Example
data: {
  names: {
    data1: "Data Name 1",
    data2: "Data Name 2"
  }
}

(static) data․onclick :function

Source:
Default Value:
  • function() {}

Set a callback for click event on each data point.

This callback will be called when each data point clicked and will receive d and element as the arguments.

  • d is the data clicked and element is the element clicked.
  • element is the current interacting svg element.
  • In this callback, this will be the Chart object.
Type:
  • function
Example
data: {
    onclick: function(d, element) {
       // d - ex) {x: 4, value: 150, id: "data1", index: 4, name: "data1"}
       // element - <circle>
       ...
    }
}

(static) data․onhidden :function

Source:
Default Value:
  • undefined

Set a callback for when data is hidden.
The callback will receive hidden data ids in array.

Type:
  • function
Example
data: {
   onhidden: function(ids) {
     // ids - ["data1", "data2", ...]
     ...
   }
 }

(static) data․onmax :function

Source:
Default Value:
  • undefined
See:

Set a callback for maximum data

  • NOTE: For 'area-line-range' and 'area-spline-range', mid data will be taken for the comparison
Type:
  • function
Example
onmax: function(data) {
   // data - ex) [{x: 3, value: 400, id: "data1", index: 3}, ... ]
   ...
 }

(static) data․onmin :function

Source:
Default Value:
  • undefined
See:

Set a callback for minimum data

  • NOTE: For 'area-line-range' and 'area-spline-range', mid data will be taken for the comparison
Type:
  • function
Example
onmin: function(data) {
   // data - ex) [{x: 3, value: 400, id: "data1", index: 3}, ... ]
   ...
 }

(static) data․onout :function

Source:
Default Value:
  • function() {}

Set a callback for mouse/touch out event on each data point.

This callback will be called when mouse cursor or via touch moves out each data point and will receive d as the argument.

  • d is the data where mouse cursor moves out.
  • element is the current interacting svg element.
  • In this callback, this will be the Chart object.
Type:
  • function
Example
data: {
    onout: function(d, element) {
       // d - ex) {x: 4, value: 150, id: "data1", index: 4}
       // element - <circle>
       ...
    }
}

(static) data․onover :function

Source:
Default Value:
  • function() {}

Set a callback for mouse/touch over event on each data point.

This callback will be called when mouse cursor or via touch moves onto each data point and will receive d and element as the argument.

  • d is the data where mouse cursor moves onto.
  • element is the current interacting svg element.
  • In this callback, this will be the Chart object.
Type:
  • function
Example
data: {
    onover: function(d, element) {
       // d - ex) {x: 4, value: 150, id: "data1", index: 4}
       // element - <circle>
       ...
    }
}

(static) data․onselected :function

Source:
Default Value:
  • function() {}

Set a callback for on data selection.

Type:
  • function
Example
data: {
    onselected: function(d, element) {
       // d - ex) {x: 4, value: 150, id: "data1", index: 4, name: "data1"}
       // element - <circle>
       ...
   }
}

(static) data․onshown :function

Source:
Default Value:
  • undefined

Set a callback for when data is shown.
The callback will receive shown data ids in array.

Type:
  • function
Example
data: {
   onshown: function(ids) {
     // ids - ["data1", "data2", ...]
     ...
   }
 }

(static) data․onunselected :function

Source:
Default Value:
  • function() {}

Set a callback for on data un-selection.

Type:
  • function
Example
data: {
    onunselected: function(d, element) {
       // d - ex) {x: 4, value: 150, id: "data1", index: 4, name: "data1"}
       // element - <circle>
       ...
   }
}

(static) data․order :string|function|null

Source:
Default Value:
  • desc
See:

This option changes the order of stacking data and pieces of pie/donut.

Available Values:

  • desc: In descending order
  • asc: In ascending order
  • null: It keeps the data load order
  • function(data1, data2) { ... }: Array.sort compareFunction

NOTE: order function, only works for Axis based types & Arc types, except Radar type.

Type:
  • string | function | null
Example
data: {
  // in descending order (default)
  order: "desc"

  // in ascending order
  order: "asc"

  // keeps data input order
  order: null

  // specifying sort function
  order: function(a, b) {
      // param data passed format
      // {
      //   id: "data1", id_org: "data1", values: [
      //      {x: 5, value: 250, id: "data1", index: 5, name: "data1"},
      //       ...
      //   ]
      // }

      const reducer = (p, c) => p + Math.abs(c.value);
      const aSum = a.values.reduce(reducer, 0);
      const bSum = b.values.reduce(reducer, 0);

      // ascending order
      return aSum - bSum;

      // descending order
      // return bSum - aSum;
  }
}

(static) data․regions :object

Source:
Default Value:
  • {}

Define regions for each data.
The values must be an array for each data and it should include an object that has start, end and style.

  • The object type should be as:
    • start {number}: Start data point number. If not set, the start will be the first data point.
    • [end] {number}: End data point number. If not set, the end will be the last data point.
    • [style.dasharray="2 2"] {object}: The first number specifies a distance for the filled area, and the second a distance for the unfilled area.
  • NOTE: Currently this option supports only line chart and dashed style. If this option specified, the line will be dashed only in the regions.
Type:
  • object
Example
data: {
  regions: {
    data1: [{
        start: 1,
        end: 2,
        style: {
            dasharray: "5 2"
        }
    }, {
        start: 3
    }],
    ...
  }
}

(static) data․rows :Array

Source:
Default Value:
  • undefined
See:

Load data from a multidimensional array, with the first element containing the data names, the following containing related data in that order.

Type:
  • Array
Example
data: {
  rows: [
    ["A", "B", "C"],
    [90, 120, 300],
    [40, 160, 240],
    [50, 200, 290],
    [120, 160, 230],
    [80, 130, 300],
    [90, 220, 320]
  ]
}

// for 'bar' type, data can contain:
// - an array of [start, end] data following the order
data: {
  rows: [
     ["data1", "data2"],
     [[100, 150], 120],
     [[200, 300], 55],
     [[-400, 500], 60]
  ],
  type: "bar"
}

// for 'range' types('area-line-range' or 'area-spline-range'), data should contain:
// - an array of [high, mid, low] data following the order
// - or an object with 'high', 'mid' and 'low' key value
data: {
  rows: [
     ["data1", "data2"],
     [
       // or {high:150, mid: 140, low: 110}, 120
       [150, 140, 110], 120
     ],
     [[155, 130, 115], 55],
     [[160, 135, 120], 60]
  ],
  types: {
      data1: "area-line-range",
      data2: "line"
  }
}

// for 'bubble' type, data can contain dimension value:
// - an array of [y, z] data following the order
// - or an object with 'y' and 'z' key value
// 'y' is for y axis coordination and 'z' is the bubble radius value
data: {
  rows: [
     ["data1", "data2"],
     [
       // or {y:10, z: 140}, 120
       [10, 140], 120
     ],
     [[100, 30], 55],
     [[50, 100], 60]
  ],
  types: {
      data1: "bubble",
      data2: "line"
  }
}

// for 'canlestick' type, data should contain:
// - an array of [open, high, low, close, volume(optional)] data following the order
// - or an object with 'open', 'high', 'low', 'close' and 'value'(optional) key value
data: {
  rows: [
     ["data1", "data2"],
		[
			// open, high, low, close, volume (optional)
			{open: 1300, high: 1369, low: 1200, close: 1339, volume: 100},
			[1000, 1100, 850, 870]
		],
		[
			{open: 1348, high: 1371, low: 1271, close: 1320},
			[870, 1250, 830, 1200, 50]
		]
  ],
  type: "candlestick"
}

(static) data․selection․draggable :boolean

Source:
Default Value:
  • false

Enable to select data points by dragging. If this option set true, data points can be selected by dragging.

  • NOTE: If this option set true, scrolling on the chart will be disabled because dragging event will handle the event.
Type:
  • boolean
Example
data: {
   selection: {
      draggable: true
  }
}

(static) data․selection․enabled :boolean

Source:
Default Value:
  • false
See:

Set data selection enabled

If this option is set true, we can select the data points and get/set its state of selection by API (e.g. select, unselect, selected).

  • NOTE: for ESM imports, needs to import 'selection' exports and instantiate it by calling selection().
    • enabled: selection()
Type:
  • boolean
Examples
data: {
   selection: {
      enabled: true
   }
}
// importing ESM
import bb, {selection} from "billboard.js";

data: {
   selection: {
      enabled: selection(),
      ...
   }
}

(static) data․selection․grouped :boolean

Source:
Default Value:
  • false

Set grouped selection enabled.

If this option set true, multiple data points that have same x value will be selected by one selection.

Type:
  • boolean
Example
data: {
   selection: {
      grouped: true
   }
}

(static) data․selection․isselectable :function

Source:
Default Value:
  • function() { return true; }

Set a callback for each data point to determine if it's selectable or not.

The callback will receive d as an argument and it has some parameters like id, value, index. This callback should return boolean.

Type:
  • function
Example
data: {
   selection: {
      isselectable: function(d) { ... }
   }
}

(static) data․selection․multiple :boolean

Source:
Default Value:
  • true

Set multiple data points selection enabled.

If this option set true, multile data points can have the selected state at the same time. If false set, only one data point can have the selected state and the others will be unselected when the new data point is selected.

Type:
  • boolean
Example
data: {
   selection: {
      multiple: false
   }
}

(static) data․stack․normalize :boolean

Source:
Default Value:
  • false
See:

Set the stacking to be normalized

  • NOTE:
    • For stacking, 'data.groups' option should be set
    • y Axis will be set in percentage value (0 ~ 100%)
    • Must have postive values
Type:
  • boolean
Example
data: {
  stack: {
     normalize: true
  }
}

(static) data․type :string

Source:
Default Value:
  • "line"
    NOTE: When importing shapes by ESM, `line()` should be specified for type.

Set chart type at once.

If this option is specified, the type will be applied to every data. This setting can be overwritten by data.types.

Available Values:

  • area
  • area-line-range
  • area-spline
  • area-spline-range
  • area-step
  • bar
  • bubble
  • candlestick
  • donut
  • gauge
  • line
  • pie
  • radar
  • scatter
  • spline
  • step
Type:
  • string
Examples
data: {
   type: "bar"
}
// Generate chart by importing ESM
// Import types to be used only, where this will make smaller bundle size.
import bb, {
  area,
  areaLineRange,
  areaSpline,
  areaSplineRange,
  areaStep,
  bar,
  bubble,
  candlestick,
  donut,
  gauge,
  line,
  pie,
  radar,
  scatter,
  spline,
  step
}

bb.generate({
  ...,
  data: {
    type: bar()
  }
});

(static) data․types :object

Source:
Default Value:
  • {}

Set chart type for each data.
This setting overwrites data.type setting.

  • NOTE: radar type can't be combined with other types.
Type:
  • object
Examples
data: {
  types: {
    data1: "bar",
    data2: "spline"
  }
}
// Generate chart by importing ESM
// Import types to be used only, where this will make smaller bundle size.
import bb, {
  area,
  areaLineRange,
  areaSpline,
  areaSplineRange,
  areaStep,
  bar,
  bubble,
  candlestick,
  donut,
  gauge,
  line,
  pie,
  radar,
  scatter,
  spline,
  step
}

bb.generate({
  ...,
  data: {
    types: {
      data1: bar(),
      data1: spline()
    }
  }
});

(static) data․url :string

Source:
Default Value:
  • undefined
See:

Load a CSV or JSON file from a URL. NOTE that this will not work if loading via the "file://" protocol as the most browsers will block XMLHTTPRequests.

Type:
  • string
Example
data: {
    url: "/data/test.csv"
}

(static) data․x :string

Source:
Default Value:
  • undefined

Specify the key of x values in the data.

We can show the data with non-index x values by this option. This option is required when the type of x axis is timeseries. If this option is set on category axis, the values of the data on the key will be used for category names.

Type:
  • string
Example
data: {
  x: "date"
}

(static) data․xFormat :string

Source:
Default Value:
  • %Y-%m-%d
See:

Set a format specifier to parse string specifed as x.

Type:
  • string
Example
data: {
   x: "x",
   columns: [
       ["x", "01012019", "02012019", "03012019"],
       ["data1", 30, 200, 100]
   ],
   // Format specifier to parse as datetime for given 'x' string value
   xFormat: "%m%d%Y"
},
axis: {
   x: {
       type: "timeseries"
   }
}

(static) data․xLocaltime :boolean

Source:
Default Value:
  • true

Set localtime format to parse x axis.

Type:
  • boolean
Example
data: {
  xLocaltime: false
}

(static) data․xs :object

Source:
Default Value:
  • {}

Specify the keys of the x values for each data.

This option can be used if we want to show the data that has different x values.

Type:
  • object
Example
data: {
  xs: {
     data1: "x1",
     data2: "x2"
  }
}

(static) data․xSort :boolean

Source:
Default Value:
  • true

Sort on x axis.

Type:
  • boolean
Example
data: {
  xSort: false
}

(static) donut :object

Source:
Properties:
Name Type Description
donut object

Donut object

Properties
Name Type Attributes Default Description
label.show boolean <optional>
 true

Show or hide label on each donut piece.
label.format function <optional>

Set formatter for the label on each donut piece.
label.threshold number <optional>
 0.05

Set threshold ratio to show/hide labels.
label.ratio number | function <optional>

Set ratio of labels position.
expand boolean <optional>
 true

Enable or disable expanding donut pieces.

Properties
Name Type Attributes Default Description
rate number <optional>
 0.98

Set expand rate.
duration number <optional>
 50

Set expand transition time in ms.
width number <optional>

Set width of donut chart.
title string <optional>
 ""

Set title of donut chart. Use \n character for line break.
padAngle number <optional>
 0

Set padding between data.
startingAngle number <optional>
 0

Set starting angle where data draws.

Set donut options

Type:
  • object
Example
donut: {
     label: {
         show: false,
         format: function(value, ratio, id) {
             return d3.format("$")(value);

             // to multiline, return with '\n' character
             // return value +"%\nLine1\n2Line2";
         },

         // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the total value.
         // if data value is below than 0.1, text label will be hidden.
         threshold: 0.1,

         // set ratio callback. Should return ratio value
         ratio: function(d, radius, h) {
         	...
         	return ratio;
         },
         // or set ratio number
         ratio: 0.5
     },

     // disable expand transition for interaction
     expand: false,

     expand: {
     	// set duration of expand transition to 500ms.
         duration: 500,

     	// set expand area rate
         rate: 1
     },

     width: 10,
     padAngle: 0.2,
     startingAngle: 1,
     title: "Donut Title"

     // title with line break
     title: "Title1\nTitle2"
 }

(static) gauge :object

Source:
See:
Properties:
Name Type Description
gauge object

Gauge object

Properties
Name Type Attributes Default Description
background boolean <optional>
 ""

Set background color. (The .bb-chart-arcs-background element)
fullCircle boolean <optional>
 false

Show full circle as donut. When set to 'true', the max label will not be showed due to start and end points are same location.
label.show boolean <optional>
 true

Show or hide label on gauge.
label.format function <optional>

Set formatter for the label on gauge. Label text can be multilined with \n character.
Will pass following arguments to the given function:

  • value {number}: absolute value
  • ratio {number}: value's ratio
  • id {string}: data's id value
label.extents function <optional>

Set customized min/max label text.
label.threshold number <optional>
 0

Set threshold ratio to show/hide labels.
expand boolean <optional>
 true

Enable or disable expanding gauge.

Properties
Name Type Attributes Default Description
rate number <optional>
 0.98

Set expand rate.
duration number <optional>
 50

Set the expand transition time in milliseconds.
min number <optional>
 0

Set min value of the gauge.
max number <optional>
 100

Set max value of the gauge.
startingAngle number <optional>
 -1 * Math.PI / 2

Set starting angle where data draws.

Limitations:

  • when gauge.fullCircle=false:
    • -1 * Math.PI / 2 <= startingAngle <= Math.PI / 2
    • startingAngle <= -1 * Math.PI / 2 defaults to -1 * Math.PI / 2
    • startingAngle >= Math.PI / 2 defaults to Math.PI / 2
  • when gauge.fullCircle=true:
    • -1 * Math.PI < startingAngle < Math.PI
    • startingAngle < -1 * Math.PI defaults to Math.PI
    • startingAngle > Math.PI defaults to Math.PI
arcLength number <optional>
 100

Set the length of the arc to be drawn in percent from -100 to 100.
Negative value will draw the arc counterclockwise.

Limitations:

  • -100 <= arcLength (in percent) <= 100
  • 'arcLength < -100' defaults to -100
  • 'arcLength > 100' defaults to 100
title string <optional>
 ""

Set title of gauge chart. Use \n character for line break.
units string <optional>

Set units of the gauge.
width number <optional>

Set width of gauge chart.
type string <optional>
 "single"

Set type of gauge to be displayed.

Available Values:

  • single
  • multi
arcs.minWidth string <optional>
 5

Set minimal width of gauge arcs until the innerRadius disappears.

Set gauge options

Type:
  • object
Example
gauge: {
     background: "#eee", // will set 'fill' css prop for '.bb-chart-arcs-background' classed element.
     fullCircle: false,
     label: {
         show: false,
         format: function(value, ratio, id) {
             return value;

             // to multiline, return with '\n' character
             // return value +"%\nLine1\n2Line2";
         },

          extents: function(value, isMax) {
             return (isMax ? "Max:" : "Min:") + value;
         },

         // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the total value.
         // if data value is below than 0.1, text label will be hidden.
         threshold: 0.1,
     },

     // disable expand transition for interaction
     expand: false,

     expand: {
     	// set duration of expand transition to 500ms.
         duration: 500,

     	// set expand area rate
         rate: 1
     },

     min: -100,
     max: 200,
     type: "single"  // or 'multi'
     title: "Title Text",
     units: "%",
     width: 10,
     startingAngle: -1 * Math.PI / 2,
     arcLength: 100,
     arcs: {
         minWidth: 5
     }
 }

(static) grid :object

Source:
Default Value:
  • undefined
See:
Properties:
Name Type Attributes Default Description
front boolean <optional>
 false

Set 'grid & focus lines' to be positioned over grid lines and chart elements.
x object

Grid x object

Properties
Name Type Attributes Default Description
show boolean <optional>
 false

Show grids along x axis.
lines Array <optional>
 []

Show additional grid lines along x axis.
This option accepts array including object that has value, text, position and class. text, position and class are optional. For position, start, middle and end (default) are available. If x axis is category axis, value can be category name. If x axis is timeseries axis, value can be date string, Date object and unixtime integer.
y object

Grid y object

Properties
Name Type Attributes Default Description
show boolean <optional>
 false

Show grids along x axis.
lines Array <optional>
 []

Show additional grid lines along y axis.
This option accepts array including object that has value, text, position and class.
ticks number <optional>
 10

Number of y grids to be shown.
focus object

Grid focus object

Properties
Name Type Attributes Default Description
edge boolean <optional>
 false

Show edged focus grid line.
NOTE: Available when tooltip.grouped=false option is set.
show boolean <optional>
 true

Show grid line when focus.
y boolean <optional>
 false

Show y coordinate focus grid line.
NOTE: Available when tooltip.grouped=false option is set.
lines object

Grid lines object

Properties
Name Type Attributes Default Description
front boolean <optional>
 true

Set grid lines to be positioned over chart elements.

Set related options

Type:
  • object
Example
grid: {
  x: {
    show: true,
    lines: [
      {value: 2, text: "Label on 2"},
      {value: 5, text: "Label on 5", class: "label-5"},
      {value: 6, text: "Label on 6", position: "start"}
    ]
  },
  y: {
    show: true,
    lines: [
      {value: 100, text: "Label on 100"},
      {value: 200, text: "Label on 200", class: "label-200"},
      {value: 300, text: "Label on 300", position: 'middle'}
    ],
    ticks: 5
  },
  front: true,
  focus: {
     show: false,

     // Below options are available when 'tooltip.grouped=false' option is set
     edge: true,
     y: true
  },
  lines: {
     front: false
  }
}

(static) interaction :object

Source:
See:
Properties:
Name Type Description
interaction object

Intersection object

Properties
Name Type Attributes Default Description
enabled boolean <optional>
 true

Indicate if the chart should have interactions.
If false is set, all of interactions (showing/hiding tooltip, selection, mouse events, etc) will be disabled.
brighten boolean <optional>
 true

Make brighter for the selected area (ex. 'pie' type data selected area)
inputType.mouse boolean <optional>
 true

enable or disable mouse interaction
inputType.touch boolean <optional>
 true

enable or disable touch interaction

Properties
Name Type Attributes Default Description
preventDefault boolean | number <optional>
 false

enable or disable to call event.preventDefault on touchstart & touchmove event. It's usually used to prevent document scrolling.

Interaction options

Type:
  • object
Example
interaction: {
   enabled: false,
   brighten: false,
   inputType: {
       mouse: true,
       touch: false

       // or declare preventDefault explicitly.
       // In this case touch inputType is enabled by default
       touch: {
           preventDefault: true

           // or threshold pixel value (pixel moved from touchstart to touchmove)
           preventDefault: 5
       }
   }
}

(static) legend :object

Source:
See:
Properties:
Name Type Description
legend object

Legend object

Properties
Name Type Attributes Default Description
show boolean <optional>
 true

Show or hide legend.
hide boolean <optional>
 false

Hide legend If true given, all legend will be hidden. If string or array given, only the legend that has the id will be hidden.
contents.bindto string | HTMLElement <optional>

Set CSS selector or element reference to bind legend items.
contents.template string | function <optional>

Set item's template.

  • If set string value, within template the 'color' and 'title' can be replaced using template-like syntax string:
    • {=COLOR}: data color value
    • {=TITLE}: data title value
  • If set function value, will pass following arguments to the given function:
  • title {string}: data's id value
  • color {string}: color string
  • data {Array}: data array
position string <optional>
 bottom

Change the position of legend.
Available values are: bottom, right and inset are supported.
inset object <optional>
 {anchor: 'top-left',x: 10,y: 0,step: undefined}

Change inset legend attributes.
This option accepts object that has the keys anchor, x, y and step.

  • anchor decides the position of the legend:
  • top-left
  • top-right
  • bottom-left
  • bottom-right
  • x and y:
  • set the position of the legend based on the anchor.
  • step:
  • defines the max step the legend has (e.g. If 2 set and legend has 3 legend item, the legend 2 columns).
equally boolean <optional>
 false

Set to all items have same width size.
padding boolean <optional>
 0

Set padding value
item.onclick function <optional>

Set click event handler to the legend item.
item.onover function <optional>

Set mouse/touch over event handler to the legend item.
item.onout function <optional>

Set mouse/touch out event handler to the legend item.
item.tile.width number <optional>
 10

Set width of item tile element
item.tile.height number <optional>
 10

Set height of item tile element
usePoint boolean <optional>
 false

Whether to use custom points in legend.

Legend options

Type:
  • object
Example
legend: {
     show: true,
     hide: true,
     //or hide: "data1"
     //or hide: ["data1", "data2"]
     contents: {
         bindto: "#legend",   // <ul id='legend'></ul>

         // will be as: <li style='background-color:#1f77b4'>data1</li>
         template: "<li style='background-color:{=COLOR}'>{=TITLE}</li>"

         // or using function
         template: function(id, color, data) {
              // if you want omit some legend, return falsy value
              if (id !== "data1") {
                   return "<li style='background-color:"+ color +">"+ id +"</li>";
              }
         }
     },
     position: "bottom",  // bottom, right, inset
     inset: {
         anchor: "top-right"  // top-left, top-right, bottom-left, bottom-right
         x: 20,
         y: 10,
         step: 2
     },
     equally: false,
     padding: 10,
     item: {
         onclick: function(id) { ... },
         onover: function(id) { ... },
         onout: function(id) { ... },

         // set tile's size
         tile: {
             width: 20,
             height: 15
         }
     },
     usePoint: true
 }

(static) line :object

Source:
Properties:
Name Type Description
line object

Line object

Properties
Name Type Attributes Default Description
connectNull boolean <optional>
 false

Set if null data point will be connected or not.
If true set, the region of null data will be connected without any data point. If false set, the region of null data will not be connected and get empty.
classes Array <optional>

If set, used to set a css class on each line.
step.type boolean <optional>
 step

Change step type for step chart.
Available values:

  • step
  • step-before
  • step-after
step.tooltipMatch boolean <optional>
 false

Set to true for step-before and step-after types to have cursor/tooltip match to hovered step's point instead of nearest point.
point boolean | Array <optional>
 true

Set to false to not draw points on linecharts. Or pass an array of line ids to draw points for.
zerobased boolean <optional>
 false

Set if min or max value will be 0 on line chart.

Set line options

Type:
  • object
Example
line: {
     connectNull: true,
     classes: [
         "line-class1",
         "line-class2"
     ],
     step: {
         type: "step-after",

         // to have cursor/tooltip match to hovered step's point instead of nearest point.
         tooltipMatch: true
     },

     // hide all data points ('point.show=false' also has similar effect)
     point: false,

     // show data points for only indicated datas
     point: [
         "data1", "data3"
     ],

     zerobased: false
 }

(static) onafterinit :function

Source:
Default Value:
  • undefined

Set a callback to execute after the chart is initialized

Type:
  • function
Example
onafterinit: function() {
  this; // chart instance itself
  ...
}

(static) onbeforeinit :function

Source:
Default Value:
  • undefined

Set a callback to execute before the chart is initialized

Type:
  • function
Example
onbeforeinit: function() {
  this; // chart instance itself
  ...
}

(static) oninit :function

Source:
Default Value:
  • undefined

Set a callback to execute when the chart is initialized.

Type:
  • function
Example
oninit: function() {
  this; // chart instance itself
  ...
}

(static) onout :function

Source:
Default Value:
  • undefined

Set a callback to execute when mouse/touch leaves the chart.

Type:
  • function
Example
onout: function() {
  this; // chart instance itself
  ...
}

(static) onover :function

Source:
Default Value:
  • undefined

Set a callback to execute when mouse/touch enters the chart.

Type:
  • function
Example
onover: function() {
  this; // chart instance itself
  ...
}

(static) onrendered :function

Source:
Default Value:
  • undefined

Set a callback which is executed when the chart is rendered. Basically, this callback will be called in each time when the chart is redrawed.

Type:
  • function
Example
onrendered: function() {
  this; // chart instance itself
  ...
}

(static) onresize :function

Source:
Default Value:
  • undefined

Set a callback to execute when user resizes the screen.

Type:
  • function
Example
onresize: function() {
  this; // chart instance itself
  ...
}

(static) onresized :function

Source:
Default Value:
  • undefined

Set a callback to execute when screen resize finished.

Type:
  • function
Example
onresized: function() {
  this; // chart instance itself
  ...
}

(static) padding :object

Source:
See:
Properties:
Name Type Attributes Default Description
padding object | boolean <optional>
 true

Set padding of chart, and accepts object or boolean type.

  • Object: Specify each side's padding.
  • false: Remove padding completely and make shape to fully occupy the container element.
    • In this case, axes and subchart will be hidden.
    • To adjust some padding from this state, use axis.[x|y].padding option.
Properties
Name Type Attributes Description
top number <optional>

padding on the top of chart
right number <optional>

padding on the right of chart
bottom number <optional>

padding on the bottom of chart
left number <optional>

padding on the left of chart

The padding of the chart element.

Type:
  • object
Example
// remove padding completely.
padding: false,

// or specify padding value for each side
padding: {
  top: 20,
  right: 20,
  bottom: 20,
  left: 20
}

(static) pie :object

Source:
See:
Properties:
Name Type Description
pie object

Pie object

Properties
Name Type Attributes Default Description
label.show boolean <optional>
 true

Show or hide label on each pie piece.
label.format function <optional>

Set formatter for the label on each pie piece.
label.threshold number <optional>
 0.05

Set threshold ratio to show/hide labels.
label.ratio number | function <optional>

Set ratio of labels position.
expand boolean | object <optional>
 true

Enable or disable expanding pie pieces.

Properties
Name Type Attributes Default Description
rate number <optional>
 0.98

Set expand rate.
duration number <optional>
 50

Set expand transition time in ms.
innerRadius number | object <optional>
 0

Sets the inner radius of pie arc.
outerRadius number | object | undefined <optional>

Sets the outer radius of pie arc.
padAngle number <optional>
 0

Set padding between data.
padding number <optional>
 0

Sets the gap between pie arcs.
startingAngle number <optional>
 0

Set starting angle where data draws.

Set pie options

Type:
  • object
Example
pie: {
     label: {
         show: false,
         format: function(value, ratio, id) {
             return d3.format("$")(value);

             // to multiline, return with '\n' character
             // return value +"%\nLine1\n2Line2";
         },

         // 0.1(10%) ratio value means, the minimum ratio to show text label relative to the total value.
         // if data value is below than 0.1, text label will be hidden.
         threshold: 0.1,

         // set ratio callback. Should return ratio value
         ratio: function(d, radius, h) {
             ...
             return ratio;
         },
         // or set ratio number
         ratio: 0.5
     },

     // disable expand transition for interaction
     expand: false,

     expand: {
     	// set duration of expand transition to 500ms.
         duration: 500,

     	// set expand area rate
         rate: 1
     },

     innerRadius: 0,

     // set different innerRadius for each data
     innerRadius: {
     	data1: 10,
     	data2: 0
     },

     outerRadius: 100,

     // set different outerRadius for each data
     outerRadius: {
     	data1: 50,
     	data2: 100
     }

     padAngle: 0.1,
     padding: 0,
     startingAngle: 1
 }

(static) plugins :Array

Source:

Set plugins

Type:
  • Array
Example
plugins: [
   new bb.plugin.stanford({ ... }),
   new PluginA(),
   ...
]

(static) point :object

Source:
See:
Properties:
Name Type Description
point object

Point object

Properties
Name Type Attributes Default Description
show boolean <optional>
 true

Whether to show each point in line.
r number | function <optional>
 2.5

The radius size of each point.

  • NOTE: Disabled for 'bubble' type
focus.expand.enabled boolean <optional>
 true

Whether to expand each point on focus.
focus.expand.r number <optional>
 point.r*1.75

The radius size of each point on focus.

  • NOTE: For 'bubble' type, the default is bubbleSize*1.15
focus.only boolean <optional>
 false

Show point only when is focused.
opacity number | null <optional>

Set point opacity value.

  • NOTE:
    • null will make to not set inline 'opacity' css prop.
    • when no value(or undefined) is set, it defaults to set opacity value according its chart types.
sensitivity number <optional>
 10

The senstivity value for interaction boundary.
select.r number <optional>
 point.r*4

The radius size of each point on selected.
type string <optional>
 "circle"

The type of point to be drawn

  • NOTE:
    • If chart has 'bubble' type, only circle can be used.
    • For IE, non circle point expansions are not supported due to lack of transform support.
  • Available Values:
    • circle
    • rectangle
pattern Array <optional>
 []

The type of point or svg shape as string, to be drawn for each line

  • NOTE:
    • This is an experimental feature and can have some unexpected behaviors.
    • If chart has 'bubble' type, only circle can be used.
    • For IE, non circle point expansions are not supported due to lack of transform support.
  • Available Values:
    • circle
    • rectangle
    • svg shape tag interpreted as string
      (ex. <polygon points='2.5 0 0 5 5 5'></polygon>)

Set point options

Type:
  • object
Example
point: {
     show: false,
     r: 5,

     // or customize the radius
     r: function(d) {
         ...
         return r;
     },

     focus: {
         expand: {
             enabled: true,
             r: 1
         },
         only: true
     },

     // do not set inline 'opacity' css prop setting
     opacity: null,

     // set every data point's opacity value
     opacity: 0.7,

     select: {
         r: 3
     },

     // having lower value, means how closer to be for interaction
     sensitivity: 3,

     // valid values are "circle" or "rectangle"
     type: "rectangle",

     // or indicate as pattern
     pattern: [
       "circle",
       "rectangle",
       "<polygon points='0 6 4 0 -4 0'></polygon>"
    ],
 }

(static) radar :object

Source:
See:
Properties:
Name Type Description
radar object

Radar object

Properties
Name Type Attributes Default Description
axis.max number <optional>

The max value of axis. If not given, it'll take the max value from the given data.
axis.line.show boolean <optional>
 true

Show or hide axis line.
axis.text.position.x number <optional>
 0

x coordinate position, relative the original.
axis.text.position.y number <optional>
 0

y coordinate position, relative the original.
axis.text.show boolean <optional>
 true

Show or hide axis text.
direction.clockwise boolean <optional>
 false

Set the direction to be drawn.
level.depth number <optional>
 3

Set the level depth.
level.show boolean <optional>
 true

Show or hide level.
level.text.format function <optional>

Set format function for the level value.
- Default value: (x) => x % 1 === 0 ? x : x.toFixed(2)
level.text.show boolean <optional>
 true

Show or hide level text.
size.ratio number <optional>
 0.87

Set size ratio.

Set radar options

  • NOTE:

When x tick text contains \n, it's used as line break.

Type:
  • object
Example
radar: {
     axis: {
         max: 50,
         line: {
             show: false
         },
         text: {
             position: {
             	x: 0,
             	y: 0
             },
             show: false
         }
     },
     direction: {
         clockwise: true
     },
     level: {
         show: false,
         text: {
             format: function(x) {
                 return x + "%";
             },
             show: true
         }
     },
     size: {
         ratio: 0.7
     }
 }

(static) regions :Array

Source:
Default Value:
  • []

Show rectangles inside the chart.

This option accepts array including object that has axis, start, end and class. The keys start, end and class are optional. axis must be x, y or y2. start and end should be the value where regions start and end. If not specified, the edge values will be used. If timeseries x axis, date string, Date object and unixtime integer can be used. If class is set, the region element will have it as class.

Type:
  • Array
Example
regions: [
   {
     axis: "x",
     start: 1,
     end: 4,
     class: "region-1-4"
   }
 ]

(static) render :object

Source:
See:
Properties:
Name Type Attributes Description
render object <optional>

render object

Properties
Name Type Attributes Default Description
lazy boolean <optional>
 true

Make to not render at initialization (enabled by default when bind element's visibility is hidden).
observe boolean <optional>
 true

Observe bind element's visibility(display or visiblity inline css property or class value) & render when is visible automatically (for IEs, only works IE11+). When set to false, call .flush() to render.

Control the render timing

Type:
  • object
Examples
render: {
   lazy: true,
   observe: true
}
// <!-- render.lazy will detect visibility defined -->
 // (a) <div id='chart' class='hide'></div>
 // (b) <div id='chart' style='display:none'></div>

 // render.lazy enabled by default when element is hidden
 var chart = bb.generate({ ... });

 // chart will be rendered automatically when element's visibility changes
 // Note: works only for inlined css property or class attribute changes
 document.getElementById('chart').classList.remove('hide')  // (a)
 document.getElementById('chart').style.display = 'block';  // (b)
// chart won't be rendered and not observing bind element's visiblity changes
 var chart = bb.generate({
    render: {
         lazy: true,
         observe: false
    }
 });

 // call at any point when you want to render
 chart.flush();

(static) resize :object

Source:
Properties:
Name Type Attributes Description
resize object <optional>

resize object

Properties
Name Type Attributes Default Description
auto boolean <optional>
 true

Set chart resize automatically on viewport changes.

Set chart resize options

Type:
  • object
Example
resize: {
     auto: false
 }

(static) scatter :object

Source:
Properties:
Name Type Attributes Description
scatter object <optional>

scatter object

Properties
Name Type Attributes Default Description
zerobased boolean <optional>
 false

Set if min or max value will be 0 on scatter chart.

Set scatter options

Type:
  • object
Example
scatter: {
     connectNull: true,
     step: {
         type: "step-after"
     },

     // hide all data points ('point.show=false' also has similar effect)
     point: false,

     // show data points for only indicated datas
     point: [
         "data1", "data3"
     ],

     zerobased: false
 }

(static) size :object

Source:
See:
Properties:
Name Type Attributes Description
size object <optional>

size object

Properties
Name Type Attributes Description
width number <optional>

width of the chart element
height number <optional>

height of the chart element

The desired size of the chart element. If value is not specified, the width of the chart will be calculated by the size of the parent element it's appended to.

Type:
  • object
Example
size: {
  width: 640,
  height: 480
}

(static) spline :object

Source:
See:
Properties:
Name Type Description
spline object

Spline object

Properties
Name Type Description
interpolation object

Spline interpolation object

Properties
Name Type Attributes Default Description
type string <optional>
 "cardinal"

Interpolation type

Set spline options

  • Available interpolation type values:
  • basis (d3.curveBasis)
  • basis-closed (d3.curveBasisClosed)
  • basis-open (d3.curveBasisOpen)
  • bundle (d3.curveBundle)
  • cardinal (d3.curveCardinal)
  • cardinal-closed (d3.curveCardinalClosed)
  • cardinal-open (d3.curveCardinalOpen)
  • catmull-rom (d3.curveCatmullRom)
  • catmull-rom-closed (d3.curveCatmullRomClosed)
  • catmull-rom-open (d3.curveCatmullRomOpen)
  • monotone-x (d3.curveMonotoneX)
  • monotone-y (d3.curveMonotoneY)
  • natural (d3.curveNatural)
  • linear-closed (d3.curveLinearClosed)
  • linear (d3.curveLinear)
  • step (d3.curveStep)
  • step-after (d3.curveStepAfter)
  • step-before (d3.curveStepBefore)
Type:
  • object
Example
spline: {
     interpolation: {
         type: "cardinal"
     }
 }

(static) subchart :object

Source:
See:
Properties:
Name Type Description
subchart object

Subchart object

Properties
Name Type Attributes Default Description
show boolean <optional>
 false

Show sub chart on the bottom of the chart.

  • NOTE: for ESM imports, needs to import 'subchart' exports and instantiate it by calling subchart().
    • show: subchart()
showHandle boolean <optional>
 false

Show sub chart's handle.
axis.x.show boolean <optional>
 true

Show or hide x axis.
axis.x.tick.show boolean <optional>
 true

Show or hide x axis tick line.
axis.x.tick.format function | string <optional>

Use custom format for x axis ticks - see axis.x.tick.format for details.
axis.x.tick.text.show boolean <optional>
 true

Show or hide x axis tick text.
init.range Array <optional>

Set initial selection domain range.
size.height number <optional>

Change the height of the subchart.
onbrush function <optional>

Set callback for brush event.
Specified function receives the current zoomed x domain.

Set subchart options.

  • NOTE: Not supported for bubble, scatter and non-Axis based(pie, donut, gauge, radar) types.
Type:
  • object
Examples
subchart: {
     show: true,
     showHandle: true,
     size: {
         height: 20
     },
     init: {
         // specify initial range domain selection
         range: [1, 2]
     },
     axis: {
     	x: {
     	  show: true,
     	    tick: {
     	      show: true,
     	      format: (x) => d3Format(".1f")(x)
     	      text: {
     	        show: false
     	      }
     	    }
     	}
     },
     onbrush: function(domain) { ... }
 }
// importing ESM
import bb, {subchart} from "billboard.js";

subchart: {
     show: subchart(),
     ...
}

(static) svg :object

Source:
Properties:
Name Type Attributes Description
svg object <optional>

svg object

Properties
Name Type Attributes Description
classname string <optional>

class name for svg element

Set svg element's class name

Type:
  • object
Example
svg: {
  classname: "test_class"
}

(static) title :object

Source:
See:
Properties:
Name Type Description
title object

Title object

Properties
Name Type Attributes Default Description
text string <optional>

Title text. If contains \n, it's used as line break allowing multiline title.
padding.top number <optional>
 0

Top padding value.
padding.right number <optional>
 0

Right padding value.
padding.bottom number <optional>
 0

Bottom padding value.
padding.left number <optional>
 0

Left padding value.
position string <optional>
 center

Available values are: 'center', 'right' and 'left'.

Set title options

Type:
  • object
Example
title: {
     text: "Title Text",

     // or Multiline title text
     text: "Main title text\nSub title text",

     padding: {
         top: 10,
         right: 10,
         bottom: 10,
         left: 10
     },
     position: "center"
 }

(static) tooltip :object

Source:
See:
Properties:
Name Type Description
tooltip object

Tooltip object

Properties
Name Type Attributes Default Description
show boolean <optional>
 true

Show or hide tooltip.
doNotHide boolean <optional>
 false

Make tooltip keep showing not hiding on interaction.
grouped boolean <optional>
 true

Set if tooltip is grouped or not for the data points.

  • NOTE: The overlapped data points will be displayed as grouped even if set false.
linked boolean <optional>
 false

Set if tooltips on all visible charts with like x points are shown together when one is shown.

Properties
Name Type Attributes Default Description
name string <optional>
 ""

Groping name for linked tooltip.
If specified, linked tooltip will be groped interacting to be worked only with the same name.
format.title function <optional>

Set format for the title of tooltip.
Specified function receives x of the data point to show.
format.name function <optional>

Set format for the name of each data in tooltip.
Specified function receives name, ratio, id and index of the data point to show. ratio will be undefined if the chart is not donut/pie/gauge.
format.value function <optional>

Set format for the value of each data in tooltip.
Specified function receives name, ratio, id and index of the data point to show. ratio will be undefined if the chart is not donut/pie/gauge. If undefined returned, the row of that value will be skipped.
position function <optional>

Set custom position function for the tooltip.
This option can be used to modify the tooltip position by returning object that has top and left.

  • Will pass following arguments to the given function:
  • data {Array}: Current selected data array object.
  • width {number}: Width of tooltip.
  • height {number}: Height of tooltip.
  • element {SVGElement}: Tooltip event bound element
  • pos {object}: Current position of the tooltip.
contents function | object <optional>

Set custom HTML for the tooltip.
Specified function receives data, defaultTitleFormat, defaultValueFormat and color of the data point to show. If tooltip.grouped is true, data includes multiple data points.

Properties
Name Type Attributes Description
bindto string | HTMLElement <optional>

Set CSS selector or element reference to bind tooltip.

  • NOTE: When is specified, will not be updating tooltip's position.
template string <optional>

Set tooltip's template.

Within template, below syntax will be replaced using template-like syntax string:

  • {{ ... }}: the doubly curly brackets indicate loop block for data rows.
  • {=CLASS_TOOLTIP}: default tooltip class name bb-tooltip.
  • {=CLASS_TOOLTIP_NAME}: default tooltip data class name (ex. bb-tooltip-name-data1)
  • {=TITLE}: title value.
  • {=COLOR}: data color.
  • {=VALUE}: data value.
text object <optional>

Set additional text content within data loop, using template syntax.

  • NOTE: It should contain { key: Array, ... } value
    • 'key' name is used as substitution within template as '{=KEY}'
    • The value array length should match with the data length
init.show boolean <optional>
 false

Show tooltip at the initialization.
init.x number <optional>
 0

Set x Axis index(or index for Arc(donut, gauge, pie) types) to be shown at the initialization.
init.position object <optional>
 {top: "0px",left: "50px"}

Set the position of tooltip at the initialization.
onshow function <optional>

Set a callback that will be invoked before the tooltip is shown.
onhide function <optional>

Set a callback that will be invoked before the tooltip is hidden.
onshown function <optional>

Set a callback that will be invoked after the tooltip is shown
onhidden function <optional>

Set a callback that will be invoked after the tooltip is hidden.
order string | function | null <optional>
 null

Set tooltip data display order.

Available Values:

  • desc: In descending data value order
  • asc: In ascending data value order
  • null: It keeps the data display order
    NOTE: When data.groups is set, the order will follow as the stacked graph order.
    If want to order as data bound, set any value rather than asc, desc or null. (ex. empty string "")
  • function(data1, data2) { ... }: Array.sort compareFunction

Tooltip options

Type:
  • object
Example
tooltip: {
     show: true,
     doNotHide: true,
     grouped: false,
     format: {
         title: function(x) { return "Data " + x; },
         name: function(name, ratio, id, index) { return name; },
         value: function(value, ratio, id, index) { return ratio; }
     },
     position: function(data, width, height, element, pos) {
         // data: [{x, index, id, name, value}, ...]
         // width: Tooltip width
         // height: Tooltip height
         // element: Tooltip event bound element
         // pos: {
         //   x: Current mouse event x position,
         //   y: Current mouse event y position,
         //   xAxis: Current x Axis position (the value is given for axis based chart type only)
         // }
         return {top: 0, left: 0}
     },

     contents: function(d, defaultTitleFormat, defaultValueFormat, color) {
         return ... // formatted html as you want
     },

      // specify tooltip contents using template
      // - example of HTML returned:
      // <ul class="bb-tooltip">
      //   <li class="bb-tooltip-name-data1"><span>250</span><br><span style="color:#00c73c">data1</span></li>
      //   <li class="bb-tooltip-name-data2"><span>50</span><br><span style="color:#fa7171">data2</span></li>
      // </ul>
      contents: {
     	bindto: "#tooltip",
     	template: '<ul class={=CLASS_TOOLTIP}>{{' +
     			'<li class="{=CLASS_TOOLTIP_NAME}"><span>{=VALUE}</span><br>' +
     			'<span style=color:{=COLOR}>{=NAME}</span></li>' +
     		'}}</ul>'
     }

      // with additional text value
      // - example of HTML returned:
      // <ul class="bb-tooltip">
      //   <li class="bb-tooltip-name-data1"><span>250</span><br>comment1<span style="color:#00c73c">data1</span>text1</li>
      //   <li class="bb-tooltip-name-data2"><span>50</span><br>comment2<span style="color:#fa7171">data2</span>text2</li>
      // </ul>
      contents: {
     	bindto: "#tooltip",
     	text: {
     		// a) 'key' name is used as substitution within template as '{=KEY}'
     		// b) the length should match with the data length
     		VAR1: ["text1", "text2"],
     		VAR2: ["comment1", "comment2"],
     	},
     	template: '<ul class={=CLASS_TOOLTIP}>{{' +
     			'<li class="{=CLASS_TOOLTIP_NAME}"><span>{=VALUE}</span>{=VAR2}<br>' +
     			'<span style=color:{=COLOR}>{=NAME}</span>{=VAR1}</li>' +
     		'}}</ul>'
     }

     // sort tooltip data value display in ascending order
     order: "asc",

     // specifying sort function
     order: function(a, b) {
        // param data passed format
        {x: 5, value: 250, id: "data1", index: 5, name: "data1"}
          ...
     },

     // show at the initialization
     init: {
         show: true,
         x: 2, // x Axis index(or index for Arc(donut, gauge, pie) types)
         position: {
             top: "150px",
             left: "250px"
         }
     },

     // fires prior tooltip is shown
     onshow: function(selectedData) {
     	// current dataset selected
     	// ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
     	selectedData;
     },

     // fires prior tooltip is hidden
     onhide: function(selectedData) {
     	// current dataset selected
     	// ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
     	selectedData;
     },

     // fires after tooltip is shown
     onshown: function(selectedData) {
     	// current dataset selected
     	// ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
     	selectedData;
     },

     // fires after tooltip is hidden
     onhidden: function(selectedData) {
     	// current dataset selected
     	// ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
     	selectedData;
     },

     // Link any tooltips when multiple charts are on the screen where same x coordinates are available
     // Useful for timeseries correlation
     linked: true,

     // Specify name to interact those with the same name only.
     linked: {
         name: "some-group"
     }
 }

(static) transition :object

Source:
Properties:
Name Type Attributes Description
transition object <optional>

transition object

Properties
Name Type Attributes Default Description
duration number <optional>
 350

duration in milliseconds

Set duration of transition (in milliseconds) for chart animation.

  • NOTE: If 0 or null set, transition will be skipped. So, this makes initial rendering faster especially in case you have a lot of data.
Type:
  • object
Example
transition: {
   duration: 500
}

(static) zoom :object

Source:
See:
Properties:
Name Type Description
zoom object

Zoom object

Properties
Name Type Attributes Default Description
enabled boolean <optional>
 false

Enable zooming.

  • NOTE: for ESM imports, needs to import 'zoom' exports and instantiate it by calling zoom().
    • enabled: zoom()
type string <optional>
 'wheel'

Set zoom interaction type.

  • Available types:
    • wheel
    • drag
rescale boolean <optional>
 false

Enable to rescale after zooming.
If true set, y domain will be updated according to the zoomed region.
extent Array <optional>
 [1, 10]

Change zoom extent.
x.min number | Date <optional>

Set x Axis minimum zoom range
x.max number | Date <optional>

Set x Axis maximum zoom range
onzoomstart function <optional>

Set callback that is called when zooming starts.
Specified function receives the zoom event.
onzoom function <optional>

Set callback that is called when the chart is zooming.
Specified function receives the zoomed domain.
onzoomend function <optional>

Set callback that is called when zooming ends.
Specified function receives the zoomed domain.
resetButton boolean | object <optional>
 true

Set to display zoom reset button for 'drag' type zoom

Properties
Name Type Attributes Default Description
onclick function <optional>

Set callback when clicks the reset button. The callback will receive reset button element reference as argument.
text string <optional>
 'Reset Zoom'

Text value for zoom reset button.

Set zoom options

Type:
  • object
Examples
zoom: {
     enabled: true,
     type: "drag",
     rescale: true,
     extent: [1, 100]  // enable more zooming
     x: {
         min: -1,  // set min range
         max: 10  // set max range
     },
     onzoomstart: function(event) { ... },
     onzoom: function(domain) { ... },
     onzoomend: function(domain) { ... },

     // show reset button when is zoomed-in
     resetButton: true,

     resetButton: {
         // onclick callback when reset button is clicked
         onclick: function(button) {
           button; // Reset button element reference
           ...
         },

         // customized text value for reset zoom button
         text: "Unzoom"
     }
 }
// importing ESM
import bb, {zoom} from "billboard.js";

zoom: {
     enabled: zoom(),
     ...
}