Axes

Wiki ▸ Documentation ▸ Axes

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

• type - [String] The type of axis. One of x or y.
• scale - [String] 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).
• format - [String] The formatting pattern for axis labels. Vega uses D3's format pattern.
• ticks - [Number] A desired number of ticks. 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).
• 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] The offset, in pixels, by which to displace the axis from the edge of the enclosing group or data rectangle.
• 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).

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, labels 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.

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

"axes": [
   {
     "type": "x",
     "scale": "x",
     "properties": {
       "ticks": {
         "stroke": {"value": "steelblue"}
       },
       "majorTicks": {
         "strokeWidth": {"value": 2}
       },
       "labels": {
         "fill": {"value": "steelblue"},
         "angle": {"value": 50},
         "fontSize": {"value": 14},
         "align": {"value": "left"},
         "baseline": {"value": "middle"},
         "dx": {"value": 3}
       },
       "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.