This website is for Vega-Lite v3. 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

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "axis": {                // Axis
        ...
      },
      ...
    },
    "y": ...,
    ...
  }
}

To customize axis, you can specify an axis object in an encoding channel’s definition. This section lists all properties of axes.

See also: This interactive article demonstrates axes and legends in the underlying Vega language.

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.

Default value: 0.5
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 towards 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-axes with top or bottom orientation, this sets the axis group x coordinate. For y-axes with left or right orientation, this sets the axis group y coordinate.

Default value: 0
zindex Number

A non-negative integer indicating the 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.

Example: Using Axis minExtent to Align Multi-View Plots

By default, Vega-Lite automatically sets the axis extent (the space axis ticks and labels use). However, to align axes between multiple plots in multi-view displays, you can manually set minExtent (and optionally maxExtent) to make the extent consistent across plots.

Domain

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
domainColor Color

Color of axis domain line.

Default value: "gray".
domainOpacity Number

Opacity of the axis domain line.
domainWidth Number

Stroke width of axis domain line

Default value: 1

Labels

Property Type Description
format String

The text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.
formatType String

The format type for labels ("number" or "time").

Default value:

  • "time" for temporal fields and ordinal and nomimal fields with timeUnit.
  • "number" for quantitative fields as well as ordinal and nomimal fields without timeUnit.
labels Boolean

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

Default value: true.
labelAlign String

Horizontal text alignment of axis tick labels, overriding the default setting for the current axis orientation.
labelAngle Number

The rotation angle of the axis labels.

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

Vertical text baseline of axis tick labels, overriding the default setting for the current axis orientation. Can be "top", "middle", "bottom", or "alphabetic".
labelBound Number | Boolean

Indicates if labels should be hidden if they exceed the axis range. If false (the default) no bounds overlap analysis is performed. If true, labels will be hidden if they exceed the axis range by more than 1 pixel. If this property is a number, it specifies the pixel tolerance: the maximum amount by which a label bounding box may exceed the axis range.

Default value: false.
labelColor Color

The color of the tick label, can be in hex color code or regular color name.
labelFlush Boolean | Number

Indicates if the first and last axis labels should be aligned flush with the scale range. Flush alignment for a horizontal axis will left-align the first label and right-align the last label. For vertical axes, bottom and top text baselines are applied instead. If this property is a number, it also indicates the number of pixels by which to offset the first and last labels; for example, a value of 2 will flush-align the first and last labels and also push them 2 pixels outward from the center of the axis. The additional adjustment can sometimes help the labels better visually group with corresponding axis ticks.

Default value: true for axis of a continuous x-scale. Otherwise, false.
labelFlushOffset Number

Indicates the number of pixels by which to offset flush-adjusted labels. For example, a value of 2 will push flush-adjusted labels 2 pixels outward from the center of the axis. Offsets can help the labels better visually group with corresponding axis ticks.

Default value: 0.
labelFont String

The font of the tick label.
labelFontSize Number

The font size of the label, in pixels.
labelFontStyle FontStyle

Font style of the title.
labelFontWeight String | Number

Font weight of axis tick labels.
labelLimit Number

Maximum allowed pixel width of axis tick labels.

Default value: 180
labelOpacity Number

The opacity of the labels.
labelOverlap 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.

Default value: 2

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

Ticks

Property Type Description
tickColor Color

The color of the axis’s tick.

Default value: "gray"
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.
tickExtra Boolean

Boolean flag indicating if an extra axis tick should be added for the initial position of the axis. This flag is useful for styling axes for band scales such that ticks are placed on band boundaries rather in the middle of a band. Use in conjunction with "bandPosition": 1 and an axis "padding" value of 0.
tickOffset Number

Position offset in pixels to apply to ticks, labels, and gridlines.
tickOpacity Number

Opacity of the ticks.
tickRound Boolean

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

Default value: true
ticks Boolean

Boolean value that determines whether the axis should include ticks.

Default value: true
tickSize Number

The size in pixels of axis ticks.

Default value: 5
tickWidth Number

The width, in pixels, of ticks.

Default value: 1
values Number[] | String[] | Boolean[] | DateTime[]

Explicitly set the visible axis tick values.

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.
titleAlign String

Horizontal text alignment of axis titles.
titleAnchor TitleAnchor

Text anchor position for placing axis titles.
titleAngle Number

Angle in degrees of axis titles.
titleBaseline String

Vertical text baseline for axis titles.
titleColor Color

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

Font of the title. (e.g., "Helvetica Neue").
titleFontSize Number

Font size of the title.
titleFontStyle FontStyle

Font style of the title.
titleFontWeight String | Number

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).
titleLimit Number

Maximum allowed pixel width of axis titles.
titleOpacity Number

Opacity of the axis title.
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.

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).

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 Color

Color of gridlines.

Default value: "lightGray".
gridDash Number[]

An array of alternating [stroke, space] lengths for dashed grid lines.
gridOpacity Number

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

Default value: 1
gridWidth Number

The grid width, in pixels.

Default value: 1

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.

An axis configuration supports all axis properties except position, orient, format, tickCount, values, and zindex.

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).