Rect¶

Rect mark displays each data object as a rectangle.

{
  "data": {
    "sequence": { "start": 0, "stop": 20, "as": "z" }
  },
  "transform": [
    { "type": "formula", "as": "x", "expr": "random()" },
    { "type": "formula", "as": "x2", "expr": "datum.x + random() * 0.3" },
    { "type": "formula", "as": "y", "expr": "random()" },
    { "type": "formula", "as": "y2", "expr": "datum.y + random() * 0.4" }
  ],
  "mark": {
    "type": "rect",
    "strokeWidth": 2,
    "stroke": "#404040",
    "cornerRadius": 5
  },
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "x2": { "field": "x2" },
    "y": { "field": "y", "type": "quantitative" },
    "y2": { "field": "y2" },
    "color": { "field": "z", "type": "quantitative" }
  }
}

Channels¶

Rect mark supports the primary and secondary position channels and the color, stroke, fill, opacity, strokeOpacity, fillOpacity, and strokeWidth 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.

cornerRadius

Type: number | ExprRef

Radius of the rounded corners.

Default value: 0

cornerRadiusBottomLeft

Type: number | ExprRef

Radius of the bottom left rounded corner. Has higher precedence than cornerRadius.

Default value: (None)

cornerRadiusBottomRight

Type: number | ExprRef

Radius of the bottom right rounded corner. Has higher precedence than cornerRadius.

Default value: (None)

cornerRadiusTopLeft

Type: number | ExprRef

Radius of the top left rounded corner. Has higher precedence than cornerRadius.

Default value: (None)

cornerRadiusTopRight

Type: number | ExprRef

Radius of the top right rounded corner. Has higher precedence than cornerRadius.

Default value: (None)

fill

Type: string | ExprRef

The fill color.

fillOpacity

Type: number | ExprRef

The fill opacity. Value between 0 and 1.

filled

Type: boolean

Whether the color represents the fill color (true) or the stroke color (false).

hatch

A hatch pattern drawn inside the mark using the stroke width, color, and opacity. The pattern is aligned in screen space and scaled by the stroke width.

Default value: "none"

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.

minHeight

Type: number | ExprRef

The minimum height of a rectangle in pixels. The property clamps rectangles' heights.

Default value: 0

minOpacity

Type: number | ExprRef

Clamps the minimum size-dependent opacity. The property does not affect the opacity channel. Valid values are between 0 and 1.

When a rectangle would be smaller than what is specified in minHeight and minWidth, it is faded out proportionally. Example: a rectangle would be rendered as one pixel wide, but minWidth clamps it to five pixels. The rectangle is actually rendered as five pixels wide, but its opacity is multiplied by 0.2. With this setting, you can limit the factor to, for example, 0.5 to keep the rectangles more clearly visible.

Default value: 0

minWidth

Type: number | ExprRef

The minimum width of a rectangle in pixels. The property clamps rectangles' widths when the viewport is zoomed out.

This property also reduces flickering of very narrow rectangles when zooming. The value should generally be at least one.

Default value: 1

opacity

Type: number | ExprRef

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

shadowBlur

Type: number | ExprRef

The blur radius of the drop shadow in pixels. Higher values produce a more diffuse shadow.

Default value: 0

shadowColor

Type: string | ExprRef

The color of the drop shadow. Any valid CSS color string is allowed.

Default value: "black"

shadowOffsetX

Type: number | ExprRef

The horizontal offset of the drop shadow in pixels. Positive values move the shadow to the right.

Default value: 0

shadowOffsetY

Type: number | ExprRef

The vertical offset of the drop shadow in pixels. Positive values move the shadow downward.

Default value: 0

shadowOpacity

Type: number | ExprRef

The opacity of the drop shadow. Value between 0 (fully transparent) and 1 (fully opaque).

Default value: 0 (disabled)

stroke

Type: string | ExprRef

The stroke color

strokeOpacity

Type: number | ExprRef

The stroke opacity. Value between 0 and 1.

strokeWidth

Type: number | ExprRef

