Axis¶

Axes explain how positional channels such as x and y map data values to positions. GenomeSpy creates axes automatically for positional field and expression encodings.

Configuration¶

Axis properties are usually placed in the encoding channel that creates the axis:

{
  "encoding": {
    "x": {
      "field": "position",
      "type": "quantitative",
      "axis": {
        "title": "Position",
        "grid": true
      }
    }
  }
}

In composed views, view-level axes.<channel> can provide a shared location for axis properties when the subtree has a unique axis resolution for that channel. See Resolution.

Set axis to null on a channel to remove the corresponding axis. In a shared axis resolution, this removes the shared axis.

Remove one axis

{
  "encoding": {
    "x": {
      "field": "position",
      "type": "quantitative",
      "axis": null
    }
  }
}

Placement¶

The orient property controls the side of the plot where the axis is placed. The default orientation is "bottom" for x axes and "left" for y axes.

Supported orientations:

top
bottom
left
right

Axes are placed outside the plotting area by default. Set placement to "inside" to draw an axis into the plot area instead. An inside axis is mirrored into the plot: for example, a left-oriented y axis keeps its domain line at the left plot edge, while ticks and labels extend rightward over the plotted data.

Inside axes do not reserve external layout space and render above marks by default. Use zindex to override that layering.

{
  "description": "Inside axis placement example.",

  "data": { "sequence": { "start": 0, "stop": 101, "step": 1, "as": "x" } },

  "transform": [{ "type": "formula", "expr": "sin(datum.x / 8)", "as": "y" }],

  "mark": "point",

  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative",
      "axis": {
        "offset": 10
      }
    },
    "y": {
      "field": "y",
      "type": "quantitative",
      "axis": {
        "placement": "inside",
        "orient": "left",
        "grid": true,
        "gridDash": [2, 4],
        "title": "sin(x / 8)"
      }
    }
  }
}

Titles¶

Axis titles default to the encoding title. If no encoding title is specified, GenomeSpy uses the encoded field name or expression. Shared axes concatenate the unique participant titles.

Set axis.title to override the generated title, or to null to remove it.

{
  "axis": {
    "title": "Copy number",
    "titlePadding": 8
  }
}

Set titleFit to "range" to constrain the axis title to the axis span. Ranged titles are squeezed when space is scarce and stay visible longer inside scrollable viewports, but cannot extend outside the axis span.

Ticks, Labels, and Grid Lines¶

Use tickCount to set the desired number of ticks on quantitative axes. The actual number may differ when GenomeSpy chooses nice tick values. tickCount can also be an expression reference. In tick-count expressions, axisLength is the current length of the axis in pixels. Use tickMinStep to set the minimum step between ticks in domain units.

Use values to set explicit tick and label values. Use format to format numeric labels with a d3-format specifier.

Set ticks or labels to false to hide tick marks or labels while keeping the rest of the axis.

Grid lines are hidden by default in the default theme. Set grid to true to show grid lines for an axis. Global grid defaults can be configured with config.axis*.

Resolution¶

Axes participate in view resolution similarly to scales and legends. Use resolve.axis in composed views to choose whether child views share one axis or create independent axes.

Shared axis resolution requires the corresponding scale resolution to be shared. Axis domain line, ticks, and labels are drawn once for each shared row or column. Grid lines are drawn for all participating views.

{
  "resolve": {
    "scale": { "x": "shared" },
    "axis": { "x": "shared" }
  }
}

For shared axis resolutions, axis properties can also be placed at the view level with axes.<channel>:

View-level axis configuration

{
  "axes": {
    "x": {
      "orient": "bottom",
      "grid": true
    }
  },
  "layer": [
    ...
  ]
}

A view-level axis config must map to one axis resolution. If the subtree has multiple independent axes for the same channel, place the config closer to the intended subtree or use local encoding.<channel>.axis settings. Do not mix view-level axes.<channel> with participating channel-level axis config for the same resolved axis.

Genome Axis for Loci¶

