Axes visualize spatial scale mappings using ticks, grid lines and labels. Vega currently supports axes for Cartesian (rectangular) coordinates. Similar to scales, axes can be defined either at the top-level of the specification, or as part of a group mark.

Axis Properties

Properties for specifying a coordinate axis.

Property Type Description
scale String Required. The name of the scale backing the axis component.
orient String Required. The orientation of the axis. See the axis orientation reference.
domain Boolean A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis (default true).
encode       Object Optional mark encodings for custom axis styling. Supports encoding blocks for axis, ticks, grid, labels, title, and domain. See custom axis encodings.
format String The format specifier pattern for axis labels. For numerical values, must be a legal d3-format specifier. For date-time values, must be a legal d3-time-format specifier.
grid Boolean A boolean flag indicating if grid lines should be included as part of the axis (default false).
gridScale String The name of the scale to use for including grid lines. By default grid lines are driven by the same scale as the ticks and labels.
labels Boolean A boolean flag indicating if labels should be included as part of the axis (default true).
labelBound Boolean | Number 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.
labelFlush Boolean | Number Indicates if labels at the beginning or end of the axis should be aligned flush with the scale range. If a number, indicates a pixel distance threshold: labels with anchor coordinates within the threshold distance for an axis end-point will be flush-adjusted. If true, a default threshold of 1 pixel is used. Flush alignment for a horizontal axis will left-align labels near the beginning of the axis and right-align labels near the end. For vertical axes, bottom and top text baselines will be applied instead.
labelFlushOffset Number Indicates the number of pixels by which to offset flush-adjusted labels (default 0). 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.
labelPadding Number The padding in pixels between labels and ticks.
labelOverlap Boolean | 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).
minExtent Number | Value The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
maxExtent Number | Value The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.
offset Number | Value The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.
position Number | Value The anchor position of the axis in pixels (default 0). 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.
ticks Boolean A boolean flag indicating if ticks should be included as part of the axis (default true).
tickCount Number | String | Object 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. For scales of type time or utc, the tick count can instead be a time interval specifier. Legal string values are "millisecond", "second", "minute", "hour", "day", "week", "month", and "year". Alternatively, an object-valued interval specifier of the form {"interval": "month", "step": 3} includes a desired number of interval steps. Here, ticks are generated for each quarter (Jan, Apr, Jul, Oct) boundary.
tickSize Number The size in pixels of axis ticks.
title String A title for the axis (none by default).
titlePadding Number | Value The offset in pixels between the axis labels and axis title.
values Array Explicitly set the visible axis tick and label values.
zindex Number The integer z-index indicating the layering of the axis group relative to other axis, mark and legend groups. The default value is 0 and axes and grid lines are drawn behind any marks defined in the same specification level. Higher values (1) will cause axes and grid lines to be drawn on top of marks.

To create themes, new default values for many axis properties can be set using a config object.

Axis Orientation Reference

Valid settings for the axis orient parameter.

Value Description
left Place a y-axis along the left edge of the chart.
right Place a y-axis along the right edge of the chart.
top Place an x-axis along the top edge of the chart.
bottom Place an x-axis along the bottom edge of the chart.

Custom Axis Encodings

Custom mark properties can be set for all axis elements using the encode parameter. The addressable elements are:

  • axis for the axis group mark,
  • ticks for tick rule marks,
  • grid for gridline rule marks,
  • labels for label text marks,
  • title for the title text mark, and
  • domain for the axis domain rule mark.

Each element accepts a set of visual encoding directives grouped into enter, update, exit, etc. objects as described in the Marks documentation. Mark properties can be styled using standard value references.

In addition, each encode block may include a string-valued name property to assign a unique name to the mark set, a boolean-valued interactive property to enable input event handling, and a string-valued (or array-valued) style property to apply default property values. Unless otherwise specified, title elements use a default style of "guide-title" and labels elements use a default style of "guide-label".

Each axis tick, grid line, and label instance is backed by a data object with the following fields, which may be accessed as part of a custom visual encoding rule.

  • label - the string label
  • value - the data value

The following example shows how to set custom colors, thickness, text angle, and fonts. The labels encoding block also make legend labels responsive to input events, and changes the text color on mouse hover.

"axes": [
    "orient": "bottom",
    "scale": "x",
    "title": "X-Axis",
    "encode": {
      "ticks": {
        "update": {
          "stroke": {"value": "steelblue"}
      "labels": {
        "interactive": true,
        "update": {
          "text": {"signal": "format(datum.value, '+,')"},
          "fill": {"value": "steelblue"},
          "angle": {"value": 50},
          "fontSize": {"value": 14},
          "align": {"value": "left"},
          "baseline": {"value": "middle"},
          "dx": {"value": 3}
        "hover": {
          "fill": {"value": "firebrick"}
      "title": {
        "update": {
          "fontSize": {"value": 16}
      "domain": {
        "update": {
          "stroke": {"value": "#333"},
          "strokeWidth": {"value": 1.5}

Custom text can be defined using the "text" property for labels. For example, one could define an ordinal scale that serves as a lookup table from axis values to axis label text.