HTML5 game publishing

Fullscreen and Resize for HTML5 Games, Including the iPhone Fallback

The Fullscreen API where it exists, a CSS expanded mode where it does not, dvh instead of 100vh, a ResizeObserver canvas, safe areas and a four-device test list.

PlayKovo Team4 min read
Games currently available on PlayKovo. Open a title to see its current listing.

"Fullscreen" is a button every game wants, and on desktop it works in two lines. On an iPhone, the same two lines do nothing. Add a resizing canvas, mobile address bars that grow and shrink, rotation and notches, and you have the single most common source of "the game looks wrong on my phone" reports. This post covers how to build fullscreen and resize handling that behaves correctly on desktop, Android and iOS, including the fallback you need on iPhone.

The Fullscreen API, and where it stops

On desktop browsers and Android, you request fullscreen on an element, in response to a user gesture:

async function enterFullscreen(el = document.documentElement) {
  const req = el.requestFullscreen || el.webkitRequestFullscreen;
  if (!req) return false;
  try { await req.call(el); return true; } catch { return false; }
}

function exitFullscreen() {
  const exit = document.exitFullscreen || document.webkitExitFullscreen;
  if (exit && (document.fullscreenElement || document.webkitFullscreenElement)) exit.call(document);
}

Three things to know:

  • The call must happen inside a user gesture such as a click or tap. Calling it on load fails.
  • If your game runs inside an iframe, the iframe needs the allow="fullscreen" attribute for the request to work. Embedders control that attribute, not you.
  • iPhone Safari does not support the Fullscreen API for ordinary page elements. It supports it for video, and iPadOS supports it more broadly, but on an iPhone the request is simply unavailable. Feature-detect it, and hide or replace the button where it is missing.

The fallback: a fixed-position "expanded" mode

Where real fullscreen is not available, make the game fill the visible viewport with CSS and hide everything else:

.game-frame.expanded {
  position: fixed;
  inset: 0;
  z-index: 9999;
  width: 100vw;
  height: 100dvh;       /* dynamic viewport height */
  background: #000;
}
body.has-expanded { overflow: hidden; }

This does not hide the browser's own interface the way fullscreen does, but it gives the game the maximum space and removes distractions. Offer the same button, and implement it as: use the API if present, otherwise toggle the CSS class. The player does not need to know which one they got.

100vh is a trap on phones

On mobile browsers, 100vh is the height with the address bar hidden, so a full-height element extends under the toolbar and part of your game is covered. Use the newer viewport units:

  • 100dvh: dynamic viewport height, follows the visible area as the bar shows and hides.
  • 100svh: smallest viewport height, always fits.
  • 100lvh: largest viewport height.

Supported in current browsers, with a fallback to 100vh for older ones. For code that computes sizes in JavaScript, use window.visualViewport.height where available, and listen to its resize event.

Resize the canvas correctly

A canvas has two sizes: the drawing buffer (canvas.width and canvas.height) and the displayed size (CSS). Keep them in sync, accounting for the pixel ratio:

function resize() {
  const dpr = Math.min(window.devicePixelRatio || 1, 2);   // cap for performance
  const r = canvas.getBoundingClientRect();
  canvas.width  = Math.round(r.width  * dpr);
  canvas.height = Math.round(r.height * dpr);
  view.scale = Math.min(canvas.width / DESIGN_W, canvas.height / DESIGN_H);
  view.offsetX = (canvas.width  - DESIGN_W * view.scale) / 2;
  view.offsetY = (canvas.height - DESIGN_H * view.scale) / 2;
}
new ResizeObserver(resize).observe(canvas);

ResizeObserver on the canvas element catches every cause of resizing, including fullscreen changes, rotation and the host page changing the iframe size, which window.onresize alone can miss inside an iframe. Our post on canvas resolution and devicePixelRatio explains the pixel ratio part in detail.

The code above letterboxes: it scales your fixed design size to fit and centers it with bars. The alternative is to adapt the layout to the aspect ratio. Letterboxing is easier and fine for most games. For portrait games in a tall box, choose the design size to match.

Rotation and safe areas

Rotating a phone changes the viewport. Handle it by reacting to the resize observer, not to orientationchange alone, which fires before the new size is final. Keep important buttons away from notches and rounded corners using environment insets:

.hud { padding: max(8px, env(safe-area-inset-top)) max(8px, env(safe-area-inset-right))
               max(8px, env(safe-area-inset-bottom)) max(8px, env(safe-area-inset-left)); }

This requires viewport-fit=cover in the viewport meta tag to take effect. See mobile browsers, touch controls, orientation and safe areas for the full picture.

Keep the game running through the change

  • Do not restart the game on resize. Rescale and continue.
  • Pause timers briefly during a big transition if the layout jumps, then resume.
  • Restore focus to the canvas after leaving fullscreen so keyboard input keeps working.
  • Remember the state: if the player pressed Esc to leave fullscreen, update your button icon in the fullscreenchange handler rather than assuming.

Test matrix

  1. Desktop Chrome and Firefox: enter and leave fullscreen with the button and with Esc.
  2. Android Chrome: fullscreen, rotation, address bar showing and hiding.
  3. iPhone Safari: no fullscreen button, expanded mode works, no content under the toolbar.
  4. Embedded in an iframe with and without allow="fullscreen".

Embedders can read about the other half in fullscreen on iPhone for embedded games.

We use optional cookies for site analytics and site advertising. You can change your choice later. Privacy policy.