The genome axis is a special axis for the "locus" scale. It displays chromosome names and intra-chromosomal coordinates. Chromosome ticks, labels, grid lines, and alternating chromosome fills can be styled with chrom* properties.

{
  "description": "Genome axis styling example for locus scales.",

  "assembly": "hg38",

  "data": { "values": [] },

  "mark": "point",

  "encoding": {
    "x": {
      "chrom": "a",
      "pos": "b",
      "type": "locus",
      "axis": {
        "chromTickColor": "#5F87F5",
        "chromLabelColor": "#E16B67",
        "grid": true,
        "gridColor": "gray",
        "gridOpacity": 0.5,
        "gridDash": [1, 11],
        "chromGrid": true,
        "chromGridDash": [3, 3],
        "chromGridColor": "#5F87F5",
        "chromGridOpacity": 0.7,
        "chromGridFillEven": "#BEFACC",
        "chromGridFillOdd": "#FDFCE8"
      }
    }
  }
}

Custom Axes¶

The "axisTicks" data source provides tick values and labels for a channel. It can be used to build custom axes or custom axis-aligned annotations.

The "axisGenome" data source provides the chromosomes and their sizes for a locus channel. It can be used to build custom chromosome ticks, bands, or grids.

Properties¶

domain

Type: boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true

domainCap

Type: string

The stroke cap for the domain line's ending style. One of "butt", "round" or "square".

Default value: "butt"

domainColor

Type: string

Color of axis domain line.

Default value: "gray".

domainDash

Type: array

An array of alternating [stroke, space] lengths for dashed domain lines.

domainDashOffset

Type: number

The pixel offset at which to start drawing with the domain dash array.

domainWidth

Type: number

Stroke width of axis domain line

Default value: 1

format

Type: string

The format specifier pattern for axis labels. Must be a legal d3-format specifier.

grid

Type: boolean

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

Default value: false

gridCap

Type: string

The stroke cap for the grid line's ending style. One of "butt", "round" or "square".

Default value: "butt"

gridColor

Type: string

Color of grid lines.

Default value: lightgray

gridDash

Type: array

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

gridDashOffset

Type: number

The pixel offset at which to start drawing with the grid mark dash array.

gridOpacity

Type: number

The opacity of the grid lines.

Default value: 1

gridWidth

Type: number

Width of the grid lines.

Default value: 1

labelAlign

Type: "left" | "center" | "right"

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

labelAngle

Type: number

The rotation angle of the axis labels.

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

labelBaseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Vertical text baseline of axis tick labels, overriding the default setting for the current axis orientation. One of "alphabetic" (default), "top", "middle", "bottom".

labelColor

Type: string

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

labelFont

Type: string

The font of the tick label.

labelFontSize

Type: number

The font size of the label, in pixels.

labelFontStyle

Type: "normal" | "italic"

Font style of the title.

labelFontWeight

Font weight of axis tick labels.

labelLimit

Type: number

Maximum allowed pixel width of axis tick labels.

Default value: 180

labelPadding

Type: number

The padding, in pixels, between axis and text labels.

Default value: 2

labels

Type: boolean

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

Default value: true.

maxExtent

Type: 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

Type: 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.

offset

Type: number

The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.

orient

Type: "top" | "bottom" | "left" | "right"

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

Default value: "bottom" for x-axes and "left" for y-axes.

placement

Type: "outside" | "inside"

Placement of the axis relative to the plotting area. Outside axes reserve layout space outside the plot. Inside axes are mirrored into the plot and do not reserve external layout space.

Default value: "outside".

style

Type: string | string[] | null

Named style reference(s) resolved from config.style. If an array is provided, later styles override earlier ones. Set to null to reset inherited axis styles.

tickCap

Type: string

The stroke cap for the tick lines' ending style. One of "butt", "round" or "square".

Default value: "butt"

tickColor

Type: string

The color of the axis's tick.

Default value: "gray"

tickCount

Type: number | ExprRef

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.

