A PWA outside of the browser manages its own window. In this chapter, you will understand the APIs and capabilities for managing a window within the operating system.
The PWA window
Running on your own window, managed by your PWA, has all the advantages and responsibilities of any window in that operating system, such as:
- The ability to resize and move the window around on multi-window operating systems, like Windows or ChromeOS.
- Sharing the screen with other app windows, as in iPadOS split mode or Android split-screen mode.
- Appearing in docks, taskbars, and in the alt-tab menu on desktop, and multi-task window lists on mobile devices.
- The ability to minimize, move the window across screens and desktops, and close it at any time.
Moving and resizing the window
Your PWA window can be of any size and positioned anywhere on the screen on desktop operating systems. By default, when the user opens the PWA for the first time after installation, the PWA gets a default window size of a percentage of the current screen, with a maximum resolution of 1920x1080 positioned at the top-left corner of the screen.
The user can move and resize the window, and the browser will remember the last preference, so the next time the user opens the app, the window will retain the size and position from the previous usage.
There is no way to define your PWA's preferred size and position within the manifest. You can only reposition and resize the window using the JavaScript API. From your code, you can move and resize your own PWA window using the moveTo(x, y)
and resizeTo(x, y)
functions of the window
object.
For example, you can resize and move your PWA window when the PWA loads using:
document.addEventListener("DOMContentLoaded", event => {
// we can move only if we are not in a browser's tab
isBrowser = matchMedia("(display-mode: browser)").matches;
if (!isBrowser) {
window.moveTo(16, 16);
window.resizeTo(800, 600);
}
});
You can query the current screen size and position using the window.screen
object; you can detect when the window is resized using the resize
event from the window
object. There is no event for capturing the window move, so your option is to query the position frequently.
Browsing to other sites
If you want to send the user to an external site that is out of the scope of your PWA, you can do so with a standard <a href>
HTML element, using location.href
or opening a new window on compatible platforms.
Currently on all browsers, if your PWA is installed, when you browse to a URL that is out of the scope of your manifest, the browser engine of your PWA will render an in-app browser within the context of your window.
Some features of the in-app browsers are:
- They appear on top of your content.
- They have a static URL bar showing the current origin, the window's title, and a menu. Typically, they're themed with the
theme_color
of your manifest. - From the contextual menu, you can open that URL in the browser.
- Users can close the browser or go back.
Authorization flows
Many web authentication and authorization flows involve redirecting the user to a different URL in a different origin to acquire a token that will return to your PWA's origin, such as using OAuth 2.0.
In these cases, the in-app browser follows the following process:
- The user opens your PWA and clicks login.
- Your PWA redirects the user to a URL that is out of the scope of the PWA so that the rendering engine will open an in-app browser within your PWA.
- The user can cancel the in-app browser and go back to your PWA at any time.
- The user logs into the in-app browser. The authentication server redirects the user to your PWA origin, sending the token as an argument.
- The in-app browser closes itself when it detects a URL that is part of the scope of the PWA.
- The engine redirects the main PWA window navigation to the URL that the authentication server went to while in the in-app browser.
- Your PWA gets the token, stores the token, and renders the PWA.
Forcing a browser's navigation
If you want to force open the browser with a URL and not an in-app browser, you can use the _blank
target of <a href>
elements. This works only on desktop PWAs; on mobile devices, there is no option to open a browser with a URL.
function openBrowser(url) {
window.open("url", "_blank", "");
}
Opening new windows
On desktop, users can open more than one window of the same PWA. Each window will be a different navigation to the same start_url
, as if you were opening two browser tabs of the same URL.
From the menu in the PWA, users can select File then New window, and from your PWA code, you can open a new window with the open()
function. Check the documentation for details.
function openNewWindow() {
window.open("/", "new-window", "width=600,height=600");
}
Calling open()
within a PWA window on iOS or iPadOS returns null
and doesn't open a window. Opening new windows on Android creates a new in-app browser for the URL—even if the URL is within the scope of your PWA—that typically doesn't trigger an external browsing experience.
Window title
The <title>
element was primarily used for SEO purposes as the space within a browser tab is limited. When you move from the browser to your window in a PWA, all the title bar space is available to you.
You can define the contents of the title bar:
- Statically in your HTML
<title>
element. - Dynamically changing the
document.title
string property at any time.
On desktop PWAs, the title is essential, and it's used in the title bar of the window and sometimes in the task manager or multi-task selection. If you have a single-page application, you may want to update your title on every route.
Tabbed mode
An experimental capability, known as tabbed mode will let your PWA have a tab-based design similar to a web browser. In this case, the user can have several tabs opened from the same PWA but all tied together in the same operating system window, as you can see in the following video:
You can read more about this experimental capability at Tabbed application mode for PWA.
Window controls overlay
We've mentioned that you can change the window's title by defining the value of the <title>
element or the document.title
property. But it's always a string value. What if we could design the title bar as we wish, with HTML, CSS, and images?
That's where Window Controls Overlay comes in, a new experimental capability in Microsoft Edge and Google Chrome for desktop PWAs.
You can read more about this capability at Customize the window controls overlay of your PWA's title bar.
Window management
With multiple screens, users will want to use all the space available to them. For example:
- Multi-window graphics editors à la Gimp can place various editing tools in accurately positioned windows.
- Virtual trading desks can show market trends in multiple windows any of which can be viewed in fullscreen mode.
- Slideshow apps can show speaker notes on the internal primary screen and the presentation on an external projector.
The Window Management API allows PWAs to do just that and more.
Getting screen details
The Window Management API adds a new method, window.getScreenDetails()
, that returns an object with screens as an immutable array of attached screens. There's also a live object accessible from ScreenDetails.currentScreen
, corresponding to the current window.screen
.
The returned object also fires a screenschange
event when the screens
array changes. (This does not happen when attributes on individual screens are changed.) Individual screens, either window.screen
or a screen in the screens
array, also fire a change
event when their attributes change.
// Request an object with a screen objects
const screenDetails = await window.getScreenDetails();
screenDetails.screens[0].isPrimary; // e.g. true
screenDetails.screens[0].isInternal; // e.g. true
screenDetails.screens[0].label; // e.g. 'Samsung Electric Company 28"'
// Access the live object corresponding to the current `window.screen`.
// The object is updated on cross-screen window placements or device changes.
screenDetails.currentScreen;
screenDetails.addEventListener('screenschange', function() {
// NOTE: Does not fire on changes to attributes of individual screens.
const screenCount = screenDetails.screens.length;
const currentScreen screenDetails.currentScreen.id;
});
If the user or the operating system moves your PWA's window from one screen to another, a currentscreenchange
event will also be fired from the screen details object.
Screen wake lock
Imagine this: you're in the kitchen following a recipe on your tablet. You've just finished prepping your ingredients. Your hands are a mess, and you turn back to your device to read the next step. Disaster! The screen's gone black! The Screen Wake Lock API is here for you and lets a PWA prevent screens from dimming, sleeping, or locking, allowing users to stop, start, leave, and return without worry.
// Request a screen wake lock
const wakeLock = await navigator.wakeLock.request();
// Listen for wake lock release
wakeLock.addEventListener('release', () => {
console.log(`Screen Wake Lock released: ${wakeLock.released}`);
});
// Manually release the wake lock
wakeLock.release();
Virtual keyboard
Touch-based devices, such as phones and tablets, offer a virtual on-screen keyboard so the user can type when form elements of your PWA are in focus.
Thanks to the VirtualKeyboard API, your PWA can now have more control of the keyboard on compatible platforms using the navigator.virtualKeyboard
interface, including:
- Showing and hiding the virtual keyboard with the functions
navigator.virtualKeyboard.show()
andnavigator.virtualKeyboard.hide()
. - Telling the browser that you are taking care of closing the virtual keyboard yourself by setting
navigator.virtualKeyboard.overlaysContent
equal totrue
. - Knowing when the keyboard appears and disappears with the event
geometrychange
ofnavigator.virtualKeyboard
. - Setting the virtual keyboard policy on editing host elements (using
contenteditable
) with thevirtualkeyboardpolicy
HTML attribute. A policy lets you decide if you want the virtual keyboard to be handled automatically by the browser using theauto
value, or handled by your script using themanual
value. - Using CSS environmental variables for getting information about the virtual keyboard appearance, such as
keyboard-inset-height
andkeyboard-inset-top
.
You can read more about this API on Full control with the VirtualKeyboard API.