Scale

Edit this page

Scales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, Vega-Lite uses Vega scales, which are derived from the d3-scale library. For more background about scales, please see “Introducing d3-scale” by Mike Bostock.

Vega-Lite automatically creates scales for fields that are mapped to position and mark property channels. To customize the scale of a field, users can provide a scale object as a part of the field definition to customize scale properties (e.g., type, domain, and range).

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "scale": {                // scale
        "type": ...,
        ...
      },
      ...
    },
    "y": ...,
    ...
  },
  ...
}

Besides the scale property of each encoding channel, the top-level configuration object (config) also provides scale config (config: {scale: {...}}) for setting default scale properties for all scales.

For more information about guides that visualize the scales, please see the axes and legends pages.

Documentation Overview

Scale Types

The type property can be specified to customize the scale type.

Property Type Description
type String

The type of scale. Vega-Lite supports the following categories of scale types:

1) Continuous Scales – mapping continuous domains to continuous output ranges ("linear", "pow", "sqrt", "symlog", "log", "time", "utc".

2) Discrete Scales – mapping discrete domains to discrete ("ordinal") or continuous ("band" and "point") output ranges.

3) Discretizing Scales – mapping continuous domains to discrete output ranges "bin-ordinal", "quantile", "quantize" and "threshold".

Default value: please see the scale type table.

By default, Vega-Lite use the following scale types for the following data types and encoding channels:

  Nominal / Ordinal Quantitative Bin-Quantitative1 Temporal
X, Y Band / Point2 Linear Linear Time
Size, Opacity Point Linear Linear Time
Color Ordinal Linear Bin-Ordinal Linear
Shape Ordinal N/A N/A N/A

1 Quantitative fields with the bin transform. 2 For positional (x and y) nominal and ordinal fields, "band" scale is the default scale type for bar, image, rect, and rule marks while "point" is the default scales for all other marks.

Scale Domains

By default, a scale in Vega-Lite draws domain values directly from a channel’s encoded field. Users can specify the domain property of a scale to customize its domain values. To sort the order of the domain of the encoded, the sort property of a field definition can be specified.

Property Type Description
domain Null[] | String[] | Number[] | Boolean[] | DateTime[] | ExprRef[] | String | ParameterExtent | DomainUnionWith | ExprRef

Customized domain values in the form of constant values or dynamic values driven by a parameter.

1) Constant domain for quantitative fields can take one of the following forms:

  • A two-element array with minimum and maximum values. To create a diverging scale, this two-element array can be combined with the domainMid property.
  • An array with more than two entries, for Piecewise quantitative scales.
  • A string value "unaggregated", if the input field is aggregated, to indicate that the domain should include the raw data values prior to the aggregation.

2) Constant domain for temporal fields can be a two-element array with minimum and maximum values, in the form of either timestamps or the DateTime definition objects.

3) Constant domain for ordinal and nominal fields can be an array that lists valid input values.

4) To combine (union) specified constant domain with the field’s values, domain can be an object with a unionWith property that specify constant domain to be combined. For example, domain: {unionWith: [0, 100]} for a quantitative scale means that the scale domain always includes [0, 100], but will include other values in the fields beyond [0, 100].

5) Domain can also takes an object defining a field or encoding of a parameter that interactively determines the scale domain.

domainMax Number | DateTime | ExprRef

Sets the maximum value in the scale domain, overriding the domain property. This property is only intended for use with scales having continuous domains.

domainMin Number | DateTime | ExprRef

Sets the minimum value in the scale domain, overriding the domain property. This property is only intended for use with scales having continuous domains.

domainMid Number | ExprRef

Inserts a single mid-point value into a two-element domain. The mid-point value must lie between the domain minimum and maximum values. This property can be useful for setting a midpoint for diverging color scales. The domainMid property is only intended for use with scales supporting continuous, piecewise domains.

domainRaw ExprRef