An expression reference can use axisLength for the current length of the axis in pixels. For example, { "expr": "ceil(axisLength / 40)" } requests one tick per 40 pixels.

Default value: an expression based on axisLength

tickDash

Type: array

An array of alternating [stroke, space] lengths for dashed tick mark lines.

tickDashOffset

Type: number

The pixel offset at which to start drawing with the tick mark dash array.

tickMinStep

Type: number

The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If tickMinStep is specified, the tickCount value will be adjusted, if necessary, to enforce the minimum step value.

tickSize

Type: number

The size in pixels of axis ticks.

Default value: 5

tickWidth

Type: number

The width, in pixels, of ticks.

Default value: 1

ticks

Type: boolean

Boolean value that determines whether the axis should include ticks.

Default value: true

title

Type: string | null

A title for the axis. By default, the title is derived from the encoding title, field, or expression. Set to null to remove it.

titleColor

Type: string

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

titleFit

Type: string

Fitting mode for the axis title. "point" anchors the title at the center of the axis without constraining its length. "range" constrains the title to the axis span using ranged text, allowing it to be squeezed to fit and kept visible inside scrollable viewports.

Default value: "point"

titleFont

Type: string

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

titleFontSize

Type: number

Font size of the title.

titleFontStyle

Type: "normal" | "italic"

Font style of the title.

titleFontWeight

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

titleOpacity

Type: number

Opacity of the axis title.

titlePadding

Type: number

The padding, in pixels, between title and axis.

values

Type: array

Explicitly set the visible axis tick and label values.

zindex

Type: number

Z-order of the axis relative to the view content.

Values greater than 0 render after the view marks. Values less than or equal to 0 render before the marks.

Default value: 0, or 10 when the view content is clipped or scrollable.

Genome Axis Properties¶

chromGrid

Type: boolean

A boolean flag indicating if chromosome grid lines should be included as part of the axis.

Default value: false

chromGridCap

Type: string

The stroke cap for the chromosome grid line's ending style. One of "butt", "round" or "square".

Default value: "butt"

chromGridColor

Type: string

Color of grid lines.

Default value: lightgray

chromGridDash

Type: array

An array of alternating [stroke, space] lengths for dashed chromosome grid mark lines.

chromGridDashOffset

Type: number

The pixel offset at which to start drawing with the chromosome grid mark dash array.

chromGridFillEven

Type: string

Fill color of odd chromosomes.

Default value: (none)

chromGridFillOdd

Type: string

Fill color of odd chromosomes.

Default value: (none)

chromGridOpacity

Type: number

The opacity of the chromosome grid lines.

Default value: 1

chromGridWidth

Type: number

Width of the chromosome grid lines.

Default value: 1

chromLabelAlign

Type: "left" | "center" | "right"

Horizontal text alignment of chromosome name labels.

Default value: "left"

chromLabelColor

Type: string

Text color of chromosome name labels.

Default value: "black"

chromLabelFont

Type: string

The font of chromosome name labels.

chromLabelFontSize

Type: number

Font size of chromosome name labels, in pixels.

Default value: 13

chromLabelFontStyle

Type: "normal" | "italic"

Font style of chromosome name labels.

Default value: "normal"

chromLabelFontWeight

Font weight of chromosome name labels.

Default value: "normal"

chromLabelPadding

Type: number

The padding, in pixels, between chromosome boundary ticks and chromosome name labels.

Default value: 7

chromLabels

Type: boolean

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

Default value: true

chromTickColor

Type: string

The color of chromosome boundary ticks.

Default value: "#989898"

chromTickDash

Type: array

An array of alternating [stroke, space] lengths for dashed chromosome boundary ticks.

Default value: [4, 2]

chromTickDashOffset

Type: number

The pixel offset at which to start drawing with the chromosome tick dash array.

Default value: 1

chromTickSize

Type: number

The size in pixels of chromosome boundary ticks.

Default value: 18

chromTickWidth

Type: number

The width, in pixels, of chromosome boundary ticks.

Default value: 1

chromTicks

Type: boolean

