Parameter Types

Reference documentation for common parameter types expected by Vega 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.


# Date

A valid JavaScript Date object or timestamp. As JSON does not support date values natively, within a Vega specification a date-time value can be expressed either as a numeric timestamp (the number of milliseconds since the UNIX epoch, as produced by the Date.getTime() method) or using a signal expression (such as {"signal": "datetime(2001, 2, 3)"}).


# Gradient ≥ 5.4

Accepts an object that specifies a gradient color pattern. To define a linear gradient based on a color scale, use a GradientValue instead.

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.

Name Type Description
gradient String Required. The type of gradient. Use "linear" for a linear gradient.
x1 Number The starting x-coordinate, in normalized [0, 1] coordinates, of the linear gradient (default 0).
y1 Number The starting y-coordinate, in normalized [0, 1] coordinates, of the linear gradient (default 0).
x2 Number The ending x-coordinate, in normalized [0, 1] coordinates, of the linear gradient (default 1).
y2 Number The ending y-coordinate, in normalized [0, 1] coordinates, of the linear gradient (default 0).
stops GradientStop[ ] Required. An array of gradient stops defining the gradient color sequence.

# 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).

Name Type Description
gradient String Required. The type of gradient. Use "radial" for a radial gradient.
x1 Number The x-coordinate, in normalized [0, 1] coordinates, for the center of the inner circle for the gradient (default 0.5).
y1 Number The y-coordinate, in normalized [0, 1] coordinates, for the center of the inner circle for the gradient (default 0.5).
r1 Number The radius length, in normalized [0, 1] coordinates, of the inner circle for the gradient (default 0).
x2 Number The x-coordinate, in normalized [0, 1] coordinates, for the center of the outer circle for the gradient (default 0.5).
y2 Number The y-coordinate, in normalized [0, 1] coordinates, for the center of the outer circle for the gradient (default 0.5).
r2 Number The radius length, in normalized [0, 1] coordinates, of the outer circle for the gradient (default 0.5).
stops GradientStop[ ] Required. An array of gradient stops defining the gradient color sequence.

# Gradient Stop

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

Name Type Description
offset Number Required. The offset fraction for the color stop, indicating its position within the gradient.
color Color Required. The color value at this point in the gradient.


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

Back to top

Data and Signal Types

# Data

Accepts a string indicating the name of a data set. For example: "table", "nodes".

Back to top

# Field

Accepts a string indicating the name of a data field. For example: "amount", "source.x", "target['x']".

Alternatively, accepts an object with a string-valued field parameter. For example: {"field": "amount"}, {"field": "source.x"}. In addition, the as parameter can be used to specify a different output name for a field. For example: {"field": "inputName", "as": "outputName"}.

Valid JavaScript object access paths using either dot (.) or bracket (foo['bar']) notation will be converted into lookups on nested objects. To specify field names that contain dots but are not nested lookups, escape the dot inline ("my\\.field") or enclose the field name in brackets ("[my.field]").

Back to top


# Signal

Accepts an object with a reference to a signal value or expression. The signal property of the object must be either a valid signal name string or an expression string indicating a derived value. For example: {"signal": "width"}, {"signal": "width / 2"}.

Back to top


# Compare

Accepts an object providing a comparator definition for sorting. Comparator objects may have two properties – field and order – indicating the data fields to sort by and the desired sort order for each field. Each property can take either a single string value (to sort by one field) or an array of string values (to sort by multiple fields).

The order property is optional. If defined, order values must be one of "ascending" (lowest-to-highest) or "descending" (highest-to-lowest). If order is not defined, or for cases where there are fewer order entries than field entries, ascending order is used by default.

A single field comparator:

{"field": "amount", "order": "ascending"}

A multi-field comparator:

{
  "field": ["amount", "date"],
  "order": ["descending", "ascending"]
}

Comparators can not be specified using a single signal instance. However, the individual field and order properties can use signals:

{
  "field": {"signal": "sortField"},
  "order": {"signal": "sortOrder"}
}

If a sort field is null, that field and any corresponding order entries will be ignored, just as if the entry did not exist.

Back to top


# Expr

Accepts an object defining an expression to apply to each data object. Some transforms (for example the wordcloud transform) have parameters that can take a static string or number value or perform a lookup operation for each datum.

There are two valid forms of expression-typed values: field references and expr references.

A field reference results in a field lookup, identical to field-typed parameters:

{
  "type": "wordcloud",
  ...
  "rotate": {"field": "angle"} // per-datum lookup of the "angle" field
}

An expr reference provides an expression string that should be evaluated once per datum:

{
  "type": "wordcloud",
  ...
  "rotate": {"expr": "datum.minAngle + round(90*random() - 45)"} // evaluate once per-datum
}

Unlike signal references that are evaluated once per parameter, expr references behave like anonymous (or lambda) functions that are evaluated independently per data object. Note that both signal and expr references will re-run if an upstream dependency changes.

Both field and expr references may include an as property that indicates the output field name to use.

Back to top


# Value

Accepts an object defining a value reference, typically used for visual encoding. A value reference consists of a base value, plus optional scale transformation and modification.

Base Value

The base value must be specified using one of the following properties:

Name Type Description
signal String A signal name or expression.
color ColorValue Specifies a color using value references for each color channel. See the color value documentation.
field FieldValue A data field name or descriptor. See the field value documentation.
value Any A constant value. Legal values include numbers, booleans, strings, colors, and gradients.

These properties are listed here in precedence order. For example, if signal is defined, any color, field or value properties will be ignored. In addition, the base value may be left undefined in the case of certain scale values, or to indicate a null value.

Scale Transforms

Once a base value is established, a scale lookup may be performed. The available scale-related properties are:

