This website is for Vega-Lite v2. Go to the main Vega-Lite homepage for the latest release.

Axis

Edit this page

Axes provide axis lines, ticks, and labels to convey how a positional range represents a data range. Simply put, axes visualize scales.

By default, Vega-Lite automatically creates axes with default properties for x and y channels when they encode data fields. User can set the axis property of x- or y-field definition to an object to customize axis properties or set axis to null to remove the axis.

Besides axis property of a field definition, the configuration object (config) also provides axis config (config: {axis: {...}}) for setting default axis properties for all axes.

Documentation Overview

Axis Properties

// Single View Specification
{
  "data": ... ,
  "mark": ... ,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "axis": {                // Axis
        ...
      },
      ...
    },
    "y": ...,
    ...
  }
}

To customize axis, an axis object in an encoding channel’s definition can contain the following groups of properties:

General

Property Type Description
domain Boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true
grid Boolean

A boolean flag indicating if grid lines should be included as part of the axis

Default value: true for continuous scales that are not binned; otherwise, false.
maxExtent Number

The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.

Default value: undefined.
minExtent Number

The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.

Default value: 30 for y-axis; undefined for x-axis.
orient String

The orientation of the axis. One of "top", "bottom", "left" or "right". The orientation can be used to further specialize the axis type (e.g., a y axis oriented for the right edge of the chart).

Default value: "bottom" for x-axes and "left" for y-axes.
offset Number

The offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle.

Default value: derived from the axis config’s offset (0 by default)
position Number

The anchor position of the axis in pixels. For x-axis with top or bottom orientation, this sets the axis group x coordinate. For y-axis with left or right orientation, this sets the axis group y coordinate.

Default value: 0
zindex Number

A non-positive integer indicating z-index of the axis. If zindex is 0, axes should be drawn behind all chart elements. To put them in front, use "zindex = 1".

Default value: 1 (in front of the marks) for actual axis and 0 (behind the marks) for grids.

See also: General Axis Config.

Labels

Property Type Description
format String

The formatting pattern for labels. This is D3’s number format pattern for quantitative fields and D3’s time format pattern for time field.

See the format documentation for more information.

Default value: derived from numberFormat config for quantitative fields and from timeFormat config for temporal fields.
labels Boolean

A boolean flag indicating if labels should be included as part of the axis.

Default value: true.
labelAngle Number

The rotation angle of the axis labels.

Default value: -90 for nominal and ordinal fields; 0 otherwise.
labelOverlap Boolean | String | String

The strategy to use for resolving overlap of axis labels. If false (the default), no overlap reduction is attempted. If set to true or "parity", a strategy of removing every other label is used (this works well for standard linear axes). If set to "greedy", a linear scan of the labels is performed, removing any labels that overlaps with the last visible label (this often works better for log-scaled axes).

Default value: true for non-nominal fields with non-log scales; "greedy" for log scales; otherwise false.
labelPadding Number

The padding, in pixels, between axis and text labels.

See also: Axis Labels Config and guide-label style config (common styles for axis, legend, and header labels).

Ticks

Property Type Description
ticks Boolean

Boolean value that determines whether the axis should include ticks.
tickCount Number

A desired number of ticks, for axes visualizing quantitative scales. The resulting number may be different so that values are “nice” (multiples of 2, 5, 10) and lie within the underlying scale’s range.
tickSize Number

The size in pixels of axis ticks.
values Number[] | String[] | Boolean[] | DateTime[]

Explicitly set the visible axis tick values.

See also: Axis Ticks Config.

Title

Property Type Description
title String | Null

A title for the field. If null, the title will be removed.

Default value: derived from the field’s name and transformation function (aggregate, bin and timeUnit). If the field has an aggregate function, the function is displayed as part of the title (e.g., "Sum of Profit"). If the field is binned or has a time unit applied, the applied function is shown in parentheses (e.g., "Profit (binned)", "Transaction Date (year-month)"). Otherwise, the title is simply the field name.

Notes:

1) You can customize the default field title format by providing the [fieldTitle property in the config or fieldTitle function via the compile function’s options.

2) If both field definition’s title and axis, header, or legend title are defined, axis/header/legend title will be used.
titleMaxLength Number

Max length for axis title if the title is automatically generated from the field’s description.
titlePadding Number

The padding, in pixels, between title and axis.

For example, the following plot has a customized x-axis title.

