Power BI Custom Visuals Development: Build Enterprise-Grade Visualizations with TypeScript
Create custom Power BI visuals using TypeScript, D3.js, and the Power BI Visuals SDK for unique data storytelling and specialized industry use cases.
Power BI ships with dozens of built-in visuals covering common chart types, but every organization eventually encounters visualization needs that standard visuals cannot address. Custom visuals fill this gap, enabling specialized industry visualizations, advanced interactivity, and unique data storytelling. Building custom visuals requires web development skills but opens unlimited possibilities for your reports.
When to Build Custom Visuals
Before investing in custom development, confirm that no existing option works:
- Built-in visuals: Power BI includes 30+ visual types. Explore conditional formatting, small multiples, and visual interactions before going custom
- AppSource marketplace: Thousands of community and commercial visuals available. Search for your use case first
- Charticulator: Microsoft's no-code custom chart builder (available as a visual) handles many unique chart designs without programming
- Custom visual: If none of the above work, build one
Common custom visual use cases include: Gantt charts with resource allocation, org charts with interactive hierarchy navigation, process flow diagrams, industry-specific gauges (manufacturing OEE, healthcare patient flow), geographic visualizations beyond standard maps, and animated data transitions.
Development Environment Setup
Custom visuals are built with TypeScript and the Power BI Visuals SDK:
- Install Node.js (LTS version)
- Install the Power BI Visual Tools CLI: npm install -g powerbi-visuals-tools
- Create a new visual project: pbiviz new MyVisual
- Navigate to the project: cd MyVisual
- Start the development server: pbiviz start
The development server launches a live preview in Power BI Service. Enable Developer Visuals in Power BI Settings to see your visual in the report editor while developing.
Visual Architecture
A custom visual project has this structure:
src/visual.ts: The main TypeScript file containing your visual class. Implements IVisual interface with constructor(), update(), and destroy() methods. The update() method is called whenever data or settings change.
capabilities.json: Defines what data the visual accepts (data roles), what settings users can configure (objects), and how the visual interacts with Power BI (tooltips, selection, drilldown).
src/settings.ts: TypeScript classes that map to the visual's property pane settings. Users configure colors, sizes, labels, and behavior through these settings.
style/visual.less: CSS styles for the visual's HTML elements.
Data Binding
The capabilities.json file defines data roles - the field wells where users drag columns:
Categorical: For dimension fields (Product Name, Region). Supports grouping and hierarchy Measure: For numeric values (Sales Amount, Count). Supports aggregation Conditions: Define minimum and maximum number of fields per role
In your TypeScript code, access bound data through the update() method's VisualUpdateOptions parameter. The dataViews property contains the transformed data in the format specified by your data view mappings.
D3.js Integration
D3.js is the most popular library for data visualization and integrates naturally with custom visuals:
Install D3: npm install d3 @types/d3. Import in your visual.ts: import * as d3 from "d3". Use D3's data binding, scales, axes, and transitions to render your visualization within the visual's HTML element.
D3 excels at: complex SVG-based charts, animated transitions, interactive elements (hover, click, drag), and data-driven document manipulation. For simpler visuals, native SVG or Canvas may be sufficient without D3.
Formatting and Settings
The property pane (Format panel) allows users to customize your visual:
- Colors: Background, border, data point colors with color picker
- Text: Font family, size, bold/italic for labels and values
- Layout: Padding, margins, alignment options
- Behavior: Animation toggle, tooltip format, selection mode
- Conditional formatting: Support data-driven colors and values
Define settings in capabilities.json under the "objects" section. Create corresponding TypeScript classes in settings.ts. Power BI automatically renders the property pane UI.
Interactivity
Custom visuals can participate in the Power BI interaction model:
Selection: Users click data points to cross-filter other visuals. Implement using the selectionManager service Tooltips: Show data details on hover. Implement using the tooltipService Context Menu: Right-click menu for drillthrough, include/exclude, and other actions Bookmarks: Support bookmark state persistence so your visual restores correctly Conditional Formatting: Allow users to bind settings to data fields for dynamic formatting
Testing and Certification
Local Testing: Use pbiviz start for live development against real data in Power BI Service. Test with various data shapes (single value, large datasets, missing values, special characters).
Performance Testing: Custom visuals must render in under 2 seconds for certification. Test with 10,000+ data points. Implement virtualization for large datasets (only render visible elements).
AppSource Certification: For public distribution, submit to Microsoft for review. Requirements include: no external network calls, accessibility support (keyboard navigation, ARIA labels), security compliance, documentation, and performance benchmarks.
Organizational Distribution: For internal-only visuals, package as .pbiviz file and import directly into reports or upload to the organizational visual store in the Power BI admin portal.
Best Practices
- Support responsive sizing - your visual should look good at any container size
- Handle empty or null data gracefully without crashing
- Implement proper cleanup in destroy() to prevent memory leaks
- Use the Power BI color palette for consistency with the report theme
- Minimize DOM manipulation for better rendering performance
- Support both light and dark themes
Related Resources
Frequently Asked Questions
Do I need to be a JavaScript/TypeScript expert to build custom Power BI visuals?
While TypeScript knowledge helps, you do not need to be an expert. Microsoft provides Visual Studio Code templates and extensive documentation that handle boilerplate code. If you understand JavaScript basics and can read TypeScript, you can modify examples to create simple custom visuals. For production-quality visuals with complex interactions, expect a learning curve of 2-4 weeks if you have web development experience. Key skills: TypeScript fundamentals, D3.js for data visualization, SVG/Canvas for rendering, and understanding of Power BI data view mappings. Many developers start by modifying open-source visuals from GitHub rather than building from scratch. Microsoft Learn offers free custom visuals development courses with hands-on exercises.
Can I sell custom visuals I develop, and how does AppSource certification work?
Yes, you can sell custom visuals through Microsoft AppSource after certification. Certification process: (1) Develop visual using official SDK, (2) Test with sample data and edge cases, (3) Submit to Microsoft for security/performance review (2-4 weeks), (4) Pass automated tests and manual review, (5) List on AppSource with pricing/licensing. You can offer free visuals, one-time purchase, or subscription models. Microsoft takes 20% revenue share for paid visuals. Certification requirements include: no external network calls (data privacy), performance standards (render under 2 seconds), accessibility compliance (keyboard navigation, screen reader support), and documentation. Alternatively, distribute visuals privately within your organization without certification—import .pbiviz files directly into reports.
What are the limitations of custom visuals compared to built-in Power BI visuals?
Custom visuals have some restrictions for security reasons: (1) No direct internet access—cannot call external APIs or load external resources, (2) Storage limitations—cannot persist data locally beyond session, (3) Performance—run in sandboxed environment with resource limits, (4) Limited Power BI feature access—some interactions like drillthrough must be implemented manually. Built-in visuals integrate deeper with Power BI features (conditional formatting, field parameters, automatic insights). However, custom visuals can achieve unique interactions impossible with built-ins: custom animations, specialized chart types (Sankey, chord diagrams), industry-specific visualizations (Gantt charts with resource allocation), and advanced D3.js effects. For most use cases, built-in visuals should be preferred—only create custom visuals when built-in options cannot meet specific requirements.