Modifying Theme Json

Power BI Report Themes

Why Themes Matter

A report without a well-designed theme accumulates formatting debt. Every visual ends up with its own bespoke title size, shadow toggle, border style, and hardcoded colors in visual.json. This creates three problems:

1. Inconsistency. Visuals drift apart as authors format each one individually. One card has 14pt titles, another has 12pt; one chart has shadows, another doesn't. The report looks unfinished. 2. Fragility. Rebranding or updating the visual style means touching every visual.json individually. A report with 40 visuals across 8 pages means 40 files to edit. With a theme, it's one file. 3. Bloated visual JSON. Each bespoke override adds lines to visual.json, making reports harder to diff, review, and maintain. A clean visual.json should contain field bindings, position, and conditional formatting; everything else should come from the theme.

Reports using the default Power BI theme or a minimal custom theme (just dataColors and a name) are leaving most formatting to Power BI's built-in defaults, which change between Desktop releases. A well-designed theme locks in the intended appearance.

Signs a theme needs attention:

• Many visuals have objects or visualContainerObjects with redundant formatting
• Visuals of the same type look inconsistent (different title fonts, shadows on some but not others)
• The theme JSON has few or no visualStyles entries
• The report uses a built-in theme like "Default" or "Classic" without customization

Tooling preference: Use pbir CLI when available (pbir theme colors, pbir visuals clear-formatting). Fall back to direct jq modification when unavailable. Always validate after every write.

Tip: Theme JSON files can be 75KB+ and 2000+ lines. Do not read the full monolithic file. Use pbir theme serialize to split into small editable files (see Author/Modify workflow below), or use jq to extract only specific keys. Serialized fragments from the serialize/build workflow are small and safe to read directly.

For PBIR JSON mechanics (property names, filter pane selectors, ThemeDataColor syntax, jq patterns), see the `pbir-format` skill (pbip plugin) -> references/theme.md.

The Formatting Hierarchy

Power BI applies visual formatting through a four-level cascade. Each level overrides the level above it:

Level 1  Power BI built-in defaults
         |
Level 2  Theme wildcard     visualStyles["*"]["*"]           applies to ALL visuals
         |
Level 3  Theme visual-type  visualStyles["lineChart"]["*"]   overrides wildcard for that type
         |
Level 4  Visual instance    visual.json objects +            overrides everything
                            visualContainerObjects

Core Principle

Push as much formatting as possible into levels 2 and 3. A well-designed theme means:

• Visual JSON files stay lean — no bespoke formatting noise cluttering visual.json
• Global style changes require editing one file
• New visuals automatically inherit correct defaults without manual intervention

Visual-level overrides (level 4) should exist only for true one-offs: content-specific formatting, exceptions to the visual-type default, or conditional formatting expressions.

Diagnosing Why a Visual Looks the Way It Does

When a visual renders unexpectedly, walk up the cascade:

1. Check visual.json → objects and visualContainerObjects (level 4 always wins) 2. Check theme visualStyles["<type>"]["*"] for that visual type (level 3) 3. Check theme visualStyles["*"]["*"] wildcard (level 2) 4. If absent everywhere, Power BI is applying a built-in default

Workflow: Audit Theme Compliance

Use when assessing whether a report's visuals are inheriting from the theme or have accumulated stale overrides.

Step 1 — Locate the custom theme:

THEME_NAME=$(jq -r '.themeCollection.customTheme.name' Report.Report/definition/report.json)
THEME="Report.Report/StaticResources/RegisteredResources/$THEME_NAME"

Step 2 — Review what the theme sets at wildcard level:

# Preferred
pbir theme colors "Report.Report"
pbir theme text-classes "Report.Report"

# Fallback
jq '.visualStyles["*"]["*"] | keys' "$THEME"

Step 3 — Continue with full audit process — see `references/theme-compliance.md` for the complete workflow: scanning all visuals for bespoke overrides, classifying stale vs intentional vs CF, severity levels, and fix decision tree.

Workflow: Enforce Theme (Clear Overrides)

After applying a new theme or making significant theme changes, stale visual-level overrides prevent the new theme from rendering correctly.

With `pbir` CLI (preferred):

# Clears bespoke formatting while preserving conditional formatting expressions
pbir visuals clear-formatting "Report.Report/**/*.Visual" --keep-cf -f

With `jq` (manual, per-visual):

# Safe: clear container chrome only (title, border, background, shadow, padding)
# Does NOT touch chart-specific objects or conditional formatting
jq 'del(.visual.visualContainerObjects)' visual.json > tmp && mv tmp visual.json

# Aggressive: clear everything including chart-specific overrides
# WARNING: also removes conditional formatting — only use if CF is confirmed absent
jq 'del(.visual.objects) | del(.visual.visualContainerObjects)' visual.json > tmp && mv tmp visual.json

# Always validate after
jq empty visual.json

When in doubt, clear visualContainerObjects only. Leave objects unless you have confirmed no conditional formatting exists in that visual.

Switching to a Different Theme (Re-Theming)

Swapping a report from one theme to another is a migration, and editing only the theme JSON leaves theme residue: surviving level-4 overrides that still win at the cascade, plus colors that were correct under the old polarity and break (often invisible text) under the new one. Re-theming sits between apply and enforce: build an old-to-new color map first, then apply the theme, sweep overrides, remap surviving literals, and run the polarity gate so foreground text survives the new background. See `references/re-theming.md`.

Workflow: Author or Modify a Theme

When building or substantially revising a theme, use the serialize/build workflow via pbir CLI. This splits the monolithic theme JSON into small, focused files that are easy to read and edit without loading 2000+ lines of JSON into context.

Serialize/Build Workflow (Recommended)

IMPORTANT: Serialize to a temporary folder outside the .Report/ directory. The PBIR validation hooks monitor .Report/ for JSON changes and will flag the serialized fragments as invalid PBIR files. Use /tmp/, a sibling folder, or the -o flag to place the .Theme folder elsewhere.

Step 1 — Serialize the theme into editable files:

# From a report (outputs to a .Theme folder)
pbir theme serialize "Report.Report" -o /tmp/MyTheme.Theme

# From a standalone theme JSON file
pbir theme serialize theme.json -o /tmp/MyTheme.Theme

This produces small, focused files: _config.json (colors, text classes, named colors), _wildcards.json (wildcard visual styles), and one file per visual-type override (e.g., slicer.json, page.json).

Step 2 — Edit the serialized files. Each file is small enough to read and edit directly. Focus on: 1. _config.json — dataColors, semantic colors, textClasses, background/foreground variants 2. _wildcards.json — container defaults (title, border, shadow, padding) 3. Visual-type files — overrides for specific types (textbox, image, card, etc.)

Step 3 — Build and apply back to the report:

# Build only (produces a merged theme.json)
pbir theme build /tmp/MyTheme.Theme

# Build and apply directly to the report
pbir theme build /tmp/MyTheme.Theme -o "Report.Report" -f --clean

The --clean flag removes the .Theme folder after building.

Quick Modifications (No Serialize Needed)

For small, targeted changes, use the CLI directly without serializing:

pbir theme set-colors "Report.Report" --good "#00B050" --bad "#FF0000"
pbir theme set-text-classes "Report.Report" title --font-size 14 --font-face "Segoe UI Semibold"
pbir theme set-formatting "Report.Report" "*.*.dropShadow.show" --value false

