Skip to content

Rule

Rule mark displays each data item as a line segment. Rules can span the whole width or height of the view. Alternatively, they may have specific endpoints.

{
  "data": {
    "sequence": { "start": 0, "stop": 15, "as": "y" }
  },
  "mark": {
    "type": "rule",
    "strokeDash": [6, 3]
  },
  "encoding": {
    "x": { "field": "y", "type": "quantitative" },
    "color": { "field": "y", "type": "nominal" }
  }
}

Channels

Rule mark supports the primary and secondary position channels and the color, opacity, and size channels.

Properties

clip
Type: boolean | "never"

If true, the mark is clipped to the UnitView's rectangle. By default, clipping is enabled for marks that have zoomable positional scales.

color
Type: string | ExprRef

Color of the mark. Affects either fill or stroke, depending on the filled property.

minBufferSize
Type: number

Minimum size for WebGL buffers (number of data items). Allows for using bufferSubData() to update graphics.

This property is intended for internal use.

minLength
Type: number | ExprRef

The minimum length of the rule in pixels. Use this property to ensure that very short ranged rules remain visible even when the user zooms out.

Default value: 0

opacity
Type: number | ExprRef

Opacity of the mark. Affects fillOpacity or strokeOpacity, depending on the filled property.

size
Type: number | ExprRef

Stroke width of "link" and "rule" marks in pixels, the area of the bounding square of "point" mark, or the font size of "text" mark.

strokeCap
Type: "butt" | "square" | "round" | ExprRef

The style of stroke ends. Available choices: "butt", "round", and "square".

Default value: "butt"

strokeDash
Type: array

An array of of alternating stroke and gap lengths or null for solid strokes.

Default value: null

strokeDashOffset
Type: number

An offset for the stroke dash pattern.

Default value: 0

tooltip
Type: HandledTooltip | null

Tooltip handler. If null, no tooltip is shown. If string, specifies the tooltip handler to use.

x
Type: number | ExprRef

Position on the x axis.

x2
Type: number | ExprRef

The secondary position on the x axis.

xOffset
Type: number

Offsets of the x and x2 coordinates in pixels. The offset is applied after the viewport scaling and translation.

Default value: 0

y
Type: number | ExprRef

Position on the y axis.

y2
Type: number | ExprRef

The secondary position on the y axis.

yOffset
Type: number

Offsets of the y and y2 coordinates in pixels. The offset is applied after the viewport scaling and translation.

Default value: 0

Examples

Ranged rules

{
  "data": {
    "values": [
      { "y": "A", "x": 2, "x2": 7 },
      { "y": "B", "x": 0, "x2": 3 },
      { "y": "B", "x": 5, "x2": 6 },
      { "y": "C", "x": 4, "x2": 8 },
      { "y": "D", "x": 1, "x2": 5 }
    ]
  },
  "mark": {
    "type": "rule",
    "size": 10,
    "strokeCap": "round"
  },
  "encoding": {
    "y": { "field": "y", "type": "nominal" },
    "x": { "field": "x", "type": "quantitative" },
    "x2": { "field": "x2" }
  }
}

Plenty of diagonal rules

{
  "width": 300,
  "height": 300,

  "data": {
    "sequence": { "start": 0, "stop": 50 }
  },

  "transform": [
    {
      "type": "formula",
      "expr": "random()",
      "as": "x"
    },
    {
      "type": "formula",
      "expr": "datum.x + random() * 0.5 - 0.25",
      "as": "x2"
    },
    {
      "type": "formula",
      "expr": "random()",
      "as": "y"
    },
    {
      "type": "formula",
      "expr": "datum.y + random() * 0.5 - 0.25",
      "as": "y2"
    },
    {
      "type": "formula",
      "expr": "random()",
      "as": "size"
    }
  ],

  "mark": {
    "type": "rule",
    "strokeCap": "round"
  },

  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative"
    },
    "x2": { "field": "x2" },
    "y": {
      "field": "y",
      "type": "quantitative"
    },
    "y2": { "field": "y2" },
    "size": {
      "field": "size",
      "type": "quantitative",
      "scale": { "type": "pow", "range": [0, 10] }
    },
    "color": {
      "field": "x",
      "type": "nominal",
      "scale": { "scheme": "category20" }
    }
  }
}