How to Create Custom Visuals in Power BI: Step-by-Step Guide

To create a custom visual in Power BI, use the Power BI Visuals SDK which lets you build visuals with TypeScript and D3.js. Start by installing the SDK, then create a new visual project, develop your visual code, test it locally, and finally package it for import into Power BI Desktop.

Syntax

Creating a custom visual involves these main parts:

• pbiviz new <project-name>: Creates a new visual project folder.
• pbiviz start: Runs a local server to test your visual in Power BI service.
• pbiviz package: Packages your visual into a .pbiviz file for import.
• src/visual.ts: Main TypeScript file where you write your visual's rendering logic.

bash

pbiviz new myCustomVisual
cd myCustomVisual
pbiviz start
pbiviz package

Output

Creates project folder, runs local test server, and packages visual for import.

Example

This example shows a simple custom visual that draws a red circle using D3.js in Power BI.

typescript

import * as d3 from 'd3';
import powerbiVisualsApi from 'powerbi-visuals-api';
import IVisual = powerbiVisualsApi.extensibility.visual.IVisual;

export class Visual implements IVisual {
  private svg: d3.Selection<SVGSVGElement, unknown, HTMLElement, any>;

  constructor(options: powerbiVisualsApi.extensibility.visual.VisualConstructorOptions) {
    this.svg = d3.select(options.element)
      .append('svg')
      .attr('width', '100%')
      .attr('height', '100%');
  }

  public update(options: powerbiVisualsApi.extensibility.visual.VisualUpdateOptions): void {
    this.svg.selectAll('*').remove();
    this.svg.append('circle')
      .attr('cx', 50)
      .attr('cy', 50)
      .attr('r', 40)
      .style('fill', 'red');
  }
}

Output

A red circle appears inside the visual area in Power BI.

Common Pitfalls

• Not installing Node.js and npm before installing the Power BI Visuals SDK.
• Forgetting to run pbiviz start to test visuals locally before packaging.
• Not updating capabilities.json to define data roles and visual properties.
• Ignoring TypeScript errors which can cause build failures.
• Trying to import the visual without packaging it into a .pbiviz file.

bash

/* Wrong: Trying to import without packaging */
// User tries to import project folder directly into Power BI Desktop

/* Right: Package first */
pbiviz package
// Then import the generated .pbiviz file into Power BI Desktop

Output

Power BI accepts the .pbiviz file and loads the custom visual.

Quick Reference

Command	Purpose
pbiviz new	Create a new custom visual project
pbiviz start	Run local server to test visual
pbiviz package	Package visual into .pbiviz file
Import .pbiviz	Add custom visual to Power BI Desktop
Edit src/visual.ts	Write visual rendering code

Key Takeaways

Install Power BI Visuals SDK and Node.js before starting.

Use pbiviz commands to create, test, and package your visual.

Write your visual logic in TypeScript using D3.js or other libraries.

Always package your visual into a .pbiviz file before importing.

Test your visual locally with pbiviz start to catch errors early.