SSVG Docs

Get Started

Using SSVG to convert your D3 SVG data visualization into a performant canvas visualization couldn’t be easier.

For the simplest use cases, consider using the Automatic Version

Include the following code snippet above your D3 code to initialize SSVG with the default options:

<script src="https://ssvg.io/ssvg-auto.js"></script>

That's all that's necessary. SSVG should work automatically!

For more control over how SSVG works, use the Standard Version

Step 1: Include SSVG in Your Project

You can download the latest version of SSVG from GitHub or use a SSVG CDN.

A simple way to install SSVG is to add a script tag to your HTML page that links to the SSVG CDN:

<script src="https://ssvg.io/ssvg.js"></script>

Step 2: Initialize SSVG

Include the following code snippet above your D3 code to initialize SSVG with the default options:

<script>
    new SSVG();
</script>

Or you can pass an options object to the SSVG constructor. Information about the options object can be found in the options section of the documentation.

Note:

Currently, SSVG must be included & initialized: After D3 has been included, After the opening <body> tag, and Before the visualization code.

Configuration

Pass the optional configuration object to the SSVG constructor when initializing SSVG to adjust aspects of how SSVG works.

Initializing SSVG with the Configuration Object

The following example demonstrates initializing SSVG with the optional configuration object:

<script>
    var configObject = {
      safeMode: false,
      maxPixelRatio: 1,
      useWorker: false,
      
      getFps: function(fps) {
        console.log(fps);
      }
    };

    new SSVG(configObject);
</script>

Configuration Object Properties

The following table summarizes the properties of the configuration object:

Name	Type	Default Value	Description
Name: safeMode	Type: boolean	Default Value: false	Description: By default, SSVG utilizes an optimization technique to batch canvas calls together. Normally, this technique speeds up canvas rendering. However, for some visualizations, this technique can cause rendering issues - most commonly with compositing when rendering overlapping elements. Set safeMode to true to turn off this optimization.
Name: maxPixelRatio	Type: number	Default Value: 2	Description: The maximum pixel ratio that will be used to render the resulting canvas visualization. Rendering at a higher pixel ratio can increase the sharpness of an image on a high pixel density display, but sometimes at the expense of rendering speed. Limiting the pixel ratio can balance performance with image quality.
Name: useWorker	Type: boolean	Default Value: true	Description: Whether a web worker will be used to optimize performance by performing calculations in a background thread.
Name: getFps	Type: function	Default Value: undefined	Description: Expects a function which takes the current FPS of the visualization as its only argument. Use this function to record the visualization's performance.

Turning Off SSVG

For debugging purposes, SSVG provides an escape hatch via URL parameters that allows developers to turn off SSVG and render the original SVG visualization instead of using Canvas.

To turn off SSVG and render the original SVG visualization, add the parameter SVG to the URL.

https://your-original-url?svg

Technical Limitations

SSVG is currently a work in progress. To replace SVG rendering efficiently, there is currently more to implement. SSVG covers the most common use cases, but relies on the community to add support for the many different ways that SVGs are used. Feel free to contribute or report any issues on GitHub.

Known Limitations:

SSVG only supports SVG visualizations made using D3 so far, and only v3+
No stroke-dasharray
No CSS color gradients
No CSS filters
No use of any SVG definitions like arrow heads
No advanced text properties
Many implicit limitations in some of the current simpler architecture. For example, using SVG transformations switches the renderer to a slower, "single element" mode.

CDN Links

The automatic and standard versions of SSVG are both available over CDN.

<script src="https://ssvg.io/ssvg.js"></script>
<script src="https://ssvg.io/ssvg-auto.js"></script>

Troubleshooting

We are currently working on implementing more descriptive and comprehensive error messages for debugging. In the meantime, if you encounter a problem with SSVG, feel free to report the issue on GitHub.