Power BI Custom Visuals Development

Power BI Custom Visuals Development

Custom Power BI visuals are web components — written in TypeScript, rendered with D3/SVG/Canvas/HTML, and packaged as a single .pbiviz file — that run sandboxed inside an iframe in Power BI Desktop and the Power BI service. You build them with the pbiviz command-line tool (the powerbi-visuals-tools npm package) against the typed powerbi-visuals-api. This skill covers the full lifecycle: scaffold → develop → debug → package → certify.

This is a knowledge plugin. It generates and reviews source files (visual.ts, capabilities.json, settings.ts, pbiviz.json) and drives the local pbiviz CLI — it does not require any MCP server or cloud credentials.

Prerequisites

• Node.js (current LTS) and npm. Install the toolchain globally: npm i -g powerbi-visuals-tools@latest (provides the pbiviz command).
• A Power BI Pro or Premium Per User (PPU) account to test in the service, plus an IDE (VS Code recommended).
• Developer mode enabled — in Power BI Desktop (File ▸ Options ▸ Report settings ▸ Develop a visual, per session) or in the service (Developer settings ▸ Power BI Developer mode). See ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/environment-setup.md.
• For certification: a Partner Center account and a public/reviewable GitHub repository.

Choosing how to build

The pbiviz SDK is the most powerful path, but not always the right one. Pick the lightest approach that meets the need: SVG rendered from a DAX measure (inline sparklines/KPIs in tables, no visual to build), Deneb (declarative Vega/Vega-Lite, certified), the HTML Content visual, Charticulator (no-code), or the full pbiviz SDK (TypeScript + D3/React) when you need lifecycle control, a custom format pane, advanced interactivity, or AppSource distribution. The full decision guide and low-code patterns are in ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/building-approaches.md. The rest of this skill covers the SDK path in depth.

Deneb — declarative Vega / Vega-Lite (the no-build path)

Deneb is a certified custom visual that runs Vega and Vega-Lite JSON specs inside Power BI — no pbiviz toolchain, no build, yet with native cross-filtering, tooltips, context menus, and report-theme colors. Reach for it when the chart exists in the Vega ecosystem but not the Power BI core set and the user wants a certified result fast. Key facts:

• Bind data via the named dataset dataset — { "data": { "name": "dataset" } } (Vega-Lite) or a dataset data source (Vega). Field names are the column display names from Deneb's Values well.
• Provider: Vega-Lite (concise mark+encoding, parameters) for standard charts; Vega (explicit scales/signals/marks) for bespoke layouts and manual interactivity.
• Cross-filtering: enable it in Settings, then style on the injected __selected__ field ('on'/'off'/'neutral'). Advanced (Vega-only) mode uses the pbiCrossFilterSelection signal with pbiCrossFilterApply(event, filter?, options?) / pbiCrossFilterClear() for brush/aggregate selection.
• Deneb expression functions: pbiColor(index, shade?) (theme colors), pbiFormat(value, fmt, opts?) (Power BI format strings + locale), pbiPatternSVG(pattern, fg, bg) (texture fills, SVG mode).
• Responsive: "width": "container", "height": "container", "autosize": { "type": "fit", "contains": "padding" }. Keep shared styling in the Config object; reuse charts via the template (usermeta) system.
• Certified-build limits: no external data.url, remote images, or external fonts — all data flows through dataset.

Run /pbiviz-deneb to author or iterate a spec. Full reference: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/deneb-vega.md; copy-paste specs: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/deneb-specs.md.

The visual lifecycle at a glance

Project structure

pbiviz new <name> scaffolds a complete project. The files that matter most:

• pbiviz.json — visual metadata: internal name, displayName, unique guid, visualClassName (must match your IVisual class name), version (four-part x.x.x.x), apiVersion, author, assets.icon, and the paths to capabilities.json and style/visual.less.
• capabilities.json — the contract with the host: what data the visual accepts and what appears in the Format pane.
• src/visual.ts — the IVisual implementation (your render code).
• src/settings.ts — the formatting settings model (Format pane cards/slices).
• style/visual.less — styles.
• assets/icon.png — the Visualizations-pane icon, a 20×20 PNG.
• tsconfig.json, package.json, package-lock.json, .eslintrc.

Full annotated layout and pbiviz.json field reference: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/project-structure.md.

capabilities.json — the data and format contract

capabilities.json tells the host what kind of data the visual accepts and what customizable properties appear in the Format pane. From API v4.6.0 all root properties are optional except privileges, which is required (use "privileges": [] when the visual needs no special access).

Root objects:

• privileges — special access the visual needs: WebAccess (external URLs — must be empty for certification), ExportContent (download to file), LocalStorage.
• dataRoles — the field wells users drag data into. Each has a name, displayName, and kind: Grouping (discrete buckets), Measure (numeric), or GroupingOrMeasure.
• dataViewMappings — how roles map into a DataView (categorical, table, matrix, or single), with conditions bounding how many fields each role accepts and a dataReductionAlgorithm (top/bottom/sample/window, default top at 1000, max 30000).
• objects — Format pane properties. Each object/property name must exactly match a card/slice in your formatting model.
• Feature flags — supportsHighlight, sorting, drilldown, expandCollapse, supportsLandingPage, supportsEmptyDataView, supportsKeyboardFocus, tooltips, advancedEditModeSupport, supportsMultiVisualSelection, subtotals, keepAllMetadataColumns.

Details and copy-paste blocks: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/capabilities.md. Complete files: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/capabilities-json.md.

DataView — reading the data

Each valid dataViewMappings entry produces a DataView delivered in update(options) as options.dataViews[0]. Power BI only populates the mapping types you declared.

