---
name: Power BI Custom Visuals
slug: power-bi-custom-visuals
category: Frontend
description: Power BI Custom Visuals builds reusable .pbiviz visuals with the pbiviz toolchain and MCP server. Use it to scaffold, implement, debug, package, certify, and publish Power BI developer visuals.
github: "https://github.com/data-goblin/power-bi-agentic-development/tree/main/plugins/custom-visuals/skills/powerbi-custom-visuals"
language: "C#"
stars: 872
forks: 129
install: "npx degit https://github.com/data-goblin/power-bi-agentic-development/tree/main/plugins/custom-visuals/skills/powerbi-custom-visuals ~/.claude/skills/powerbi-custom-visuals"
installs_to: ~/.claude/skills/powerbi-custom-visuals
source_path: plugins/custom-visuals/skills/powerbi-custom-visuals/SKILL.md
collection_size: 25
category_size: 567
collection_url: "https://dirskills.com/collections/data-goblin/power-bi-agentic-development"
added: 2026-08-22T05:21:23.853Z
last_synced: 2026-08-22T05:21:23.853Z
canonical_url: "https://dirskills.com/skills/power-bi-custom-visuals"
---

# Power BI Custom Visuals

Power BI Custom Visuals builds reusable .pbiviz visuals with the pbiviz toolchain and MCP server. Use it to scaffold, implement, debug, package, certify, and publish Power BI developer visuals.

**Install:**

```bash
npx degit https://github.com/data-goblin/power-bi-agentic-development/tree/main/plugins/custom-visuals/skills/powerbi-custom-visuals ~/.claude/skills/powerbi-custom-visuals
```

## README

# Power BI Custom Visuals (pbiviz)

Build distributable Power BI **developer visuals**: TypeScript/D3 visuals packaged
as a `.pbiviz` file, written against the `powerbi-visuals-api` and built with the
`pbiviz` CLI (`powerbi-visuals-tools`). This skill covers the full loop: scaffold,
develop, live-preview, package, certify, and publish.

## Pick the right tool first

This plugin holds five visual approaches. Choose before building:

```yaml
deneb-visuals:    no-code Vega / Vega-Lite specs inside a report; no packaging, no TypeScript
python-visuals:   matplotlib / seaborn script visuals (static image, computes at render)
r-visuals:        ggplot2 script visuals (static image); R's stats ecosystem
svg-visuals:      SVG drawn by a DAX measure (ImageUrl); inline in tables/cards, no visual sandbox
powerbi-custom-visuals (this skill): a real .pbiviz developer visual, reusable across
                  reports and shareable on AppSource; full interactivity, formatting pane, certification
```

Reach for this skill when the need is a reusable, interactive, distributable visual
with its own formatting pane. For a one-off chart in a single report, a sibling
skill is usually faster and lighter.

## Prerequisites

- Node.js 20.19 or later (the `powerbi-visuals-tools` engine minimum)
- `pbiviz` CLI: run via `npx -y powerbi-visuals-tools <command>`, or install it globally
- Developer mode for live preview: enable the developer visual in Power BI Desktop, or
  turn on developer mode in the Power BI service

## Core workflow

1. **Scaffold**: `pbiviz new <VisualName>` creates the project (`src/visual.ts`,
   `capabilities.json`, `pbiviz.json`, `tsconfig.json`, `package.json`, `style/`, `assets/`)
2. **Implement the visual class** in `src/visual.ts`. Implement the `IVisual` interface;
   the class name must equal `visualClassName` in `pbiviz.json`. Core methods:
   `constructor` (set up DOM and services), `update` (render on data/size/settings change),
   `getFormattingModel` (populate the format pane), `destroy` (cleanup)
3. **Declare data and formatting** in `capabilities.json`: `dataRoles` (the field wells),
   `dataViewMappings` (how roles map to the dataView), and `objects` (format-pane properties)
4. **Build the formatting model** with `powerbi-visuals-utils-formattingmodel`
   (`FormattingSettingsService`, cards, slices). A card name matches a `capabilities.json`
   object; a slice name matches a property
5. **Live-preview**: `pbiviz start`, then add the developer visual to a report and iterate
   against real data
6. **Package**: `pbiviz package` produces the `.pbiviz` under `dist/`; import it into a report

Full command flags, the project layout, the `IVisual` lifecycle, and formatting-model
patterns are in `references/pbiviz-toolchain.md`.

## Use the bundled pbiviz MCP server

This plugin ships a `.mcp.json` that starts the `pbiviz` MCP server
(`npx -y powerbi-visuals-tools mcp`). It grounds development in current, correct API
usage instead of guessed code. Prefer its tools while building:

```yaml
get_available_apis:    look up data, formatting, interaction, and utility APIs with examples
get_best_practices:    API-version management, performance, security, accessibility, testing
add_feature:           list features available to add (bookmarks, tooltips, drill-down, selection, localization)
implement_feature:     step-by-step instructions, code templates, and config changes for a feature
list_visual_info:      extract a project's GUID, version, author, data roles, dependencies
check_vulnerabilities: scan dependencies and source for risky patterns (eval, innerHTML)
prepare_certification: verify required files, configuration, capabilities, and assets pre-submission
```

Setup, client config, and per-tool detail are in `references/mcp-server.md`.

## Certify and publish

Certification unlocks export to PowerPoint and email subscriptions, and signals a
reviewed visual. Key gates: a lowercase `certification` branch matching the package,
`eslint-plugin-powerbi-visuals` passing, no `eval`/`fetch`/`XMLHttpRequest`, a clean
`npm audit`, and the latest API. Audit with `pbiviz package --certification-audit`.
Publishing goes through Partner Center to AppSource. R-based visuals cannot be certified.

Requirements and the submission flow are in `references/certification-publishing.md`.

## Learn from shipped visuals

Microsoft publishes the full source of official and certified visuals. Start from the
tutorials (`circlecard`, `sampleBarChart`) and read a production visual close to the
target (`gantt`, `sankey`, `sunburst`, `timeline`, `ChicletSlicer`) for real patterns.
A curated list with what each one teaches is in `references/community-examples.md`.

## Additional resources

### Reference files
- **`references/pbiviz-toolchain.md`** ... CLI commands, project structure, IVisual lifecycle, capabilities.json, formatting model, key npm packages
- **`references/mcp-server.md`** ... the bundled pbiviz MCP: setup and its tools
- **`references/certification-publishing.md`** ... certification requirements and AppSource publishing
- **`references/community-examples.md`** ... official and certified example visuals worth reading

### Examples
- **`examples/vscode-mcp.json`** ... standalone `.vscode/mcp.json` for a visual project outside this plugin
- **`examples/capabilities-objects.json`** ... a `capabilities.json` `objects` block wired to a formatting card