See the `pbir-cli` skill → references/modifying-theme.md for full CLI command reference.

Design Sequence

Whether using serialize/build or direct CLI commands, follow this order:

1. Start from a valid base. Use a template (pbir theme apply-template), the SQLBI/Data Goblins theme, or a community template. Do not author from an empty {}. 2. Design the color system first (dataColors, semantic colors, background/foreground variants). Color decisions cascade everywhere. 3. Set typography (textClasses) — font face and size for title, header, label, callout, dataTitle. Stick to Segoe UI / Segoe UI Semibold; custom fonts will not render on other users' machines. 4. Set wildcard container defaults (visualStyles["*"]["*"]): title visibility/font/size, dropShadow.show: false, padding, border, filter pane. 5. Add visual-type overrides for types that differ from the wildcard — at minimum, textbox and image to suppress title/border/background/shadow. 6. Validate with pbir theme validate "Report.Report", deploy, and visually verify.

For detailed design guidance, see `references/theme-authoring.md`. For visual-type override patterns, see `references/visual-type-overrides.md`.

Workflow: Promote Bespoke Formatting to Theme

When a visual.json has formatting that should become a theme default — either for that visual type or for all visuals — promote it.

With `pbir` CLI (preferred):

# Preview what would be pushed from a well-formatted visual into the theme
pbir theme push-visual "Report.Report/Page.Page/Card.Visual" --dry-run

# Push formatting to theme as the default for that visual type
pbir theme push-visual "Report.Report/Page.Page/Card.Visual"

# Push only specific components (title, background, border, etc.)
pbir theme push-visual "Report.Report/Page.Page/Card.Visual" --components title,background,border

Manual process (when CLI is unavailable):

1. Identify what's in visual.objects (chart-specific) and visual.visualContainerObjects (container chrome) 2. Decide whether it belongs in the wildcard (["*"]["*"]) or a visual-type section (["lineChart"]["*"]) 3. Write the value into the theme, then validate 4. Remove the override from the visual, then validate 5. Verify the visual still renders correctly

Both objects and visualContainerObjects properties map to the same visualStyles[type][state] section in the theme. The distinction in visual.json doesn't exist in the theme.

For complete property mapping tables, wildcard vs visual-type decision guide, color handling, and batch promotion across many visuals, see `references/promoting-formatting.md`.

Workflow: Validate a Theme

With `pbir` CLI (preferred):

# Validate a report's theme (checks JSON syntax, structure, and completeness)
pbir theme validate "Report.Report"

# Validate a standalone theme file
pbir theme validate "theme.json"

# Validate a serialized .Theme folder before building
pbir theme validate "MyTheme.Theme"

Manual validation (when CLI is unavailable):

# 1. JSON syntax
jq empty "$THEME" && echo "JSON valid"

# 2. Required top-level keys
jq '{dataColors: (.dataColors | type), visualStyles: (.visualStyles | type), textClasses: (.textClasses | type)}' "$THEME"

# 3. Wildcard section
jq 'if .visualStyles["*"]["*"] then "wildcard exists" else "MISSING wildcard" end' "$THEME"

# 4. Valid hex colors
jq '[.dataColors[] | select(test("^#[0-9A-Fa-f]{6}$") | not)]' "$THEME"

# 5. No null visual-type sections
jq '[.visualStyles | to_entries[] | select(.value == null) | .key]' "$THEME"

After validation, deploy and visually verify:

• Wildcard container chrome (titles, borders, shadows) applies to all visuals
• Filter pane and filter cards render correctly on all pages
• Visual-type overrides correctly suppress the wildcard for exempt types (e.g., textboxes have no title)
• Data colors cycle correctly on multi-series charts

Schema and Documentation

Resolve the current schema version at author time rather than hardcoding a number:

gh api repos/microsoft/powerbi-desktop-samples/contents/"Report Theme JSON Schema" \
  --jq '.[].name' | sort | tail -1

IDE Integration ($schema)

Add a $schema property to the theme JSON to enable autocomplete and validation in VS Code. Use the versioned raw GitHub URL, not the generic powerbi.com marker:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/powerbi-desktop-samples/main/Report%20Theme%20JSON%20Schema/reportThemeSchema-2.154.json",
  "name": "MyTheme",
  "dataColors": ["#1971c2", "..."]
}

Power BI validates an imported theme against the schema baked into the Desktop build. Validation is reject-unknown-fields: one misspelled key refuses the entire theme. A theme passing jq validation can still fail Desktop import on a typo. See references/theme-authoring.md for the full schema version guidance.

Theme Top-Level Keys

name:          string   # display name shown in Power BI UI
dataColors:    string[] # ordered hex palette for data series

# Semantic CF colors (flat hex keys; CF measures return these names as strings)
good / bad / neutral: string

# Gradient CF colors (flat hex keys; "null" is the key name, not JSON null)
maximum / center / minimum / null: string

# Structural colors (non-data chrome: gridlines, axis labels, filter-card bg, etc.)
# Use level-N names for new themes; CLI alias equivalents shown in parentheses
firstLevelElements:  string  # (foreground)
secondLevelElements: string  # (foregroundNeutralSecondary)
thirdLevelElements:  string  # (backgroundLight)
fourthLevelElements: string  # (foregroundNeutralTertiary)
background:          string
secondaryBackground: string  # (backgroundNeutral)
tableAccent:         string

# Extended surface/foreground palette
foregroundLight / foregroundDark: string
backgroundLight / backgroundNeutral / backgroundDark: string

textClasses:   object  # typography per semantic role (title, label, callout, header, boldLabel, etc.)
visualStyles:  object  # [visualType][state] formatting cascade

For textClasses: 4 primary classes you set; 8 secondary classes that derive automatically. See references/theme-authoring.md.

For visualStyles: named style presets are a second key alongside "*" inside a visual-type section; they surface in the Format pane Style dropdown. See references/advanced-theme-features.md.

References

• `references/theme-authoring.md` — Color system design (data colors, semantic, structural, null gradient), text class inheritance, $id filter-card states, wildcard minimum set, schema version guidance
• `references/advanced-theme-features.md` — Named style presets (Format-pane dropdown), base theme layering model, organizational theme distribution, mobile-only formatting overrides
• `references/serialize-build.md` — Serialize/build workflow: splitting themes into editable files, editing, rebuilding, validation, temporary folder guidance
• `references/applying-themes.md` — Applying templates, post-apply enforcement, clearing visual overrides, normalizing hardcoded colors
• `references/re-theming.md` — Switching a report to a new theme without leaving residue: old-to-new color map, inline-override sweep on shapes/textboxes/buttons, the polarity-flip foreground-text sweep, dark-mode checklist, slicer header role-preserving remap
• `references/copying-themes.md` — Copying themes between reports, extracting/downloading themes, comparing themes, consolidating across a portfolio
• `references/promoting-formatting.md` — Promoting bespoke visual.json formatting to theme: push-visual CLI, objects vs visualContainerObjects, wildcard vs visual-type, property mapping tables
• `references/theme-compliance.md` — Systematic audit workflow, stale override classification, severity levels, fix decision tree
• `references/visual-type-overrides.md` — Override patterns for textbox, image, shape, card, kpi, slicer, lineChart, barChart, tableEx, and matrix

