Skip to content

Update the default PWA offline page to the new design #26458

Description

@totally-not-ai

Describe your motivation

The built-in PWA offline page (flow-server/src/main/resources/com/vaadin/flow/server/default-offline-page.html) is shown by the service worker whenever an installed Vaadin PWA cannot reach the server, unless the app configures its own offlinePath. Its look is outdated: a dark-only layout with a large app-name heading and a bar above it, the app icon pushed aside, and a long explanatory paragraph. It doesn't follow the user's color scheme, and the application's own identity (icon + name) isn't front and center.

Describe the solution you'd like

Update the default offline page to the following design:

  • Content centered vertically and horizontally on a plain background.
  • The application's icon (the largest cached PWA icon, i.e. what %%%LOGO_PATH%%% already resolves to) shown as a rounded-square app icon, with the application name (%%%PROJECT_NAME%%%) below it in bold. With the default icon this shows the Vaadin logo; with a custom app icon, the custom icon is shown.
  • Below that, a small vertical "broken connection" indicator: two dots, a crossed-out cloud icon, two dots.
  • Heading: Connection Lost.
  • Muted body text: Check your network connection and try reloading the page.
  • Light and dark variants following prefers-color-scheme (light: white background, dark text; dark: black background, white text, grey secondary text).

Light, default icon:
Offline page, light, default icon

Dark, default icon:
Offline page, dark, default icon

Light, custom app icon:
Offline page, light, custom icon

Dark, custom app icon:
Offline page, dark, custom icon

Constraints from the current implementation:

  • The page must stay fully self-contained (inline CSS/SVG, no external resources), since it is pre-cached and served while the server is unreachable.
  • PwaRegistry joins the file line-by-line, stripping newlines, so any inline script must use block comments and terminate statements with semicolons.
  • Keep the existing template variables (%%%PROJECT_NAME%%%, %%%LOGO_PATH%%%, %%%META_ICONS%%%, %%%BACKGROUND_COLOR%%%) working, and keep the auto-reload-on-reconnect behavior.

Additional context

Whether the embedded offline game added in #25526 should remain on the default page is discussed separately in #26460. This issue only covers the visual design; the redesign shouldn't make that decision.

Activity

  1. totally-not-ai commented on Oct 15, 2026

    @totally-not-ai
    ContributorAuthor

    Triage

    Type: valid enhancement request (not a bug). The current behavior is as designed since #25526.

    Where it lives

    • Template: flow-server/src/main/resources/com/vaadin/flow/server/default-offline-page.html (~520 lines, of which ~370 are the inline Reindeer Runner script/CSS).
    • Rendering: PwaRegistry#initializeOfflinePage reads the file line by line, joins the lines with no newlines, then substitutes %%%PROJECT_NAME%%%, %%%BACKGROUND_COLOR%%%, %%%LOGO_PATH%%% (href of the largest icon) and %%%META_ICONS%%%. Apps that set @PWA(offlinePath = ...) are not affected, because their own page is used.

    Assessment

    • What the issue says about the constraints is correct. Because the lines are joined, any inline JS must use /* */ comments and explicit semicolons. The page must have no external resources. The online → location.reload() listener has to stay.
    • The requested design fits in one self-contained HTML file: a flex-centered column, <img src="%%%LOGO_PATH%%%"> with border-radius for the app icon, the bold app name, an inline SVG for the dots / crossed-out cloud indicator, the "Connection Lost" heading and a muted paragraph. Light/dark is handled with @media (prefers-color-scheme: dark). No Java or API changes are needed.
    • %%%BACKGROUND_COLOR%%% is substituted today, but the current template doesn't actually use it. The new design calls for a plain white/black background, so the variable can keep working without being used, or it can tint the light-mode background. That needs a decision.
    • Edge case: when no icons are configured, %%%LOGO_PATH%%% resolves to "". The new page should hide the icon (e.g. img[src=""] { display: none }) rather than show a broken image.

    Why I'm not opening a PR right away
    This removes a feature that shipped very recently (#25526), and the exact visual design depends on the mockups that haven't been attached yet. Both are product decisions, so they should be confirmed by the team, and ideally by @samie as author of #25526, before anything is implemented.

    Options

    1. Redesign and drop the game (as proposed). Smallest and cleanest default. Apps that want a game can add it with a custom offlinePath page, and the game could be published as a sample or add-on.
    2. Redesign, but keep the game behind a small "Play while you wait" link in the same page (hidden by default). No new API, but the default page keeps carrying ~370 lines of script.
    3. Only remove the game and keep the current layout. Minimal change, but it doesn't address the design concerns.

    Recommendation: option 1. Once the mockups are attached and the direction is confirmed, the change is a single-file template rewrite, plus a test asserting that the rendered default offline page contains the app name/logo and the reload listener.

  2. jouni commented on Oct 15, 2026

    @jouni
    Member

    The default app icon should be updated at the same time.

  3. changed the title [-]Redesign the default PWA offline page and remove the embedded game[/-] [+]Update the default PWA offline page to the new design[/+] on Oct 15, 2026
  4. Artur- commented on Oct 21, 2026

    @Artur-
    Member

    @totally-not-ai do 1 on top of #26557

  5. totally-not-ai commented on Oct 21, 2026

    @totally-not-ai
    ContributorAuthor

    @Artur- Done: I opened #26573 as a draft PR, stacked on #26557.

    • It rewrites the default offline page to match the mockups. The app icon (the largest cached icon) is shown as a rounded square with the app name below it, followed by the dots and crossed-out cloud indicator, the "Connection Lost" heading and the muted help text. The page follows prefers-color-scheme for the light and dark variants.
    • The page is still self-contained, with inline CSS and SVG and no external resources. The reload when the browser comes back online still works.
    • If no cached icon exists, %%%LOGO_PATH%%% resolves to an empty string and the icon is hidden, so there is no broken image.
    • %%%BACKGROUND_COLOR%%% is still substituted but stays unused. The design uses plain white or black instead. If the page should use the manifest background color, that is a small follow-up.
    • I added a test that checks the rendered page contains the app name and the largest cached icon, with no unresolved placeholders.
  6. added a commit that references this issue on Oct 23, 2026
    8cc5ccb
  7. vaadin-bot commented on Nov 6, 2026

    @vaadin-bot
    Collaborator

    This ticket/PR has been released with Vaadin 25.4.0-alpha5.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions