This website is for Vega-Lite v3. Go to the main Vega-Lite homepage for the latest release.

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

In addition, all view composition specifications (layer, facet, concat, and repeat) and unit specifications with facet channels can have the following composition layout and resolution properties:

Property Type Description
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 | RowCol

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 | RowCol

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)
resolve Resolve

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

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/v3.json. Setting the $schema property allows automatic validation and autocomplete in editors that support JSON schema.
background String

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

Default value: none (transparent)
padding Number | Object

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

Sets 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. "fit" is only supported for single and layered views that don’t use rangeStep.

Default value: pad
config Config

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

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/v3.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 FacetedEncoding

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

The width of a visualization.

Default value: This will be determined by the following rules:

Note: For plots with row and column channels, this represents the width of a single view.

See also: The documentation for width and height contains more examples.
height Number

The height of a visualization.

Default value:

Note: For plots with row and column channels, this represents the height of a single view.

See also: The documentation for width and height contains more examples.
view spec.html#view-background

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

Default value: none (transparent)
selection Selection{}

A key-value mapping between selection names and definitions.
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

The radius in pixels of rounded rectangle corners.

Default value: 0
fill Color | Null

The fill color.

Default value: undefined
fillOpacity Number

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

Default value: 1
opacity Number

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

The stroke color.

Default value: "#ddd"
strokeCap String

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

Default value: "square"
strokeDash Number[]

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

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

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

Default value: "miter"
strokeMiterLimit Number

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

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

Default value: 1
strokeWidth Number

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
      "width": ...,
      "height": ...,
      // 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 width and height properties of the view configuration determine the width of a single view with a continuous x-scale and the height of a single view with a continuous y-scale respectively.

Property Type Description
width Number

The default width of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) x-scale or ordinal x-scale with rangeStep = null.

Default value: 200
height Number

The default height of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) y-scale with rangeStep = null.

Default value: 200

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