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 localpbivizCLI — 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 thepbivizcommand). - 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 adatasetdata 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 thepbiCrossFilterSelectionsignal withpbiCrossFilterApply(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 throughdataset.
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
| Stage | Command / artifact | Reference |
|---|---|---|
| Set up environment | npm i -g powerbi-visuals-tools@latest, enable dev mode |
references/environment-setup.md |
| Scaffold a project | pbiviz new <name> |
references/project-structure.md |
| Declare data + format contract | capabilities.json |
references/capabilities.md |
| Shape the incoming data | dataViewMappings + parse options.dataViews[0] |
references/dataview-mapping.md |
| Render & handle lifecycle | IVisual class in src/visual.ts |
references/visual-api.md |
| Build the Format pane | getFormattingModel + formatting model utils |
references/formatting-model.md |
| Add interactivity | selection, tooltips, context menu, drill, bookmarks | references/interactivity.md |
| Live debug | pbiviz start + Developer Visual |
command /pbiviz-debug |
| Test & lint | ESLint + jasmine/karma unit tests | references/testing.md |
| Package | pbiviz package → dist/<name>.pbiviz |
references/packaging-certification.md |
| Certify & publish | Partner Center + AppSource | references/packaging-certification.md |
Project structure
pbiviz new <name> scaffolds a complete project. The files that matter most:
pbiviz.json— visual metadata: internalname,displayName, uniqueguid,visualClassName(must match yourIVisualclass name),version(four-partx.x.x.x),apiVersion,author,assets.icon, and the paths tocapabilities.jsonandstyle/visual.less.capabilities.json— the contract with the host: what data the visual accepts and what appears in the Format pane.src/visual.ts— theIVisualimplementation (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 aname,displayName, andkind:Grouping(discrete buckets),Measure(numeric), orGroupingOrMeasure.dataViewMappings— how roles map into aDataView(categorical,table,matrix, orsingle), withconditionsbounding how many fields each role accepts and adataReductionAlgorithm(top/bottom/sample/window, defaulttopat 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. Groupvaluesbya series role for hierarchical/series data; read groups withcategorical.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 ofDataViewMatrixNode(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. Captureoptions.element(your DOM root) andoptions.host(theIVisualHost), and create long-lived services (createSelectionManager,createLocalizationManager,colorPalette,tooltipService,eventService).update(options)— runs on every change.options.viewportis the size,options.dataViewsthe data,options.typeflags the cause (Data | Resize | ViewMode | Style | ResizeEnd). Re-render here.getFormattingModel()— returns the Format pane model (replaces the deprecatedenumerateObjectInstances).
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):
- Declare a settings model in
src/settings.tsextendingformattingSettings.Model, composed of cards (formattingSettings.SimpleCard/CompositeCard) → optional groups → slices (ToggleSwitch,NumUpDown,Slider,ColorPicker,ItemDropdown,AutoDropdown,FontControl,TextInput,AlignmentGroup, …). Cardnamemust equal the object name and slicenamemust equal the property name incapabilities.json. - In the constructor:
this.formattingSettingsService = new FormattingSettingsService(localizationManager?). - In
update:this.settings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews); - 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
ISelectionManagerin the constructor and anISelectionIdper data point withhost.createSelectionIdBuilder().withCategory(...)/.withSeries(...)/.withTable(...)/.withMatrixNode(...). CallselectionManager.select(id, multiSelect)on click; reflectselectionManager.getSelectionIds()visually. Support Ctrl-click for multi-select. - Highlighting — set
"supportsHighlight": trueand render thevalues[i].highlightsarray (non-highlighted portions dimmed) when other visuals cross-filter yours. - Tooltips — declare
"tooltips"in capabilities and usehost.tooltipService(orpowerbi-visuals-utils-tooltiputils) to show/move/hide tooltips on pointer events. - Context menu —
selectionManager.showContextMenu(selectionId, {x, y}, dataRole?)oncontextmenu. ThedataRoleargument is required when the visual supportsdrilldownorexpandCollapse. - 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 packagewritesdist/<name>.pbiviz. Thedescriptionfield inpbiviz.jsonmust be filled in or the command fails. Bump the four-partversionbefore each package. - Certify: publish to AppSource via Partner Center, then optionally request certification. Requirements: latest API, a lowercase
certificationGit branch matching the submitted package, OSS-only libraries, Rendering Events API support, no external network access (WebAccessempty/omitted), no minified code, and a cleanpbiviz 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
| File | Path | Content |
|---|---|---|
| Building approaches | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/building-approaches.md |
Choosing SDK vs Deneb vs SVG-via-DAX vs HTML Content vs Charticulator; React + pbiviz MCP |
| Deneb (Vega/Vega-Lite) | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/deneb-vega.md |
Deneb editor, dataset binding, cross-filter (__selected__, pbiCrossFilterApply), pbiColor/pbiFormat/pbiPatternSVG, themes, templates, certified limits |
| Environment setup | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/environment-setup.md |
Node, pbiviz install, dev mode, account/SSL setup |
| Project structure | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/project-structure.md |
Folder layout, pbiviz.json, tsconfig, package.json |
| Capabilities | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/capabilities.md |
privileges, dataRoles, mappings, objects, feature flags |
| DataView mapping | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/dataview-mapping.md |
single/categorical/table/matrix parsing, reduction, conditions |
| Visual API | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/visual-api.md |
IVisual lifecycle, host services, rendering events |
| Formatting model | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/formatting-model.md |
Format pane, utils, slice types, conditional formatting |
| Interactivity | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/interactivity.md |
selection, tooltips, context menu, drill, bookmarks, landing page |
| Testing | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/testing.md |
ESLint, unit tests, debugging, security rules |
| Packaging & certification | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/packaging-certification.md |
pbiviz package, AppSource, certification checklist |
| Utils & troubleshooting | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/references/utils-and-troubleshooting.md |
utility packages, common errors and fixes |
Example files
| File | Path | Content |
|---|---|---|
| Visual (bar chart) | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/visual-ts-barchart.md |
Complete visual.ts: IVisual, D3, selection, tooltips, rendering events |
| capabilities.json | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/capabilities-json.md |
Complete capabilities for categorical, table, and matrix visuals |
| Formatting settings | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/formatting-settings.md |
settings.ts cards/groups/slices + conditional formatting |
| Config files | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/pbiviz-and-config.md |
pbiviz.json, tsconfig.json, package.json, .eslintrc |
| Scaffold walkthrough | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/scaffold-walkthrough.md |
End-to-end: new → develop → start → package → certify |
| Deneb specs | ${CLAUDE_PLUGIN_ROOT}/skills/powerbi-custom-visuals/examples/deneb-specs.md |
Copy-paste Vega/Vega-Lite specs: cross-filter bar, rolling-mean line, bullet, pattern fills, advanced-mode Vega, theme config, template usermeta |