Related Skills

• `pbir-cli` → references/modifying-theme.md — Full CLI command reference for theme operations (serialize/build, set-colors, set-text-classes, set-formatting, push-visual, fonts, background, icons, diff)
• `pbir-cli` → references/apply-theme.md — Applying templates, copying themes between reports, clearing visual overrides
• `pbir-format` (pbip plugin) — Full theme mechanics: ThemeDataColor syntax, filter pane selectors, jq modification patterns, clearing overrides
• `pbi-report-design` — Report design principles: 3-30-300 rule, layout, spacing, color usage, accessibility

actionButton (Action Button)

An interactive button visual that supports bookmark navigation, page navigation, Q&A, drill-through, and web URL actions.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "actionButton": {
      "*": {
        "fill": [{ "show": true, "transparency": 0 }],
        "text": [{
          "show": true,
          "fontFamily": "Segoe UI Semibold",
          "fontSize": 11,
          "horizontalAlignment": "center"
        }],
        "outline": [{ "show": false }],
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      },
      "hover": {
        "fill": [{ "transparency": 20 }]
      },
      "press": {
        "fill": [{ "transparency": 40 }]
      },
      "selected": {
        "outline": [{ "show": true }]
      },
      "disabled": {
        "fill": [{ "transparency": 60 }],
        "text": [{ "show": false }]
      }
    }
  }
}

Notes

• State keys are * (default), hover, press, selected, and disabled — only * is required; omitted states inherit from *.
• fill.$id and text.$id are internal identifiers returned by pbir schema describe but should not be included in theme JSON.
• text.fontColor is a color object ({"solid": {"color": "#FFFFFF"}}), not a plain string; fill.fillColor follows the same pattern.

advancedSlicerVisual (Advanced Slicer)

Card-style slicer that displays items as styled cards with a separate label and value; structurally distinct from the classic slicer visual.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "advancedSlicerVisual": {
      "*": {
        "label": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "fontColor": { "solid": { "color": "#252423" } },
            "bold": false,
            "horizontalAlignment": "left"
          }
        ],
        "value": [
          {
            "show": true,
            "fontSize": 13,
            "fontFamily": "Segoe UI",
            "fontColor": { "solid": { "color": "#252423" } },
            "horizontalAlignment": "left",
            "labelDisplayUnits": 0
          }
        ]
      }
    }
  }
}

Notes

• Has no items or header containers — those belong to the classic slicer type; applying them here has no effect.
• Uses fontSize (not textSize) in both label and value.
• label supports a position property (belowValue / aboveValue) that controls whether the label renders above or below the value within each card.

aiNarratives (AI Narratives)

AI-generated natural language summary visual that produces text descriptions of data from connected visuals or manual prompts.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "aiNarratives": {
      "*": {
        "text": [
          {
            "fontColor": { "solid": { "color": "#252423" } },
            "fontFamily": "Segoe UI",
            "fontSize": 11,
            "textAlignment": "Left"
          }
        ],
        "summary": [
          {
            "autoRefresh": false
          }
        ]
      }
    }
  }
}

Notes

• text is the only container with visual styling properties; fontColor, fontFamily, fontSize, and textAlignment cover all available text formatting.
• summary.autoRefresh is a behaviour toggle (re-run AI generation on data refresh), not a style property — consider whether setting this at theme level is appropriate for your report.
• Background, border, and title styling use the shared background, border, and title containers common to all visuals, not aiNarratives-specific containers.

areaChart (Area Chart)

Area chart that shades the region below each line series; supports the same containers as the line chart.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "areaChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineShow": false
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "lineStyles": [
          {
            "strokeWidth": 2,
            "areaShow": true,
            "showMarker": false
          }
        ]
      }
    }
  }
}

Notes

• Container list is identical to lineChart — see lineChart.md for axis and legend property details.
• lineStyles.areaShow controls whether the fill area is rendered; areaMatchStrokeColor ties the fill to the line colour.
• areaColor accepts { "solid": { "color": "#hex" } } and is only applied when areaMatchStrokeColor is false.

azureMap (Azure Map)

Azure Maps visual supporting multiple layer types: bubbles, heat maps, filled regions, route paths, tile overlays, and 3D bar charts.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "azureMap": {
      "*": {
        "bubbleLayer": [
          {
            "show": true,
            "fillColor": { "solid": { "color": "#0078D4" } },
            "bubbleRadius": 8,
            "mapTransparency": 20,
            "clusteringEnabled": false
          }
        ],
        "filledMap": [
          {
            "show": false,
            "defaultColor": { "solid": { "color": "#0078D4" } },
            "strokeColor": { "solid": { "color": "#FFFFFF" } },
            "strokeWidth": 1,
            "mapTransparency": 20
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "labelColor": { "solid": { "color": "#252423" } },
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ]
      }
    }
  }
}

Notes

• Only one layer type is typically active at a time; set show: false on inactive layers to avoid conflicts.
• bubbleLayer has 42 properties covering clustering, marker images, zoom-range visibility, and bezier easing — theme is appropriate only for baseline defaults, not per-series customisation.
• Map tile style, zoom defaults, and traffic overlays are controlled at the visual level (mapControls, traffic), not meaningfully overridden by theme for most use cases.

barChart (Bar Chart)

Horizontal bar chart; base type for the bar/column family. Most containers (axes, legend, labels, dataPoint, ribbonBands, totals) are shared across all chart types in this family.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "barChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "labels": [
          {
            "show": false,
            "fontSize": 10,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } },
            "labelPosition": "OutsideEnd"
          }
        ],
        "dataPoint": [
          {
            "fillTransparency": 0
          }
        ]
      }
    }
  }
}

Notes

• In a bar chart (horizontal), categoryAxis is the Y-axis (categories) and valueAxis is the X-axis (values) — the opposite of a column chart.
• Axis label color is labelColor, not fontColor; the property name differs from most other visual containers.
• ribbonBands and totals are present on barChart and control stacked/ribbon overlay appearance; for non-stacked series they have no visible effect unless enabled.

bookmarkNavigator (Bookmark Navigator)

A navigation bar that renders a set of bookmarks as clickable tiles, allowing readers to switch report states.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "bookmarkNavigator": {
      "*": {
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "text": [{
          "fontFamily": "Segoe UI",
          "fontSize": 11,
          "fontColor": { "solid": { "color": "#252423" } },
          "bold": false,
          "horizontalAlignment": "center",
          "verticalAlignment": "middle"
        }],
        "fill": [{
          "show": true,
          "fillColor": { "solid": { "color": "#F3F2F1" } },
          "transparency": 0
        }],
        "outline": [{
          "show": true,
          "lineColor": { "solid": { "color": "#C8C6C4" } },
          "weight": 1,
          "transparency": 0
        }],
        "shape": [{ "tileShape": "rectangle", "roundEdge": 4 }],
        "layout": [{ "orientation": 2, "cellPadding": 4 }]
      }
    }
  }
}

Notes

• text styles the label on each bookmark tile; fill and outline control the tile background and border respectively — these are the three primary styling containers.
• layout.orientation accepts 0, 1, or 2; shape.tileShape accepts values including "rectangle", "arrow", "arrowChevron", "arrowPentagon", and others — see pbir schema describe bookmarkNavigator.shape for the full set.
• The bookmarks container controls behaviour (which bookmark group to show, deselection handling) rather than appearance, so it is typically set per-visual rather than via theme.

