Group Marks

Jeffrey Heer edited this page Mar 7, 2017 · 10 revisions

This wiki documents Vega version 2. For Vega 3 documentation, see

WikiDocumentationGroup Marks

Group marks are a special kind of mark that can contain other marks. A group mark definition is in many ways similar to the top-level Visualization definition: a group can contain scales, axes, legends and marks. However, note that one can not set top-level width, height, padding or data definitions. Instead, group marks use the same "from" data definition and visual property sets as other marks.

Group marks can be used in a variety of designs. For example:

  • To incorporate multiple visualizations within the same Vega specification.
  • To create layered or stacked visualizations, in which each layer or stack contains a different subset of data.
  • To create small multiples displays in which a visualization design is systematically repeated over different data subsets.

Visual Properties

Group marks support the same visual properties as rect marks. For instance, group marks can have x, y, width, and height values, as well as fill and stroke properties (fill, fillOpacity, stroke, strokeOpacity, strokeWidth, strokeDash, strokeDashOffset). By default, group marks have no stroke or fill, and inherit the spatial properties of their parent group or top-level visualization.

Group marks also support the following additional properties:

Property Type Description
clip ValueRef → Boolean If true, and the group's width and height properties are specified, the contents of the group are clipped to its dimensions (i.e., any overflow is hidden).

Backing Data

Group marks are populated from data just like any other mark: the from property defines a source data set along with any desired data transforms. One group instance will be created for each element in the backing data set. If no from property is specified, the group will receive data from its parent group (if it is nested within another group) or will be backed by a single null value (if it is a top-level group).

Groups differ from other mark types in their ability to contain children marks. Marks defined within a group mark can inherit data from their parent group. For inheritance to work each data element for a group must contain data elements of its own. This arrangement of nested data is typically achieved by facetting the data, such that each group-level data element includes its own array of sub-elements. Facets can be constructed using the facet or window data transforms (see the Data Transforms page) or can be loaded directly as hierarchical data (e.g., using the treejson data type, see the Data page for more).

Scales, Axes and Legends

Groups can also contain their own scales, axes, and legends definitions. These definitions are the same as those used in a top-level visualization definition, barring a few simple differences:

  • Scales, axes and legends defined at the group level reference the width and height values of the current group, not the top-level visualization.
  • If a scale is defined using the same name as a previously defined scale, the pre-existing scale will be shadowed (overloaded) by the new definition within the context of this group. Scale definitions cascade, so that any (non-shadowed) scales defined at a higher level are still accessible.
  • Scale domain definitions can omit the (normally required) "data" property. If no "data" property is provided in the domain definition, the group-level data will be used to determine the domain. Note that this group-level data is exactly the same data that gets passed along to child marks.


Groups are perhaps more easily understood by example. The visualization specifications included with the online Vega editor showcase a number of use cases for groups, including:

  • The stacked_area and jobs examples use a facet transform to gather data into individual series (or stacks). A group mark is then used to layer each stack. In this case, each group has the same position.
  • The barley example similarly uses facets and group marks, but rather than layering data, each sub-group is placed in its own plot to create a small multiples display. In addition, a group-level scale is used to conveniently place items along the y-axis in each plot.
  • The grouped_bar example uses the group mark to subdivide data to create a grouped bar chart display.
  • The scatter_matrix example uses the cross transform and group marks to create a scatter plot matrix display.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.