Web components

Datawrapper visualizations can be embedded as web components by using the Embed with script embed code that is provided in the Publish step once you have published your visualization:

The “script embed” option uses the web components standard. Using this will insert your Datawrapper visualizations directly into your website using a custom element called <datawrapper-visualization>.

The HTML markup and styles for the embedded visualization are encapsulated within the web component (using a technology called Shadow DOM), so the styles won’t affect the embedding website.

This is how a typical script embed code looks:

   <script type="text/javascript" defer 
      <img src="https://datawrapper.dwcdn.net/b3TBj/full.png" alt="[aria-description]" />

For maximum compatibility, the embed code includes an image fallback in case the page is opened in a browser without JavaScript enabled. If you’re curious to see what script embeds look like under the hood, inspect the table embedded further down in this blog post.

To learn why you should consider embedding your Datawrapper visualizations with web components instead of iframes, read this feature announcement on our blog.

What do I have to consider before using the new script embed?

We recommend you create an unlisted test page on your website to try out the new embed before using it on production. One requirement is that your CMS allow you to insert custom JavaScript tags. But chances are good that if you used our responsive iframe embeds before, the new script embeds will also work for you.

If you use our self-hosting feature to publish your visualizations on a custom domain, you need to ensure it supports CORS requests from the website in which you are embedding visualizations.

How can I pass render flags to enforce dark mode or other behaviors?

With iframe embeds, you could set certain render flags via query parameters, such as ?dark=1. With the new script embed, you can do the same by setting the flags as data attributes to the script tag:

    type="text/javascript" defer 
    data-dark="true" data-logo="on">

What browsers support the new script embed?

Browser support for the Web Components standard is over 95%. All major browsers support it. If a browser without web component support encounters your visualization, the embed will fall back to an iframe. If it is rendered in a browser with JavaScript disabled, it will fall back to a static PNG image of the visualization.

Won’t the JavaScript code interfere with the code of the embedding website?

We took great precautions so that this won’t happen. Our visualization code doesn’t load or inject external dependencies into the global scope of the website it’s embedded in. The embed will only add a global datawrapper object to the window scope, which is used for sharing resources.

The visualization code also doesn’t make any DOM changes, with one exception: custom elements can’t define their own web fonts, so we have to inject these fonts into the embedding page (but we’ll only do so if the font is not already loaded).

What happens if my visualization links to another visualization via <a target=“_self”>?

In visualizations embedded as an iframe, you could link to other visualizations that open within the same iframe using a trick we explained in our Academy here. This will also work without iframes. Our embed script will detect these links and load a different visualization into the same spot when they are clicked.

Are my existing visualizations compatible with the script embed?

Yes, but you need to re-publish the visualization if it has been last published before March 3rd, 2023. You can see when the visualization was published last by clicking on it in the Datawrapper Archive. In general, if you’re embedding multiple visualizations on the same page, we recommend you publish the visualizations around the same time.