An expression for an array of raw values that, if non-null, directly overrides the domain property. This is useful for supporting interactions such as panning or zooming a scale. The scale may be initially determined using a data-driven domain, then modified in response to user input by setting the rawDomain value.

A common use case for the domain property is to limit, for example, the x range of values to include in a plot. However, setting the domain property alone is insufficient to achieve the desired effect.

Example: Customizing Domain for a Time Scale

For a time scale, we can set scale domain to an array datetime objects, as shown below.

Example: Clipping or Removing Unwanted Data Points

For example, consider the line plot specification below in which the x domain is restricted to the range [300, 450].

There are two approaches to keep the mark from being plotted outside the desired x range of values.

  • The first one is to set clip: true in mark definition.

  • The second approach is to use transform. Note that these two approaches have slightly different behaviors. Using transform removes unwanted data points, yet setting clip to true clips the mark to be the enclosing group’s width and height.

Example: Using domainRaw to bind domain interactively

Scale Ranges

The range of the scale represents the set of output visual values. Vega-Lite automatically determines the default range for each encoding channel using the following rules:

Channels Default Range
x The range is by default [0, width].
y The range is by default [0, height].
opacity Derived from the scale config’s min/maxOpacity.
color Derived from the following named ranges based on the field’s type:
"category" for nominal fields.
"ordinal" for ordinal fields.
"heatmap" for quantitative and temporal fields with "rect" marks and "ramp' for other marks.

See the color scheme section for examples.
size Derived from the following named ranges based on the mark type:
min/maxBandSize for bar and tick.
min/maxStrokeWidth for line and rule.
min/maxSize for point, square, and circle
min/maxFontSize for text
shape Derived from the pre-defined named range "symbol".

To customize range values, users can directly specify range or specify the special scheme property for ordinal and continuous color scales.

Property Type Description
range String | Number[] | String[] | Number[] | ExprRef[] | FieldRange

The range of the scale. One of:

  • A string indicating a pre-defined named scale range (e.g., example, "symbol", or "diverging").

  • For continuous scales, two-element array indicating minimum and maximum values, or an array with more than two entries for specifying a piecewise scale.

  • For discrete and discretizing scales, an array of desired output values or an object with a field property representing the range values. For example, if a field color contains CSS color names, we can set range to {field: "color"}.

Notes:

1) For color scales you can also specify a color scheme instead of range.

2) Any directly specified range for x and y channels will be ignored. Range can be customized via the view’s corresponding size (width and height).

rangeMin Number | String | ExprRef

Sets the minimum value in the scale range, overriding the range property or the default range. This property is only intended for use with scales having continuous ranges.

rangeMax Number | String | ExprRef

Sets the maximum value in the scale range, overriding the range property or the default range. This property is only intended for use with scales having continuous ranges.

Example: Setting Color Range based on a Field

In this example, we create a scale that maps the field "l" to colors specified in the field "c":

Note: This only works if there is a 1:1 mapping between the color domain field (l) and the range field (c).

Example: Setting Range Min/Max

We may use rangeMin if we want to override just the minimum value of the range, while keeping the default maximum value of the range.

Similarly, we may use rangeMax if we want to override just the maximum value of the range, while keeping the default minimum value of the range.

Color Schemes

Color schemes provide a set of named color palettes as a scale range for the color channel. Vega-Lite (via Vega) provides a collection of perceptually-motivated color schemes, many of which are drawn from the d3-scale, d3-scale-chromatic, and ColorBrewer projects.

By default, Vega-Lite assigns different default color schemes based on the types of the encoded fields:

There are multiple ways to customize the scale range for the color encoding channel:

1. Set a custom scheme.

Property Type Description
scheme ColorScheme | SchemeParams | ExprRef

A string indicating a color scheme name (e.g., "category10" or "blues") or a scheme parameter object.

Discrete color schemes may be used with discrete or discretizing scales. Continuous color schemes are intended for use with color scales.

To set a custom scheme, instead set the list of values as the scale range.

For the full list of supported schemes, please refer to the Vega Scheme reference.

