Scale
Edit this pageScales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, VegaLite uses Vega scales, which are derived from the d3scale library. For more background about scales, please see “Introducing d3scale” by Mike Bostock.
VegaLite 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 toplevel 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
 Scale Domains
 Scale Ranges
 Common Scale Properties
 Continuous Scales
 Discrete Scales
 Discretizing Scales
 Disabling Scale
 Configuration
Scale Types
The type
property can be specified to customize the scale type.
Property  Type  Description 

type  String 
The type of scale. VegaLite supports the following categories of scale types: 1) Continuous Scales – mapping continuous domains to continuous output ranges ( 2) Discrete Scales – mapping discrete domains to discrete ( 3) Discretizing Scales – mapping continuous domains to discrete output ranges Default value: please see the scale type table. 
By default, VegaLite use the following scale types for the following data types and encoding channels:
Nominal / Ordinal  Quantitative  BinQuantitative^{1}  Temporal  

X, Y  Band / Point^{2}  Linear  Linear  Time 
Size, Opacity  Point  Linear  Linear  Time 
Color  Ordinal  Linear  BinOrdinal  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 VegaLite 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
2) Constant 3) Constant 4) To combine (union) specified constant domain with the field’s values, 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 
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 midpoint value into a twoelement domain. The midpoint 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. 
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. Usingtransform
removes unwanted data points, yet settingclip
totrue
clips the mark to be the enclosing group’s width and height.
Scale Ranges
The range of the scale represents the set of output visual values. VegaLite 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 predefined 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:
Notes: 1) For color scales you can also specify a color 2) Any directly specified 
rangeMin  Number  String  ExprRef 
Sets the minimum value in the scale range, overriding the 
rangeMax  Number  String  ExprRef 
Sets the maximum value in the scale range, overriding the 
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. VegaLite (via Vega) provides a collection of perceptuallymotivated color schemes, many of which are drawn from the d3scale, d3scalechromatic, and ColorBrewer projects.
By default, VegaLite assigns different default color schemes based on the types of the encoded fields:
 Nominal fields use the
"categorical"
predefined named range (the"tableau10"
scheme by default).
 Ordinal fields use the
"ordinal"
predefined named color range (the"blues"
color scheme by default).
 Quantitative and temporal fields use the predefined named color range
"heatmap"
(the"viridis"
scheme by default) for rect marks and"ramp"
(the"blues"
scheme by default) for other marks.
There are multiple ways to customize the scale range for the color encoding channel:
1. Set a custom scheme
.
Property  Type  Description 

scheme  String  SchemeParams  ExprRef 
A string indicating a color scheme name (e.g., Discrete color schemes may be used with discrete or discretizing scales. Continuous color schemes are intended for use with color scales. 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  String 
Required. A color scheme name for ordinal scales (e.g., 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 
count  Number 
The number of colors to use in the scheme. This can be useful for scale types such as 
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: 
round  Boolean  ExprRef 
If Default value: 
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, VegaLite 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 Default value: derived from the scale config’s 
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

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, For temporal fields with time and utc scales, the Default value: 
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 For band scales, shortcut for setting For point scales, alias for Default value: For continuous scales, derived from the scale config’s 
zero  Boolean  ExprRef 
If Default value: Note: Log, time, and utc scales do not support 
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 
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 log_{a}(x) + b, where a is the logarithmic base
.
As log(0) = ∞, a log scale domain must be strictlypositive or strictlynegative; the domain must not include or cross zero. A log scale with a positive domain has a welldefined behavior for positive values, and a log scale with a negative domain has a welldefined 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 
Example: The following plot has a logarithmic yscale.
Symlog Scales
Symmetric log scales (symlog) are quantitative scales scales that provide scaling similar to log scales, but supports nonpositive numbers. Symlog scales are particularly useful for plotting data that varies over multiple orders of magnitude but includes negative or zerovalued data. For more, see “A bisymmetric log transformation for widerange 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 Default value: 
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 scheme
s 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, VegaLite 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 color
s and a set of shape
s.
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 reordered 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 d3scale 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 d3scale documentation illustrates how a point scale works:
By default, VegaLite 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
, VegaLite uses point scales by default.
For example, the following bar chart has uses a band scale for its xposition.
To customize the step size of band scales for x/yfields, 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 Default value: 
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 For band scales, shortcut for setting For point scales, alias for Default value: For continuous scales, derived from the scale config’s 
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 
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 
Discretizing Scales
Discretizing scales break up a continuous domain into discrete segments, and then map values in each segment to a range value.
BinLinear Scales
Binned linear scales ("binlinear"
) are a special type of linear scale for use with binned fields to correctly create legend labels. VegaLite 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.
BinOrdinal Scales
Binned ordinal scales ("binordinal"
) are a special type of ordinal scale for use with binned fields to correctly create legend labels. VegaLite 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:

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 59 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 59 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, For temporal fields with time and utc scales, the Default value: 
zero  Boolean  ExprRef 
If Default value: Note: Log, time, and utc scales do not support 
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
// Toplevel 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 Default value:

barBandPaddingInner  Number  ExprRef 
Default inner padding for Default value: 
rectBandPaddingInner  Number  ExprRef 
Default inner padding for Default value: 
bandWithNestedOffsetPaddingInner  Number  ExprRef 
Default inner padding for Default value: 
offsetBandPaddingInner  Number  ExprRef 
Default padding inner for xOffset/yOffset’s band scales. Default Value: 
bandPaddingOuter  Number  ExprRef 
Default outer padding for Default value: 
bandWithNestedOffsetPaddingOuter  Number  ExprRef 
Default outer padding for Default value: 
offsetBandPaddingOuter  Number  ExprRef 
Default padding outer for xOffset/yOffset’s band scales. Default Value: 
continuousPadding  Number  ExprRef 
Default padding for continuous x/y scales. Default: The bar width for continuous xscale of a vertical bar and continuous yscale of a horizontal bar.; 
pointPadding  Number  ExprRef 
Default outer padding for Default value: 
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 with zero=false. Default value: 
maxFontSize  Number 
The default max value for mapping quantitative fields to text’s size/fontSize. Default value: 
minFontSize  Number 
The default min value for mapping quantitative fields to tick’s size/fontSize scale with zero=false Default value: 
maxOpacity  Number 
Default max opacity for mapping a field to opacity. Default value: 
minOpacity  Number 
Default minimum opacity for mapping a field to opacity. Default value: 
maxSize  Number 
Default max value for point size scale. 
minSize  Number 
Default minimum value for point size scale with zero=false. Default value: 
maxStrokeWidth  Number 
Default max strokeWidth for the scale of strokeWidth for rule and line marks and of size for trail marks. Default value: 
minStrokeWidth  Number 
Default minimum strokeWidth for the scale of strokeWidth for rule and line marks and of size for trail marks with zero=false. Default value: 
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 
xReverse  Boolean  ExprRef 
Reverse xscale by default (useful for righttoleft 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 This property only works with aggregate functions that produce values within the raw data domain ( Default value: 
zero  Boolean 
Default Default value: 
Range Config
The scale range configuration (config: {range: {...}}
) defines keyvalue 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, VegaLite (via Vega) includes the following predefined 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 rankordered 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.