The stroke width in pixels.

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¶

Heatmap¶

When used with "band" or "index" scales, the rectangles fill the whole bands when only the primary positional channel is defined.

{
  "data": {
    "sequence": { "start": 0, "stop": 800, "as": "z" }
  },
  "transform": [
    { "type": "formula", "as": "y", "expr": "floor(datum.z / 40)" },
    { "type": "formula", "as": "x", "expr": "datum.z % 40" },
    {
      "type": "formula",
      "as": "z",
      "expr": "sin(datum.x / 8) + cos(datum.y / 10 - 0.5 + sin(datum.x / 20) * 2)"
    }
  ],
  "mark": "rect",
  "encoding": {
    "x": { "field": "x", "type": "index" },
    "y": { "field": "y", "type": "index" },
    "color": {
      "field": "z",
      "type": "quantitative",
      "scale": {
        "scheme": "magma"
      }
    }
  }
}

Bars¶

{
  "data": {
    "sequence": { "start": 0, "stop": 60, "as": "x" }
  },
  "transform": [
    {
      "type": "formula",
      "expr": "sin((datum.x - 30) / 4) + (datum.x - 30) / 30",
      "as": "y"
    }
  ],
  "mark": "rect",
  "encoding": {
    "x": { "field": "x", "type": "index", "scale": { "padding": 0.1 } },
    "y": { "field": "y", "type": "quantitative" },
    "y2": { "datum": 0 },
    "color": {
      "field": "y",
      "type": "quantitative",
      "scale": {
        "type": "threshold",
        "domain": [0],
        "range": ["#ed553b", "#20639b"]
      }
    }
  }
}

Hatch Patterns¶

Rect marks can be filled with hatch patterns using the hatch property. The hatch pattern is drawn inside the mark with the stroke color and stroke opacity, aligned in screen space and scaled by the stroke width. The value can be a fixed pattern string (such as "diagonal" or "dots") or an expression that evaluates to one of these patterns.

The hatch pattern is currently a mark property, i.e., the same for all instances of the mark, but may be promoted to a visual channel in the future to allow different hatch patterns for different data points.

{
  "params": [
    {
      "name": "hatch",
      "value": "diagonal",
      "bind": {
        "input": "select",
        "options": [
          "none",
          "diagonal",
          "antiDiagonal",
          "cross",
          "vertical",
          "horizontal",
          "grid",
          "dots",
          "rings",
          "ringsLarge"
        ]
      }
    },
    {
      "name": "strokeWidth",
      "value": 2,
      "bind": { "input": "range", "min": 0, "max": 50, "step": 0.25 }
    }
  ],
  "data": { "values": {} },
  "mark": {
    "type": "rect",
    "fill": "#caf0f8",
    "stroke": "black",
    "strokeWidth": { "expr": "strokeWidth" },
    "hatch": { "expr": "hatch" }
  }
}

Drop Shadow¶

Shadowed marks¶

{
  "padding": 20,
  "data": { "values": [1, 2, 3, 4] },
  "mark": {
    "type": "rect",
    "shadowOpacity": 0.4,
    "shadowBlur": 20,
    "shadowOffsetX": 10,
    "shadowOffsetY": 10,
    "clip": true
  },
  "encoding": {
    "x": { "field": "data", "type": "ordinal", "scale": { "padding": 0.3 } },
    "y": {
      "field": "data",
      "type": "quantitative",
      "scale": { "padding": 0.1 }
    }
  }
}

Shadowed view¶

As the view background is a rect, it can also be decorated with a shadow.

{
  "padding": 20,
  "view": {
    "shadowOpacity": 0.2,
    "shadowBlur": 15,
    "shadowOffsetY": 3
  },
  "data": { "values": [1, 2, 3, 4] },
  "mark": "rect",
  "encoding": {
    "x": { "field": "data", "type": "ordinal", "scale": { "padding": 0.3 } },
    "y": {
      "field": "data",
      "type": "quantitative",
      "scale": { "padding": 0.1 }
    }
  }
}