You can customize the scheme by referencing an existing color scheme. For example, the following plot uses the "category20b" scheme.

The scheme property can also be a scheme parameter object, which contain the following properties:

Property Type Description
name ColorScheme

Required. A color scheme name for ordinal scales (e.g., "category10" or "blues").

For the full list of supported schemes, please refer to the Vega Scheme reference.

extent Number[]

The extent of the color range to use. For example [0.2, 1] will rescale the color scheme such that color values in the range [0, 0.2) are excluded from the scheme.

count Number

The number of colors to use in the scheme. This can be useful for scale types such as "quantize", which use the length of the scale range to determine the number of discrete bins for the scale domain.

2. Setting the range property to an array of valid CSS color strings.

3. Change the default color schemes using the range config.

See the range config documentation for details.

Common Scale Properties

In addition to type, domain, and range, all scales share the following properties:

Property Type Description
reverse Boolean | ExprRef

If true, reverses the order of the scale range. Default value: false.

round Boolean | ExprRef

If true, rounds numeric output values to integers. This can be helpful for snapping to the pixel grid.

Default value: false.

Continuous Scales

Continuous scales map a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). Supported continuous scale types for quantitative fields are "linear", "log", "pow", "sqrt", and "symlog". Meanwhile, supported continuous scale types for temporal fields are "time", "utc", and "symlog".

By default, Vega-Lite uses "linear" scales for quantitative fields and uses "time" scales for temporal fields for all encoding channels.

In addition to type, domain, and range, continuous scales support the following properties:

Property Type Description
clamp Boolean | ExprRef

If true, values that exceed the data domain are clamped to either the minimum or maximum range value

Default value: derived from the scale config’s clamp (true by default).

interpolate String | ExprRef | ScaleInterpolateParams

The interpolation method for range values. By default, a general interpolator for numbers, dates, strings and colors (in HCL space) is used. For color ranges, this property allows interpolation in alternative color spaces. Legal values include rgb, hsl, hsl-long, lab, hcl, hcl-long, cubehelix and cubehelix-long (‘-long’ variants use longer paths in polar coordinate spaces). If object-valued, this property accepts an object with a string-valued type property and an optional numeric gamma property applicable to rgb and cubehelix interpolators. For more, see the d3-interpolate documentation.

  • Default value: hcl
nice Boolean | Number | String | Object | ExprRef

Extending the domain so that it starts and ends on nice round values. This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value. Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0].

For quantitative scales such as linear, nice can be either a boolean flag or a number. If nice is a number, it will represent a desired tick count. This allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.

For temporal fields with time and utc scales, the nice value can be a string indicating the desired time interval. Legal values are "millisecond", "second", "minute", "hour", "day", "week", "month", and "year". Alternatively, time and utc scales can accept an object-valued interval specifier of the form {"interval": "month", "step": 3}, which includes a desired number of interval steps. Here, the domain would snap to quarter (Jan, Apr, Jul, Oct) boundaries.

Default value: true for unbinned quantitative fields without explicit domain bounds; false otherwise.

padding Number | ExprRef

For continuous scales, expands the scale domain to accommodate the specified number of pixels on each of the scale range. The scale range must represent pixels for this parameter to function as intended. Padding adjustment is performed prior to all other adjustments, including the effects of the zeronicedomainMin, and domainMax properties.

For band scales, shortcut for setting paddingInner and paddingOuter to the same value.

For point scales, alias for paddingOuter.

Default value: For continuous scales, derived from the scale config’s continuousPadding. For band and point scales, see paddingInner and paddingOuter. By default, Vega-Lite sets padding such that width/height = number of unique values * step.

zero Boolean | ExprRef

If true, ensures that a zero baseline value is included in the scale domain.

Default value: true for x and y channels if the quantitative field is not binned and no custom domain is provided; false otherwise.

Note: Log, time, and utc scales do not support zero.

Linear Scales

Linear scales ("linear") are quantitative scales scales that preserve proportional differences. Each range value y can be expressed as a linear function of the domain value x: y = mx + b.