card (Card)

The legacy single-value card visual that displays one measure value with an optional category label below it.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "card": {
      "*": {
        "labels": [{
          "fontFamily": "Segoe UI Semibold",
          "fontSize": 28,
          "labelDisplayUnits": 0
        }],
        "categoryLabels": [{
          "show": true,
          "fontFamily": "Segoe UI",
          "fontSize": 11
        }],
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• Both labels.color and categoryLabels.color are named color, not fontColor — this differs from most other visual containers.
• labels.labelDisplayUnits accepts integer values: 0 = Auto, 1 = None, 1000 = Thousands, 1000000 = Millions, etc.
• card is the legacy visual; the modern replacement is cardVisual. They do not share container names or property conventions.

cardVisual (Multi-row Card — New Card Visual)

The modern card visual (introduced in 2023) that replaces the legacy card. Supports multiple fields, reference labels, images, and rich layout options.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "cardVisual": {
      "*": {
        "value": [{
          "fontFamily": "Segoe UI Semibold",
          "fontSize": 28,
          "horizontalAlignment": "center",
          "labelDisplayUnits": 0
        }],
        "label": [{
          "show": true,
          "fontFamily": "Segoe UI",
          "fontSize": 11,
          "position": "belowValue"
        }],
        "cardCalloutArea": [{ "show": true, "rectangleRoundedCurve": 4 }],
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• value.fontColor and label.fontColor use fontColor (not color) — the opposite convention from the legacy card visual.
• label.position accepts "belowValue" or "aboveValue", controlling where the field label appears relative to the number.
• cardVisual is the type name used in Power BI's theme JSON even though the visual is marketed as the "New Card"; do not confuse it with multiRowCard, which is a separate legacy visual.

clusteredBarChart (Clustered Bar Chart)

Horizontal clustered bar chart; groups multiple series side-by-side on the same axis.

Containers

Same container structure as barChart with one difference: clusteredBarChart does not have ribbonBands or totals containers. All other containers (categoryAxis, valueAxis, legend, labels, dataPoint, etc.) are identical in property count and names.

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "clusteredBarChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "labels": [
          {
            "show": false,
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ]
      }
    }
  }
}

Notes

• No ribbonBands or totals containers — those are only available on stacked variants and barChart.
• See barChart.md for full container property reference; all shared containers are identical.
• dataPoint has 9 properties here vs 10 on barChart — fillRule (gradient fill rule) is absent on clustered variants.

clusteredColumnChart (Clustered Column Chart)

Vertical clustered column chart; groups multiple series side-by-side. The vertical counterpart to clusteredBarChart.

Containers

Same container structure as clusteredBarChart — no ribbonBands or totals. All axis, legend, labels, and dataPoint containers are identical in properties to barChart.

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "clusteredColumnChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "labels": [
          {
            "show": false,
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ]
      }
    }
  }
}

Notes

• In a column chart (vertical), categoryAxis is the X-axis and valueAxis is the Y-axis — the opposite of barChart.
• No ribbonBands or totals containers — see columnChart.md if you need those.
• See barChart.md for full property reference on all shared containers.

columnChart (Column Chart)

Vertical column chart (single or stacked); adds totals and ribbonBands containers on top of the standard bar/column container set.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "columnChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "labels": [
          {
            "show": false,
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ],
        "totals": [
          {
            "show": true,
            "fontSize": 10,
            "fontFamily": "Segoe UI Semibold",
            "color": { "solid": { "color": "#252423" } }
          }
        ]
      }
    }
  }
}

Notes

• totals labels appear at the top of stacked columns showing the sum; show must be true and the visual must have a legend/series field in the stack.
• ribbonBands controls the connecting bands between stacked segments across categories; most useful when fillMatchColor is false to set a custom ribbon color.
• dataPoint gains a fillRule property (gradient fill rule) compared to clustered variants, enabling gradient fills on individual columns.

decompositionTreeVisual (Decomposition Tree)

AI-assisted hierarchical breakdown visual for exploring root causes and contributions across multiple dimensions.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "decompositionTreeVisual": {
      "*": {
        "levelHeader": [
          {
            "levelTitleFontFamily": "Segoe UI Semibold",
            "levelTitleFontSize": 11,
            "levelTitleFontColor": { "solid": { "color": "#252423" } },
            "levelTitleBold": false,
            "levelSubtitleFontFamily": "Segoe UI",
            "levelSubtitleFontSize": 9,
            "levelSubtitleFontColor": { "solid": { "color": "#605E5C" } },
            "levelHeaderBackgroundColor": { "solid": { "color": "#F3F2F1" } },
            "showSubtitles": true
          }
        ],
        "dataLabels": [
          {
            "dataLabelFontFamily": "Segoe UI",
            "dataLabelFontSize": 10,
            "dataLabelFontColor": { "solid": { "color": "#252423" } },
            "dataLabelBold": false
          }
        ],
        "dataBars": [
          {
            "positiveBarColor": { "solid": { "color": "#0078D4" } },
            "negativeBarColor": { "solid": { "color": "#D13438" } },
            "dataBarWidthPercentage": 80
          }
        ],
        "categoryLabels": [
          {
            "categoryLabelFontFamily": "Segoe UI",
            "categoryLabelFontSize": 10,
            "categoryLabelFontColor": { "solid": { "color": "#252423" } },
            "categoryLabelBold": false
          }
        ]
      }
    }
  }
}

Notes

• Property names in levelHeader are prefixed (levelTitleFontFamily, levelSubtitleFontFamily) — there is no bare fontFamily or fontSize at this level.
• dataBars supports positiveBarColor and negativeBarColor separately; dataBarColor sets the colour when there is no positive/negative distinction.
• dataBars.dataBarScalingType controls relative vs. absolute bar scaling: topNode, parentNode, or levelMaximum.

donutChart (Donut Chart)

Donut chart — a pie chart with a hollow centre; container set is identical to pieChart. The centre hole size is governed by slices.innerRadiusRatio.

Containers

labels.position values: Outside, Inside, BestFit (PascalCase — lowercase values are silently ignored by Power BI)

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "donutChart": {
      "*": {
        "labels": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } },
            "position": "Outside",
            "labelStyle": "Percent of total"
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "slices": [
          {
            "innerRadiusRatio": 60
          }
        ]
      }
    }
  }
}

Notes

• donutChart has no dedicated centre-label container in the schema — the hole is purely visual, sized by slices.innerRadiusRatio (integer, represents a percentage of the outer radius).
• All properties are identical to pieChart — see pieChart.md for full property details.
• Setting slices.innerRadiusRatio to 0 on a donut effectively renders it as a pie.

filledMap (Filled Map)

Choropleth map visual that shades geographic regions by data value using Bing Maps boundary data.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "filledMap": {
      "*": {
        "dataPoint": [
          {
            "defaultColor": { "solid": { "color": "#0078D4" } },
            "transparency": 20,
            "showAllDataPoints": false
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "labelColor": { "solid": { "color": "#252423" } },
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ],
        "stroke": [
          {
            "show": true,
            "strokeColor": { "solid": { "color": "#FFFFFF" } },
            "strokeWidth": 1
          }
        ],
        "mapStyles": [
          {
            "mapTheme": "canvasLight",
            "showLabels": true
          }
        ],
        "mapControls": [
          {
            "autoZoom": true,
            "showZoomButtons": false
          }
        ]
      }
    }
  }
}

