Customizing Size

This page describe how to adjust width and height of visualizations in Vega-lite.

Documentation Overview

Width and Height of Single and Layered Plots
Width and Height of Multi-View Displays

Width and Height of Single and Layered Plots

Single view and layer specifications can contain width and height properties for customizing the view size. By default, width and height set the size of the data rectangle (plotting) dimensions. To set the overall size of the visualization, the autosize property can be specified.

Explicitly Specified Width and Height

When the top-level width property is specified, the width of the single plot is the specified value for all scale types of the x-axis. Similarly, when the top-level height property is specified, the height of the single plot is the specified value for all scale types of the y-axis.

Note: If numeric rangeStep for a discrete x/y-scale is specified when width / height is specified, the rangeStep will be ignored (overridden with null).

Warning: If the cardinality of the x/y-field’s domain is too high, the rangeStep might become less than one pixel and the mark might not appear correctly.

Default Width and Height

If the top-level width / height property is not specified, the width / height of a single view is determined by the properties of the x / y channel:

If (1) the view’s autosize type is "fit" or (2) the x / y axis has a continuous scale (either quantitative or time) or a discrete scale with rangeStep = null, the width/height is drawn directly from the config.view.width / config.view.height property.
If the autosize type is not "fit" and the x / y channel has a band or point scale in which rangeStep is a number or unspecified, the width / height is determined based on the scale’s range step, paddings, and the cardinality of the encoded field (the number of possible distinct values of the field).

This example shows a plot with a continuous y-scale and a discrete x-scale:

If the x / y channel has a discrete scale with rangeStep = null, the width / height is drawn directly from the config.view.width / config.view.height property and the band of the scale will be adjusted to fit to the width.

If x / y is not mapped to a field, the width / height is derived from config.scale.rangeStep except for the width when the mark is text. In that case, the width will be drawn from config.scale.textXRangeStep.

For example, the following plot use 21 as a default height.

Autosize

The specified dimensions of a chart as explained above set the size of the data rectangle (plotting) dimensions. You can override this behavior by setting the autosize property in the top level specification. Please note the limitations below.

The autosize property can be a string or an object with the following properties:

Property Type Description

type

String

Property	Type	Description
type	String	The sizing format type. One of `"pad"`, `"fit"` or `"none"`. See the autosize type documentation for descriptions of each. Default value: `"pad"`
resize	Boolean	A boolean flag indicating if autosize layout should be re-calculated on every view update. Default value: `false`
contains	String	Determines how size calculation should be performed, one of `"content"` or `"padding"`. The default setting (`"content"`) interprets the width and height settings as the data rectangle (plotting) dimensions, to which padding is then added. In contrast, the `"padding"` setting includes the padding within the view size calculations, such that the width and height settings indicate the total intended size of the view. Default value: `"content"`

The sizing format type. One of "pad", "fit" or "none". See the autosize type documentation for descriptions of each.

Default value: "pad"

resize

Boolean

A boolean flag indicating if autosize layout should be re-calculated on every view update.

Default value: false

contains

String

Determines how size calculation should be performed, one of "content" or "padding". The default setting ("content") interprets the width and height settings as the data rectangle (plotting) dimensions, to which padding is then added. In contrast, the "padding" setting includes the padding within the view size calculations, such that the width and height settings indicate the total intended size of the view.

Default value: "content"

The total size of a Vega-Lite visualization may be determined by multiple factors: specified width, height, and padding values, as well as content such as axes, legends, and titles. To support different use cases, there are three different autosize types for determining the final size of a visualization view:

none: No automatic sizing is performed. The total visualization size is determined solely by the provided width, height and padding values. For example, by default the total width is calculated as width + padding.left + padding.right. Any content lying outside this region will be clipped. If autosize.contains is set to "padding", the total width is instead simply width.
pad: Automatically increase the size of the view such that all visualization content is visible. This is the default autosize setting, and ensures that axes, legends and other items outside the normal width and height are included. The total size will often exceed the specified width, height, and padding.
fit: Automatically adjust the layout in an attempt to force the total visualization size to fit within the given width, height and padding values. This setting causes the plotting region to be made smaller in order to accommodate axes, legends and titles. As a result, the value of the width and height signals may be changed to modify the layout. Though effective for many plots, the fit method can not always ensure that all content remains visible. For example, if the axes and legends alone require more space than the specified width and height, some of the content will be clipped. Similar to none, by default the total width will be width + padding.left + padding.right, relative to the original, unmodified width value. If autosize.contains is set to "padding", the total width will instead be the original width.

Limitations

In order to fit a chart into specified dimensions, it has to satisfy two requirements:

The view must be either a single view or a layered view. Fit does not work with other kinds of composed views (facet/hconcat/vconcat/repeat).
The width and height of the chart cannot depend on an explicitly specified rangeStep of a discrete scale. Any specified rangeStep will be ignored.

Example

Below is an example of a bar chart that fits exactly into 300px width.

Width and Height of Multi-View Displays

Currently, width and height of multi-view displays including concatenated, faceted, and repeated are determined based on the size of the composed unit and layered views. To adjust the size of multi-view displays, you can width and height of the inner unit and layered views.

For example, you can adjust width and height of the inner single view specification to adjust the size of a faceted plot.

Note: If you use the row or column channel to create a faceted plot, width and height will be applied to the inner single-view plot. For example, this specification is equivalent to the specification above.