Power Scales

Power scales ("pow") are quantitative scales scales that apply an exponential transform to the input domain value before the output range value is computed. Each range value y can be expressed as a polynomial function of the domain value x: y = mx^k + b, where k is the exponent value. Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.

Property Type Description
exponent Number | ExprRef

The exponent of the pow scale.

Square Root Scales

Square root ("sqrt") scales are a convenient shorthand for power scales with an exponent of 0.5, indicating a square root transform.

Logarithmic Scales

Log scales ("log") are quantitative scales in which a logarithmic transform is applied to the input domain value before the output range value is computed. Log scales are particularly useful for plotting data that varies over multiple orders of magnitude. The mapping to the range value y can be expressed as a logarithmic function of the domain value x: y = m loga(x) + b, where a is the logarithmic base.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values. (For a negative domain, input and output values are implicitly multiplied by -1.) The behavior of the scale is undefined if you run a negative value through a log scale with a positive domain or vice versa.

Property Type Description
base Number | ExprRef

The logarithm base of the log scale (default 10).

Example: The following plot has a logarithmic y-scale.

Symlog Scales

Symmetric log scales (symlog) are quantitative scales scales that provide scaling similar to log scales, but supports non-positive numbers. Symlog scales are particularly useful for plotting data that varies over multiple orders of magnitude but includes negative- or zero-valued data. For more, see “A bi-symmetric log transformation for wide-range data” by Webber for more.

Property Type Description
constant Number | ExprRef

A constant determining the slope of the symlog function around zero. Only used for symlog scales.

Default value: 1

Time and UTC Scales

Time and UTC scales ("time" and "utc") are continuous scales with a temporal domain: values in the input domain are assumed to be Date objects or timestamps. Time scales use the current local timezone setting. UTC scales instead use Coordinated Universal Time.

Piecewise and Diverging Scales

