Extensibility API

Vega can be extended at runtime with new scales, projections, color schemes, and data transforms. While sometimes useful for custom deployments, keep in mind that extending Vega with new components can result in Vega JSON specifications that others may not be able to use directly.

Extensibility API Reference

Projections

# vega.projection(type[, projection]) <>

Registry function for adding and accessing cartographic projections. The type argument is a String indicating the name of the projection type. If the projection argument is not specified, this method returns the matching projection constructor in the registry, or null if not found. If the projection argument is provided, it must be a projection constructor function to add to the registry under the given type name.

By default, Vega includes all cartographic projections provided by the d3-geo library. Projections created using the constructor returned by this method have an additional copy method that generates a new clone of a projection. Vega can be extended with additional projections, such as those found in the d3-geo-projection library. For example:

// d3-geo-projections must be imported and added to d3 object
// to register with Vega, provide a name and d3 projection function
vega.projection('winkel3', d3.geoWinkel3);

// Vega parser and runtime now support the 'winkel3' projection
var runtime = vega.parse({
  ...,
  "projections": [
    { "name": "proj", "type": "winkel3" }
  ],
  ...
});

Scales

# vega.scale(type[, scale]) <>

Registry function for adding and accessing scale constructor functions. The type argument is a String indicating the name of the scale type. If the scale argument is not specified, this method returns the matching scale constructor in the registry, or null if not found. If the scale argument is provided, it must be a scale constructor function to add to the registry under the given type name.

By default, the scale registry includes entries for all scale types provided by the d3-scale module. Scales created using the constructor returned by this method have an additional type property indicating the scale type. All scales supporting either an invert or invertExtent method are augmented with an additional invertRange function that returns an array of corresponding domain values for a given interval in the scale’s output range.

// linear scale
var linear = vega.scale('linear');
var scale = linear().domain([0, 10]).range([0, 100]);
scale.type; // 'linear'
scale.invertRange([0, 100]); // [0, 10]
var ordinal = vega.scale('ordinal');

// ordinal scale
var scale1 = ordinal().domain(['a', 'b', 'c']).range([0, 1, 2]);
scale1.type; // 'ordinal'

// ordinal scale with range set to the 'category20' color palette
var scale2 = ordinal().range(vega.scheme('category20'));
var seq = vega.scale('sequential');

// sequential scale, using the plasma color palette
var scale1 = seq().interpolator(vega.scheme('plasma'));
scale1.type; // 'sequential'

Color Schemes

# vega.scheme(name[, scheme]) <>

Registry function for adding and accessing color schemes. The name argument is a String indicating the name of the color scheme. If the scheme argument is not specified, this method returns the matching scheme value in the registry, or undefined if not found. If the scheme argument is provided, it must be a valid color array or interpolator to add to the registry under the given name.

By default, the scheme registry includes entries for all scheme types provided by the d3-scale-chromatic module. Valid schemes are either arrays of color values (e.g., applicable to 'ordinal' scales) or interpolator functions (e.g., applicable to 'sequential' scales.)

# vega.schemeDiscretized(name[, schemes, interpolator]) <>

Registry function for adding and accessing discretized color schemes, consisting of an array of color schemes for specific value counts. The name argument is a String indicating the name of the color scheme. If the schemes argument is not specified, this method returns the matching array of color schemes value in the registry, or undefined if not found. If the schemes argument is provided, it must be an array of valid color arrays, with non-null entries at indices for each supported value count. For example, the array at index 3 should be a 3-color array. The optional interpolator argument provides a continuous color interpolator to use when a specific item count is not provided or undefined. If the interpolator argument is not provided, an interpolator will be automatically created using basis spline interpolation in the RGB color space for the last (largest) color array in schemes.

Transforms

# vega.transforms <>

An object that maps transform names to transform constructors. To add a new transform to Vega, assign the transform to this object under the desired name.

In order to parse transform references within a Vega specification, the transform constructor must also have a Definition property that provides the necessary metadata and parameter information. The vega-transforms repository includes a collection of transforms demonstrating the syntax of definition objects.

Note that if a transform is added at runtime, any Vega JSON specifications using the new transform will fail JSON schema validation, as the new transform is not included in the default schema definition. To include new transforms within a custom JSON schema, developers can create a custom Vega build, adding new transforms to the vega-dataflow transforms export during the build process.

Data Formats

# vega.formats(name[, format]) <>

Registry function for data format parsers. If invoked with two arguments, adds a new format parser with the provided name. Otherwise, returns an existing parser with the given name. The method signature of a format parser is:

  • format(data, options)

A format parser that accepts two arguments, the input data to parse (e.g., a block of CSV text) and a set of format-specific options. The following data formats are registered by default:

  • dsv: Delimiter-separated values format. Each line of text is a record, with each field separated by a delimiter string. Accepts a delimiter option indicating the delimiter string used to separate field values.
  • csv: Comma-separated values format. A dsv instance with a comma (,) delimiter.
  • tsv: Tab-separated values format. A dsv instance with a tab (\t) delimiter.
  • json: JavaScript Object Notation (JSON) format. Accepts a property option, indicating a sub-property of the parsed JSON to return; useful if a data array is nested within a larger object.
  • topojson: TopoJSON format for compressed encoding of geographic data. Requires either a feature option indicating the name of the geographic feature to extract (e.g., extracts individual paths for all countries), or a mesh option indicating a feature name for which a single mesh should be extracted (e.g., all country boundaries in a single path). Please see the TopoJSON documentation for more.

Expression Functions

# vega.expressionFunction(name[, fn, visitor]) <>

Registry function for adding and accessing expression functions. The name argument is a String indicating the name of the function, as used within the Vega expression language. If the fn argument is not specified, this method returns the matching function value in the registry, or undefined if not found. If the fn argument is provided, it must be a valid JavaScript function to add to the registry under the given name. Once added, the parser will accept Vega specifications with expressions invoking this named function.

The visitor argument is an expression AST (abstract syntax tree) visitor function which can be used to perform dependency analysis (e.g., for scale or data source lookups), and is used internally by Vega. For most basic functions no visitor is needed, in which case this argument can be omitted.

Note that new expressions must be added before parsing a spec that uses the custom function. After registering a new expression function, all subsequently parsed Vega specifications will have access to the function.