Notes

• dataPoint.defaultColor sets the single-series fill; for multi-series, use dataPoint.fill with a fillRule gradient object.
• stroke controls the boundary outline between regions — setting show: false removes region borders entirely.
• categoryLabels in filledMap has only a show property (1 property); label styling is not exposed here.

filter (Filter Entity)

A filter entity attached to a visual, page, or report — not a standalone visual and not the filter pane chrome.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "filter": {
      "*": {
        "general": [{ "requireSingleSelect": false, "isInvertedSelectionMode": false }]
      }
    }
  }
}

Notes

• filter has only one container (general) with two behavioural boolean properties — there is no visual styling (color, font, border) available here.
• This is not the filter pane. Filter pane styling (outspacePane, filterCard) is applied via report-level theme properties, not via visualStyles. See pbir-format skill references: references/filter-pane.md and references/theme.md.
• Use this container sparingly — forcing requireSingleSelect or isInvertedSelectionMode via theme applies the setting globally to all filter entities across the report.

funnel (Funnel)

Funnel chart that displays values as proportionally sized horizontal bars in descending order; supports data labels and a percentage-bar overlay.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "funnel": {
      "*": {
        "labels": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#ffffff" } },
            "funnelLabelStyle": "Data"
          }
        ],
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "percentBarLabel": [
          {
            "show": true,
            "fontSize": 10,
            "fontFamily": "Segoe UI"
          }
        ]
      }
    }
  }
}

Notes

• labels.funnelLabelStyle controls what is shown: Data, Percent of first, Percent of previous, and combined variants.
• percentBarLabel styles the small percentage annotation shown next to the funnel bar; it has show, fontSize, fontFamily, color, bold, italic, underline.
• categoryAxis in a funnel is a simple text label list; it supports show, fontSize, fontFamily, and color only (no gridline properties).

gauge (Gauge)

Dial/gauge chart that plots a single value against a min/max arc; the large central value display is styled via calloutValue.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "gauge": {
      "*": {
        "calloutValue": [
          {
            "show": true,
            "fontFamily": "Segoe UI Semibold",
            "color": { "solid": { "color": "#252423" } },
            "bold": false,
            "labelDisplayUnits": 0
          }
        ],
        "labels": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } }
          }
        ],
        "dataPoint": [
          {
            "fill": { "solid": { "color": "#0078D4" } }
          }
        ]
      }
    }
  }
}

Notes

• calloutValue does not have a fontSize property — font size for the central callout is not directly theme-controllable; use fontFamily and bold to adjust its appearance.
• labels controls the min/max/target tick labels around the arc rim, not the centre value.
• dataPoint.fill sets the arc bar colour; dataPoint.target sets the target indicator colour.

group (Group)

A visual group container that wraps multiple visuals so they can be moved, sized, and layered together as a single unit.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "group": {
      "*": {
        "background": [{ "show": false }],
        "lockAspect": [{ "show": false }]
      }
    }
  }
}

Notes

• group has only three containers; it has no title, border, dropShadow, or visualHeader.
• general properties (x, y, width, height) are positional and stored per-visual — they are not meaningful at theme level.
• Group background is transparent by default; enabling it is useful to give a panel of visuals a shared fill color.

hundredPercentStackedAreaChart (100% Stacked Area Chart)

Stacked area chart normalised to 100% at every category point; each series shows its proportional share rather than absolute values.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "hundredPercentStackedAreaChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "labels": [
          {
            "show": false
          }
        ]
      }
    }
  }
}

Notes

• Container set is identical to stackedAreaChart — see lineChart.md for shared axis and legend details.
• The value axis always displays percentages (0–100%); setting start/end on valueAxis is not meaningful here.
• totals labels show 100% for every category point and are typically hidden.

hundredPercentStackedBarChart (100% Stacked Bar Chart)

Horizontal 100% stacked bar chart; each bar always fills 100% of the axis width, showing relative proportions rather than absolute values.

Containers

Same container structure as barChart plus ribbonBands and totals. All containers are identical in properties to columnChart.

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "hundredPercentStackedBarChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "labels": [
          {
            "show": true,
            "fontSize": 10,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#FFFFFF" } },
            "labelPosition": "InsideCenter"
          }
        ]
      }
    }
  }
}

Notes

• Value axis will always render as 0–100% regardless of start/end settings on valueAxis; those properties are effectively inert here.
• labels are commonly positioned InsideCenter or InsideEnd since bars always span the full width.
• See barChart.md for full property reference; this type is a horizontal stacked variant with the same complete container set.

hundredPercentStackedColumnChart (100% Stacked Column Chart)

Vertical 100% stacked column chart; each column fills 100% of the axis height, showing relative proportions. The vertical counterpart to hundredPercentStackedBarChart.

Containers

Same container structure as columnChart — includes ribbonBands and totals. All containers are identical in properties.

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "hundredPercentStackedColumnChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "labels": [
          {
            "show": true,
            "fontSize": 10,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#FFFFFF" } },
            "labelPosition": "InsideCenter"
          }
        ]
      }
    }
  }
}

Notes

• Value axis renders as 0–100% regardless of start/end values; those properties are inert on this type.
• In column orientation, categoryAxis is the X-axis and valueAxis is the Y-axis.
• See barChart.md for full property reference and hundredPercentStackedBarChart.md for the horizontal equivalent.

image (Image)

A static image container that displays a URL, embedded binary, or data-bound image field on the report canvas.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "image": {
      "*": {
        "image": [{ "fit": "Fit", "transparency": 0 }],
        "lockAspect": [{ "show": true }],
        "title": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• fit accepts "Fit", "Stretch", "Fill", or "Normal" — "Fit" is the safest default for logos and icons.
• lockAspect.show locks the width/height ratio during resize; enable it in the theme to prevent accidental distortion.
• The image source (sourceType, sourceUrl, sourceFile, sourceField) is stored per-visual in the report definition, not in the theme; only presentational properties like fit and transparency are meaningful at theme level.

keyDriversVisual (Key Influencers)

AI visual that analyses a metric to surface the factors (influencers) that drive it up or down.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "keyDriversVisual": {
      "*": {
        "keyInfluencersVisual": [
          {
            "canvasColor": { "solid": { "color": "#FFFFFF" } },
            "primaryColor": { "solid": { "color": "#0078D4" } },
            "secondaryColor": { "solid": { "color": "#E1DFDD" } },
            "fontColor": { "solid": { "color": "#252423" } },
            "primaryFontColor": { "solid": { "color": "#FFFFFF" } },
            "secondaryFontColor": { "solid": { "color": "#252423" } }
          }
        ],
        "keyDriversDrillVisual": [
          {
            "defaultColor": { "solid": { "color": "#0078D4" } },
            "referenceLineColor": { "solid": { "color": "#D13438" } }
          }
        ]
      }
    }
  }
}

Notes

• keyDrivers container controls analysis configuration (analysis type, sort order, target value), not visual styling — leave this out of theme unless setting report-wide analysis defaults.
• keyInfluencersVisual does not expose font family or size — typography for this visual is not theme-controllable.
• The AI analysis itself is not influenced by theme settings; only the colour palette of the rendered output changes.