A boolean flag indicating if chromosome boundary ticks should be included as part of the genome axis.

Default value: true

domain

Type: boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true

domainCap

Type: string

The stroke cap for the domain line's ending style. One of "butt", "round" or "square".

Default value: "butt"

domainColor

Type: string

Color of axis domain line.

Default value: "gray".

domainDash

Type: array

An array of alternating [stroke, space] lengths for dashed domain lines.

domainDashOffset

Type: number

The pixel offset at which to start drawing with the domain dash array.

domainWidth

Type: number

Stroke width of axis domain line

Default value: 1

format

Type: string

The format specifier pattern for axis labels. Must be a legal d3-format specifier.

grid

Type: boolean

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

Default value: false

gridCap

Type: string

The stroke cap for the grid line's ending style. One of "butt", "round" or "square".

Default value: "butt"

gridColor

Type: string

Color of grid lines.

Default value: lightgray

gridDash

Type: array

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

gridDashOffset

Type: number

The pixel offset at which to start drawing with the grid mark dash array.

gridOpacity

Type: number

The opacity of the grid lines.

Default value: 1

gridWidth

Type: number

Width of the grid lines.

Default value: 1

labelAlign

Type: "left" | "center" | "right"

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

labelAngle

Type: number

The rotation angle of the axis labels.

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

labelBaseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Vertical text baseline of axis tick labels, overriding the default setting for the current axis orientation. One of "alphabetic" (default), "top", "middle", "bottom".

labelColor

Type: string

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

labelFont

Type: string

The font of the tick label.

labelFontSize

Type: number

The font size of the label, in pixels.

labelFontStyle

Type: "normal" | "italic"

Font style of the title.

labelFontWeight

Font weight of axis tick labels.

labelLimit

Type: number

Maximum allowed pixel width of axis tick labels.

Default value: 180

labelPadding

Type: number

The padding, in pixels, between axis and text labels.

Default value: 2

labels

Type: boolean

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

Default value: true.

maxExtent

Type: 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

Type: 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.

offset

Type: number

The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.

orient

Type: "top" | "bottom" | "left" | "right"

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

Default value: "bottom" for x-axes and "left" for y-axes.

placement

Type: "outside" | "inside"

Placement of the axis relative to the plotting area. Outside axes reserve layout space outside the plot. Inside axes are mirrored into the plot and do not reserve external layout space.

Default value: "outside".

style

Type: string | string[] | null

Named style reference(s) resolved from config.style. If an array is provided, later styles override earlier ones. Set to null to reset inherited axis styles.

tickCap

Type: string

The stroke cap for the tick lines' ending style. One of "butt", "round" or "square".

Default value: "butt"

tickColor

Type: string

The color of the axis's tick.

Default value: "gray"

tickCount

Type: number | ExprRef

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.

An expression reference can use axisLength for the current length of the axis in pixels. For example, { "expr": "ceil(axisLength / 40)" } requests one tick per 40 pixels.

Default value: an expression based on axisLength

tickDash

Type: array

An array of alternating [stroke, space] lengths for dashed tick mark lines.

tickDashOffset

Type: number

The pixel offset at which to start drawing with the tick mark dash array.

tickMinStep

Type: number

The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If tickMinStep is specified, the tickCount value will be adjusted, if necessary, to enforce the minimum step value.

tickSize

Type: number

The size in pixels of axis ticks.

Default value: 5

tickWidth

Type: number

The width, in pixels, of ticks.

Default value: 1

ticks

Type: boolean

Boolean value that determines whether the axis should include ticks.

Default value: true

title

Type: string | null

A title for the axis. By default, the title is derived from the encoding title, field, or expression. Set to null to remove it.

titleColor

Type: string

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

titleFit

Type: string

Fitting mode for the axis title. "point" anchors the title at the center of the axis without constraining its length. "range" constrains the title to the axis span using ranged text, allowing it to be squeezed to fit and kept visible inside scrollable viewports.

Default value: "point"

titleFont

Type: string

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

titleFontSize

Type: number

