Parameter Types

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

Parameter Type Reference

• Any
• Array
• Boolean
• Color
• Date
• Gradient
• Number
• Object
• String
• URL
• Data
• Field
• Signal
• Compare
• Expr
• Value
• ColorValue
• FieldValue
• GradientValue
• TimeMultiFormat

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.

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

# Gradient Stop

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

# 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:

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:

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.

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:

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:

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.

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