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

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

Single View Specifications

  // Properties for top-level specification (e.g., standalone single view specifications)
  "$schema": "",
  "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

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)