What Is a Power BI Theme File (theme.json)?

A Power BI theme file is a plain JSON file (often named something like mytheme.json) that tells Power BI which colors, fonts, and default formatting to apply across an entire report. Instead of styling each chart one visual at a time, you load one theme file and the whole report restyles at once. It's the fastest way to make a report look consistent and on-brand.

This guide covers what's actually inside a theme file, the two parts that matter most (dataColors and the structural classes), how to load one, and how to generate a valid file without hand-writing JSON.

What a theme file actually controls

A theme governs the look of a report, not the data. Think of it as a visual stylesheet that sits on top of your semantic model. A single theme can set:

• Data colors — the palette used to color chart series (bars, lines, slices, points).
• Structural colors — backgrounds, foreground text, table accents, gridlines, and dividers.
• Text classes — fonts, sizes, and weights for titles, axis labels, callout values, and more.
• Visual styles — formatting defaults that apply to every visual of a type (for example, turning data labels on for all bar charts, or setting a default corner radius).

What it does not control: the numbers themselves, your relationships, your measures, or page layout. A theme restyles what's already on the canvas; it doesn't move or model anything.

The anatomy of a theme.json

The only strictly required field is name. In practice you'll almost always include dataColors too, and everything else is optional and layers on more control. Here's a compact but valid example:

{
  "name": "Acme Brand",
  "dataColors": [
    "#1F4E79", "#2E86AB", "#E8A33D",
    "#6A8D73", "#9B2D30", "#52527A"
  ],
  "foreground": "#252423",
  "background": "#FFFFFF",
  "tableAccent": "#1F4E79",
  "textClasses": {
    "title":   { "fontFace": "Segoe UI Semibold", "fontSize": 14, "color": "#252423" },
    "label":   { "fontFace": "Segoe UI", "fontSize": 9 },
    "callout": { "fontFace": "Segoe UI", "fontSize": 28, "color": "#1F4E79" }
  }
}

Save that as acme.json and you have a working theme. Power BI reads the keys it recognizes and ignores the rest, which is why even a tiny file works.

dataColors: the part you'll touch most

dataColors is an ordered array of hex color strings. Power BI assigns them to series in order: the first category gets the first color, the second gets the second, and so on. When a chart has more series than you have colors, Power BI generates additional colors by varying saturation and hue, so it's worth supplying at least 8 to 10 distinct colors of your own.

A few practical rules:

• Lead with your strongest brand color. It lands on the first series in most visuals, so make it count.
• Keep colors distinguishable. Avoid two near-identical blues sitting next to each other in the array — they're hard to tell apart in a stacked bar.
• Mind accessibility. Aim for enough contrast that colorblind viewers can separate series. Putting red and green next to each other is the classic mistake.

You can still override a single visual's colors after applying a theme, but the goal of dataColors is to almost never need to.

Structural colors and text classes: the report frame

Where dataColors styles the data, the structural keys style everything around it. The most commonly used:

Key	What it controls
foreground	Default text and icon color for many elements (cards, KPIs, table text)
background	Visual and canvas background fills
tableAccent	Accent and border color in tables and matrices
firstLevelElements / secondLevelElements	Text and detail shades in the newer schema versions
good / neutral / bad	Status colors used by KPI and waterfall visuals
textClasses	Named font styles (title, label, callout, header) reused across visuals

textClasses is the lever for typography. Set title and label once and every visual title and axis label inherits the same font and size. That consistency is what makes a themed report feel designed rather than assembled.

Built-in themes vs. custom JSON

Power BI ships with a set of built-in themes you can pick from the View → Themes gallery (Default, Executive, and others). They're convenient but generic. A custom theme.json is how you express your brand or a client's: exact hex codes, the right font, sensible defaults.

There's also a distinction worth knowing inside .pbip projects — the newer folder-based "Power BI Project" format that saves a report as plain files instead of a single binary .pbix, which makes it friendlier for source control. In a PBIP, the report theme lives as a JSON file inside the report folder, so the same concepts apply. It's still a theme.json, just stored in a versionable project structure rather than baked invisibly into a .pbix.

How to load a theme into Power BI Desktop

Power BI Desktop is the free authoring app, so you don't need a paid license to apply a theme. The flow:

1. Open your report in Power BI Desktop.
2. Go to the View ribbon.
3. Open the Themes dropdown.
4. Click Browse for themes.
5. Select your .json file. The report restyles instantly.

To adjust after loading, choose Customize current theme for a no-code dialog (colors, text, visual defaults), then Save current theme to export it back out as a .json you can reuse on other reports or share with teammates. That export is the cleanest way to clone a look across a portfolio of reports.

A couple of gotchas:

• If a file fails to import, it's almost always invalid JSON — a trailing comma, a missing quote, or a # left off a hex code. Run it through a JSON validator first.
• Applying a theme respects manual overrides already set on individual visuals. If a chart "won't change color," it likely has a hard-coded color in its formatting pane; clear that and the theme takes over.

Generate a valid theme without writing JSON

Hand-editing JSON is error-prone, and the full schema supports hundreds of optional visual-style keys most people never need. The faster path is to generate the file:

• Use Power BI Desktop's Customize current theme dialog and export — good for quick palette and font changes.
• Or use a dedicated builder. Instant PowerBI's free Power BI theme generator lets you pick a palette and fonts and download a ready-to-import theme.json — no JSON syntax to get wrong, and it produces the dataColors array and structural keys for you.

If you want to go deeper on palette choices and brand consistency, our guide to building a branded Power BI report walks through pairing a theme with a clean star schema, so the whole report — not just the colors — looks intentional.

When a theme is enough, and when it isn't

A theme file solves consistency and branding. It won't fix a messy data model, awkward visual choices, or a report that's slow because of poor relationships. The best results come from doing both: a tidy semantic model with well-named measures, plus a theme that makes the output look like it belongs to your organization. The theme is the last 10% that makes a report feel finished — but it can't rescue the first 90%.

---

If you'd rather skip the theming, modeling, and formatting altogether, that's what Instant PowerBI does. Send us your raw CSV or Excel data and we'll send back a finished, branded Power BI report — fully modeled, themed to your colors, and ready to open in the free Power BI Desktop. Get started, and grab a starter palette from our free theme generator while you're at it.