Parameter Types

Edit this page

Reference documentation for common parameter types expected by Vega-Lite specification properties.

Parameter Type Reference

Literal Values

# Any or *

Accepts any literal value, including a string, number, boolean, or null.


# Array or Type[]

Accepts array values. For example: [], [1, 2, 3], ["foo", "bar"]. If individual array items must adhere to a specific type, bracket notation – such as Number[] or String[] – is used to indicate the item type.

In most cases, arrays may also have signal references as items. For example: [{"signal": "width"}, {"signal": "height"}].


# Boolean

Accepts boolean values. For example: true, false.


# Color

Accepts a valid CSS color string. For example: #f304d3, #ccc, rgb(253, 12, 134), steelblue.


# Gradient

Accepts an object that specifies a gradient color pattern.

For example:

{
  "gradient": "linear",
  "stops": [{"offset": 0.0, "color": "red"}, {"offset": 0.5, "color": "white"}, {"offset": 1.0, "color": "blue"}]
}

# Linear Gradient

A linear gradient interpolates colors along a line, from a starting point to an ending point. By default a linear gradient runs horizontally, from left to right. Use the x1, y1, x2, and y2 properties to configure the gradient direction. All coordinates are defined in a normalized [0, 1] coordinate space, relative to the bounding box of the item being colored.

Property Type Description
gradient Any
x1 Any
x2 Any
y1 Any
y2 Any
stops Any

# Radial Gradient

A radial gradient interpolates colors between two circles, from an inner circle boundary to an outer circle boundary. By default a radial gradient runs from the center point of the coordinate system (zero radius inner circle), out to the maximum extent (0.5 radius outer circle). Use the x1, y1, x2, and y2 properties to configure the inner and outer circle center points, and use the r1 and r2 properties to configure the circle radii. All coordinates are defined in a normalized [0, 1] coordinate space, relative to the bounding box of the item being colored. A value of 1 corresponds to the maximum extent of the bounding box (width or height, whichever is larger).

Property Type Description
gradient Any
x1 Any
x2 Any
y1 Any
y2 Any
r1 Any
r2 Any
stops Any

# Gradient Stop

A gradient stop consists of a Color value and an offset progress fraction.

Property Type Description
color Color

Required. The color value at this point in the gradient.

offset Number

Required. The offset fraction for the color stop, indicating its position within the gradient.

Example: Gradient Area Plot

Setting the area plot’s color encoding to "linear" gradient value produces a gradient area plot


# DateTime

A DateTime object (in filter transform, scale domain, and axis/legend values) must have at least one of the following properties:

Property Type Description
year Number

Integer value representing the year.

quarter Number

Integer value representing the quarter of the year (from 1-4).

month Number | String

One of: (1) integer value representing the month from 1-12. 1 represents January; (2) case-insensitive month name (e.g., "January"); (3) case-insensitive, 3-character short month name (e.g., "Jan").

date Number

Integer value representing the date from 1-31.

day Number | String

Value representing the day of a week. This can be one of: (1) integer value – 1 represents Monday; (2) case-insensitive day name (e.g., "Monday"); (3) case-insensitive, 3-character short day name (e.g., "Mon").

Warning: A DateTime definition object with day** should not be combined with year, quarter, month, or date.

hours Number

Integer value representing the hour of a day from 0-23.

minutes Number

Integer value representing the minute segment of time from 0-59.

seconds Number

Integer value representing the second segment (0-59) of a time value

milliseconds Number

Integer value representing the millisecond segment of time.

For example {"year": 2006, "month": "jan", "date": 1} represents Jan 1, 2006.


# Expression

To enable custom calculations, Vega-Lite uses Vega’s expression language for writing basic formulas. Each datum object can be referred using bound variable datum.

Please read the Vega documentation for expressions for details.


# Number

Accepts number values. For example: 1, 3.14, 1e5.


# Object

Accepts object literals. For example: {"left":5, "right":30, "top":5, "bottom":50}. The valid object property names and types will vary across parameters; read the individual parameter descriptions for more information.


# String

Accepts string values. For example: "bold", "step-before", "".


# URL

Accepts a valid URL string linking to external site or resource. For example: "data/stocks.csv", "images/logo.png", "https://vega.github.io/".