Vega-Lite View Specification

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
 Top-Level Specifications
 Single View Specifications
 Layered and Multi-view Specifications
 View Configuration
o Default View Size
o View Styles

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.
String |
title Title for the plot.
TitleParams
data Data An object describing the data source
An array of data transformations such as filter and
transform Transform[]
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
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 .
$schema String
Setting the $schema property allows automatic
validation and autocomplete in editors that support
JSON schema.
CSS color property to use as the background of
visualization.
background String
Default value: none (transparent)
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
padding Number | Object
{"left": 5, "top": 5, "right": 5, "bottom": 5} to
specify padding for each side of the visualization.

Default value: 5
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
String | content sizing and automatic resizing. "fit" is only
autosize
AutoSizeParams supported for single and layered views that don’t use
rangeStep .

Default value: pad

Vega-Lite configuration object. This property can only
config Config
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., point s or bar s) 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

The width of a visualization.

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

 If a view’s autosize type is "fit" or its x-channel has a

continuous scale, the width will be the value of
config.view.width .
 For x-axis with a band or point scale: if rangeStep is a
numeric value or unspecified, the width is determined
by the range step, paddings, and the cardinality of the
width Number field mapped to x-channel. Otherwise, if the rangeStep
is null , the width will be the value of
config.view.width .
 If no field is mapped to x channel, the width will be the
value of config.scale.textXRangeStep for text mark
and the value of rangeStep for other marks.

Note: For plots with row and column channels, this represents
the width of a single view.
Property Type Description
See also: The documentation for width and height contains
more examples.
The height of a visualization.

Default value:

 If a view’s autosize type is "fit" or its y-channel has a

continuous scale, the height will be the value of
config.view.height .
 For y-axis with a band or point scale: if rangeStep is a
numeric value or unspecified, the height is determined
by the range step, paddings, and the cardinality of the
height Number field mapped to y-channel. Otherwise, if the rangeStep
is null , the height will be the value of
config.view.height .
 If no field is mapped to y channel, the height will be the
value of rangeStep .

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.
A key-value mapping between selection names and
selection Selection{}
definitions.
Required. A string describing the mark type (one of "bar" ,
mark Mark "circle" , "square" , "tick" , "line" , "area" , "point" , "rule" ,
and "text" ) or a mark definition object.
Required. A key-value mapping between encoding channels
encoding Encoding
and definition of fields.

Layered and Multi-view Specifications

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

 layer
 facet
 concat
 repeat

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

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
width Number ordinal x-scale with rangeStep = null .

Default value: 200

The default height of the single plot or each plot in a trellis plot
when the visualization has a continuous (non-ordinal) y-scale
height Number 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.
The fill color.
fill String
Default value: (none)
The fill opacity (value between [0,1]).
fillOpacity Number
Default value: (none)
The stroke color.
stroke String
Default value: (none)
The stroke opacity (value between [0,1]).
strokeOpacity Number
Default value: (none)
 Property Type Description
The stroke width, in pixels.
strokeWidth Number
Default value: (none)
An array of alternating stroke, space lengths for creating
dashed or dotted lines.
strokeDash Number[]
Default value: (none)
The offset (in pixels) into which to begin drawing with
the stroke dash array.
strokeDashOffset Number
Default value: (none)