Axes

Yuri Astrakhan edited this page Sep 4, 2017 · 27 revisions

This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.

WikiDocumentationAxes

Axes provide axis lines, ticks and labels to convey how a spatial range represents a data range. Simply put, axes visualize scales. Vega currently supports axes for Cartesian (rectangular) coordinates. Future versions may introduce support for polar (circular) coordinates. Similar to scales, axes can be defined either at the top-level visualization, or as part of a group mark.

Axes provide three types of tick marks: major, minor and end ticks. Minor ticks use smaller lines than major ticks. End ticks appear at the edges of the scales.

Axis Properties

Property Type Description
type String (Required) The type of axis. One of x or y.
scale String (Required) The name of the scale backing the axis component.
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). By default, x axis is placed on the bottom and y axis is placed on the left.
title String A title for the axis (none by default).
titleOffset Number The offset (in pixels) from the axis at which to place the title.
format String The formatting pattern for axis labels. Vega uses D3's format pattern (d3.format if formatType is number and d3.timeFormat if formatType is time or utc).
formatType String Set the type of formatter that should be used. One of time, utc, string, number. For string, the data will be coerced to string type.
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.
values Array Explicitly set the visible axis tick values.
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.
tickPadding Number The padding, in pixels, between ticks and text labels.
tickSize Number The size, in pixels, of major, minor and end ticks.
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.
offset Number | Object If a number, then the value is the offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle. The offset can also be specified as an object with scale and value properties in which scale refers to the name of a scale and value is a value in the domain of the scale. The resulting value will be a number in the range of the scale.
layer String A string indicating if the axis (and any gridlines) should be placed above or below the data marks. One of "front" (default) or "back".
grid Boolean A flag indicate if gridlines should be created in addition to ticks.
properties Object Optional mark property definitions for custom axis styling. The input object can include sub-objects for ticks (both major and minor), majorTicks, minorTicks, labels and axis (for the axis line). These mark property definitions can make value references to their scale domain data via data property like so: {field: "data"}. This is a shorthand for {field: {datum: "data"}}. The template follows suite: {template: "datum.data"}.

Custom Axis Styles

Custom mark properties can be set for all axis elements through the axis properties setting. The addressable elements are ticks (both major and minor), majorTicks, minorTicks, grid (for gridlines), labels, title and axis (for the axis line, including end ticks). Each element can be styled using standard Vega Value References, as described in the Marks documentation.

Note that enclosing ticks at the start and end of the axis are drawn as part of the axis baseline. Custom styling properties for axis will thus affect both the axis line and the end ticks, if shown.

The following example shows how to set custom colors, thickness, text angle, and fonts.

"axes": [
   {
     "type": "x",
     "scale": "x",
     "title": "X-Axis",
     "properties": {
       "ticks": {
         "stroke": {"value": "steelblue"}
       },
       "majorTicks": {
         "strokeWidth": {"value": 2}
       },
       "labels": {
         "text": {"template": "{{datum.data|number:'+,'}}"},
         "fill": {"value": "steelblue"},
         "angle": {"value": 50},
         "fontSize": {"value": 14},
         "align": {"value": "left"},
         "baseline": {"value": "middle"},
         "dx": {"value": 3}
       },
       "title": {
         "fontSize": {"value": 16}
       },
       "axis": {
         "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.