kpi (KPI)

A KPI visual that shows a primary indicator value against a goal, with an optional trend sparkline and status colouring.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "kpi": {
      "*": {
        "indicator": [{
          "fontFamily": "Segoe UI Semibold",
          "fontSize": 28,
          "horizontalAlignment": "center",
          "showIcon": true
        }],
        "trendline": [{ "show": true, "transparency": 0 }],
        "goals": [{ "showGoal": true, "showDistance": true, "direction": "High is good" }],
        "status": [{ "direction": "Positive" }],
        "title": [{ "show": true }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• The container is trendline (lowercase L) — a common typo is trendLine; the wrong casing will silently be ignored.
• status.direction controls whether positive variance is good ("Positive") or bad ("Negative"); it defaults to "Positive" but must be set explicitly in the theme if your KPIs measure costs.
• goals.direction and status.direction are independent settings: goals.direction labels the distance metric, status.direction determines the colour logic.

lineChart (Line Chart)

Standard line chart for plotting continuous data series over a category or time axis.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "lineChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineShow": false
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "labels": [
          {
            "show": false
          }
        ],
        "lineStyles": [
          {
            "strokeWidth": 2,
            "lineChartType": "linear",
            "showMarker": false
          }
        ]
      }
    }
  }
}

Notes

• gridlineColor and labelColor are objects: { "solid": { "color": "#hex" } }, not plain strings.
• lineChartType controls interpolation: linear, smooth, or step; lineStyle controls stroke pattern: solid, dashed, dotted, custom.
• labels.labelPosition accepts Auto, InsideEnd, OutsideEnd, and others — check schema for the full enum.

lineClusteredColumnComboChart (Line and Clustered Column Chart)

Combo chart that overlays a line series on clustered columns; the primary (left) Y-axis scales the columns and the secondary (right) Y-axis scales the line — both live inside the single valueAxis container.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "lineClusteredColumnComboChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1,
            "secShow": true,
            "secFontSize": 11,
            "secFontFamily": "Segoe UI"
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "lineStyles": [
          {
            "strokeWidth": 2,
            "lineChartType": "linear",
            "showMarker": false
          }
        ]
      }
    }
  }
}

Notes

• Primary and secondary Y-axes share one valueAxis container: primary properties use no prefix (show, fontSize, gridlineColor), secondary properties use the sec prefix (secShow, secFontSize, secLabelColor).
• valueAxis.alignZeros (boolean) aligns the zero tick marks of both axes — useful when one axis goes negative.
• lineStyles applies only to the line series; column styling is controlled via dataPoint.

lineStackedColumnComboChart (Line and Stacked Column Chart)

Combo chart that overlays a line series on stacked columns; adds a totals container for stacked column sum labels compared to the clustered-column variant.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "lineStackedColumnComboChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1,
            "secShow": true,
            "secFontSize": 11,
            "secFontFamily": "Segoe UI"
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "totals": [
          {
            "show": false,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } }
          }
        ]
      }
    }
  }
}

Notes

• Identical to lineClusteredColumnComboChart.md except for the addition of the totals container which labels the sum of each stacked column.
• The dual-axis pattern (sec* prefix on valueAxis) is the same as the clustered-column combo — see that file for details.
• totals.color accepts { "solid": { "color": "#hex" } }.

listSlicer (List Slicer)

New-generation list slicer visual with card-style item rendering; shares the same container structure as advancedSlicerVisual, not the classic slicer.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "listSlicer": {
      "*": {
        "label": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "fontColor": { "solid": { "color": "#252423" } },
            "horizontalAlignment": "left"
          }
        ],
        "value": [
          {
            "show": true,
            "fontSize": 13,
            "fontFamily": "Segoe UI",
            "fontColor": { "solid": { "color": "#252423" } },
            "horizontalAlignment": "left",
            "labelDisplayUnits": 0
          }
        ]
      }
    }
  }
}

Notes

• Despite the name, listSlicer is NOT the same as the classic slicer — it has no items or header containers.
• Uses fontSize (not textSize) in label and value, same as advancedSlicerVisual.
• Adds an expansionIcon container (absent in advancedSlicerVisual) for hierarchical list expansion control.

map (Map)

Bing Maps bubble/heat map visual for geographic data visualisation using latitude/longitude or address geocoding.

Containers

Theme Example

{
  "map": {
    "legend": {
      "show": true,
      "position": "Bottom",
      "labelColor": { "solid": { "color": "#252423" } },
      "fontSize": 10,
      "fontFamily": "Segoe UI"
    },
    "dataPoint": {
      "defaultColor": { "solid": { "color": "#0078D4" } },
      "transparency": 20
    },
    "categoryLabels": {
      "show": true,
      "color": { "solid": { "color": "#252423" } },
      "fontSize": 9,
      "fontFamily": "Segoe UI"
    },
    "mapStyles": {
      "mapTheme": "canvasLight",
      "showLabels": true
    },
    "mapControls": {
      "autoZoom": true,
      "showZoomButtons": true
    }
  }
}

Notes

• mapStyles.mapTheme accepts: aerial, canvasDark, canvasLight, road, grayscale.
• heatMap.show must be true for heat map layer properties to take effect; heat map and bubble layers are mutually exclusive display modes.
• Practical theme impact is limited — map tile style, geocoding culture, and zoom defaults are the main levers; per-data-point colours require field-level conditional formatting.

multiRowCard (Multi-Row Card)

A legacy multi-row card visual that displays multiple fields per record in a repeating card layout with an optional left accent bar.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "multiRowCard": {
      "*": {
        "cardTitle": [{
          "fontFamily": "Segoe UI Semibold",
          "fontSize": 12
        }],
        "dataLabels": [{
          "fontFamily": "Segoe UI",
          "fontSize": 11
        }],
        "card": [{ "barShow": false }],
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• cardTitle.color and dataLabels.color are named color, not fontColor — consistent with the legacy card visual and inconsistent with cardVisual.
• To hide the left accent bar, set card.barShow to false — there is no separate bar container; barShow lives inside the card container.
• multiRowCard is a distinct legacy visual type; the modern equivalent is cardVisual (the New Card), which has a completely different container structure.

pieChart (Pie Chart)

Circular chart that divides a whole into proportional slices; supports outside, inside, and adaptive label placement.

Containers

labels.position values: outside, inside, preferOutside, preferInside

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "pieChart": {
      "*": {
        "labels": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } },
            "position": "outside",
            "labelStyle": "Percent of total"
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "dataPoint": [
          {
            "fillTransparency": 0
          }
        ]
      }
    }
  }
}

Notes

• labels.color and legend.labelColor accept { "solid": { "color": "#hex" } }, not plain strings.
• slices.innerRadiusRatio converts a pie into a donut when set > 0; use donutChart if you want a donut with a centre label.
• labels.labelStyle controls what is shown on each slice: Category, Data, Percent of total, and combinations thereof.

pivotTable (Matrix)

