Power BI Background Image Shows White Bars: Fit vs Fill vs Normal (and the Theme JSON Naming Swap)

The canvas has a fixed pixel size (Format page, Canvas settings; 16:9 at 1920×1080, the Fluent 2 default for new pages, or 1280×720 on Classic reports). The background image has its own pixel size. When the two aspect ratios match, any fit mode fills the canvas. When they do not, something has to give: either the image keeps its proportions and leaves empty canvas (bars), or it is stretched to the canvas (distortion), or it is scaled to cover the canvas and cropped (no bars, lost edges).

The bars are the canvas background colour showing through. On Classic base themes that is white; on Fluent 2, where "the wallpaper and background are now shades of grey", the bars are grey. Same cause, different colour.

A second, less common cause is transparency: a page background set to a high Transparency value fades the image into the canvas colour. Check that Transparency is 0% before chasing dimensions.

Describe them by what they do to a mismatched image, because the labels vary (next section).

Scale to fit, keep ratio: the image is scaled until one dimension matches the canvas, the other falls short, and you get bars on the short axis. Sharp, undistorted, bars.

Stretch to both dimensions: width and height are scaled independently to fill the canvas. No bars, but circles become ovals and text widens. Distortion is proportional to the ratio mismatch.

Scale to cover, keep ratio (Fill): the image is scaled until both dimensions are at least the canvas size, then the overflow is cropped. No bars, no distortion, edges lost.

For a designed background, Fill is the only mode that is predictable at 1× and 2×, provided you export at the canvas ratio so there is nothing to crop.

If you set backgrounds in a theme file, the values are not the pane's words. Microsoft's Report Theme JSON Schema (reportThemeSchema-2.159.json, October 2026) defines the page background image scaling property as a string with three allowed values, each carrying the label it maps to in the UI:

1. JSON "Normal", labelled "Fit" in the schema: scale to fit, keep ratio (the bars mode).
2. JSON "Fit", labelled "Stretch": stretch to both dimensions.
3. JSON "Fill", labelled "Fill": scale to cover and crop.

So a theme that says "scaling": "Fit" produces a stretched image, not a fitted one, and "Normal" is what the pane calls Fit. Older Desktop builds labelled the dropdown Normal, Fit, Fill, which is how the JSON values got their names; if your pane still shows those words, Normal means fit-with-bars and Fit means stretch. Use "Fill" in the JSON and Fill in the pane and the question never comes up.

Export the background at the canvas size, or at exactly 2× for high-DPI screens; both have the canvas ratio so Fill crops nothing.

1. 16:9, 1280×720 (HD): export 1280×720 or 2560×1440.
2. 16:9, 1920×1080 (Full HD, the Fluent 2 default for new pages): export 1920×1080 or 3840×2160.
3. 16:9, 2560×1440 (QHD) and 3840×2160 (4K): export at the size, or 2× for QHD.
4. 4:3, 960×720: export 960×720 or 1920×1440.
5. Letter, 816×1056: export 816×1056 or 1632×2112.
6. Tooltip, 320×240: export 320×240 or 640×480.
7. Custom: the width and height you typed, or exactly double.

Worked mismatch: a 1920×1200 (16:10) image on a 1280×720 page in the fit mode scales by the limiting axis. Width would need 0.667 (1280/1920) but height only allows 0.6 (720/1200), so the image renders 1152×720 and leaves two 64 px bars. In Fill it scales by 0.667 to 1280×800 and crops 40 px top and bottom. In Stretch it becomes 1280×720 with everything 10% too wide.

Fluent 2 case: a 1280×720 background on a new 1920×1080 page has the same ratio, so no bars in any mode, but it is upscaled 1.5× and looks soft. Re-export at 1920×1080 or 3840×2160.

1. Click an empty part of the page and open Format page in the Visualizations pane (or Design ribbon, Page background).
2. Expand Canvas settings and note Type and Size. That is your target ratio and pixel size.
3. Expand Canvas background. Browse to the image, set Transparency to 0%.
4. Set Image fit to Fill. If the pane shows Normal, Fit, Fill, choose Fill as well; it is the only label that means the same thing everywhere.
5. If bars remain, the image ratio is wrong: re-export at the sizes above. If the image is soft, you are upscaling: export at 2×.
6. To apply the same background to every page, put it in the theme (code above) and import via Design, Import theme; new pages inherit it and existing pages pick it up unless they have their own background set.

One more source of confusion: the area outside the page is Wallpaper, not the canvas background, and Page view (View ribbon: Fit to page, Fit to width, Actual size) decides how much of it readers see. Letterboxing around the whole page in the Service is wallpaper, controlled by Page view and the Wallpaper colour; bars inside the page are the canvas and Image fit. If your "white bars" are outside the page outline, change the wallpaper colour or the page view, not the image.

Most bar problems start with an image made at the wrong size. The free Design Studio draws on the Power BI canvas presets (16:9 at 1920×1080, the Fluent 2 default, and 1280×720, plus 4:3 and Letter) with an 8 px grid, and exports the background PNG at 1× or 2× of the canvas and a theme JSON that embeds it with "scaling": "Fill". The background gallery has ready-made designs with PNG downloads at 1920×1080 and 1280×720.