Powerbi Report CLI

Conditional Formatting Patterns

Contents

• Field-Value Result Contracts and Support Guardrails

  • Result contracts

  • Shared authoring checks

  • Support decision and fallbacks

  • Validation and diagnostics

• VCO Conditional Formatting

  • Data-Bound Expression Rules

• Authoring Workflow

• Formatting Options by Visual Type

  • Tables/matrices

  • Charts

Read this when applying data-driven visual formatting in PBIR. Conditional formatting is supported on chart dataPoint properties, line and marker colors, selected data-label colors,table / matrix values cells, and selected card/KPI font-color properties. Support is property-specific; do not assume that every color property accepts a rule. The supported visual-container properties are listed under VCO Conditional Formatting. Other container objects such as axes and legends are not covered by these patterns.

Page canvas and wallpaper colors are also not conditional-formatting targets. Use static colors only; see page-formatting.md § Dynamic Color Limitation (see page-formatting.md, section dynamic-color-limitation).

Related references:

• formatting.md (see formatting.md) — value encoding, selectors, VCOs.

• formatting-overview.md (see formatting-overview.md) — cascade and encoding.

• expressions.md (see expressions.md) — Measure, Column, Aggregation, NativeMeasure, and ScopedEval expression trees.

• table.md (see table.md) — table/matrix authoring and style presets.

Examples use illustrative <table>.<measure> identifiers — substitute your own.

Field-Value Result Contracts and Support Guardrails

A field-value binding is valid only when its driver resolves to one scalar value that the target property accepts. A valid PBIR expression shape does not prove that the runtime value is valid or that the target supports field-value formatting.

Use this section as a contract and routing index. Keep detailed PBIR mechanics in the linked result-type and visual-specific sections below.

Result contracts

Shared authoring checks

• Refuse incompatible or unknown result types before writing PBIR. A color field-value driver must be verified as text-typed and return valid color strings; a Web URL driver must be text-typed and return absolute HTTP(S) URLs; an image driver must additionally have dataCategory: ImageUrl. Do not author a deliberately invalid binding to discover Desktop's fallback. If the driver's type, data category, or representative values cannot be verified, stop and request a valid field or the required semantic-model correction.

• Keep the displayed/formatting target separate from the driver that supplies the result. Follow Driving field vs. target field (continued in conditional-formatting-part-03.md).

• Ensure the driver resolves to one scalar value. Reference measures directly; aggregate raw columns as documented in Aggregation: columns vs. measures (continued in conditional-formatting-part-03.md).

• Treat Min/Max only as scalarization. Use it when all contributing rows should return the same result or lexical minimum/maximum is intentional; otherwise use a measure that defines the business rule.

• Use the target visual's documented expression and selector route; see the selector summary (continued in conditional-formatting-part-03.md). Do not infer one visual's route from another.

Support decision and fallbacks

1. Confirm the visual type, object, property, and accepted expression type with powerbi-report-author catalog describe and powerbi-report-author formatting describe-object.

2. Check the target-specific matrices in this file. A property typed as fill proves its value shape, not that the target property supports field-value, Rules, or Gradient formatting.

3. Verify the model field/measure exists, has the required data type and data category, and returns values matching the table above. This is a hard pre-authoring gate: reject numeric/boolean color outputs, non-URL action values, and image fields without ImageUrl metadata rather than persisting them for Desktop to diagnose. Delegate model changes or data inspection to the semantic-model authoring capability.

4. If the target is supported, author the documented selector and expression. If unsupported, do not move the expression to a similarly named property or rely on schema permissiveness. Explain the limitation and offer a static value or a supported built-in visual/target.

5. Run PBIR validation, load the latest report, and review a screenshot with representative nonblank, blank, and invalid values where those cases can occur.

Known cross-cutting unsupported cases include:

• Page canvas and wallpaper field-value colors; use static colors and see page-formatting.md (see page-formatting.md, section dynamic-color-limitation).

• Table/matrix column width is static and not conditionally formattable; see Column width (continued in conditional-formatting-part-07.md).

• Button icon glyph/size/placement, shape geometry, and shadow/glow numeric parameters; only their documented color or text properties are data-driven.

• Chart Web URL actions and field-driven icon names.

• Any visual/property combination marked No* or unsupported in a capability matrix in this file.

