DEV Community 👩‍💻👨‍💻

Cover image for #11 - Displaying Content More Like An App
Nitya Narasimhan, Ph.D for Microsoft Azure

Posted on • Originally published at microsoft.github.io

#11 - Displaying Content More Like An App

Welcome to Day 11 of #30DaysOfPWA! New to the series? Three things you can do to catch up:

This is a shortened version of this canonical post for the #30DaysOfPWA.


About The Author

Today's post is authored by Stephanie Stimac Developer Advocate and Developer Experience PM on the Microsoft Edge team. Follow Stephanie at @seaotta or here on dev.to.


Welcome to Week 2 Day 4 of the 30 Days of PWA series! Today’s blog post will walk you through the different display modes you can set for your website, and the experimental Window Controls Overlay feature which allows the customization of the title bar of your PWA.


Display Modes

The way Progressive Web Apps get displayed by an operating system after installation may be different than the way the app appears when opened in a web browser. On a mobile device for example, an installed PWA can be displayed full screen, while on a desktop operating system, it can be displayed in a standalone window.

There are four different display modes available to choose from and each provides a different browser UI experience that you’ll want to consider when deciding which display mode is right for your PWA.

You set your preferred display mode via the web app manifest’s display member with one of the following values: "fullscreen," "standalone," "minimal-ui," or "browser":

{
    “display”: “standalone”
}
Enter fullscreen mode Exit fullscreen mode

In the event a browser doesn’t support a display mode, which is possible since they’re not required or support all the display mode options, the display mode will fall back to a supported one in this order:

fullscreen > standalone > minimal-ui > browser

Standalone display mode

The "standalone" display mode makes your PWA look and behave the most like a native application. It opens in a different window from the browser and hides all the browser UI elements like the address bar. It keeps standard system UI elements like a back button or a close window button. In this mode, your application can also have its own icon in the application launcher. If standalone isn’t available, it will fall back to the "minimal-ui" display mode. Twitter uses "standalone" for their PWA.

Twitter displayed in its own window on Android

Fullscreen display mode

The "fullscreen" display mode takes up the entirety of the display area available and hides all of the browser UI elements. If "fullscreen" isn’t available, it will fall back to "standalone." Here's an example of a game that uses the "fullscreen" display mode.

This PacMan game is a PWA and was built with the fullscreen display mode

View the PacMan PWA here.

Minimal-UI display mode

The "minimal-ui" display mode gives your PWA a similar experience to the standalone display mode. It opens in its own window, but the application retains a minimal set of browser UI controls. The UI that is retained will vary between browsers. The OneDrive PWA uses the "minimal-ui" display mode.

The OneDrive PWA utilizes the minimal-ui display mode

Browser display mode

The browser display mode retains the browser experience with all the browser UI and your web app will not be installable. It will open in a normal browser window or tab. If Twitter were not using standalone mode, it would display in the browser like a normal tab.

Twitter in a browser window.

Targeting different display modes with the display-mode media feature

Depending on the display mode you choose for your PWA there may be elements you want to hide when the web app is open in the browser tab, especially if you’re launching in a mode like standalone or fullscreen that hides the browser UI buttons. You need to ensure there’s a way for people to go back if there’s no back button. Or maybe you want to modify your site styles slightly to display better when the app is in fullscreen mode.

You can do this by targeting certain display modes with the display-mode media feature.

.app-button {
    display: none;
}

@media (display-mode: standalone) {
.app-button {
        display: block;
    }
}
Enter fullscreen mode Exit fullscreen mode

In this example, the button with the class .app-button would only be shown when the PWA is in standalone mode. You can go even further and combine media queries to change how things are displayed on smaller screens versus a desktop when a user in standalone mode to tailor the experience.


Customizing display options further with Window Controls Overlay

The previous display modes I mentioned currently only offer customization of the display below the title bar on desktop PWAs when in standalone mode. Window Controls Overlay is an experimental display option that will allow you to customize the title bar of your PWA with CSS and JavaScript. It provides access to the space next to the controls that minimize, maximize, or close the app’s window.

Because this feature is experimental and in development, the way it currently works is subject to change. You can turn this feature on in Chrome and Edge by going to about://flags and enabling the Desktop PWA Window Controls Overlay flag.

A title bar with window controls overlay enabled and a title bar without it

This example from the specification draft shows how the title bar area becomes available when WCO is enabled.

Using Window Controls Overlay

In order to use this feature we need to add “display_override” to our web app manifest file.

{
    “display_override”: [“window-controls-overlay”]
}
Enter fullscreen mode Exit fullscreen mode

The customized title bar will only show when in a separate PWA window on a desktop operating system. After our display_override, we would then follow up with our preferred display mode when window controls overlay isn’t available.

{
    “display_override”: [“window-controls-overlay”],
    "display": "standalone",
}
Enter fullscreen mode Exit fullscreen mode

Now that we’ve stated via the manifest we would like to use window controls overlay, we need to add some CSS to position the content in our title bar area. We can do that with the following CSS environment variables:

  • titlebar-area-x
  • titlebar-area-y
  • titlebar-area-width
  • titlebar-area-height

Using these environment variables would look something like this:

.titleBar {
    position: fixed;
    left: env(titlebar-area-x, 0);
    top: env(titlebar-area-y, 0);
    width: env(titlebar-area-width, 100%);
    height: env(titlebar-area-height, 40px);
}
Enter fullscreen mode Exit fullscreen mode

The titlebar-area-x variable gives us the distance from the left of the viewport to where the titlebar appears, with a fallback integer. The titlebar-area-y variable gives us the distance from the top. And titlebar-area-width and titlebar-area-height set the width and height respectively, with fallback values. The fallback values are used when the app isn't installed, when Window Controls Overlay isn't supported or the user has opted-out of the feature.

Keeping the title bar draggable

Once you’ve positioned and styled your title bar, there’s one more step left. The window is no longer draggable if you’ve turned on window control overlay, so we need to fix this with the app-region CSS property.

.titleBar {
    position: fixed;
    left: env(titlebar-area-x, 0);
    top: env(titlebar-area-y, 0);
    width: env(titlebar-area-width, 100%);
    height: env(titlebar-area-height, 40px);
    -webkit-app-region: drag;
    app-region: drag;
}
Enter fullscreen mode Exit fullscreen mode

This CSS property is also experimental, so -webkit-app-region is needed for it to work and is only supported in Chromium-based browsers.


Resources

MDN display-mode

App Design: Display Modes

WCO: Breaking Out of the Box


Summary

Display modes are an easy way to make your PWA feel like a native app and are set via the web app manifest display member. The ability to further customize the title bar area for an even greater native desktop app feel when your PWA is displayed in a separate window is available via the experimental Window Controls Overlay setting available in Chromium browsers.

Tune in for the next post in the series tomorrow where we will cover caching.


Exercise

Pick a sample app and change the display modes in the manifest to see how each presents when opened. What features are missing or added in each display mode? How does the UI change?


Want to read more content from Microsoft technologists? Don't forget to follow Azure right here on dev.to:


Top comments (1)

Collapse
 
shajib729 profile image
Mohammed Sajidul Islam

I want to make display modes minimal-ui for large screen and standalone for mobile or tablet...how can i proceed?

Take a look at this:

Settings

Go to your customization settings to nudge your home feed to show content more relevant to your developer experience level. 🛠