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

Bar

Edit this page
// Single View Specification
{
  "data": ... ,
  "mark": "bar",
  "encoding": ... ,
  ...
}

Bar marks are useful in many visualizations, including bar charts, stacked bar charts, and timelines.

Documentation Overview

Bar Mark Properties

// Single View Specification
{
  ...
  "mark": {
    "type": "bar",
    ...
  },
  "encoding": ... ,
  ...
}

A bar mark definition can contain any standard mark properties and the following special properties:

Property Type Description
orient String

The orientation of a non-stacked bar, tick, area, and line charts. The value is either horizontal (default) or vertical.

  • For bar, rule and tick, this determines whether the size of the bar and tick should be applied to x or y dimension.
  • For area, this property determines the orient property of the Vega output.
  • For line and trail marks, this property determines the sort order of the points in the line if config.sortLineBy is not specified. For stacked charts, this is always determined by the orientation of the stack; therefore explicitly specified value will be ignored.
binSpacing Number

Offset between bars for binned field. Ideal value for this is either 0 (Preferred by statisticians) or 1 (Vega-Lite Default, D3 example style).

Default value: 1

cornerRadius Number

The radius in pixels of rounded rectangle corners.

Default value: 0

Examples

Single Bar Chart

Mapping a quantitative field to either x or y of the bar mark produces a single bar chart.

Bar Chart

If we map a different discrete field to the y channel, we can produce a horizontal bar chart. Specifying scale.rangeStep of the discrete field will adjust the band and point scale’s range step.

While the bar mark typically uses the x and y channels to encode a pair of discrete and continuous fields, it can also be used with continuous fields on both channels. For example, given a bar chart with a temporal field on x, we can see that the x-scale is a continuous scale. By default, the size of bars on continuous scales will be set based on the continuousBandSize config.

If you want to use a discrete scale instead, you can cast the field to have an "ordinal" type. This casting strategy can be useful for time units with low cardinality such as "month".

Histogram

If the data is not pre-aggregated (i.e. each record in the data field represents one item), mapping a binned quantitative field to x and aggregate count to y produces a histogram.

If you prefer to have histogram without gaps between bars, you can set the binSpacing mark property to 0.

Stacked Bar Chart

Adding color to the bar chart (by using the color attribute) creates a stacked bar chart by default. Here we also customize the color’s scale range to make the color a little nicer. (See stack for more details about customizing stack.)

Layered Bar Chart

To disable stacking, you can alternatively set stack to null. This produces a layered bar chart. To make it clear that bars are layered, we can make marks semi-transparent by setting the opacity to a value between 0 and 1 (e.g., 0.7).

Normalized Stacked Bar Chart

You can also create a normalized stacked bar chart by setting stack to "normalize". Here we can easily see the percentage of male and female population at different ages.

Grouped Bar Chart

Faceting a bar chart produces a grouped bar chart.

Ranged Bars

Specifying x2 or y2 for the quantitative axis of bar marks creates ranged bars. For example, we can use ranged bars to create a gantt chart.

Bar Config

// Top-level View Specification
{
  ...
  "config": {
    "bar": ...,
    ...
  }
}

The bar property of the top-level config object sets the default properties for all bar marks. If mark property encoding channels are specified for marks, these config values will be overridden.

Besides standard mark properties, bar config can contain the following additional properties:

Property Type Description
binSpacing Number

Offset between bars for binned field. Ideal value for this is either 0 (Preferred by statisticians) or 1 (Vega-Lite Default, D3 example style).

Default value: 1

continuousBandSize Number

The default size of the bars on continuous scales.

Default value: 5

discreteBandSize Number

The size of the bars. If unspecified, the default size is bandSize-1, which provides 1 pixel offset between bars.