Customize the title bar of your WinUI3 app

WinUI3 allows you to customize your title bar. You can make simple customizations, like changing the color, title or icon or you can fully customize it, adding controls and having full control to its appearance. In this article, I will show you how you can customize the title bar of your application and give it a complete new look.

Customizing colors, title and icon

To customize the title bar of a WinUI3 app, you have to get the instance of the AppWindow for the main window. With it you can get the AppWindowTitleBar instance and start customizing it.

The AppWindow is an abstraction for the container for the app, representing the entity that the users interact when they move or resize the window. It can be seen as an abstraction of the HWND in Win32 and there is a 1:1 mapping between the AppWindow and the HWND for the main window of the application. You can get it with this code:

_appWindow = this.AppWindow;

With the AppWindow instance, you can get the AppWindowTitle instance with some code like this:

private AppWindow _appWindow;
private AppWindowTitleBar _titleBar;

...

_appWindow = this.AppWindow;
if (AppWindowTitleBar.IsCustomizationSupported())
{
    _titleBar = _appWindow.TitleBar;
}

We will create an app that customizes the title bar. In Visual Studio, create a new project and select "Blank App, Packaged with Windows Application Packaging Project (WinUI 3 in Desktop)".

Once you do that, it will create a solution with two projects: the main project, where you will make your changes and the packaging project, which will create a package for your app, giving an identity, resources and a MSIX installer to it.

The packaging project will add all the reources the app needs for the store and will create a msix installer. For example, to add images for the store, we can start with our app image, like this one:

We open the package.appxmanifest file and get the package manifest editor, where we can add the assets needed for the file:

In the Visual Assets page we can add our image:

Just add the image to the Source box and click on Generate, Visual Studio will generate all the images needed and add them to the package. That way, your app will have all assets needed for the store.

In MainWindow.xaml.cs we will add the code to get the AppWindow and AppWindowTitle:

public MainWindow()
{
    this.InitializeComponent();

    _appWindow = this.AppWindow;
    if (AppWindowTitleBar.IsCustomizationSupported())
    {
        _titleBar = _appWindow.TitleBar;
    }
}

Note that we only will get the AppWindowTitleBar instance if IsCustomizationSupported returns true.

With the AppWindowTitleBar instance, we can customize the title bar:

_appWindow = this.AppWindow;
_appWindow.Title = "My new WinUI App";
_appWindow.SetIcon("AppIcon.ico"); 
if (AppWindowTitleBar.IsCustomizationSupported())
{
   _titleBar = _appWindow.TitleBar;
   SetTitleBarColors();
}

We are setting the title, colors and icon for the app. AppIcon.ico is an icon file (format .ico) added to the root folder to the project as content.

SetTitleBarColors will set the title bar colors:

private void SetTitleBarColors()
{
    // Set active window colors.
    _titleBar.ForegroundColor = Colors.White;
    _titleBar.BackgroundColor = Color.FromArgb(0xff, 0xb0, 0x0e, 0x25);
    _titleBar.ButtonForegroundColor = Colors.White;
    _titleBar.ButtonBackgroundColor = Color.FromArgb(0xff, 0xb0, 0x0e, 0x25);
    _titleBar.ButtonHoverForegroundColor = Colors.White;
    _titleBar.ButtonHoverBackgroundColor = Color.FromArgb(0xff, 0x82, 0x03, 0x1c);
    _titleBar.ButtonPressedForegroundColor = Colors.White;
    _titleBar.ButtonPressedBackgroundColor = Color.FromArgb(0xff, 0x82, 0x03, 0x1c);

    // Set inactive window colors.
    _titleBar.InactiveForegroundColor = Colors.Black; 
    _titleBar.InactiveBackgroundColor = Color.FromArgb(0xff, 0xfe, 0xc1, 0xc1);
    _titleBar.ButtonInactiveForegroundColor = Colors.Black;
    _titleBar.ButtonInactiveBackgroundColor = Color.FromArgb(0xff, 0xfe, 0xc1, 0xc1);
}

These color changes will have no effect on Windows 10, as this OS doesn't support the color customization. Now, when you run the app, you will see the new icon, title and colors:

Customizing the full title bar

So far, we customized just the appearance of the title bar, but sometimes we want more: we would like to add a textbox or other controls. To do that, the first step is to set the ExtendsContentIntoTitleBar property to true:

ExtendsContentIntoTitleBar = true;

This will remove the title bar and will extend the content to the top part. One exception to this is the minimize, maximize and close buttons, that won't be removed. You will still be able to drag the window by the top border. If you want to completely remove the buttons and drag behavior, you must create a new presenter for the app window, with this code:

_appWindow.SetPresenter(OverlappedPresenter.CreateForContextMenu());

In this case, you won't be able to move or resize the window - you will have to add your own mechanism to drag or resize the window.

We want to customize our title bar and add a search box in the top. For that, we must add the controls that will be on the top of the page. We can create a new UserControl and add the design we want. Create a new UserControl and name it TitleBar. In TitleBar.xaml, add this code: