How to create external tooltips

External tooltips can be used to display the tooltips outside of the iframe. This is useful when you want to  customize the size and style of your tooltip box or if you want the tooltips to be visible regardless of the position of the visualization. 

This article is for advanced Datawrapper users and it may be helpful to have basic knowledge of HTML/CSS/Javascript. For those with a good understanding of event listeners and Javascript, we recommend that you go directly to Gregor Aisch's original blog post that this was based on here. 

See the Pen External Tooltip demo

Here are the steps to create an external tooltip like the above: 

1. Create a chart/map and embed it into your website 

2. Add an events.js script to your website which includes the datawrapper.on helper function (explained in step 3). One way to do this is to go into the HTML source code of your webpage where your visualization is embedded and add the following line in the <header> part of your HTML code. 

<script src="//static.dwcdn.net/js/events.js"></script>

3. Now, let's say that we want to turn a tooltip like the one below into an external tooltip: 

This is what it looks like in the Datawrapper tooltip editor: 

To recreate the tooltip as an external tooltip, you will have to include the following snippets somewhere in your HTML source code on your web page where the map is embedded. 

<style>
h3,p {
    font-family: Roboto;
    line-height: 1.35
    max-width: 600px;
    margin: 1em auto !important;
}

.tooltip {
    position: fixed;
    left: 5px;
    right: 5px;
    bottom: 5px;
    /* change the background color below to change the tooltip background */
    background: #fffbc1;
    padding: 10px;
    border: 1px solid #f5f5f5;
    display: none;
    box-shadow: 3px 3px 3px rgba(0, 0, 0, .1);
}
</style>

<script>
const tooltip = document.querySelector('.tooltip');

    datawrapper.on('region.mouseenter', ({ chartId, data }) => {
	// first we want to check the chart id, since there could be multiple charts on the page
      if (chartId === 'yc0Gv') {
	// now we can show tooltip. 
        // data contains the data the user uploaded to the map.
    tooltip.innerHTML = `
        <h3>${ data.region }, ${ data.country }</h3>
        <p><big>${ data.average }%</big> annual average population growth between 2001 and 2016</p>
        `;
        tooltip.style.display = 'block';
      }
    });
    datawrapper.on('region.mouseleave', ({ chartId }) => {
      if (chartId === 'yc0Gv') {
	// hide the tooltip
        tooltip.style.display = 'none';
      }
    });
</script>

Now let's break this down! 

The first half wrapped in <style> tag determines what the external tooltip should look like. The second half wrapped in <script> tag is 'listens out' for interactions between readers and the map and displays/hides the tooltip when a reader hovers over a region. These interactions are called events and there are many events you can listen out for. To create an external tooltip for a  choropleth map, there are two relevant events that are being used in this example: region.mouseenter event and region.mouseleave event. The events you should listen out for will be different depending on the chart/map type. Find the full list of events in our developer docs. 

To get started on customizing the above snippets for your own needs: 

1. Replace chartId 'yc0Gv' with the one from your own chart/map 
2. Replace the text inside tooltip.innerHTML = `...` with your own tooltip code. In the Datawrapper tooltip editor, you can insert placeholders using the column name from your dataset. For example, the names of the regions can be inserted using the placeholder {{ region }}. For external tooltips, the placeholders can be accessed via the events.data object. For example, {{ region }} becomes ${data.region} and {{ country }} becomes ${data.country}. Note that inserted variables are case-sensitive and should exactly match the casing of the column title in your dataset.

That's it! For more details and examples, see this blog post here.

If you have any questions, reach out to support@datawrapper.de.