Marketplace, organizational, and private custom visuals define their own capabilities. The built-in catalog and matrices in this guide cannot guarantee their field-value support. Inspect the visual package's capabilities.dataRoles and formatting capabilities or authoritative vendor documentation, then verify in Desktop. Successful registration and recognition do not prove that a custom visual supports conditional formatting. See custom-visuals.md (see custom-visuals.md).

Validation and diagnostics

Offline validation cannot evaluate the values returned by model measures or columns, so runtime rendering remains required.

VCO Conditional Formatting

Visual-container conditional formatting is stored in visual.json → visual.visualContainerObjects. VCOs are visual-wide settings and do not use selectors.

general.altText describes the visual and its meaningful insights for accessibility.

Data-Bound Expression Rules

Literal and ThemeDataColor are constant/static expressions rather than conditional-formatting types. FillRule corresponds to Type 1, and Conditional.Cases[] corresponds to Type 2.

Authoring Workflow

1. Identify the visual type. Start with the relevant section under Formatting Options by Visual Type.

2. Validate the result and target. Apply the field-value result contracts and support guardrails, then follow the linked type for the desired result, such as a gradient, rules, icons, data bars, links, or field-driven color.

3. Build the formatting expression. Reference the field or measure that drives the formatting and follow the driver-expression decision path (continued in conditional-formatting-part-03.md): an existing visual query selection uses SelectRef; otherwise a DAX measure uses Measure, and a raw column uses Aggregation(Column, Function). Keep the driving field distinct from the target field (continued in conditional-formatting-part-03.md) and use only valid hex color results (continued in conditional-formatting-part-03.md).

4. Apply the correct object and selector. Use the selector summary (continued in conditional-formatting-part-03.md); requirements differ across tables, matrices, charts, cards, and KPIs.

5. Validate and render. Run powerbi-report-author validate <path>, reload the report in Desktop, and confirm that the formatting appears.

Formatting Options by Visual Type

Tables/matrices

• Cell gradients: Type 1: Color Gradient (continued in conditional-formatting-part-04.md)

• Rule-based cell colors: Type 2: Rules-Based Formatting (continued in conditional-formatting-part-05.md)

• Cell icons: Type 3: Icon Sets (continued in conditional-formatting-part-06.md)

• In-cell bars: Type 4: Data Bars (continued in conditional-formatting-part-06.md)

• Clickable links: Type 5: Web URL (continued in conditional-formatting-part-06.md)

• Colors supplied by a field: Type 6: Field-Driven Color (continued in conditional-formatting-part-07.md)

• Images in cells: Type 7: Image Field Values (continued in conditional-formatting-part-07.md)

• Totals/subtotals targeting: Totals, subtotals, and the matrix total slot (continued in conditional-formatting-part-07.md)

• Column width (not conditionally formattable; static width lives in table.md § Column width (static) (see table.md, section column-width-static)): Column width — not conditionally formattable (continued in conditional-formatting-part-07.md)

tableEx (table) and pivotTable (matrix) share the same CF syntax for Types 1–6. Those types use the same objects and selectors on both visuals; the examples below use a table for brevity and apply to a matrix unchanged. On a matrix the metadata queryRef still targets the Values measure whose cells you format (Types 1/2/3/5/6 use dataViewWildcard + metadata; Type 4 data bars are metadata-only). Type 7 (image field values) differs between the two — a table binds an ImageUrl column directly, while a matrix needs a measure or an Aggregation-wrapped column; see Type 7 (continued in conditional-formatting-part-07.md) for the placement rules.

Cell CF targets Values-role fields. Both visuals bind the formatted field through the Values role. In a pivotTable, cell CF (Background color, Font color, Data bars, Icons, Web URL) is available only for Values-role fields — fields in the Rows or Columns role cannot be conditionally formatted this way, so the metadata selector must reference a Values-role field's queryRef, never a Rows/Columns field. A tableEx has a single Values role that holds every displayed column, so any column can be formatted. (Row/column header styling is a separate format-pane setting, not cell CF.)

Charts

• Data-point, line, marker, and label gradients: Type 1: Color Gradient (continued in conditional-formatting-part-04.md)

• Rule-based chart colors: Type 2: Rules-Based Formatting (continued in conditional-formatting-part-05.md)

• Colors supplied by a field: Type 6: Field-Driven Color (continued in conditional-formatting-part-07.md)

• Legend and series-label color consistency: Chart color inheritance (continued in conditional-formatting-part-07.md)