Vega-Lite View Specification

Edit this page

Vega-Lite specifications are JSON objects that describe a diverse range of interactive visualizations. The simplest form of specification is a specification of a single view, which describes a view that uses a single mark type to visualize the data. Besides using a single view specification as a standalone visualization, Vega-Lite also provides operators for composing multiple view specifications into a layered or multi-view specification. These operators include layer, facet, concat, and repeat.

Documentation Overview

Common Properties of Specifications

All view specifications in Vega-Lite can contain the following properties:

Property Type Description
name String

Name of the visualization for later reference.
description String

Description of this mark for commenting purpose.
title Text | TitleParams

Title for the plot.
data Data | Null

Required. An object describing the data source. Set to null to ignore the parent’s data source. If no data is set, it is derived from the parent.
transform Transform[]

An array of data transformations such as filter and new field calculation.
params TopLevelParameter[]

An array of parameters that may either be simple variables, or more complex selections that map user input to data queries.

In addition, all view composition specifications (layer, facet, concat, and repeat) can have the resolve property for scale, axes, and legend resolution:

Property Type Description
resolve Resolve

Scale, axis, and legend resolutions for view composition specifications.

Finally, all view layout composition (facet, concat, and repeat) can have the following layout properties:

Property Type Description
align String | Object

The alignment to apply to grid rows and columns. The supported string values are "all", "each", and "none".

  • For "none", a flow layout will be used, in which adjacent subviews are simply placed one after the other.
  • For "each", subviews will be aligned into a clean grid structure, but each row or column may be of variable size.
  • For "all", subviews will be aligned and each row or column will be sized identically based on the maximum observed size. String values for this property will be applied to both grid rows and columns.

Alternatively, an object value of the form {"row": string, "column": string} can be used to supply different alignments for rows and columns.

Default value: "all".
bounds String

The bounds calculation method to use for determining the extent of a sub-plot. One of full (the default) or flush.

  • If set to full, the entire calculated bounds (including axes, title, and legend) will be used.
  • If set to flush, only the specified width and height values for the sub-view will be used. The flush setting can be useful when attempting to place sub-plots without axes or legends into a uniform grid structure.

Default value: "full"
center Boolean | Object

Boolean flag indicating if subviews should be centered relative to their respective rows or columns.

An object value of the form {"row": boolean, "column": boolean} can be used to supply different centering values for rows and columns.

Default value: false
spacing Number | Object

The spacing in pixels between sub-views of the composition operator. An object of the form {"row": number, "column": number} can be used to set different spacing values for rows and columns.

Default value: Depends on "spacing" property of the view composition configuration (20 by default)

Top-Level Specifications

In addition to the common properties, any kind of top-level specifications (including a standalone single view specification as well as layered and multi-view specifications) can contain the following properties:

Property Type Description
$schema String

URL to JSON schema for a Vega-Lite specification. Unless you have a reason to change this, use https://vega.github.io/schema/vega-lite/v5.json. Setting the $schema property allows automatic validation and autocomplete in editors that support JSON schema.
background Color | ExprRef

CSS color property to use as the background of the entire view.

Default value: "white"
padding Number | Object | ExprRef

The default visualization padding, in pixels, from the edge of the visualization canvas to the data rectangle. If a number, specifies padding for all sides. If an object, the value should have the format {"left": 5, "top": 5, "right": 5, "bottom": 5} to specify padding for each side of the visualization.

Default value: 5
autosize String | AutoSizeParams

How the visualization size should be determined. If a string, should be one of "pad", "fit" or "none". Object values can additionally specify parameters for content sizing and automatic resizing.

Default value: pad
config Config

Vega-Lite configuration object. This property can only be defined at the top-level of a specification.
usermeta Object

Optional metadata that will be passed to Vega. This object is completely ignored by Vega and Vega-Lite and can be used for custom metadata.

Single View Specifications

{
  // Properties for top-level specification (e.g., standalone single view specifications)
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "background": ...,
  "padding": ...,
  "autosize": ...,
  "config": ...,
  "usermeta": ...,

  // Properties for any specifications
  "title": ...,
  "name": ...,
  "description": ...,
  "data": ...,
  "transform": ...,

  // Properties for any single view specifications
  "width": ...,
  "height": ...,
  "mark": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      ...
    },
    "y": ...,
    "color": ...,
    ...
  }
}

A single view specification describes a graphical mark type (e.g., points or bars) and its encoding, or the mapping between data values and properties of the mark. By simply providing the mark type and the encoding mapping, Vega-Lite automatically produces other visualization components including axes, legends, and scales. Unless explicitly specified, Vega-Lite determines properties of these components based on a set of carefully designed rules. This approach allows Vega-Lite specifications to be succinct and expressive, but also enables customization.

As it is designed for analysis, Vega-Lite also supports data transformation such as aggregation, binning, time unit conversion, filtering, and sorting.

To summarize, a single-view specification in Vega-Lite can have the following properties (in addition to common properties of a specification):

