Customizing SizeEdit this page
This page describe how to adjust width and height of visualizations in Vega-Lite.
- 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 the
height properties for customizing the view size. By default,
height set the size of the data rectangle (plotting) dimensions. To set the overall size of the visualization, the
autosize property can be specified.
Default Width and Height
If the top-level
height property is not specified, the width / height of a single view is determined based on the view config.
The width will be based on
config.view.continuousWidth for a plot with a continuous x-field (
200 by default). For a plot with either a discrete x-field or no x-field, the width is based on
config.view.discreteWidth, which is set to have step width based on the default step size (
20 by default).
Similarly, the height will be based on
config.view.continuousHeight for a plot with a continuous y-field and
config.view.discreteHeight for a plot with either a discrete y-field or no y-field.
For example, the following bar chart has a fixed 200px height and a 20px width per x-field’s discrete step.
Specifying Fixed Width and Height
height property can be set to numbers indicating fixed width and height of the plot.
For a discrete axis, specifying a fixed size (e.g., width in the following plot) would automatically scale the discrete step to fit the size.
Warning: If the cardinality of a discrete x- or y-field is too high, the plot might become too packed.
Specifying Responsive Width and Height
You can set the top-level
height properties to
"container" to indicate that the width or height of the plot should be the same as its surrounding container. The
height can be set independently, for example, you can have a responsive
width and a fixed
height by setting
height to a number.
"container", you need to ensure that the container’s width or height is determined outside the plot. For example, the container can be a
<div> element that has style
width: 100%; height: 300px. When the container is not available or its size is not defined (e.g., in server-side rendering), the default width and height are
- This responsive mode is available only for single view or layer specifications.
- Vega listens to the
window.resizeevent to update plot size from container size. This should cover many use cases. However, if you change the container size programmatically (e.g., you build a custom divider view), you’ll need to trigger
window.resizemanually. In a modern browser, you can do:
Specifying Width and Height per Discrete Step
For a discrete x-field or discrete y-field, we can also set
height) to be an object indicating the width (or height) per discrete
Note: By default, Vega-Lite sets padding for band and point scales such that width/height = number of unique values * step. See the scale documentation to read more about the relationship among width/height, step, and other scale properties.
Step for Offset Channel
For a discrete x-field or discrete y-field with nested offset, the step will be applied to the offset step by default.
To specify step for the x/y scale instead, you can include
"for": "position" in the
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.
Note that for performance reasons Vega-Lite doesn’t re-calculate layouts on every view change by default. If your view is cut off after the view updates, you can either set
true or manually call
view.resize() through the Vega view API.
The autosize property can be a string or an object with the following properties:
The sizing format type. One of
A boolean flag indicating if autosize layout should be re-calculated on every view update.
Determines how size calculation should be performed, one of
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
fitmethod 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.
fit-x: Automatically adjust the layout in an attempt to force the total visualization size to fit within the given width and left and right padding values.
fit-y: Automatically adjust the layout in an attempt to force the total visualization size to fit within the given height and top and bottom padding values.
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 (
- The width and height of the chart cannot depend on an explicitly specified
stepof a discrete scale. Discrete scale
stephas higher precendence than
fit, and the respective channel of fit will be dropped. E.g., an explicit
fitand make it
Below is an example of a bar chart that fits exactly into 300px width and the default 200px height.
Width and Height of Multi-View Displays
The 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 set the
height properties of the inner unit and layered views.
For example, you can adjust
height of the inner single view specification to adjust the size of a faceted plot.
Note: If you use the
column channel to create a faceted plot,
height will be applied to the inner single-view plot. For example, this specification is equivalent to the specification above.