• single — one aggregated value (dataView.single.value). For KPI cards.
• categorical — independent groupings + measures (dataView.categorical.categories[] and .values[]). The most common mapping for charts. Group values by a series role for hierarchical/series data; read groups with categorical.values.grouped().
• table — a flat list of rows (dataView.table.columns[], dataView.table.rows[]). Do not assume row order.
• matrix — hierarchical rows/columns as a tree of DataViewMatrixNode (dataView.matrix.rows.root, .columns.root, .valueSources). Supports expand/collapse of row headers (API 4.1+).

Always null-check the mapping (if (!dataView?.categorical?.values) return;) before reading — a user may not have populated every field well. Parsing patterns for every mapping type: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/dataview-mapping.md.

The IVisual API

Every visual is a class implementing IVisual (named exactly as visualClassName in pbiviz.json):

export class Visual implements IVisual {
    constructor(options: VisualConstructorOptions) { /* one-time setup */ }
    public update(options: VisualUpdateOptions): void { /* render on every data/size/view change */ }
    public getFormattingModel(): powerbi.visuals.FormattingModel { /* build the Format pane */ }
    public destroy(): void { /* optional cleanup */ }
}

• constructor(options) — runs once. Capture options.element (your DOM root) and options.host (the IVisualHost), and create long-lived services (createSelectionManager, createLocalizationManager, colorPalette, tooltipService, eventService).
• update(options) — runs on every change. options.viewport is the size, options.dataViews the data, options.type flags the cause (Data | Resize | ViewMode | Style | ResizeEnd). Re-render here.
• getFormattingModel() — returns the Format pane model (replaces the deprecated enumerateObjectInstances).

Host services (selection, tooltips, color palette, launchUrl, persistProperties, fetchMoreData, storageService, eventService, displayWarningIcon, acquireAADTokenService) are detailed in ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/visual-api.md.

Rendering Events API (required for certification): call host.eventService.renderingStarted(options) at the start of update, renderingFinished(options) when the DOM is fully drawn, and renderingFailed(options, reason) on error. This signals "export to PDF/PowerPoint" and automated tests that rendering is complete.

The modern Format pane (API 5.1+)

Use API version 5.1 or later and implement getFormattingModel. The recommended approach is the formatting model utils (powerbi-visuals-utils-formattingmodel):

1. Declare a settings model in src/settings.ts extending formattingSettings.Model, composed of cards (formattingSettings.SimpleCard / CompositeCard) → optional groups → slices (ToggleSwitch, NumUpDown, Slider, ColorPicker, ItemDropdown, AutoDropdown, FontControl, TextInput, AlignmentGroup, …). Card name must equal the object name and slice name must equal the property name in capabilities.json.
2. In the constructor: this.formattingSettingsService = new FormattingSettingsService(localizationManager?).
3. In update: this.settings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews);
4. Implement getFormattingModel() → return this.formattingSettingsService.buildFormattingModel(this.settings);

Property type ↔ capabilities value-type mapping, composite slices, conditional formatting (per-data-point colors via dataViewWildcard selectors + instanceKind), and reset-to-default: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/formatting-model.md. Full settings.ts: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/formatting-settings.md.

Interactivity

• Selection & cross-filtering — create an ISelectionManager in the constructor and an ISelectionId per data point with host.createSelectionIdBuilder().withCategory(...) / .withSeries(...) / .withTable(...) / .withMatrixNode(...). Call selectionManager.select(id, multiSelect) on click; reflect selectionManager.getSelectionIds() visually. Support Ctrl-click for multi-select.
• Highlighting — set "supportsHighlight": true and render the values[i].highlights array (non-highlighted portions dimmed) when other visuals cross-filter yours.
• Tooltips — declare "tooltips" in capabilities and use host.tooltipService (or powerbi-visuals-utils-tooltiputils) to show/move/hide tooltips on pointer events.
• Context menu — selectionManager.showContextMenu(selectionId, {x, y}, dataRole?) on contextmenu. The dataRole argument is required when the visual supports drilldown or expandCollapse.
• Drill-down / expand-collapse, bookmarks (register a selection callback, restore on update), landing page (supportsLandingPage + supportsEmptyDataView), launchUrl, local storage, and the color palette are all covered in ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/interactivity.md.

Testing, linting, and security

Certification requires eslint, eslint-plugin-powerbi-visuals, and typescript in package.json, a clean npm audit (no high/moderate), and no JS console errors. Unit tests use jasmine + karma with powerbi-visuals-utils-testutils. Manipulate the DOM safely — never use innerHTML/D3.html() with user data, and avoid eval/Function/dynamic setTimeout. See ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/testing.md.

Packaging & certification

• Package: pbiviz package writes dist/<name>.pbiviz. The description field in pbiviz.json must be filled in or the command fails. Bump the four-part version before each package.
• Certify: publish to AppSource via Partner Center, then optionally request certification. Requirements: latest API, a lowercase certification Git branch matching the submitted package, OSS-only libraries, Rendering Events API support, no external network access (WebAccess empty/omitted), no minified code, and a clean pbiviz package --certification-audit. Full checklist: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/packaging-certification.md.

Utility packages

Microsoft ships helper packages so you don't reinvent common chart plumbing: powerbi-visuals-utils-formattingmodel (Format pane), -dataviewutils, -formattingutils (number/date formatting + text measurement), -svgutils, -chartutils (axes/legend), -colorutils, -interactivityutils, -tooltiputils, -typeutils, and -testutils. Reference + common errors: ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/utils-and-troubleshooting.md.

Reference files

Example files