scales/configuration

132 notes in this subject, read out of this brain and free to use. This is page 1 of 3.

grid scale option

The `grid` option is an object that configures grid line display for the scale. More details are available in the grid line configuration documentation.

ticks scale option

The `ticks` option is an object that configures tick display and behavior for the scale. More details are available in the tick configuration documentation.

min scale option

The `min` option accepts a number and sets a user-defined minimum value for the scale, overriding the minimum value derived from data.

stacked scale option

The `stacked` option accepts a boolean or string with default value `false`. It controls whether data should be stacked. More details are available in the stacking documentation.

Common scale options namespace

Common options to all axes are located in the namespace `options.scales[scaleId]`.

Scale type option

The `type` option is a string that specifies the type of scale being employed. Custom scales can be created and registered with a string key. This allows changing the type of an axis for a chart.

border scale option

The `border` option is an object that configures the border of the scale. More details are available in the border configuration documentation.

display scale option

The `display` option controls axis global visibility and accepts a boolean or the string `'auto'`. Default is `true`. When `true`, the axis is visible. When `false`, the axis is hidden. When `display: 'auto'`, the axis is visible only if at least one associated dataset is visible.

alignToPixels scale option

The `alignToPixels` option is a boolean with default value `false`. When enabled, it aligns pixel values to device pixels.

weight scale option

The `weight` option is a number with default value `0`. It specifies the weight used to sort the axis. Higher weights position the axis further away from the chart area.

max scale option

The `max` option accepts a number and sets a user-defined maximum value for the scale, overriding the maximum value derived from data.

suggestedMin scale option

The `suggestedMin` option accepts a number and provides an adjustment used when calculating the minimum data value for the scale.

backgroundColor scale option

The `backgroundColor` option accepts a Color value and sets the background color of the scale area.

reverse scale option

The `reverse` option is a boolean with default value `false`. When enabled, it reverses the scale direction.

suggestedMax scale option

The `suggestedMax` option accepts a number and provides an adjustment used when calculating the maximum data value for the scale.

Common tick options for all axes

All axes support common tick configuration options under the namespace options.scales[scaleId].ticks. The available options are: backdropColor (Color, scriptable, default 'rgba(255, 255, 255, 0.75)'): Color of label backdrops. backdropPadding (Padding, default 2): Padding of label backdrop. callback (function): Returns the string representation of the tick value as it should be displayed on the chart. display (boolean, default true): If true, show tick labels. color (Color, scriptable, default Chart.defaults.color): Color of ticks. font (Font, scriptable, default Chart.defaults.font): Font configuration for ticks. major (object, default {}): Major ticks configuration. padding (number, default 3): Sets the offset of the tick labels from the axis. showLabelBackdrop (boolean, scriptable, default true for radial scale and false otherwise): If true, draw a background behind the tick labels. textStrokeColor (Color, scriptable, default empty): The color of the stroke around the text. textStrokeWidth (number, scriptable, default 0): Stroke width around the text. z (number, default 0): z-index of tick layer, useful when ticks are drawn on chart area; values <= 0 are drawn under datasets, > 0 on top.

Cartesian axes common options reference

All cartesian axes share common options configured under `options.scales[scaleId]`. The complete set of options is: `bounds` (string, default 'ticks') determines the scale bounds; `clip` (boolean, default true) clips dataset drawing against scale size instead of chart area if true; `position` (string or object) sets axis position; `stack` (string) defines stack group, with axes at same position and same stack value stacked together; `stackWeight` (number, default 1) determines allocated space for the scale within its stack group; `axis` (string) specifies axis type with possible values 'x' or 'y', inferred from first character of ID if not set; `offset` (boolean, default false) adds extra space at edges and scales axis to fit chart area when true, set to true for bar charts by default; `title` (object) configures scale title.

Common tick options namespace

Common tick options for all cartesian axes are configured under the namespace `options.scales[scaleId].ticks`.

Cartesian tick configuration options reference