Matrix visual with row/column hierarchies, stepped layout, and independent row/column total styling.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "pivotTable": {
      "*": {
        "columnHeaders": [
          {
            "backColor": { "solid": { "color": "#252423" } },
            "fontColor": { "solid": { "color": "#FFFFFF" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "outlineColor": { "solid": { "color": "#3B3A39" } },
            "outlineStyle": 2,
            "outlineWeight": 1
          }
        ],
        "rowHeaders": [
          {
            "backColor": { "solid": { "color": "#F3F2F1" } },
            "fontColor": { "solid": { "color": "#252423" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "stepped": true,
            "steppedLayoutIndentation": 10
          }
        ],
        "values": [
          {
            "backColorPrimary": { "solid": { "color": "#FFFFFF" } },
            "backColorSecondary": { "solid": { "color": "#F3F2F1" } },
            "fontColorPrimary": { "solid": { "color": "#252423" } },
            "fontColorSecondary": { "solid": { "color": "#252423" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "total": [
          {
            "backColor": { "solid": { "color": "#E1DFDD" } },
            "fontColor": { "solid": { "color": "#252423" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "applyToHeaders": true
          }
        ],
        "grid": [
          {
            "gridHorizontal": true,
            "gridHorizontalColor": { "solid": { "color": "#E1DFDD" } },
            "gridHorizontalWeight": 1,
            "gridVertical": false
          }
        ]
      }
    }
  }
}

Notes

• The theme key is `pivotTable`, not `matrix`. Using matrix has no effect — this is a common gotcha.
• stepped and steppedLayoutIndentation (pixels) in rowHeaders control the cascading indent for hierarchy levels.
• pivotTable has separate columnTotal and rowTotal containers (8 properties each) for independent grand total styling beyond what total covers.

pythonVisual (Python Visual)

Renders output from a Python script (e.g. matplotlib, seaborn) as a static image inside a Power BI visual container.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "pythonVisual": {
      "*": {
        "title": [{ "fontFamily": "Segoe UI", "fontSize": 12, "bold": false }],
        "background": [{ "show": true, "color": { "solid": { "color": "#F5F5F5" } }, "transparency": 0 }],
        "border": [{ "show": false }],
        "padding": [{ "top": 8, "right": 8, "bottom": 8, "left": 8 }]
      }
    }
  }
}

Notes

• The script container holds provider (e.g. "PBI_CV_...") and source (the Python code string); neither is meaningful to theme — they are set per-visual.
• The rendered plot image fills the visual container; no data-layer formatting (axes, colors, fonts inside the plot) is controlled by Power BI themes — style those inside the Python script itself.
• Use the python-visuals skill (custom-visuals plugin) when authoring or editing the Python script.

qnaVisual (Q&A Visual)

Provides a natural language question-and-answer interface that generates visuals from typed queries.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "qnaVisual": {
      "*": {
        "title": [{ "fontFamily": "Segoe UI", "fontSize": 12, "bold": false }],
        "background": [{ "show": true, "color": { "solid": { "color": "#FFFFFF" } }, "transparency": 0 }],
        "inputBox": [{
          "questionFontFamily": "Segoe UI",
          "questionFontSize": 14,
          "questionFontColor": { "solid": { "color": "#252423" } },
          "background": { "solid": { "color": "#F3F2F1" } },
          "acceptedColor": { "solid": { "color": "#107C10" } },
          "errorColor": { "solid": { "color": "#D13438" } }
        }],
        "suggestions": [{
          "show": true,
          "headerFontFamily": "Segoe UI Semibold",
          "headerFontSize": 11,
          "headerFontColor": { "solid": { "color": "#252423" } },
          "cardFontFamily": "Segoe UI",
          "cardFontSize": 11,
          "cardFontColor": { "solid": { "color": "#605E5C" } }
        }]
      }
    }
  }
}

Notes

• inputBox has separate font properties for the question text (questionFontFamily, questionFontSize, questionFontColor) and the restatement line (restatementFontFamily, restatementFontSize, restatementFontColor) — these are distinct fields, not a single fontFamily/fontColor.
• suggestions similarly splits header and card typography; show controls whether the suggestions panel appears at all.
• State colors (acceptedColor, errorColor, warningColor) provide semantic feedback and should maintain sufficient contrast against the background object color.

rdlVisual (Paginated Report Visual)

Embeds a Power BI paginated report (SSRS/RDL) inside a Power BI report page as a visual.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "rdlVisual": {
      "*": {
        "title": [{ "fontFamily": "Segoe UI", "fontSize": 12, "bold": false }],
        "background": [{ "show": true, "color": { "solid": { "color": "#FFFFFF" } }, "transparency": 0 }],
        "border": [{ "show": true, "color": { "solid": { "color": "#E0E0E0" } }, "width": 1 }],
        "toolbar": [{ "show": true, "position": 0, "pageNavigation": true, "paramButton": true }],
        "export": [{ "show": true, "exportPDF": true, "exportExcel": true }]
      }
    }
  }
}

Notes

• The reportInfo container (reportId, workspaceId, reference) identifies which paginated report to embed and is set per-visual, not via theme.
• The content of the paginated report itself (fonts, colors, layout defined in the RDL) is not controlled by Power BI report themes — style it in the paginated report directly (Power BI Report Builder or Fabric).
• toolbar.position accepts 0 (top) or 1 (bottom); useFloatingToolbar makes the toolbar appear only on hover.

ribbonChart (Ribbon Chart)

Column chart that shows rank changes over time using ribbon connectors between bars; the ribbonBands container controls the connector appearance.

Containers

Same container structure as columnChart — includes ribbonBands and totals.

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "ribbonChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } },
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "ribbonBands": [
          {
            "show": true,
            "fillMatchColor": true,
            "fillTransparency": 30,
            "borderShow": false
          }
        ]
      }
    }
  }
}

Notes

• ribbonBands.fillMatchColor: true tints ribbons to match their corresponding bar color; set to false and use fillColor to override with a custom color.
• ribbonBands.show: false removes the connecting ribbons entirely, leaving a plain column chart appearance.
• borderColorMatchFill controls whether the ribbon border inherits the fill color; set to false to use borderColor independently.

scatterChart (Scatter Chart)

Scatter and bubble chart for plotting two (or three) numeric measures against each other; supports play-axis animation.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "scatterChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineShow": true,
            "gridlineColor": { "solid": { "color": "#E0E0E0" } }
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "categoryLabels": [
          {
            "show": false,
            "fontSize": 9,
            "fontFamily": "Segoe UI"
          }
        ]
      }
    }
  }
}

Notes

• scatterChart has no `labels` container — attempting to set one is silently ignored. Per-point labels use categoryLabels instead.
• categoryAxis in scatter context controls the X-axis (horizontal numeric axis), not discrete categories.
• dataPoint.fill supports conditional formatting rules, making it the right place to drive colour-by-category or colour-by-measure logic.

scorecard (Scorecard)

Power BI goals/metrics tracker visual that connects to a Fabric scorecard to display progress against targets.

Containers

Theme Example

{
  "scorecard": {
    "header": {
      "show": true,
      "showTitle": true,
      "showToolbar": false,
      "backgroundColor": { "solid": { "color": "#252423" } },
      "foregroundColor": { "solid": { "color": "#FFFFFF" } }
    },
    "columnHeaders": {
      "show": true,
      "foregroundColor": { "solid": { "color": "#605E5C" } }
    },
    "scorecard": {
      "backgroundColor": { "solid": { "color": "#FFFFFF" } },
      "foregroundColor": { "solid": { "color": "#252423" } },
      "tableBackgroundColor": { "solid": { "color": "#F3F2F1" } },
      "fontFamily": "Segoe UI",
      "displayMode": "list",
      "showCommandBar": false
    },
    "goals": {
      "backgroundColor": { "solid": { "color": "#FFFFFF" } },
      "foregroundColor": { "solid": { "color": "#252423" } }
    }
  }
}