We can use any types of continuous scales ("linear", "pow", "sqrt", "log", "symlog", "time", "utc" to create a diverging color graph by specifying a custom domain with multiple elements.

If range is specified, the number of elements in range should match with the number of elements in domain. Diverging color schemes are also useful as a range for a piecewise scale.

Example

Discrete Scales

Discrete scales map values from a discrete domain to a discrete or continuous range.

Ordinal Scales

Ordinal scales ("ordinal") have a discrete domain and range. These scales function as a “lookup table” from a domain value to a range value.

By default, Vega-Lite automatically creates ordinal scales for color and shape channels. For example, the following plot implicitly has two ordinal scales, which map the values of the field "Origin" to a set of colors and a set of shapes.

The range of an ordinal scale can be an array of desired output values, which are directly mapped to elements in the domain. Both domain and range array can be re-ordered to specify the order and mapping between the domain and the output range. For ordinal color scales, a custom scheme can be set as well.

Band and Point Scales

Band and point scales accept a discrete domain similar to ordinal scales, but map this domain to a continuous, numeric output range such as pixels.

Band scales ("band") compute the discrete output values by dividing the continuous range into uniform bands. Band scales are typically used for bar charts with an ordinal or categorical dimension.

In addition to a standard numerical range value (such as [0, 500]), band scales can be given a fixed step size for each band. The actual range is then determined by both the step size and the cardinality (element count) of the input domain.

This image from the d3-scale documentation illustrates how a band scale works:

Point scales ("point") are a variant of band scales where the internal band width is fixed to zero. Point scales are typically used for scatterplots with an ordinal or categorical dimension. Similar to band scales, point scale range values may be specified using either a numerical extent ([0, 500]) or a step size ({"step": 20}).

This image from the d3-scale documentation illustrates how a point scale works:

By default, Vega-Lite uses band scales for nominal and ordinal fields on position channels (x and y) of bar or rect marks. For x and y of other marks and size and opacity, Vega-Lite uses point scales by default.

For example, the following bar chart has uses a band scale for its x-position.

To customize the step size of band scales for x/y-fields, we can set the step property of the view’s width/height.

For example, we can either make a bar chart have a fixed width:

or set the width per discrete step:

To customize the range of band and point scales, users can provide the following properties:

Property Type Description
align Number | ExprRef

The alignment of the steps within the scale range.

This value must lie in the range [0,1]. A value of 0.5 indicates that the steps should be centered within the range. A value of 0 or 1 may be used to shift the bands to one side, say to position them adjacent to an axis.

Default value: 0.5

padding Number | ExprRef

For continuous scales, expands the scale domain to accommodate the specified number of pixels on each of the scale range. The scale range must represent pixels for this parameter to function as intended. Padding adjustment is performed prior to all other adjustments, including the effects of the zeronicedomainMin, and domainMax properties.

For band scales, shortcut for setting paddingInner and paddingOuter to the same value.

For point scales, alias for paddingOuter.

Default value: For continuous scales, derived from the scale config’s continuousPadding. For band and point scales, see paddingInner and paddingOuter. By default, Vega-Lite sets padding such that width/height = number of unique values * step.

paddingInner Number | ExprRef

The inner padding (spacing) within each band step of band scales, as a fraction of the step size. This value must lie in the range [0,1].

For point scale, this property is invalid as point scales do not have internal band widths (only step sizes between bands).

Default value: derived from the scale config’s bandPaddingInner.

paddingOuter Number | ExprRef

The outer padding (spacing) at the ends of the range of band and point scales, as a fraction of the step size. This value must lie in the range [0,1].

Default value: derived from the scale config’s bandPaddingOuter for band scales and pointPadding for point scales. By default, Vega-Lite sets outer padding such that width/height = number of unique values * step.

Discretizing Scales

Discretizing scales break up a continuous domain into discrete segments, and then map values in each segment to a range value.

Bin-Linear Scales

Binned linear scales ("bin-linear") are a special type of linear scale for use with binned fields to correctly create legend labels. Vega-Lite always uses binned linear scales with binned quantitative fields on size and opacity channels.

For example, the following plot has a binned field on the size channel.

Bin-Ordinal Scales

Binned ordinal scales ("bin-ordinal") are a special type of ordinal scale for use with binned fields to correctly create legend labels. Vega-Lite always uses binned ordinal scales with binned quantitative fields on the color channel.

For example, the following plot has a binned field on the color channel.

Similar to ordinal color scales, a custom range or scheme can be specified for binned ordinal scales.

In addition, bins property can be used to specify bin boundaries over the scale domain.

Property Type Description
bins ScaleBins

Bin boundaries can be provided to scales as either an explicit array of bin boundaries or as a bin specification object. The legal values are:

  • An array literal of bin boundary values. For example, [0, 5, 10, 15, 20]. The array must include both starting and ending boundaries. The previous example uses five values to indicate a total of four bin intervals: [0-5), [5-10), [10-15), [15-20]. Array literals may include signal references as elements.
  • A bin specification object that indicates the bin step size, and optionally the start and stop boundaries.
  • An array of bin boundaries over the scale domain. If provided, axes and legends will use the bin boundaries to inform the choice of tick marks and text labels.

Bins Parameter

The bin specification object for the scale bins properties support the following properties:

Property Type Description
bins Any

Quantile Scales

Quantile scales ("quantile") map a sample of input domain values to a discrete range based on computed quantile boundaries. The domain is considered continuous and thus the scale will accept any reasonable input value; however, the domain is specified as a discrete set of sample values. The number of values in (i.e., the cardinality of) the output range determines the number of quantiles that will be computed from the domain. To compute the quantiles, the domain is sorted, and treated as a population of discrete values. The resulting quantile boundaries segment the domain into groups with roughly equals numbers of sample points per group. If the range is not specified, the domain will be segmented into 4 quantiles (quartiles) by default.

Quantile scales are particularly useful for creating color or size encodings with a fixed number of output values. Using a discrete set of encoding levels (typically between 5-9 colors or sizes) sometimes supports more accurate perceptual comparison than a continuous range. For related functionality see quantize scales, which partition the domain into uniform domain extents, rather than groups with equal element counts. Quantile scales have the benefit of evenly distributing data points to encoded values. In contrast, quantize scales uniformly segment the input domain and provide no guarantee on how data points will be distributed among the output visual values.

Quantize Scales

Quantize scales ("quantize") are similar to linear scales, except they use a discrete rather than continuous range. The quantize scale maps continuous value to a discrete range by dividing the domain into uniform segments based on the number of values in (i.e., the cardinality of) the output range. Each range value y can be expressed as a quantized linear function of the domain value x: y = m round(x) + b. If the range property is not specified, the domain will be divided into 4 uniform segments by default.

Quantize scales are particularly useful for creating color or size encodings with a fixed number of output values. Using a discrete set of encoding levels (typically between 5-9 colors or sizes) sometimes supports more accurate perceptual comparison than a continuous range. For related functionality see quantile scales, which partition the domain into groups with equal element counts, rather than uniform domain extents.

Property Type Description
nice Boolean | Number | String | Object | ExprRef

Extending the domain so that it starts and ends on nice round values. This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value. Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0].