Font size of the title.

titleFontStyle

Type: "normal" | "italic"

Font style of the title.

titleFontWeight

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

titleOpacity

Type: number

Opacity of the axis title.

titlePadding

Type: number

The padding, in pixels, between title and axis.

values

Type: array

Explicitly set the visible axis tick and label values.

zindex

Type: number

Z-order of the axis relative to the view content.

Values greater than 0 render after the view marks. Values less than or equal to 0 render before the marks.

Default value: 0, or 10 when the view content is clipped or scrollable.

Styling¶

Axis defaults can be configured with config.axis. More specific config buckets such as config.axisX, config.axisY, config.axisTop, config.axisBottom, config.axisLeft, config.axisRight, config.axisQuantitative, config.axisIndex, and config.axisLocus refine those defaults. A channel-level axis object overrides the configured defaults for that axis.

Named styles from config.style can also be referenced with axis.style.

{
  "config": {
    "axis": {
      "domainColor": "black",
      "tickColor": "black",
      "labelFontSize": 11,
      "titleFontSize": 12
    },
    "axisQuantitative": {
      "grid": true,
      "gridColor": "#ddd"
    }
  }
}

Config Properties¶

chromGrid

Type: boolean

A boolean flag indicating if chromosome grid lines should be included as part of the axis.

Default value: false

chromGridCap

Type: string

The stroke cap for the chromosome grid line's ending style. One of "butt", "round" or "square".

Default value: "butt"

chromGridColor

Type: string

Color of grid lines.

Default value: lightgray

chromGridDash

Type: array

An array of alternating [stroke, space] lengths for dashed chromosome grid mark lines.

chromGridDashOffset

Type: number

The pixel offset at which to start drawing with the chromosome grid mark dash array.

chromGridFillEven

Type: string

Fill color of odd chromosomes.

Default value: (none)

chromGridFillOdd

Type: string

Fill color of odd chromosomes.

Default value: (none)

chromGridOpacity

Type: number

The opacity of the chromosome grid lines.

Default value: 1

chromGridWidth

Type: number

Width of the chromosome grid lines.

Default value: 1

chromLabelAlign

Type: "left" | "center" | "right"

Horizontal text alignment of chromosome name labels.

Default value: "left"

chromLabelColor

Type: string

Text color of chromosome name labels.

Default value: "black"

chromLabelFont

Type: string

The font of chromosome name labels.

chromLabelFontSize

Type: number

Font size of chromosome name labels, in pixels.

Default value: 13

chromLabelFontStyle

Type: "normal" | "italic"

Font style of chromosome name labels.

Default value: "normal"

chromLabelFontWeight

Font weight of chromosome name labels.

Default value: "normal"

chromLabelPadding

Type: number

The padding, in pixels, between chromosome boundary ticks and chromosome name labels.

Default value: 7

chromLabels

Type: boolean

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

Default value: true

chromTickColor

Type: string

The color of chromosome boundary ticks.

Default value: "#989898"

chromTickDash

Type: array

An array of alternating [stroke, space] lengths for dashed chromosome boundary ticks.

Default value: [4, 2]

chromTickDashOffset

Type: number

The pixel offset at which to start drawing with the chromosome tick dash array.

Default value: 1

chromTickSize

Type: number

The size in pixels of chromosome boundary ticks.

Default value: 18

chromTickWidth

Type: number

The width, in pixels, of chromosome boundary ticks.

Default value: 1

chromTicks

Type: boolean

A boolean flag indicating if chromosome boundary ticks should be included as part of the genome axis.

Default value: true

domain

Type: boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true

domainCap

Type: string

The stroke cap for the domain line's ending style. One of "butt", "round" or "square".

Default value: "butt"

domainColor

Type: string

Color of axis domain line.

Default value: "gray".

domainDash

Type: array

An array of alternating [stroke, space] lengths for dashed domain lines.

domainDashOffset

Type: number

The pixel offset at which to start drawing with the domain dash array.

domainWidth

Type: number