Name Type Description
scale String | FieldValue The name of a scale transform to apply. If this parameter is an object, it indicates a field value from which to dynamically lookup the scale name. For example {"datum": "s"} will use the value of field s on the current data object as the scale name, whereas {"parent": "t"} will use the value of field t on the parent group’s data object as the scale name.
band Number If specified, returns the band width of the scale, multiplied by the given number. This parameter applies only to band scales. For example, {"band": 1} indicates the full band width, while {"band": 0.5} indicates half the band width. If the base value is defined, the multiplied band width is added to the output of the scale transform. For example, {"field": "a", "scale": "s", "band": 0.5} translates to scale(datum.a) + 0.5 * scale.bandwidth().

Value Modifiers

After any scale transformations are applied, the resulting value can be further modified using the following properties. The basic formula of a value reference is: pow(scale(baseValue), exponent) * mult + offset. Value modifiers are intended for use only with numeric values.

Name Type Description
exponent Number | Value Raise the value to a given exponent, equivalent to pow(value, exponent). If specified, exponentiation is applied immediately after any scale transformation.
mult Number | Value A multiplier for the value, equivalent to mult * value. Multipliers are applied after any scale transformation or exponentiation.
offset Number | Value An additive offset for the final value, equivalent to value + offset. Offsets are added after any scale transformation, exponentiation or multipliers.
round Boolean Indicates if the final value should be rounded (default false). Rounding is performed after all other modifiers. If true, equivalent to round(value).

Examples

  • {"value": 5} - The constant value 5.
  • {"field": "price"} - The value of price, for the current datum.
  • {"field": "index", "mult": 20} - The value of index for the current datum, multiplied by 20.
  • {"scale": "x", "value": 0} - The result of running the value 0 through the scale named x.
  • {"scale": "y", "field": "price"} - The result of running price for the current datum through the scale named y.
  • {"scale": "x", "band": 1} - The range band width of the band scale x. Note that the scale must be of type “band”!
  • {"scale": "x", "band": 1, "offset": -1} - The range band width of the band scale x, reduced (negative offset) by one pixel.

Back to top


# ColorValue

Accepts an object that defines a custom color using value references for each color channel in a chosen color space. The color space is automatically inferred from the channel names used.

Typically color values are specified as a single value indicating an RGB color. However, sometimes a designer may wish to target specific color fields or use a different color space. In the following example, we can set the red and blue channels of an RGB color as constants, and determine the green channel from a scale transform.

{
  "fill": {
    "color": {
      "r": {"value": 255},
      "g": {"scale": "green", "field": "g"},
      "b": {"value": 0}
    }
  }
}

Vega supports the following color spaces:

Name Description
RGB Red, green, and blue channels defined with properties "r", "g", and "b".
HSL Hue, saturation, and lightness channels defined with properties "h", "s", and "l".
LAB Luminance, A (green-red contrast), and B (blue-yellow contrast) channels defined with properties "l", "a", and "b". LAB is a perceptual color space with distances based on human color judgments.
HCL Hue, chroma, and luminance channels defined with properties "h", "c", and "l". HCL color space is a simple transform of LAB that uses polar coordinates for the AB plane.

Back to top


# FieldValue

Accepts a string or an object indicating a data field value. If string-valued, the given data field name is used. If object-valued, the following properties may be used:

Property Type Description
signal String Evaluate the signal name or expression, and use the result as the field name to lookup.
datum FieldValue Perform a lookup on the current data object using the given field name. This is similar to simply providing a string value.
group FieldValue Use a property of the enclosing group mark instance as the value (e.g., "field": {"group": "width"} or "field": {"group": "height"}).
parent FieldValue Use a field of the enclosing group mark’s data object as the value (e.g., "field": {"parent": "fieldInParentData"}.

These properties can be arbitrarily nested in order to perform indirect field lookups. For example, {"parent": {"datum": "f"}} will first retrieve the value of the f field on the current mark’s data object. This value will then be used as the property name to lookup on the enclosing parent group mark’s data object.

In addition, group and parent references may include an optional level property to access grandparents and other ancestors. For example, {"parent": "f", "level": 2} will use the value of the f field of the grandparent’s datum. By default, level = 1, indicating the immediate parent scope.

Back to top


# GradientValue

Defines a linear gradient based on a scale range to determine colors for a fill or stroke encoding channel. To define a gradient directly, without reference to a scale, assign a Gradient definition as an encoding’s value property.

Property Type Description
gradient String | FieldValue Required. The name of a scale whose range is a continuous color scheme.
start Number[ ] The starting coordinate for the gradient as an [x, y] array within a normalized [0, 1] coordinate system. This coordinate is relative to the bounds of the item being colored. Defaults to [0, 0].
stop Number[ ] The stopping coordinate for the gradient as an [x, y] array within a normalized [0, 1] coordinate system. This coordinate is relative to the bounds of the item being colored. Defaults to [1, 0], for a horizontal gradient that spans the full bounds of an item.
count Number A suggested target number of sample points to take from the color scale.

Example

{
  "encode": {
    "fill": {
      "gradient": "colorScale",
      "start": [0, 1],
      "stop": [0, 0],
      "count": 10
    }
  }
}

Back to top


# TimeMultiFormat

An object defining custom multi-format specifications for date-time values. This object must be a legal input to the timeFormat API method:

  • Object keys must be valid time units (e.g., year, month, etc).
  • Object values must be valid d3-time-format specifier strings.

These values, in conjunction with defaults for unspecified units, will then be used to create a dynamic formatting function that uses different formats depending on the granularity of the input date (e.g., if the date lies on a year, month, date, hour, etc. boundary). For more information, see the timeFormat API documentation.

Back to top