Axis

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

By default, Vega-Lite automatically creates axes for x, y, row, and column channels when they are encoded. Axis can be customized via the axis property of a channel definition.

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

Customizing Axis

The field’s axis can be removed by setting axis to false. If axis is true, default axis properties are applied.

Axis properties can be customized by setting axis to an axis property object. The axis property object supports the following properties:

General

Property	Type	Description
axisColor	Color	Color of axis line. Default value: (none, using Vega default).
axisWidth	Number	Width of the axis line. Default value: (none, using Vega default).
layer	String	A string indicating if the axis (and any gridlines) should be placed above or below the data marks. One of `"front"` or `"back"`. Default value: derived from axis config’s `layer`. If the `layer` config is undefined, the default is `"back"` if `grid` is `true` and `"front"` otherwise.
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 axis config’s `offset` (`0` by default)
orient	String	The orientation of the axis. One of `top` or `bottom` for `y` and `row` channels, and `left` or `right` for `x` and `column` channels. Default value: `x` axis is placed on the bottom, `y` axis is placed on the left, `column`”s x-axis is placed on the top, `row`”s y-axis is placed on the right.

Grid

Property	Type	Description
grid	Boolean	A flag indicate if gridlines should be created in addition to ticks. Default value: `true` for (1) quantitative fields that are not binned and (2) time fields; 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	Enable or disable labels Default value: derived from axis config’s `labels` (`true` by default).
format	String	The formatting pattern for axis labels. This is D3’s number format pattern for quantitative axis and D3’s time format pattern for time axis. Default value: derived from `numberFormat` config for quantitative axis and from `timeFormat` config for time axis.
labelAngle	Number	Rotation angle for axis labels. Default value: `-45` for time or ordinal axis and `0` otherwise.
labelMaxLength	Integer	Max length for axis labels. Longer labels are truncated. Default value: derived from axis config’s `labelMaxLength` (`25` by default).
shortTimeLabels	Boolean	Whether month and day names should be abbreviated. Default value: derived from axis config’s `shortTimeLabels` (`false` by default).

Ticks

Property	Type	Description
subdivide	Number	If provided, sets the number of minor ticks between major ticks (the value 9 results in decimal subdivision). Only applicable for axes visualizing quantitative scales.
ticks	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. Default value: derived from axis config’s `ticks`. If the `ticks` config is undefined (default), `ticks` is `5` for x-scale without binning, and `10` otherwise.
tickColor	String	The color of the axis’s tick.
tickLabelColor	String	The color of the tick label.
tickLabelFont	String	The font of tick label (e.g., `Helvetica Neue`).
tickLabelFontSize	Number	The font size of label, in pixels. Default value: 10.
tickPadding	Number	The padding, in pixels, between ticks and text labels.
tickSize	Number	The size, in pixels, of major, minor and end ticks. Default value: derived from axis config’s `tickSize` (`6` by default).
tickSizeMajor	Number	The size, in pixels, of major ticks.
tickSizeMinor	Number	The size, in pixels, of minor ticks.
tickSizeEnd	Number	The size, in pixels, of end ticks.
tickWidth	Number	The width, in pixels, of ticks.
values	Number[] \| DateTime[]	Explicitly set the visible axis tick values.

Title

Property	Type	Description
title	String	A title for the axis. Default value: derived from the field’s name and transformation function applied e.g, “field_name”, “SUM(field_name)”, “BIN(field_name)”, “YEAR(field_name)”.
titleColor	String	The color of the title.
titleFont	String	The font of title (e.g., `Helvetica Neue`).
titleFontWeight	Number	The font weight of title (e.g., `bold`).
titleFontSize	Number	The font size of title, in pixels. Default value: 10.
titleOffset	Number	The offset (in pixels) from the axis at which to place the title.
titleMaxLength	Integer	Max length for axis title when the title is automatically generated from the field's description. Default value: automatically determined based on the cell size (`config.cell.width`, `config.cell.height`) and `characterWidth` property.
characterWidth	Integer	Character width for automatically determining the value of `titleMaxLength`. Default value: derived from axis config’s `characterWidth` (`6` by default).