Stroke width of axis domain line

Default value: 1

format

Type: string

The format specifier pattern for axis labels. Must be a legal d3-format specifier.

grid

Type: boolean

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

Default value: false

gridCap

Type: string

The stroke cap for the grid line's ending style. One of "butt", "round" or "square".

Default value: "butt"

gridColor

Type: string

Color of grid lines.

Default value: lightgray

gridDash

Type: array

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

gridDashOffset

Type: number

The pixel offset at which to start drawing with the grid mark dash array.

gridOpacity

Type: number

The opacity of the grid lines.

Default value: 1

gridWidth

Type: number

Width of the grid lines.

Default value: 1

labelAlign

Type: "left" | "center" | "right"

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

labelAngle

Type: number

The rotation angle of the axis labels.

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

labelBaseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Vertical text baseline of axis tick labels, overriding the default setting for the current axis orientation. One of "alphabetic" (default), "top", "middle", "bottom".

labelColor

Type: string

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

labelFont

Type: string

The font of the tick label.

labelFontSize

Type: number

The font size of the label, in pixels.

labelFontStyle

Type: "normal" | "italic"

Font style of the title.

labelFontWeight

Font weight of axis tick labels.

labelLimit

Type: number

Maximum allowed pixel width of axis tick labels.

Default value: 180

labelPadding

Type: number

The padding, in pixels, between axis and text labels.

Default value: 2

labels

Type: boolean

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

Default value: true.

maxExtent

Type: 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

Type: 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.

offset

Type: number

The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.

orient

Type: "top" | "bottom" | "left" | "right"

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

Default value: "bottom" for x-axes and "left" for y-axes.

placement

Type: "outside" | "inside"

Placement of the axis relative to the plotting area. Outside axes reserve layout space outside the plot. Inside axes are mirrored into the plot and do not reserve external layout space.

Default value: "outside".

style

Type: string | string[] | null

Named style reference(s) resolved from config.style. If an array is provided, later styles override earlier ones. Set to null to reset inherited axis styles.

tickCap

Type: string

The stroke cap for the tick lines' ending style. One of "butt", "round" or "square".

Default value: "butt"

tickColor

Type: string

The color of the axis's tick.

Default value: "gray"

tickCount

Type: number | ExprRef

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.

An expression reference can use axisLength for the current length of the axis in pixels. For example, { "expr": "ceil(axisLength / 40)" } requests one tick per 40 pixels.

Default value: an expression based on axisLength

tickDash

Type: array

An array of alternating [stroke, space] lengths for dashed tick mark lines.

tickDashOffset

Type: number

The pixel offset at which to start drawing with the tick mark dash array.

tickMinStep

Type: number

The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If tickMinStep is specified, the tickCount value will be adjusted, if necessary, to enforce the minimum step value.

tickSize

Type: number

The size in pixels of axis ticks.

Default value: 5

tickWidth

Type: number

The width, in pixels, of ticks.

Default value: 1

ticks

Type: boolean

Boolean value that determines whether the axis should include ticks.

Default value: true

title

Type: string | null

A title for the axis. By default, the title is derived from the encoding title, field, or expression. Set to null to remove it.

titleColor

Type: string

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

titleFit

Type: string

Fitting mode for the axis title. "point" anchors the title at the center of the axis without constraining its length. "range" constrains the title to the axis span using ranged text, allowing it to be squeezed to fit and kept visible inside scrollable viewports.

Default value: "point"

titleFont

Type: string

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

titleFontSize

Type: number

Font size of the title.

titleFontStyle

Type: "normal" | "italic"

Font style of the title.

titleFontWeight

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

titleOpacity

Type: number

Opacity of the axis title.

titlePadding

Type: number

The padding, in pixels, between title and axis.

values

Type: array

Explicitly set the visible axis tick and label values.

zindex

Type: number

Z-order of the axis relative to the view content.

Values greater than 0 render after the view marks. Values less than or equal to 0 render before the marks.

Default value: 0, or 10 when the view content is clipped or scrollable.