Custom Shapes - nyurik/vega GitHub Wiki

This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.

Symbols are used in chart marks and legends. There are six predefined symbol shapes: circle, cross, diamond, square, triangle-up and triangle-down. Custom symbols are specified as SVG path strings and are drawn within a unit square, from -0.5 to 0.5 in both the x and y directions. The size mark property determines the area, in pixels, of this unit square and thus can be used to scale custom shapes.

Handlebar notations can be used as part of the path string to perform inline computation. For example, M 0 {{-1 / sqrt(2 * (Math.tan(40 * Math.PI / 180)))}}. Any Vega expression constants and functions may be used within handlebars.

Custom shapes can be specified inline as part of a Vega JSON specification. For example, here we specify that a legend should use squares rather than circles.

"legends": [{
  "fill": "color",
  "properties": {
    "symbols": {
      "size": {"value": 200},
      "shape": {
        "value": "M-0.5,-0.5L0.5,-0.5 0.5,0.5 -0.5,0.5Z"
      }
    }
  }
}]

Alternatively, custom shapes can also be named and defined in a configuration. The keys are the names of custom shapes that can then subsequently be used in specifications.

config.shape = {
  "star": "M0,0.2L0.2351,0.3236 0.1902,0.0618 0.3804,-0.1236 0.1175,-0.1618 0,-0.4 -0.1175,-0.1618 -0.3804,-0.1236 -0.1902,0.0618 -0.2351,0.3236 0,0.2Z"
}

"marks": [{
  "type": "symbol",
  "properties": {
    "enter": {
      "shape": {"value": "star"}
    }
  }
}]

Examples

Although there is a limited set of default shapes, a whole range of custom shapes can be created. Below are a few examples.

#####House

"marks": [{
  "type": "symbol",
  "properties": {
    "enter": {
      "size": {"value": 5000},
      "fill": {"value": "#000"},
      "shape": {
        "value": "M-0.5,0L0,-0.5 0.5,0 0.3,0 0.3,0.5 0.05,0.5 0.05,0.2 -0.05,0.2 -0.05,0.5 -0.3,0.5 -0.3,0 -0.5,0Z"
      }
    }
  }
}]

#####Heart

"marks": [{
  "type": "symbol",
  "properties": {
    "enter": {
      "size": {"value": 40000},
      "fill": {"value": "#000"},
      "shape": {
        "value": "M0.3408,0.0984c0.0507,0,0.0919,0.0413,0.0919,0.0923c0,0.0262,-0.0109,0.0498,-0.0283,0.0666L0.256,0.4071L0.105,0.2546c-0.0158,-0.0166,-0.0256,-0.0391,-0.0256,-0.0639c0-0.051,0.0411,-0.0923,0.0919,-0.0923c0.0382,0,0.0709,0.0234,0.0848,0.0568C0.2698,0.1219,0.3026,0.0984,0.3408,0.0984 M0.3408,0.083z"
      }
    }
  }
}]

By setting the stroke and strokeColor, it is also possible to create an outline of the shape instead.

#####Star

"marks": [{
  "type": "symbol",
  "properties": {
    "enter": {
      "size": {"value": 10000},
      "fill": {"value": "#FFF"},
      "stroke": {"value": "#000"},
      "strokeWidth": {"value": 5},
      "shape": {
        "value": "M0,0.2L0.2351,0.3236 0.1902,0.0618 0.3804,-0.1236 0.1175,-0.1618 0,-0.4 -0.1175,-0.1618 -0.3804,-0.1236 -0.1902,0.0618 -0.2351,0.3236 0,0.2Z"
      }
    }
  }
}]