For quantitative scales such as linear, nice can be either a boolean flag or a number. If nice is a number, it will represent a desired tick count. This allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.

For temporal fields with time and utc scales, the nice value can be a string indicating the desired time interval. Legal values are "millisecond", "second", "minute", "hour", "day", "week", "month", and "year". Alternatively, time and utc scales can accept an object-valued interval specifier of the form {"interval": "month", "step": 3}, which includes a desired number of interval steps. Here, the domain would snap to quarter (Jan, Apr, Jul, Oct) boundaries.

Default value: true for unbinned quantitative fields without explicit domain bounds; false otherwise.

zero Boolean | ExprRef

If true, ensures that a zero baseline value is included in the scale domain.

Default value: true for x and y channels if the quantitative field is not binned and no custom domain is provided; false otherwise.

Note: Log, time, and utc scales do not support zero.

Threshold Scales

Threshold scales ("threshold") are similar to quantize scales, except they allow mapping of arbitrary subsets of the domain (not uniform segments) to discrete values in the range. The input domain is still continuous, and divided into slices based on a set of threshold values provided to the required domain property. The range property must have N+1 elements, where N is the number of threshold boundaries provided in the domain.

Disabling Scale

To directly encode the data value, the scale property can be set to null.

For example, the follow bar chart directly encodes color names in the data.

Configuration

// Top-level View Specification
{
  ...
  "config": {
    "scale": {
      ...                       // Scale Config
    },
    "range": {
      ...                       // Scale Range Config
    },
    ...
  }
  ...
}

Scale Config

To provide themes for all scales, the scale config (config: {scale: {...}}) can contain the following properties:

Padding

Property Type Description
bandPaddingInner Number | ExprRef

Default inner padding for x and y band scales.

Default value:

  • nestedOffsetPaddingInner for x/y scales with nested x/y offset scales.
  • barBandPaddingInner for bar marks (0.1 by default)
  • rectBandPaddingInner for rect and other marks (0 by default)
barBandPaddingInner Number | ExprRef

Default inner padding for x and y band-ordinal scales of "bar" marks.

Default value: 0.1

rectBandPaddingInner Number | ExprRef

Default inner padding for x and y band-ordinal scales of "rect" marks.

Default value: 0

bandWithNestedOffsetPaddingInner Number | ExprRef

Default inner padding for x and y band scales with nested xOffset and yOffset encoding.

Default value: 0.2

offsetBandPaddingInner Number | ExprRef

Default padding inner for xOffset/yOffset’s band scales.

Default Value: 0

bandPaddingOuter Number | ExprRef

Default outer padding for x and y band scales.

Default value: paddingInner/2 (which makes width/height = number of unique values * step)

bandWithNestedOffsetPaddingOuter Number | ExprRef

