Skip to content

Latest commit

 

History

History
184 lines (130 loc) · 5.17 KB

options.md

File metadata and controls

184 lines (130 loc) · 5.17 KB

Options

Option resolution

Options are resolved from top to bottom, using a context dependent route.

Chart level options

  • options
  • overrides[config.type]
  • defaults

Dataset level options

dataset.type defaults to config.type, if not specified.

  • dataset
  • options.datasets[dataset.type]
  • options
  • overrides[config.type].datasets[dataset.type]
  • defaults.datasets[dataset.type]
  • defaults

Dataset animation options

  • dataset.animation
  • options.datasets[dataset.type].animation
  • options.animation
  • overrides[config.type].datasets[dataset.type].animation
  • defaults.datasets[dataset.type].animation
  • defaults.animation

Dataset element level options

Each scope is looked up with elementType prefix in the option name first, then without the prefix. For example, radius for point element is looked up using pointRadius and if that does not hit, then radius.

  • dataset
  • options.datasets[dataset.type]
  • options.datasets[dataset.type].elements[elementType]
  • options.elements[elementType]
  • options
  • overrides[config.type].datasets[dataset.type]
  • overrides[config.type].datasets[dataset.type].elements[elementType]
  • defaults.datasets[dataset.type]
  • defaults.datasets[dataset.type].elements[elementType]
  • defaults.elements[elementType]
  • defaults

Scale options

  • options.scales
  • overrides[config.type].scales
  • defaults.scales
  • defaults.scale

Plugin options

A plugin can provide additionalOptionScopes array of paths to additionally look for its options in. For root scope, use empty string: ''. Most core plugins also take options from root scope.

  • options.plugins[plugin.id]
  • (options.[...plugin.additionalOptionScopes])
  • overrides[config.type].plugins[plugin.id]
  • defaults.plugins[plugin.id]
  • (defaults.[...plugin.additionalOptionScopes])

Scriptable Options

Scriptable options also accept a function which is called for each of the underlying data values and that takes the unique argument context representing contextual information (see option context). A resolver is passed as second parameter, that can be used to access other options in the same context.

:::tip Note

The context argument should be validated in the scriptable function, because the function can be invoked in different contexts. The type field is a good candidate for this validation.

:::

Example:

color: function(context) {
    const index = context.dataIndex;
    const value = context.dataset.data[index];
    return value < 0 ? 'red' :  // draw negative values in red
        index % 2 ? 'blue' :    // else, alternate values in blue and green
        'green';
},
borderColor: function(context, options) {
    const color = options.color; // resolve the value of another scriptable option: 'red', 'blue' or 'green'
    return Chart.helpers.color(color).lighten(0.2);
}

Indexable Options

Indexable options also accept an array in which each item corresponds to the element at the same index. Note that if there are less items than data, the items are looped over. In many cases, using a function is more appropriate if supported.

Example:

color: [
    'red',    // color for data at index 0
    'blue',   // color for data at index 1
    'green',  // color for data at index 2
    'black',  // color for data at index 3
    //...
]

Option Context

The option context is used to give contextual information when resolving options and currently only applies to scriptable options. The object is preserved, so it can be used to store and pass information between calls.

There are multiple levels of context objects:

  • chart
    • dataset
      • data
    • scale
      • tick
      • pointLabel (only used in the radial linear scale)
    • tooltip

Each level inherits its parent(s) and any contextual information stored in the parent is available through the child.

The context object contains the following properties:

chart

  • chart: the associated chart
  • type: 'chart'

dataset

In addition to chart

  • active: true if an element is active (hovered)
  • dataset: dataset at index datasetIndex
  • datasetIndex: index of the current dataset
  • index: same as datasetIndex
  • mode: the update mode
  • type: 'dataset'

data

In addition to dataset

  • active: true if an element is active (hovered)
  • dataIndex: index of the current data
  • parsed: the parsed data values for the given dataIndex and datasetIndex
  • raw: the raw data values for the given dataIndex and datasetIndex
  • element: the element (point, arc, bar, etc.) for this data
  • index: same as dataIndex
  • type: 'data'

scale

In addition to chart

  • scale: the associated scale
  • type: 'scale'

tick

In addition to scale

  • tick: the associated tick object
  • index: tick index
  • type: 'tick'

pointLabel

In addition to scale

  • label: the associated label value
  • index: label index
  • type: 'pointLabel'

tooltip

In addition to chart

  • tooltip: the tooltip object
  • tooltipItems: the items the tooltip is displaying