Property Type Description
mark Mark

Required. A string describing the mark type (one of "bar", "circle", "square", "tick", "line", "area", "point", "rule", "geoshape", and "text") or a mark definition object.
encoding Encoding

A key-value mapping between encoding channels and definition of fields.
width Number | String | Object

The width of a visualization.

  • For a plot with a continuous x-field, width should be a number.
  • For a plot with either a discrete x-field or no x-field, width can be either a number indicating a fixed width or an object in the form of {step: number} defining the width per discrete step. (No x-field is equivalent to having one discrete step.)
  • To enable responsive sizing on width, it should be set to "container".

Default value: Based on config.view.continuousWidth for a plot with a continuous x-field and config.view.discreteWidth otherwise.

Note: For plots with row and column channels, this represents the width of a single view and the "container" option cannot be used.

See also: width documentation.
height Number | String | Object

The height of a visualization.

  • For a plot with a continuous y-field, height should be a number.
  • For a plot with either a discrete y-field or no y-field, height can be either a number indicating a fixed height or an object in the form of {step: number} defining the height per discrete step. (No y-field is equivalent to having one discrete step.)
  • To enable responsive sizing on height, it should be set to "container".

Default value: Based on config.view.continuousHeight for a plot with a continuous y-field and config.view.discreteHeight otherwise.

Note: For plots with row and column channels, this represents the height of a single view and the "container" option cannot be used.

See also: height documentation.
view ViewBackground

An object defining the view background’s fill and stroke.

Default value: none (transparent)
projection Projection

An object defining properties of geographic projection, which will be applied to shape path for "geoshape" marks and to latitude and "longitude" channels for other marks.

View Background

The background property of a top-level view specification defines the background of the whole visualization canvas. Meanwhile, the view property of a single-view or layer specification can define the background of the view with the following properties:

Property Type Description
style String | String[]

A string or array of strings indicating the name of custom styles to apply to the view background. A style is a named collection of mark property defaults defined within the style configuration. If style is an array, later styles will override earlier styles.

Default value: "cell" Note: Any specified view background properties will augment the default style.
cornerRadius Number | ExprRef

The radius in pixels of rounded rectangles or arcs’ corners.

Default value: 0
cursor String

The mouse cursor used over the view. Any valid CSS cursor type can be used.
fill Color | Null | ExprRef

The fill color.

Default value: undefined
fillOpacity Number | ExprRef

The fill opacity (value between [0,1]).

Default value: 1
opacity Number | ExprRef

The overall opacity (value between [0,1]).

Default value: 0.7 for non-aggregate plots with point, tick, circle, or square marks or layered bar charts and 1 otherwise.
stroke Color | Null | ExprRef

The stroke color.

Default value: "#ddd"
strokeCap String | ExprRef

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

Default value: "butt"
strokeDash Number[] | ExprRef

An array of alternating stroke, space lengths for creating dashed or dotted lines.
strokeDashOffset Number | ExprRef

The offset (in pixels) into which to begin drawing with the stroke dash array.
strokeJoin String | ExprRef

The stroke line join method. One of "miter", "round" or "bevel".

Default value: "miter"
strokeMiterLimit Number | ExprRef

The miter limit at which to bevel a line join.
strokeOpacity Number | ExprRef

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

Default value: 1
strokeWidth Number | ExprRef

The stroke width, in pixels.

Example: Background

For example, the following plot has orange as the whole visualization background color while setting the view background to yellow.

Layered and Multi-view Specifications

To create layered and multi-view graphics, please refer to the following pages:

View Configuration

// Top-level View Specification
{
  ...,
  "config": { // Configuration Object

    "view": { // - View Configuration

      // View Size
      "continuousWidth": ...,
      "continuousHeight": ...,
      "discreteWidth": ...,
      "discreteHeight": ...,
      // View Background Properties
      "fill": ...,
      "stroke": ...,
      ...
    },
    ...
  }
}

The style of a single view visualization can be customized by specifying the view property of the config object. The view config support all view background properties except "style".

In addition, the following properties of the view configuration determine the default width and height of single and layered views.

Property Type Description
continuousWidth Number

The default width when the plot has a continuous field for x or longitude, or has arc marks.

Default value: 200
continuousHeight Number

The default height when the plot has a continuous y-field for x or latitude, or has arc marks.

Default value: 200
discreteWidth Number | Object

The default width when the plot has non-arc marks and either a discrete x-field or no x-field. The width can be either a number indicating a fixed width or an object in the form of {step: number} defining the width per discrete step.

Default value: a step size based on config.view.step.
discreteHeight Number | Object

The default height when the plot has non arc marks and either a discrete y-field or no y-field. The height can be either a number indicating a fixed height or an object in the form of {step: number} defining the height per discrete step.

Default value: a step size based on config.view.step.
step Number

Default step size for x-/y- discrete fields.

For example, setting the step property in the view config can adjust default discrete step in the plot.

For more information about view size, please see the size documentation.