The following options configure ticks for all cartesian axes, located at `options.scales[scaleId].ticks`: | Name | Type | Default | Description | | ---- | ---- | ------- | ----------- | | `align` | `string` | `'center'` | The tick alignment along the axis. Can be `'start'`, `'center'`, `'end'`, or `'inner'`. `inner` alignment means align `start` for first tick and `end` for the last tick of horizontal axis | | `crossAlign` | `string` | `'near'` | The tick alignment perpendicular to the axis. Can be `'near'`, `'center'`, or `'far'`. See [Tick Alignment](/axes/cartesian/#tick-alignment) | | `sampleSize` | `number` | `ticks.length` | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. | | `autoSkip` | `boolean` | `true` | If true, automatically calculates how many labels can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. | | `autoSkipPadding` | `number` | `3` | Padding between the ticks on the horizontal axis when `autoSkip` is enabled. | | `includeBounds` | `boolean` | `true` | Should the defined `min` and `max` values be presented as ticks even if they are not "nice". | | `labelOffset` | `number` | `0` | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis). *Note: this can cause labels at the edges to be cropped by the edge of the canvas* | | `maxRotation` | `number` | `50` | Maximum rotation for tick labels when rotating to condense labels. Note: Rotation doesn't occur until necessary. *Note: Only applicable to horizontal scales.* | | `minRotation` | `number` | `0` | Minimum rotation for tick labels. *Note: Only applicable to horizontal scales.* | | `mirror` | `boolean` | `false` | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* | | `padding` | `number` | `0` | Padding between the tick label and the axis. When set on a vertical axis, this applies in the horizontal (X) direction. When set on a horizontal axis, this applies in the vertical (Y) direction. | | `maxTicksLimit` | `number` | `11` | Maximum number of ticks and gridlines to show. |

Scale bounds property

The bounds property controls the scale boundary strategy and accepts two values: 'data' (makes sure data are fully visible, labels outside are removed) or 'ticks' (makes sure ticks are fully visible, data outside are truncated). The bounds property is bypassed by min/max options.

Tick alignment configuration

Tick alignment is controlled by two settings on the ticks configuration object: align (configures how labels align with the tick mark along the axis direction) and crossAlign (configures how labels align with the tick mark in the perpendicular direction). For example, on a Y axis, crossAlign: 'far' left-aligns the labels.

Grid lines configuration

Grid lines are configured under scales.[axisId].grid. The grid object accepts properties: color (the color of grid lines), borderColor (the color of the axis border), and tickColor (the color of tick marks).

Ticks and tick marks configuration

Ticks are configured under scales.[axisId].ticks. The tickColor for tick marks is configured under scales.[axisId].grid.tickColor. The color property under ticks controls the label text color.

Axis title configuration

The axis title is configured under scales.[axisId].title. The title object accepts properties: color (text color), display (boolean to show/hide), and text (the title string).

Axis position options

An axis can be positioned in three ways. Set position to 'top', 'left', 'bottom', or 'right' to position at the chart edge. Set position to 'center' to position at the center of the chart area (requires either an axis option or axis ID starting with 'x' or 'y'). Set position to an object like {x: -20} to position at a specific data value on the axis with ID 'x'.

crossAlign preconditions

The crossAlign setting is only effective when tick rotation is 0 and axis position is 'top', 'left', 'bottom', or 'right'.

Axis border configuration

The axis border is configured under scales.[axisId].border. For example, to set the border color to red, use scales.x.border.color = 'red'.

Time axis configuration options

Time axis configuration is set in the namespace options.scales[scaleId]. The following options are available: min (number|string), max (number|string), suggestedMin (number|string), suggestedMax (number|string), adapters.date (object, default {}), bounds (string, default 'data'), offsetAfterAutoskip (boolean, default false), ticks.source (string, default 'auto'), time.displayFormats (object), time.isoWeekday (boolean|number, default false), time.parser (string|function), time.round (string, default false), time.tooltipFormat (string), time.unit (string, default false), time.minUnit (string, default 'millisecond').

Stacking behavior with stacked option

By default, data is not stacked. If the stacked option of the value scale is true, positive and negative values are stacked separately. To stack positive and negative values together, specify stacked: 'single'. Additionally, a stack option can be defined per dataset to further divide into stack groups.

Scale callbacks API

Scale callbacks are supplied at the top level of the axis options under the namespace options.scales[scaleId]. Available callbacks are: beforeUpdate (called before update process starts), beforeSetDimensions (before dimensions set), afterSetDimensions (after dimensions set), beforeDataLimits (before data limits determined), afterDataLimits (after data limits determined), beforeBuildTicks (before ticks created), afterBuildTicks (after ticks created, useful for filtering ticks), beforeTickToLabelConversion (before ticks converted to strings), afterTickToLabelConversion (after ticks converted to strings), beforeCalculateLabelRotation (before tick rotation determined), afterCalculateLabelRotation (after tick rotation determined), beforeFit (before scale fits to canvas), afterFit (after scale fits to canvas), afterUpdate (at end of update process). Each callback receives the axis as an argument.

Updating default scale configuration

The default configuration for a scale can be changed by setting new options to Chart.defaults.scales[type]. For example, to set the minimum value of 0 for all linear scales: Chart.defaults.scales.linear.min = 0; Any scales of that type created after this change will use the new defaults.

suggestedMin and suggestedMax example with line chart

A line chart with suggestedMin and suggestedMax settings: new Chart(ctx, { type: 'line', data: { datasets: [{ label: 'First dataset', data: [0, 20, 40, 50] }], labels: ['January', 'February', 'March', 'April'] }, options: { scales: { y: { suggestedMin: 50, suggestedMax: 100 } } } }); The largest positive value is 50, but the data maximum is expanded to 100. However, because the lowest data value is below suggestedMin, it is ignored.

Scale improvements in Chart.js v2.0+

Scales in Chart.js v2.0 and later include several improvements over v1.0: multiple X and Y axes are supported, a built-in label auto-skip feature detects overlapping ticks and labels and removes every nth label to keep display normal, scale titles are supported, and new scale types can be extended without writing an entirely new chart type.

Default scale IDs for chart types

The default scaleId values for cartesian charts are 'x' and 'y'. For radial charts, the default scaleId is 'r'.

Default scales for new bar chart

A new bar chart created without custom scale configuration will have scales 'x' and 'y'.

Custom scale with explicit axis and yAxisID example

A bar chart can define custom scale IDs and axis types. When a custom yAxisID is used on a dataset, it must correspond to a scale definition. Example: new Chart(ctx, { type: 'bar', data: { datasets: [{ yAxisID: 'yAxis' }] }, options: { scales: { xAxis: { type: 'time' } } } });

Dataset to scale mapping

Each dataset is mapped to a scale for each axis it requires. The scaleIds that a dataset is mapped to are determined by the xAxisID, yAxisID, or rAxisID properties. If the ID for an axis is not specified, the first scale for that axis is used. If no scale for an axis is found, a new scale is created.

Radar chart default scale

A radar chart created without custom scale configuration will have an 'r' scale.

Custom radial scale example

A radar chart can define a custom radial scale by setting the axis property to 'r'. Example: new Chart(ctx, { type: 'radar', scales: { myScale: { axis: 'r' } } });

Ticks callback return value behavior

If the ticks.callback method returns null or undefined, the associated grid line will be hidden.

Scale Title Configuration options table

Scale title configuration has the following options: display (boolean, default false) - if true, display the axis title; align (string, default 'center') - alignment of the axis title with possible options 'start', 'center', and 'end'; text (string or string array, default '') - the text for the title; color (Color, default Chart.defaults.color) - color of label; strokeColor (Color, default undefined) - color of text stroke; strokeWidth (number, default undefined) - size of stroke width in pixels; font (Font, default Chart.defaults.font) - see Fonts documentation; padding (Padding, default 4) - padding to apply around scale labels where only top, bottom, and y are implemented.

Ticks callback method signature and scope

The ticks.callback method receives three arguments: value (the tick value in the internal data format of the associated scale, for time scale this is a timestamp), index (the tick index in the ticks array), and ticks (the array containing all tick objects). The call to the method is scoped to the scale, meaning 'this' inside the method refers to the scale object.

Calling default formatter in ticks.callback

When overriding ticks.callback, you are responsible for all formatting of the label. To call the default formatter and modify its output, use: Chart.Ticks.formatters.numeric.apply(this, [value, index, ticks]). This forwards the 'this' context to the default formatter.

Responsibility when overriding ticks.callback

Overriding ticks.callback means you are responsible for all formatting of the label. Depending on your use case, you may want to call the default formatter and then modify its output.

Scale Title Configuration namespace

Scale title configuration is located at the namespace options.scales[scaleId].title and defines options for the scale title. This only applies to cartesian axes.

Custom tick format with dollar sign example

This example shows how to format Y-axis labels with a dollar sign prefix: const chart = new Chart(ctx, { type: 'line', data: data, options: { scales: { y: { ticks: { // Include a dollar sign in the ticks callback: function(value, index, ticks) { return '$' + value; } } } } } });

Grid line configuration namespace

Grid line configuration options are found at `options.scales[scaleId].grid`. These options define the appearance and behavior of grid lines that run perpendicular to an axis.

Border configuration namespace

Border configuration options are found at `options.scales[scaleId].border`. These options define the appearance of the border that runs perpendicular to an axis (at the edge between the axis and the chart area).

Grid line configuration options table

Grid line options: `circular` (boolean, default false) - if true, gridlines are circular on radar and polar area charts only. `color` (Color, default Chart.defaults.borderColor, scriptable and indexable) - the color of grid lines; if an array, the first color applies to the first grid line, the second to the second, and so on. `display` (boolean, default true) - if false, do not display grid lines for this axis. `drawOnChartArea` (boolean, default true) - if true, draw lines on the chart area inside the axis lines. `drawTicks` (boolean, default true) - if true, draw lines beside the ticks in the axis area beside the chart. `lineWidth` (number, default 1, scriptable and indexable) - stroke width of grid lines. `offset` (boolean, default false) - if true, grid lines will be shifted to be between labels (true by default for bar charts). `tickBorderDash` (number array, default [], scriptable and indexable) - length and spacing of the tick mark line; if not set, defaults to the grid line `borderDash` value. `tickBorderDashOffset` (number, scriptable and indexable) - offset for the line dash of the tick mark; if unset, defaults to the grid line `borderDashOffset` value. `tickColor` (Color, scriptable and indexable) - color of the tick line; if unset, defaults to the grid line color. `tickLength` (number, default 8) - length in pixels that the grid lines will draw into the axis area. `tickWidth` (number, scriptable and indexable) - width of the tick mark in pixels; if unset, defaults to the grid line width. `z` (number, default -1) - z-index of the gridline layer; values <= 0 are drawn under datasets, > 0 on top.

Major tick configuration namespace and options

Major tick configuration options are found at `options.scales[scaleId].ticks.major`. The `enabled` option is a boolean (default false); if true, major ticks are generated and `major` will be defined on ticks in the scriptable options context for use in callbacks. A major tick will affect autoskipping.

Border configuration options table

Border options: `display` (boolean, default true) - if true, draw a border at the edge between the axis and the chart area. `color` (Color, default Chart.defaults.borderColor) - the color of the border line. `width` (number, default 1) - the width of the border line. `dash` (number array, default [], scriptable) - length and spacing of dashes on the border line; see MDN setLineDash. `dashOffset` (number, default 0.0, scriptable) - offset for line dashes; see MDN lineDashOffset. `z` (number, default 0) - z-index of the border layer; values <= 0 are drawn under datasets, > 0 on top.

suggestedMin and suggestedMax behavior

The suggestedMax and suggestedMin settings only change the data values that are used to scale the axis. They are useful for extending the range of the axis while maintaining the auto-fit behaviour. The calculation is: minDataValue = Math.min(mostNegativeValue, options.ticks.suggestedMin) and maxDataValue = Math.max(mostPositiveValue, options.ticks.suggestedMax). When actual data values are outside the suggested range, the data value takes precedence.

min and max settings behavior

In contrast to the suggestedMin and suggestedMax settings, the min and max settings set explicit ends to the axes. When these are set, some data points may not be visible.

stepSize behavior for scale ticks

If set, the scale ticks will be enumerated by multiples of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm.

Common axis configuration options table

Grid line configuration options table

Bar chart offset grid lines explanation

When offset is true, bars for a particular data point fall between grid lines and the grid line moves left by one half of the tick interval, which is the space between grid lines. When offset is false, the grid line goes right down the middle of the bars. This is set to true for a category scale in a bar chart by default.

Bar chart scale configuration defaults

Bar charts set unique default values for scale options: offset (boolean, default true) - if true, extra space is added to both edges and the axis is scaled to fit into the chart area. grid.offset (boolean, default true) - if true, bars for a particular data point fall between grid lines and the grid line moves left by one half of the tick interval; if false, the grid line goes through the middle of the bars.

locale option for number formatting

The locale option enables language-sensitive number formatting on chart scales. It accepts a Unicode BCP 47 locale identifier string and leverages the INTL NumberFormat API. The default value is undefined, which uses the default locale of the platform running the chart.

Unicode BCP 47 locale identifier structure

A Unicode BCP 47 locale identifier consists of a language code, optionally a script code, optionally a region or country code, optionally one or more variant codes, and optionally one or more extension sequences, with all present components separated by hyphens.

Give your agent this brain