How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 1 - Dev Env Setup, Reference and Testing

UPDATE: The Liquid Fill Gauge visual is now available to download from the Power BI Custom Visual Gallery!

I’ve been digging into the new Power BI Custom Visual SDK and just pushed my first visual called Liquid Fill Gauge. It’s a circle gauge that represents a percentage value. All it does at the moment is display the value and nothing is configurable. I will continue to push new features as I finish them. It is based off of Curtis Bratton‘s Liquid Fill Gauge. The premise of this post is to take an existing open source d3 visual and see how easy it is to create a Power BI Custom Visual out of it.

This is Part 1 of the series, here are the other posts:
2. How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 2 - Capabilities, dataRoles and dataViewMappings

3. How to Create a Power BI Custom Visual Based on an Existing d3 Visual - Part 3 - Custom Format Properties

You can download the visual and use within your reports here:

Setup Power BI Custom Visual Dev Environment

Follow the instructions here to get your dev env setup:

Clone Repo

Open Code

I use VS Code, but feel free to use any editor.

I walk through each step below – feel free to skim through it, use it as a reference or follow along step-by-step.

Create Custom Visual

This uses the new SDK to create a custom visual template.

This is what the dir structure looks like in VS Code.


Reference d3 Typings

You create Custom Visuals using TypeScript and d3, but d3 isn’t referenced by default in the new Custom Visual SDK. Here’s How to get it installed and referenced so TypeScript can see it.

Go to this post for instructions on how to add d3 to your visual and then come back here.

Add liquidFillGauge.js File

1. Create a file in the “src” folder called “liquidFillGauge.js”.
2. Copy the code from the following file into it. If you cloned the repo, you will have this file locally as well.

=====The following is informational only, you do not need to make these changes===

The liquidFillGauge was originally pushed to GitHub as a stand alone d3 visual. I only had to change a the following two things about it for it to work with Power BI.

  • PowerBI puts all Custom Visuals in IFRAMEs so the clip-path needs to reference the absolute url of the page like so:
  • Once I deployed my visual to I ran into another IFRAME issue that required me to pass in the d3 selection instance, versus doing the inside the visual. Instead of passing in elementId, I pass in a reference to the svg element

Add TypeScript Definition File

The premise of this exercise is to take an existing d3 visual and easily turn it into a custom visual without having to rewrite the entire thing in TypeScript. What I would like to do is clone the existing visual and reference it from my visual.ts file. In order to do that, I need to make the visual file visual in TypeScript. You could define all of the methods and come up with a more sophisticated definition file, but I’ve found that the following works great.

  • Create a new file in the “src” folder called “liquidFillGauge.d.ts” and add the following code to it.

Add liquidFillGauge files to tsconfig.json

  • Open tsconfig.json and add references to the liquidFillGauge.js and liquidFillGauge.d.ts files.

Add liquidFillGauge to visual.ts

  • Open visual.ts and copy the following code into it.

The final step is to add code to the visual.ts file that will call the liquidFillGauge methods and create the visual.

  • Notice the amd-dependency line at the top. This maps the TypeScript type definition to the visual.ts file so we can call loadLiquidFileGage that is in the liquidFillGauge file.
  • I added another local variable to hold a reference to the gauge and then either call loadLiquidFillGauge for the first load or call this.gauge.update for subsequent calls.

Test on

1. Start your local server

2. Go to
3. Create a report that uses your visual
4. Map a data value to the “Measure Data” field. I’m using the Month column in the Dates table in the Customer Profitability Sample dataset.
5. You should then see your custom visual rendered.


If you do not see it, then compare your code to the code in this GitHub repo and fix anything that is different.

Hope this gets you on your way to creating your own visuals.