This website is for Vega-Lite v2. 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, 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

Required. An object describing the data source
transform Transform[]

An array of data transformations such as filter and new field calculation.

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/v2.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 visualization.

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.

Single View Specifications

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

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

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

The style of a single view visualization can be customized by specifying the view property of the config object.

Default View Size

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.

View Styles

Property Type Description
clip Boolean

Whether the view should be clipped.
fill String

The fill color.

Default value: (none)
fillOpacity Number

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

Default value: (none)
stroke String

The stroke color.

Default value: (none)
strokeOpacity Number

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

Default value: (none)
strokeWidth Number

The stroke width, in pixels.

Default value: (none)
strokeDash Number[]

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

Default value: (none)
strokeDashOffset Number

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

Default value: (none)