Default outer padding for x and y band scales with nested xOffset and yOffset encoding.

Default value: 0.2

offsetBandPaddingOuter Number | ExprRef

Default padding outer for xOffset/yOffset’s band scales.

Default Value: 0

continuousPadding Number | ExprRef

Default padding for continuous x/y scales.

Default: The bar width for continuous x-scale of a vertical bar and continuous y-scale of a horizontal bar.; 0 otherwise.

pointPadding Number | ExprRef

Default outer padding for x and y point-ordinal scales.

Default value: 0.5 (which makes width/height = number of unique values * step)

Range

Property Type Description
maxBandSize Number

The default max value for mapping quantitative fields to bar’s size/bandSize.

If undefined (default), we will use the axis’s size (width or height) - 1.

minBandSize Number

The default min value for mapping quantitative fields to bar and tick’s size/bandSize scale.

Default value: 2

maxFontSize Number

The default max value for mapping quantitative fields to text’s size/fontSize scale.

Default value: 40

minFontSize Number

The default min value for mapping quantitative fields to text’s size/fontSize scale.

Default value: 8

maxOpacity Number

Default max opacity for mapping a field to opacity.

Default value: 0.8

minOpacity Number

Default minimum opacity for mapping a field to opacity.

Default value: 0.3

maxSize Number

Default max value for point size scale.

minSize Number

Default minimum value for point size scale.

Default value: 9

maxStrokeWidth Number

Default max strokeWidth for the scale of strokeWidth for rule and line marks and of size for trail marks.

Default value: 4

minStrokeWidth Number

Default minimum strokeWidth for the scale of strokeWidth for rule and line marks and of size for trail marks.

Default value: 1

Scale Output for Invalid Values

Property Type Description
invalid ScaleInvalidDataConfig

An object that defines scale outputs per channel for invalid values (nulls and NaNs on a continuous scale).

  • The keys in this object are the scale channels.
  • The values is either "zero-or-min" (use zero if the scale includes zero or min value otherwise) or a value definition {value: ...}.

Example: Setting this config.scale.invalid property to {color: {value: '#aaa'}} will make the visualization color all invalid values with ‘#aaa’.

See https://vega.github.io/vega-lite/docs/invalid-data.html for more details.

Other

Property Type Description
clamp Boolean | ExprRef

If true, values that exceed the data domain are clamped to either the minimum or maximum range value

round Boolean | ExprRef

If true, rounds numeric output values to integers. This can be helpful for snapping to the pixel grid. (Only available for x, y, and size scales.)

xReverse Boolean | ExprRef

Reverse x-scale by default (useful for right-to-left charts).

useUnaggregatedDomain Boolean

Use the source data range before aggregation as scale domain instead of aggregated data for aggregate axis.

This is equivalent to setting domain to "unaggregate" for aggregated quantitative fields by default.

This property only works with aggregate functions that produce values within the raw data domain ("mean", "average", "median", "q1", "q3", "min", "max"). For other aggregations that produce values outside of the raw data domain (e.g. "count", "sum"), this property is ignored.

Default value: false

zero Boolean

Default scale.zero for continuous scales except for (1) x/y-scales of non-ranged bar or area charts and (2) size scales.

Default value: true

Range Config

The scale range configuration (config: {range: {...}}) defines key-value mapping for named scale ranges: the keys represent the range names, while the values define valid range or, for named color ranges, Vega scheme definitions.

By default, Vega-Lite (via Vega) includes the following pre-defined named ranges:

Property Type Description
category RangeScheme | Color[]

Default color scheme for categorical data.

diverging RangeScheme | Color[]

Default color scheme for diverging quantitative ramps.

heatmap RangeScheme | Color[]

Default color scheme for quantitative heatmaps.

ordinal RangeScheme | Color[]

Default color scheme for rank-ordered data.

ramp RangeScheme | Color[]

Default color scheme for sequential quantitative ramps.

symbol String[]

Array of symbol names or paths for the default shape palette.

See this file for the default values of named ranges.