This website is for Vega-Lite v3. Go to the main Vega-Lite homepage for the latest release.

Concatenating views

Edit this page

To place views side-by-side, Vega-Lite’s view composition provides the following concatenation operators:

  • hconcat - horizontal concatenation
  • vconcat - vertical concatenation
  • concat - general concatenation (wrappable)

If you concatenate similar views where the only difference is the field that is used in an encoding, use the repeat operator.

Documentation Overview

Horizontal Concatenation

To put multiple views into a column, set the "hconcat" to an array of view specifications.

{
  "hconcat": [
    ...  // Specifications
  ],
  ...
}

In addition to common properties of a view specification, a horizontal concat specification has the following properties:

Property Type Description
hconcat Spec[]

Required. A list of views to be concatenated and put into a row.

Example

Vertical Concatenation

To put multiple views into a row, set the "vconcat" to an array of view specifications.

{
  "vconcat": [
    ...  // Specifications
  ],
  ...
}

In addition to common properties of a view specification, a vertical concat specification has the following properties:

Property Type Description
vconcat Spec[]

Required. A list of views to be concatenated and put into a column.

Example

General (Wrappable) Concatenation

To put multiple views into a flexible flow layout, set the "concat" to an array of view specifications and specify the "columns" property to set the number of maximum items per rows.

{
  "concat": [
    ...  // Specifications
  ],
  "columns": ...,
  ...
}

In addition to common properties of a view specification, a general concat specification has the following properties:

Property Type Description
concat Spec[]

Required. A list of views to be concatenated.

columns Number

The number of columns to include in the view composition layout.

Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat).

Note:

1) This property is only for:

  • the general (wrappable) concat operator (not hconcat/vconcat)
  • the facet and repeat operator with one field/repetition definition (without row/column nesting)

2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat).

Example

Resolve

The default resolutions for concatenation are independent scales and axes for position channels and shared scales and legends for all other channels. Currently, Vega-Lite does not support shared axes for concatenated views.

Concat Configuration

// Top-level View Specification
{
  ...,
  "config": { // Configuration Object

    "concat": { // - Concat Configuration
      "spacing": ...,
      "columns": ...,
    },
    ...
  }
}

The concat configuration supports the following properties:

Property Type Description
columns Number

The number of columns to include in the view composition layout.

Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat).

Note:

1) This property is only for:

  • the general (wrappable) concat operator (not hconcat/vconcat)
  • the facet and repeat operator with one field/repetition definition (without row/column nesting)

2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat).

spacing Number

The default spacing in pixels between composed sub-views.

Default value: 20