svg-visuals

# SVG Visuals via DAX Measures (PBIR) > **Use `pbir` for every report mutation.** The `pbir-format` skill is read-only schema context. > If the CLI is unavailable or lacks an operation, stop and report the gap. Generate inline SVG graphics using DAX measures that return SVG markup strings. These render as images in table, matrix, card, image, and slicer visuals. Store as extension measures in `reportExtensions.json`. ## How It Works 1. A DAX measure returns an SVG string prefixed with `data:image/svg+xml;utf8,` 2. The measure's `dataCategory` is set to `ImageUrl` 3. Power BI renders the SVG as an image in supported visuals ## Supported Visuals - Table (`tableEx`): `grid.imageHeight` / `grid.imageWidth` -- `references/svg-table-matrix.md` - Matrix (`pivotTable`): same as table -- `references/svg-table-matrix.md` - Image (`image`): `sourceType='imageData'` + `sourceField` -- `references/svg-image-visual.md` - Card/New (`cardVisual`): `callout.imageFX` -- `references/svg-card-slicer.md` - Slicer/New (`advancedSlicerVisual`): header images -- `references/svg-card-slicer.md` ## Workflow: Creating an SVG Measure ### Step 0: Design and Preview Before writing DAX, design the SVG visually: 1. **Query the model first** -- use DAX Studio or Tabular Editor CLI to get actual values with the intended filter context. Use real numbers, not placeholders. 2. **Write static SVG to a temp file** -- save to `/tmp/mockup.svg` and `open` it in a browser to preview layout, colors, and proportions. 3. **Ask for feedback** before converting to DAX -- iterating on static SVG is far easier than on DAX string concatenation. 4. **Colors must be hex codes with `#`** -- e.g., `fill='#2B7A78'`. Never use `%23` URL encoding or named colors. Always hex. ### Step 1: Create the Extension Measure Create the extension measure in `reportExtensions.json` manually (see the `pbir-format` skill in the pbip plugin for JSON structure). ```python # Example using pbir_object_model (if available): report.add_extension_measure( table="Orders", name="Sparkline SVG", expression=''' VAR _Prefix = "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 30'>" VAR _Bar = "<rect x='0' y='0' width='50' height='30' fill='#2196F3'/>" VAR _Suffix = "</svg>" RETURN _Prefix & _Bar & _Suffix ''', data_type="Text", data_category="ImageUrl", display_folder="SVG Charts", ) report.save() ``` ### Step 1b: Review Before presenting the measure to the user, dispatch the `svg-reviewer` agent to validate syntax and provide design feedback. ### Step 2: Bind to a Visual Extension measures use `"Schema": "extension"` in the SourceRef: ```json { "field": { "Measure": { "Expression": { "SourceRef": {"Schema": "extension", "Entity": "Orders"} }, "Property": "Sparkline SVG" } } } ``` For **image visuals**, bind the SVG measure through `pbir add visual image --image`; see `references/svg-image-visual.md`. ### Step 3: Validate Validate with `pbir validate "Report.Report" --all` and inspect bindings with `pbir visuals bind "...Visual" --show`. ## Prefer UDF Libraries Over Custom DAX Before writing a custom SVG measure from scratch, check whether an existing UDF library already provides the chart type: - **PowerofBI.IBCS** (Andrzej Leszkiewicz) -- IBCS-compliant bar, column, waterfall, pin, small multiples, and P&L charts. Preferred for business reporting with AC/PY/BU/FC comparisons. Install from https://daxlib.org/package/PowerofBI.IBCS/ - **DaxLib.SVG** (Jake Duddy) -- general-purpose sparklines, bars, boxplots, heatmaps, jitter, violin, progress bars, pills. Install from https://daxlib.org/package/DaxLib.SVG/ -- source at https://github.com/daxlib/dev-daxlib-svg - **PowerBI MacGuyver Toolbox** (Stepan Resl / Data Goblins) -- C# scripts that generate SVG measures via Tabular Editor To check if a library is installed, look for functions/measures starting with `PowerofBI.IBCS.`, `Viz.`, `Compound.`, or `Element.`. Only write custom SVG DAX when no library function covers the required visualization. See `references/community-examples.md` for full function listings and additional libraries. ### Installing UDF libraries UDF libraries are installed into the semantic model, not the report. Use one of these tools: - **Tabular Editor CLI** (`te` command) -- use the `te-docs` skill for guidance - **Power BI MCP server** -- if available, use it to modify the model directly - **`connect-pbid` skill** -- connect to Power BI Desktop's local Analysis Services instance via TOM/PowerShell - **`tmdl` skill** -- edit TMDL files directly in a PBIP project (last resort) ## DAX SVG Conventions ### Measure Structure (VAR Pattern) Every SVG measure must follow a strict VAR-based structure. Organize code into clearly separated regions: ```dax SVG Measure = -- CONFIG: Input fields and visual parameters VAR _Actual = [Sales Amount] VAR _Target = [Sales Target] VAR _Scope = ALLSELECTED ( 'Product'[Category] ) -- CONFIG: Colors VAR _BarColor = "#5B8DBE" VAR _TargetColor = "#333333" -- NORMALIZATION: Scale values to SVG coordinate space VAR _AxisMax = CALCULATE( MAXX( _Scope, [Sales Amount] ), REMOVEFILTERS( 'Product'[Category] ) ) * 1.1 VAR _AxisRange = 100 VAR _ActualNormalized = DIVIDE( _Actual, _AxisMax ) * _AxisRange -- SVG ELEMENTS: One VAR per visual element VAR _SvgPrefix = "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 25'>" VAR _Sort = "<desc>" & FORMAT( _Actual, "000000000000" ) & "</desc>" VAR _Bar = "<rect x='0' y='5' width='" & _ActualNormalized & "' height='15' fill='" & _BarColor & "'/>" VAR _TargetLine = "<rect x='" & DIVIDE( _Target, _AxisMax ) * _AxisRange & "' y='2' width='2' height='21' fill='" & _TargetColor & "'/>" VAR _SvgSuffix = "</svg>" -- ASSEMBLY: Combine in rendering order (back to front) VAR _SVG = _SvgPrefix & _Sort & _Bar & _TargetLine & _SvgSuffix RETURN _SVG ``` Key conventions: - **CONFIG section first** -- input measures, scope column, colors, font settings. Users change only this section. - **NORMALIZATION section** -- scale raw values to SVG coordinate space (see below) - **SVG ELEMENTS** -- one VAR per `<rect>`, `<circle>`, `<text>`, `<line>`, etc. - **ASSEMBLY** -- concatenate elements in document order (first = back layer, last = front) - **`<desc>` sort trick** -- embed `FORMAT(_Actual, "000000000000")` in a `<desc>` tag so the table/matrix can sort by the SVG column ### Axis Normalization (Critical) SVG coordinates must be normalized to a fixed range. Raw measure values (e.g., 1,234,567) cannot be used directly as pixel coordinates. The standard pattern: ```dax -- 1. Define the SVG coordinate range VAR _BarMin = 0 -- leftmost position (or offset for labels) VAR _BarMax = 100 -- rightmost position -- 2. Find the maximum value across all rows in the visual's filter context VAR _Scope = ALLSELECTED( 'Table'[GroupColumn] ) VAR _MaxInScope = CALCULATE( MAXX( _Scope, [Measure] ), REMOVEFILTERS( 'Table'[GroupColumn] ) ) VAR _AxisMax = _MaxInScope * 1.1 -- 10% padding -- 3. Normalize each value to the SVG range VAR _AxisRange = _BarMax - _BarMin VAR _Normalized = DIVIDE( _Actual, _AxisMax ) * _AxisRange ``` Use `ALLSELECTED` for the scope when the chart should respond to slicer context. Use `ALL` for a fixed axis across all filter contexts. The `* 1.1` padding prevents bars from touching the edge. ### HASONEVALUE Guard Table/matrix SVG measures must guard against subtotal/total rows where multiple categories are in scope: ```dax IF( HASONEVALUE( 'Table'[GroupColumn] ), -- SVG code here ) ``` Without this guard, the measure evaluates on grand total rows with meaningless aggregated values. ### Escaping and Color Rules - **Single quotes for SVG attributes** -- avoids DAX double-quote escaping: `fill='#2196F3'` - **Double quotes in DAX**: escape as `""` (DAX convention) - **`viewBox`** for responsive scaling: `viewBox='0 0 100 25'` - **`xmlns`** required on `<svg>` element - **Hex colors with `#` only** -- e.g., `fill='#2196F3'`. `%23` URL encoding causes errors in image visuals. Never use named colors. - **No JavaScript** -- SVG must be purely declarative ### SVG Coordinate System - Y=0 is at the **top** -- invert values for charts: `_Height - _Value` - Use `viewBox` with a 0-100 range for normalized coordinates - Elements render in document order (first = back, last = front) ### CONCATENATEX for Series Data For sparklines and multi-point charts, build coordinate strings with CONCATENATEX: ```dax VAR _Points = CONCATENATEX( _SparklineTable, [X] & "," & (100 - [Y]), " ", [Date], ASC ) -- Produces: "0,80 10,60 20,40 30,20" -- Use in: <polyline points='...'/> ``` ## Best Practices - Check UDF libraries first -- use DaxLib.SVG or MacGuyver Toolbox functions before writing custom DAX - VAR pattern mandatory -- one VAR per config value, one VAR per SVG element, assembly at the end - Normalize all values -- raw measure values must be scaled to SVG coordinate range - HASONEVALUE guard -- always guard against total/subtotal rows in table/matrix context; use `ISINSCOPE` for nested hierarchy levels - `<desc>` sort trick -- embed formatted value in `<desc>` for sortable SVG columns - Use `viewBox` for responsive scaling instead of fixed width/height - Round coordinates to integers for performance (shorter strings, cheaper FORMAT calls) - Store as extension measures -- SVG measures don't belong in the semantic model - Use `display_folder` to organize SVG measures (e.g., `"SVG Charts"`) - Preview first -- save static SVG to `/tmp/`, open in browser, iterate before writing DAX - 32K character limit on the rendered SVG string per cell (not the DAX expression); see `references/svg-table-matrix.md` for diagnosis and mitigation - Pre-aggregate in model measures -- let the storage engine cache aggregations; the SVG measure maps numbers to coordinates only - Hex colors only -- `#` directly, never `%23` URL encoding - Image visuals need no `query` block -- only `objects.image` with `sourceType='imageData'` and `sourceField` - Accessibility: every SVG encoding primary data needs adjacent readable columns and a dynamic alt-text measure; see `references/svg-accessibility.md` ## reportExtensions.json Format ```json { "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/reportExtension/1.0.0/schema.json", "name": "extension", "entities": [{ "name": "ExistingTable", "measures": [{ "name": "Sparkline SVG", "dataType": "Text", "dataCategory": "ImageUrl", "expression": "...", "displayFolder": "SVG Charts" }] }] } ``` ## Limitations - No interactivity -- SVG images are static (no hover, click, tooltip) - No JavaScript -- inline scripts are stripped - 32K character limit per rendered cell string (not the DAX expression); `CONCATENATEX` over 30+ series points easily approaches this; prefer `<polyline>` over individual shapes, integer coordinates, and pre-aggregated series; see `references/svg-table-matrix.md` for full diagnosis - Per-cell formula-engine cost -- each visible cell evaluates the string-building expression; push aggregations into model measures so SVG assembly is coordinate-mapping only - Accessibility gap -- screen readers receive no per-cell data from an SVG URI; mitigate with adjacent readable columns and dynamic alt text; see `references/svg-accessibility.md` - Classic card (`card`) does NOT support SVG -- use `cardVisual` instead ## When to Use SVG Measures SVG measures are the preferred choice for **simple inline graphics** embedded in tables, matrices, cards, and image visuals. Use SVG when you need: - Sparklines, data bars, progress bars, or status indicators inside table/matrix cells - KPI micro-charts in card visuals - Lightweight visuals that don't require interactivity or complex data transforms - No additional custom visual registration (works with native visuals) **Use Deneb instead** for complex, interactive visualizations (cross-filtering, tooltips, hover states) or chart types that require extensive data transforms. **Use Python/R instead** for statistical analysis charts (distributions, regressions, correlations). ## References ### Community Examples and Libraries - **`references/community-examples.md`** -- Community SVG templates organized by target visual type (Table/Matrix, Image, Card), including DaxLib.SVG functions, Kerry Kolosko templates, and PowerBI MacGuyver Toolbox patterns ### By Visual Type - **`references/svg-table-matrix.md`** -- Patterns for Table/Matrix: data bar, bullet chart, dumbbell, overlapping bars, lollipop, status pill, sparkline, bar sparkline, area sparkline, UDF patterns; axis normalization, sort trick, image size configuration, and per-cell performance guidance - **`references/svg-image-visual.md`** -- Patterns for Image visuals: KPI header, sparkline with endpoint, dashboard tile; sourceType binding, dynamic/conditional layout, responsive width guidance - **`references/svg-card-slicer.md`** -- Patterns for Card/Slicer: arrow indicator, mini gauge, mini donut, progress bar, narrative sentence; card binding via `callout.imageFX` ### Accessibility - **`references/svg-accessibility.md`** -- Accessibility for SVG measures: adjacent readable columns, dynamic alt text, color-only encoding, contrast requirements, and severity guidance for audit findings ### General - **`references/svg-elements.md`** -- SVG element reference (rect, circle, line, polyline, text, path, gradient, group) ### Examples Ready-to-use DAX measure expressions in `examples/`: - **`sparkline-measure.dax`** -- Line sparkline (polyline + CONCATENATEX) - **`progress-bar-measure.dax`** -- Conditional progress bar - **`dumbbell-chart-measure.dax`** -- Actual vs target dumbbell