Ankush Bansal Logo
← Back to All Articles

Create Custom Power BI Visuals with D3.js – Step-by-Step Guide

Published on

Learn how to build and import custom Power BI visuals using D3.js. A complete guide for setup, development, packaging, and deployment.

How to Create Custom Visuals in Power BI Using D3.js and Load It into Power BI

Introduction

Power BI is a powerful data visualization tool from Microsoft that offers a wide range of standard visuals like bar charts, pie charts, maps, and tables. However, sometimes the built-in visuals are not enough to meet specific business requirements or to deliver a unique user experience. In such cases, creating custom visuals becomes essential.

One of the most flexible and popular libraries for custom visual development is D3.js (Data-Driven Documents), a JavaScript library that enables you to bind data to the DOM and apply data-driven transformations to the document.

This comprehensive guide covers the end-to-end process of creating custom visuals in Power BI using D3.js, from setting up your development environment to packaging and importing the visual into Power BI.

Table of Contents

  1. Overview of Power BI Custom Visuals
  2. Why Use D3.js for Custom Visuals?
  3. Setting Up Your Development Environment
  4. Creating a Custom Visual Project
  5. Understanding the Project Structure
  6. Developing with D3.js in Power BI Visuals
  7. Styling and Formatting
  8. Adding Capabilities.json Configuration
  9. Packaging the Visual
  10. Importing the Visual into Power BI
  11. Testing and Debugging Your Visual
  12. Publishing Your Visual to the AppSource (Optional)
  13. Best Practices for Custom Visual Development
  14. Common Pitfalls and Troubleshooting
  15. Conclusion

1. Overview of Power BI Custom Visuals

Power BI custom visuals are components developed using TypeScript, HTML, CSS, and optionally third-party libraries like D3.js or Chart.js. These visuals are designed to work seamlessly within Power BI reports and dashboards.

The Power BI visuals SDK (pbiviz) provides a scaffolding and API access to help developers build and test their custom visuals.

2. Why Use D3.js for Custom Visuals?

D3.js is a powerful JavaScript library that offers granular control over SVG and HTML elements. It excels in building:

  • Highly customized and interactive charts
  • Animated visualizations
  • Data transformations and transitions

When used in Power BI, D3 allows developers to create visuals beyond the standard template, including chord diagrams, force-directed graphs, and radial charts.

3. Setting Up Your Development Environment

Prerequisites

  • Node.js (LTS version recommended)
  • Power BI Visuals Tools (pbiviz)
  • Visual Studio Code (or any preferred IDE)
  • Git (optional but recommended)

Install Node.js

Download and install the latest LTS version from nodejs.org.

Install pbiviz

npm install -g powerbi-visuals-tools

Check the installation:

pbiviz --version

4. Creating a Custom Visual Project

Run the following command to scaffold a new custom visual project:

pbiviz new MyD3Visual
cd MyD3Visual

This creates a directory with boilerplate code and project structure.

5. Understanding the Project Structure

  • src/: Contains your TypeScript and HTML files
  • style/: Holds your SCSS/CSS styling files
  • capabilities.json: Defines the visual's data model and formatting options
  • pbiviz.json: Configuration file for packaging the visual
  • node_modules/: Dependencies

Key file:

  • visual.ts: The main TypeScript file where the custom visual logic lives.

6. Developing with D3.js in Power BI Visuals

Step 1: Install D3.js

Inside the project directory:

npm install d3 --save

Step 2: Import D3 in visual.ts

import * as d3 from "d3";

Step 3: Use D3 to Draw a Simple Chart

Here is a basic bar chart example:

public update(options: VisualUpdateOptions) {
    const dataView = options.dataViews[0];
    const svg = d3.select(this.target)
        .append("svg")
        .attr("width", options.viewport.width)
        .attr("height", options.viewport.height);

    const data = [10, 20, 30, 40];

    svg.selectAll("rect")
        .data(data)
        .enter()
        .append("rect")
        .attr("x", (d, i) => i * 50)
        .attr("y", d => 100 - d)
        .attr("width", 40)
        .attr("height", d => d)
        .attr("fill", "steelblue");
}

7. Styling and Formatting

Power BI supports SCSS for styling. Modify the style/visual.less or style/visual.scss file to define custom styles.

Example:

.visual {
    font-family: 'Segoe UI';
    rect {
        transition: fill 0.3s;
    }
    rect:hover {
        fill: orange;
    }
}

Compile SCSS to CSS automatically using the pbiviz start command.

8. Adding Capabilities.json Configuration

The capabilities.json file defines the data roles, objects, and settings available to the user.

Basic structure:

{
  "dataRoles": [
    {
      "name": "category",
      "kind": "Grouping"
    },
    {
      "name": "measure",
      "kind": "Measure"
    }
  ],
  "dataViewMappings": [
    {
      "categorical": {
        "categories": {
          "for": { "in": "category" }
        },
        "values": {
          "select": [ { "bind": { "to": "measure" } } ]
        }
      }
    }
  ]
}

9. Packaging the Visual

Once development is complete, package the visual:

pbiviz package

This generates a .pbiviz file inside the dist/ folder.

10. Importing the Visual into Power BI

  1. Open Power BI Desktop
  2. Go to Insert > More visuals > Import a visual from file
  3. Select the .pbiviz file
  4. Use the visual in your report canvas

11. Testing and Debugging Your Visual

Run the visual in developer mode:

pbiviz start

This opens a browser window with the developer visual sandbox at https://localhost:8080/assets/visual.js.

Use developer tools to debug errors and inspect data.

12. Publishing Your Visual to the AppSource (Optional)

You can publish your custom visual to Microsoft AppSource for public distribution.

Steps:

  • Ensure your visual passes all validation checks using pbiviz validate
  • Register with Partner Center
  • Submit your visual along with documentation and screenshots

13. Best Practices for Custom Visual Development

  • Modularize code for better maintainability
  • Use TypeScript features like interfaces and types
  • Avoid blocking UI threads
  • Support responsive layouts
  • Keep visuals lightweight
  • Follow Power BI accessibility guidelines

14. Common Pitfalls and Troubleshooting

Problem Solution
Visual not showing Check if visual.ts has valid DOM code
Styles not applied Ensure styles are defined in style/visual.scss and compiled
Data not binding Review capabilities.json and DataView mappings
D3 version mismatch Ensure correct D3 version is imported and referenced

15. Conclusion

Creating custom visuals in Power BI using D3.js opens up limitless possibilities for data storytelling and unique user experiences. With control over every pixel and interaction, D3.js empowers developers to craft rich, interactive visuals that meet specific business needs.

By following this comprehensive guide, you should be able to:

  • Set up your Power BI visual development environment
  • Integrate D3.js into your custom visuals
  • Style and package your visuals
  • Load them into Power BI Desktop

This workflow is invaluable for analytics teams, developers, and organizations looking to enhance the default capabilities of Power BI.

Continue exploring D3's documentation and Power BI's SDK to push the boundaries of visual analytics even further.

Happy Visualizing!