Power BI extensions to Vega
Use the Power BI colour schemes, expression functions, pattern fills, and container signals that Ataytis Vega Studio adds to the standard Vega runtime.
What the Studio adds to Vega
A specification written for Ataytis Vega Studio is standard Vega, with a small set of additions registered into the runtime before your specification is parsed. They exist so a visual can inherit the report theme, format numbers the way the rest of the report formats them, and drive Power BI cross-filtering — none of which plain Vega knows anything about.
Container signals
If your specification omits width or height, the Studio supplies them as the signals pbiContainerWidth and pbiContainerHeight, so the visual fills whatever space Power BI gives it. Declaring your own fixed width and height overrides this, which is usually what you want only while designing at a known size.
A third signal, pbiContainer, carries the full container and scroll state as an object, for designs that need to react to scrolling as well as size.
| Property | Meaning |
|---|---|
pbiContainer.width / height | Current visible container dimensions. |
pbiContainer.scrollWidth / scrollHeight | Total dimensions of scrollable content. |
pbiContainer.scrollLeft / scrollTop | Current horizontal and vertical scroll positions. |
Report theme colour schemes
Four Vega colour schemes are bound to the current Power BI report theme. Use them in a scale range and the visual will follow the report theme instead of hard-coded colours, including when the theme changes later.
| Scheme | Use for |
|---|---|
pbiColorNominal | Unordered categories — the report theme's data colours in order. |
pbiColorOrdinal | Ordered categories such as ratings or size bands. |
pbiColorLinear | A continuous measure rendered as a sequential ramp. |
pbiColorDivergent | A measure read against a meaningful midpoint, such as variance to target. |
{
"name": "colorScale",
"type": "ordinal",
"domain": { "data": "chartData", "field": "Category" },
"range": { "scheme": "pbiColorNominal" }
}Expression functions
These functions are available anywhere a Vega expression is, including signals, update encodings, and tooltip signals.
| Function | What it returns |
|---|---|
pbiColor(value, shadePercent) | A colour from the report theme, selected by zero-based index or by name. The optional second argument shades the result by a percentage. |
pbiFormat(value, formatString) | The value formatted with a Power BI format string, so a mark label matches the rest of the report. |
pbiFormatAutoUnit(value, formatString) | The same, but applying automatic display units — the equivalent of the Auto option in the Power BI formatting pane. |
pbiPatternSVG(id, foreground, background) | A pattern fill reference that can be used as a mark fill. |
pbiCrossFilterApply(event, filterExpression) | Applies a cross-filter selection to the report. See Power BI interactions. |
pbiCrossFilterClear() | Clears the current cross-filter selection. |
Named theme colours
As well as a numeric index, pbiColor accepts the report theme's named colours. These follow the theme's sentiment and divergent settings, so a visual signalling good and bad states stays consistent with the rest of the report.
| Name | Theme colour |
|---|---|
positive / good | Sentiment positive. |
negative / bad | Sentiment negative. |
neutral | Sentiment neutral. |
min, middle, max | The divergent minimum, midpoint, and maximum. |
"fill": {
"signal": "datum.Variance < 0 ? pbiColor('bad') : pbiColor('good')"
}Pattern fills
Pattern fills give a second visual channel alongside colour, which matters when a report must stay readable in greyscale or for colour-blind viewers. pbiPatternSVG takes a pattern identifier and a foreground and background colour, and returns a fill reference.
| Group | Identifiers |
|---|---|
| Diagonal stripes | diagonal-stripe-1 to diagonal-stripe-6 |
| Horizontal stripes | horizontal-stripe-1 to horizontal-stripe-9 |
| Vertical stripes | vertical-stripe-1 to vertical-stripe-9 |
| Circles | circles-1 to circles-9 |
| Dots | dots-1 to dots-9 |
| Other | crosshatch, houndstooth |
"fill": {
"signal": "pbiPatternSVG('diagonal-stripe-3', pbiColor(0), '#ffffff')"
}