Notes

• The scorecard container uses foregroundColor / backgroundColor (not fontColor / backColor) — naming differs from table-family visuals.
• scorecard.scorecardId and scorecard.scorecardReference are connection properties set at report level, not in theme.
• Theme control is intentionally limited; most scorecard appearance (status colours, KPI icons) is governed by the connected Fabric scorecard definition.

scriptVisual (R Script Visual)

Renders output from an R script (e.g. ggplot2, base R graphics) as a static image inside a Power BI visual container.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "scriptVisual": {
      "*": {
        "title": [{ "fontFamily": "Segoe UI", "fontSize": 12, "bold": false }],
        "background": [{ "show": true, "color": { "solid": { "color": "#F5F5F5" } }, "transparency": 0 }],
        "border": [{ "show": false }],
        "padding": [{ "top": 8, "right": 8, "bottom": 8, "left": 8 }]
      }
    }
  }
}

Notes

• The script container holds provider and source (the R code string); neither property is meaningful to theme — they are set per-visual.
• The rendered plot image fills the container; axis colors, fonts, and chart styling inside the R plot are not controlled by Power BI themes — apply those via ggplot2 themes or base R par() in the script itself.
• Use the r-visuals skill (custom-visuals plugin) when authoring or editing the R script.

shape (Shape)

A decorative geometric shape (rectangle, circle, line, arrow, etc.) used for visual layout and framing on the report canvas.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "shape": {
      "*": {
        "fill": [{ "show": true, "transparency": 0 }],
        "outline": [{ "show": false }],
        "title": [{ "show": false }],
        "background": [{ "show": false }],
        "border": [{ "show": false }],
        "dropShadow": [{ "show": false }]
      }
    }
  }
}

Notes

• fill.fillColor and outline.lineColor are color objects — not plain strings. Use {"solid": {"color": "#DDDDDD"}}.
• shape.tileShape controls the geometry (e.g. "rectangle", "oval", "line", "arrow"); this is typically set per-visual, not in the theme.
• The shape type has no visualHeader container — there is no hover action bar for decorative shapes.

shapeMap (Shape Map)

Custom shape map visual that renders user-supplied TopoJSON/GeoJSON shape files, coloured by data values.

Containers

Theme Example

{
  "shapeMap": {
    "dataPoint": {
      "defaultColor": { "solid": { "color": "#0078D4" } },
      "showAllDataPoints": true
    },
    "legend": {
      "show": true,
      "position": "Bottom",
      "labelColor": { "solid": { "color": "#252423" } },
      "fontSize": 10,
      "fontFamily": "Segoe UI"
    },
    "defaultColors": {
      "defaultColor": { "solid": { "color": "#E1DFDD" } },
      "borderColor": { "solid": { "color": "#FFFFFF" } },
      "borderThickness": 1,
      "defaultShow": true
    }
  }
}

Notes

• Requires a custom shape file (TopoJSON format) — the visual renders no map without one.
• defaultColors.defaultColor fills shapes that have no matching data; defaultColors.defaultShow controls whether those unmatched shapes are visible at all.
• dataPoint in shapeMap has no transparency property (unlike filledMap) — opacity is not adjustable via theme.

slicer (Slicer)

List-style slicer for filtering by discrete field values; supports list, dropdown, and tile display modes.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "slicer": {
      "*": {
        "items": [
          {
            "textSize": 11,
            "fontFamily": "Segoe UI",
            "fontColor": { "solid": { "color": "#252423" } },
            "bold": false,
            "padding": 4
          }
        ],
        "header": [
          {
            "show": true,
            "textSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "fontColor": { "solid": { "color": "#252423" } },
            "showRestatement": true
          }
        ],
        "searchBox": [
          {
            "borderColor": { "solid": { "color": "#D1D1D1" } }
          }
        ]
      }
    }
  }
}

Notes

• Both items and header use textSize, not fontSize — using fontSize is silently ignored.
• fontColor is an object { "solid": { "color": "#hex" } }, not a plain string.
• The searchBox container styles the hover/focus search input that appears when search is enabled on the slicer; it has no font controls.

stackedAreaChart (Stacked Area Chart)

Stacked area chart that accumulates series values so the filled areas do not overlap; adds seriesLabels and totals on top of the standard area chart containers.

Containers

legend.position enum: Top, TopCenter, TopRight, Left, Right, LeftCenter, RightCenter, Bottom, BottomCenter, BottomRight

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "stackedAreaChart": {
      "*": {
        "categoryAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "valueAxis": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "gridlineColor": { "solid": { "color": "#E0E0E0" } },
            "gridlineThickness": 1
          }
        ],
        "legend": [
          {
            "show": true,
            "position": "Bottom",
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "labelColor": { "solid": { "color": "#252423" } }
          }
        ],
        "totals": [
          {
            "show": true,
            "fontSize": 11,
            "fontFamily": "Segoe UI",
            "color": { "solid": { "color": "#252423" } }
          }
        ]
      }
    }
  }
}

Notes

• All axis, legend, lineStyles, and markers containers are identical to lineChart — see lineChart.md.
• seriesLabels.textSize (not fontSize) controls the end-of-series label font size; seriesPosition is Left or Right.
• totals renders a data label at the top of each stacked column showing the sum across all series.

tableEx (Table)

Standard tabular data visual with alternating row support and configurable grid lines.

Containers

Theme Example

{
  "name": "My Theme",
  "visualStyles": {
    "tableEx": {
      "*": {
        "columnHeaders": [
          {
            "backColor": { "solid": { "color": "#252423" } },
            "fontColor": { "solid": { "color": "#FFFFFF" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "outlineColor": { "solid": { "color": "#3B3A39" } },
            "outlineStyle": 2,
            "outlineWeight": 1
          }
        ],
        "values": [
          {
            "backColorPrimary": { "solid": { "color": "#FFFFFF" } },
            "backColorSecondary": { "solid": { "color": "#F3F2F1" } },
            "fontColorPrimary": { "solid": { "color": "#252423" } },
            "fontColorSecondary": { "solid": { "color": "#252423" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI"
          }
        ],
        "total": [
          {
            "backColor": { "solid": { "color": "#E1DFDD" } },
            "fontColor": { "solid": { "color": "#252423" } },
            "fontSize": 11,
            "fontFamily": "Segoe UI Semibold",
            "totals": true
          }
        ],
        "grid": [
          {
            "gridHorizontal": true,
            "gridHorizontalColor": { "solid": { "color": "#E1DFDD" } },
            "gridHorizontalWeight": 1,
            "gridVertical": false
          }
        ]
      }
    }
  }
}

Notes

• Use backColor (not backgroundColor) for column headers and totals row background.
• backColorPrimary / backColorSecondary control alternating row banding in values; backColor in values sets a flat (non-banded) background.
• outlineStyle is an integer — common values: 0 (none), 1 (bottom only), 2 (all sides).