microsoft / microsoft/microsoft-ui-xaml

Feature Request: Provide official API for custom background image in WinUI 3 / XAML Islands apps

Open
#11,269 9 comments 0 reactions 0 assignees View on GitHub
area-Materials needs-triage
Dominant language
C++
Stars
8.4k
Forks
942
Avg merge
2d 7h
Merged PRs (30d)
105

Description

**Is your feature request related to a problem? Please describe.**

Currently, WinUI 3 applications (including system apps like Settings, Start Menu, File Explorer, and Task Manager) are limited to fixed Mica or Acrylic background effects. Users have no official way to customize the background of these applications with their own images while retaining the Mica effect.

Many users in the Windows community have been requesting this feature for a long time. Currently, the only workarounds involve unstable third-party tools such as MicaForEveryone, ExplorerBlurMica, or Windhawk, which often crash, fail to function, or even cause system instability—especially on Windows 11 24H2/25H2.

**Describe the solution you'd like**

I would like to request an official API for WinUI 3 and XAML Islands applications that enables:

1. **Setting a custom background image** for the entire application window or specific surfaces.
2. **Optional blending with Mica/Acrylic material** – allowing the custom background to overlay with Mica, preserving the modern Fluent Design aesthetic while enabling personalization.
3. **A simple property** for developers, such as:
```xaml

```
or equivalent programmatic APIs.

Additionally, I hope this API can be extended to system-level settings (e.g., under "Settings > Personalization"), allowing users to uniformly customize backgrounds across all WinUI 3 system applications (Settings, Start Menu, File Explorer, Task Manager, Calculator, etc.) as well as third-party WinUI 3 apps.

**Describe alternatives you've considered**

1. **Third-party Hook tools** (MicaForEveryone, ExplorerBlurMica, Windhawk) – unstable, pose security risks, and often break after Windows updates.
2. **Self-implemented rendering** – as seen in Windows Terminal (via `experimental.useBackgroundImageForWindow`) and Steam++ (Watt Toolkit). While these prove the technical feasibility, they require deep platform knowledge and are not accessible to all developers.

**Technical feasibility evidence**

Several applications have already implemented custom background images, demonstrating that this is technically achievable:

- **Windows Terminal** – uses its own renderer with an experimental global setting `experimental.useBackgroundImageForWindow` to enable background images for the entire window.
- **Steam++ (Watt Toolkit)** – added support for setting dynamic wallpapers as application backgrounds in version 2.6.0.

These examples show that the underlying platform capabilities exist, but they are not standardized or officially exposed for general WinUI 3 development.

**Why this should be official**

- **Stability** – Official API is more reliable than third-party hooks.
- **Security** – Avoids the security risks associated with system-level hooking.
- **Ecosystem consistency** – Both pure WinUI apps and XAML Islands hybrid apps can have consistent customization capabilities.
- **Developer accessibility** – Lowers the barrier for third-party developers to implement this feature.
- **User demand** – This is a highly requested feature in the Windows community (Feedback Hub, Microsoft Answers, Reddit, etc.).

**Additional context**

- This feature would benefit both **system apps** (Settings, Start Menu, File Explorer, Task Manager) and **third-party WinUI 3 apps**.
- Special consideration may be needed for **XAML Islands (Win32 hybrid)** applications, which rely on both HWND and XAML trees.
- I have already submitted this suggestion via Microsoft Q&A. This GitHub Issue is per the official response I received from Microsoft support, which suggested submitting API requests here.

**Related links:**
- Microsoft Q&A post: *(https://learn.microsoft.com/zh-cn/answers/questions/5950658/windows-11-mica)*

Thank you for considering this feature!

---

Contributor guide

Open the contributing guide

Research direction

No repository files, tests, or entry points are named. Start by reviewing the existing WinUI 3 and XAML Islands background and material APIs, then compare the requested scope with Windows Terminal's experimental background-image setting and the linked Microsoft Q&A post. Done would require an agreed official API design covering app and surface backgrounds, Mica/Acrylic blending, and system-app considerations.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.