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

Line

Edit this page
{
  "data": ... ,
  "mark": "line",
  "encoding": ... ,
  ...
}

The line mark represents the data points stored in a field with a line connecting all of these points. Line marks are commonly used to depict trajectories or change over time. Unlike most other marks that represent one data element per mark, one line mark represents multiple data element as a single line, akin to area and trail.

Note: For line segments that connect (x,y) positions to (x2,y2) positions, please use rule marks. For continuous lines with varying size, please use trail marks.

Documentation Overview

Line Mark Properties

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

An line mark definition can contain any standard mark properties and the following line interpolation and point overlay 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.
interpolate String

The line interpolation method to use for line and area marks. One of the following:

  • "linear": piecewise linear segments, as in a polyline.
  • "linear-closed": close the linear segments to form a polygon.
  • "step": alternate between horizontal and vertical segments, as in a step function.
  • "step-before": alternate between vertical and horizontal segments, as in a step function.
  • "step-after": alternate between horizontal and vertical segments, as in a step function.
  • "basis": a B-spline, with control point duplication on the ends.
  • "basis-open": an open B-spline; may not intersect the start or end.
  • "basis-closed": a closed B-spline, as in a loop.
  • "cardinal": a Cardinal spline, with control point duplication on the ends.
  • "cardinal-open": an open Cardinal spline; may not intersect the start or end, but will intersect other control points.
  • "cardinal-closed": a closed Cardinal spline, as in a loop.
  • "bundle": equivalent to basis, except the tension parameter is used to straighten the spline.
  • "monotone": cubic interpolation that preserves monotonicity in y.
tension Number

Depending on the interpolation type, sets the tension parameter (for line and area marks).

point Boolean | OverlayMarkDef | String

A flag for overlaying points on top of line or area marks, or an object defining the properties of the overlayed points.

  • If this property is "transparent", transparent points will be used (for enhancing tooltips and selections).

  • If this property is an empty object ({}) or true, filled points with default properties will be used.

  • If this property is false, no points would be automatically added to line or area marks.

Default value: false.

Examples

Line Chart

Using line with one temporal or ordinal field (typically on x) and another quantitative field (typically on y) produces a simple line chart with a single line.

We can add create multiple lines by grouping along different attributes, such as color or detail.

Multi-series Colored Line Chart

Adding a field to a mark property channel such as color groups data points into different series, producing a multi-series colored line chart.

Multi-series Line Chart with the Detail Channel

To group lines by a field without mapping the field to any visual properties, we can map the field to the detail channel to create a multi-series line chart with the same color.

The same method can be used to group lines for a ranged dot plot.

Line Chart with Point Markers

By setting the point property of the mark definition to true or an object defining a property of the overlaying point marks, we can overlay point markers on top of line. Here we set the point color to "red" and set the line color to "green".

This is equilvalent to adding another layer of filled point marks.

Note that the overlay point marks have opacity = 1 by default (instead of semi-transparent like normal point marks).

Line Chart with Invalid Values

By default, data points with invalid x- or y-values (null or NaN) will cause break in the lines.

Note that individual points without connecting points will still be invisible by default.

To show individual points without connecting points, you may set strokeCap to "square":

or overlay it with marker points:

Connected Scatter Plot (Line Chart with Custom Path)

As shown in previous example, the line’s path (order of points in the line) is determined by data values on the temporal/ordinal field by default. However, a field can be mapped to the order channel for determining a custom path.

For example, to show a pattern of data change over time between gasoline price and average miles driven per capita we use order channel to sort the points in the line by time field (year). In this example, we also use the point property to overlay point marks over the line marks to highlight each data point.

Line interpolation

The interpolate property of a mark definition can be used to change line interpolation method. For example, we can set interpolate to "monotone".

We can also set interpolate to "step-after" to create a step-chart.

For the list of all supported interpolate properties, please see the mark definition documentation.

Geo Line

By mapping geographic coordinate data to longitude and latitude channels of a corresponding projection, we can draw lines through geographic points.

Line Config

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

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

The line config can contain any line mark properties (except type, style, and clip).