Skip to main content
March 14, 2023

Taking control of your application’s title bar

Web technology is a common way to develop desktop applications. A growing number of apps are being built using an open technology stack based solely on web standards. These apps, or PWAs, can be installed from both the Microsoft Edge browser and the Microsoft Store. Once they are installed, they integrate with the operating system using advanced web capabilities that enable expected behaviours around sharing, file handling, and even UI refinements.

One UI aspect that is important to keep in mind is the title bar and the information it shows. Among other things, title bars are important since they can be read by screen readers, and also provide useful identifying information about the applications that are running.

More often than not, text in the title of the app is used to display badging, notifications, and other information that can be detrimental to the UX of the website and PWA. Some of these anti-patterns come from developers adapting to a lack of modern APIs in the past, like actual badging and push notifications. Good UX practices involve using these modern APIs and leaving the title bar text readable and relevant.

In this article, we’ll look at the different ways you can alter the title bar of your PWA. We’ll also introduce a new proposal for better accessibility and navigation at the end, so read on for more.

Customize the upper part of the window

We will start by mentioning the way you can completely customize the installed application’s title bar. You can use the Window Controls Overlay API that is shipping in Chromium browsers to free the area that would previously be occupied by the title bar of the window. This API allows you to emulate advanced title bars with built-in controls like menus and other form controls, or use it to clear space for your app and give it have a more immersive feel. This is a powerful capability that requires custom work with either CSS or JavaScript.

To learn how to use this, read more about how to close a 30 pixel gap between native and web. You can also use media queries to detect when the app is running with this feature enabled and layout content appropriately. The sample code below shows how you can detect this feature in your CSS.

@media (display-mode: window-controls-overlay){
    // Change styles accordingly if the WCO feature is enabled
A PWA title bar showing web content drawn in the titlebar, including a "+" icon, "save" icon, "upload" icon, and a stylized app title reading "The PWinter."

However, understanding how your app’s default title bar works can also be very useful to provide a good user experience.

Understanding the default title bar’s text

Title bars are important. We mentioned before how they play a role in accessibility and navigation. We can tweak how the title bar text can be customized. For this let’s first understand how the title bar text is sourced for installed web applications. Out of the box, without you having to do anything, there are 2 possible scenarios:

  1. The installed web application title bar shows the name of the application.
    A standard Windows titlebar listed over a PWA, showing the name of the app, "The PWinter," and standard Windows controls.
  2. The installed web application title bar shows the name of the application, followed by some other text.
    A standard Windows titlebar on a PWA, showing the title of the app along with a custom string, "The PWinter - Custom colored PWA logos."

To control the text in the title bar, we must understand where it is coming from. In both scenarios, the first part of the text in the title bar comes from the name member in the web application manifest file.

/* manifest.json */
    "name": "The PWinter",

The second part of the text in the title bar, comes from the inner text of the HTML title tag in the document. This part is only shown if it is different from the name member in the manifest file, to avoid repetition.

For the images pictured above, scenario 1 and 2, the former has an html title that is the same as the name of the app in the manifest file. The title of the web page is <title>The PWinter<title>. For this reason, only the string “The PWinter” is displayed.

The latter image (scenario 2) shows the same installed web application, but with the inner text of the page’s title tag set to “Custom colored PWA logos”. This causes the additional information to appear after a dash. In this case, title for said page would be <title>Custom colored PWA logos</title>.

There is a third case, which is a slight variation of the scenario where the text in the title is different from the application’s name, but starts with the application’s name. For example, if the web page’s title is <title>The PWinter :: Custom colored PWA logos</title>, then the installed app title bar will ignore the name of the application and append the rest of the string in the inner text of the title tag.

A standard Windows titlebar on a PWA, showing only the text from the title element, "The PWinter :: Custom colored PWA logos," and omitting the app name, "The PWinter"

As you can see, there are plenty of cases, and having an understanding of where the strings are sourced to compose the text that appears in the title bar of your installed web application is important to deliver the exact experience you want for your users. It can also help create a more polished feeling for your application that can delight users.

Now that we know how the text in the title bar works, we have three recommendations to make sure your app’s title bar is exactly how you want your users to experience it:

  1. Completely customize the appearance of the upper part of the window by using the Window Controls Overlay
  2. Display your application title only.
  3. Display the app title and additional contextual information.

Display your application title only

If you need a clean and minimal title bar that only has the title of the application, make sure that the content of the HTML title tag is the same as the name member in the manifest file. It is as easy as this.

Display your application title and additional contextual information

Another option is to display additional information in the title bar. For example, if you have an installed web application that does note-taking, word-processing, image-editing or other type of productivity task that involves files, you could set the additional information to the name of the open file.

This is important as it can help your users quickly identify your application in surfaces that expose opened apps, like pressing Alt+Tab on Windows.

As explained earlier, the additional contextual information comes from the content of the title tag in the current document. If you only want to do this when your application is installed, as opposed to running in a browser tab, you can use a media query.

Using the display-mode media query we can identify when an installed app is running in standalone, fullscreen or minimal-UI mode. These are the display modes needed to install a Web app. standalone display mode will show the window’s title bar, and this is an indication that we can alter the content of the page’s title tag to specify relevant contextual information. To do so, we can programmatically change the title property of the active document.

let mql = window.matchMedia('(display-mode: standalone)');
    document.title = "my new title";

By identifying when your installed PWA is running in standalone mode, you can update the text on the title of the document to provide relevant contextual information. Use this technique to display the title as you intend when your app is running in a browser tab, and when it is running as an installed self-contained window!

What’s next

Does using a media query seem cumbersome for quickly updating this contextual information? We are also investing in making this easier, while giving you the ability to still have fine grained control of how text displays in the title bar.

Our current proposal is exposing a new subtitle field in the document, where developers could store this information for quick retrieval and update. We want to make sure this idea fit your needs, so let us know what you think.

Whether you’re thinking of completely customizing the appearance and layout of the title bar space, or providing contextual information about the current open file in your web app, making sure your title bar behaves just as you envisioned is key for accessibility, navigation, and an all-round subtle detail that exudes attention to detail and best in class user experience!