See also: Axis Title Config and guide-title style config (common styles for axis, legend, and header titles).

Axis Config

// Top-level View Specification
{
  ...
  "config": {
    "axis": : ...,
    "axisX": : ...,
    "axisY": : ...,
    "axisLeft": : ...,
    "axisRight": : ...,
    "axisTop": : ...,
    "axisBottom": : ...,
    "axisBand": : ...,
    ...
  }
}

Axis configuration defines default settings for axes. Properties defined under the "axis" property in the top-level config object are applied to all axes.

Additional property blocks can target more specific axis types based on the orientation ("axisX", "axisY", "axisLeft", "axisTop", etc.) or band scale type ("axisBand"). For example, properties defined under the "axisBand" property will only apply to axes visualizing "band" scales. If multiple axis config blocks apply to a single axis, type-based options take precedence over orientation-based options, which in turn take precedence over general options.

General

Property Type Description
bandPosition Number

An interpolation fraction indicating where, for band scales, axis ticks should be positioned. A value of 0 places ticks at the left edge of their bands. A value of 0.5 places ticks in the middle of their bands.
domain Boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true
domainColor String

Color of axis domain line.

Default value: (none, using Vega default).
domainWidth Number

Stroke width of axis domain line

Default value: (none, using Vega default).
maxExtent Number

The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.

Default value: undefined.
minExtent Number

The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.

Default value: 30 for y-axis; undefined for x-axis.

See also: General Axis Properties.

Grid

Property Type Description
grid Boolean

A boolean flag indicating if grid lines should be included as part of the axis

Default value: true for continuous scales that are not binned; otherwise, false.
gridColor String

Color of gridlines.
gridDash Number[]

The offset (in pixels) into which to begin drawing with the grid dash array.
gridOpacity Number

The stroke opacity of grid (value between [0,1])

Default value: (1 by default)
gridWidth Number

The grid width, in pixels.

Labels

Property Type Description
labels Boolean

A boolean flag indicating if labels should be included as part of the axis.

Default value: true.
labelAngle Number

The rotation angle of the axis labels.

Default value: -90 for nominal and ordinal fields; 0 otherwise.
labelColor String

The color of the tick label, can be in hex color code or regular color name.
labelFont String

The font of the tick label.
labelFontSize Number

The font size of the label, in pixels.
labelLimit Number

Maximum allowed pixel width of axis tick labels.
labelOverlap Boolean | String | String

The strategy to use for resolving overlap of axis labels. If false (the default), no overlap reduction is attempted. If set to true or "parity", a strategy of removing every other label is used (this works well for standard linear axes). If set to "greedy", a linear scan of the labels is performed, removing any labels that overlaps with the last visible label (this often works better for log-scaled axes).

Default value: true for non-nominal fields with non-log scales; "greedy" for log scales; otherwise false.
labelPadding Number

The padding, in pixels, between axis and text labels.

The shortTimeLabels property is also available for the general axis config (config.axis), but not for specific axis config (e.g., config.axisX).

Property Type Description
shortTimeLabels Boolean

Whether month names and weekday names should be abbreviated.

Default value: false

See also: Axis Labels Properties and guide-label style config (common styles for by axis, legend, and header labels).

Ticks

Property Type Description
ticks Boolean

Boolean value that determines whether the axis should include ticks.
tickColor String

The color of the axis’s tick.
tickRound Boolean

Boolean flag indicating if pixel position values should be rounded to the nearest integer.
tickSize Number

The size in pixels of axis ticks.
tickWidth Number

The width, in pixels, of ticks.

See also: Axis Tick Properties.

Title

Property Type Description
titleAlign String

Horizontal text alignment of axis titles.
titleAngle Number

Angle in degrees of axis titles.
titleBaseline String

Vertical text baseline for axis titles.
titleColor String

Color of the title, can be in hex color code or regular color name.
titleFont String

Font of the title. (e.g., "Helvetica Neue").
titleFontWeight String

Font weight of the title. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
titleFontSize Number

Font size of the title.
titleLimit Number

Maximum allowed pixel width of axis titles.
titleMaxLength Number

Max length for axis title if the title is automatically generated from the field’s description.
titlePadding Number

The padding, in pixels, between title and axis.
titleX Number

X-coordinate of the axis title relative to the axis group.
titleY Number

Y-coordinate of the axis title relative to the axis group.

See also: Axis Title Properties and guide-title style config (common styles for axis, legend, and header titles).