manifest widgets browser support

widgets is a web app manifest member that Microsoft’s Edge PWA documentation describes as “an array that can contain multiple widget definitions”. Each definition registers one widget for an operating-system widgets board, which the PWA’s service worker then renders and updates.

Browser support

This entry carries no compatibility table. Neither source below exposes a per-browser support table, and a guessed one is worse than none — so what follows is what those two sources actually document, and nothing beyond it.

• Microsoft Edge PWA documentation documents the member on Windows 11, where “widgets appear in the Widgets Board, which you open from the left side of the taskbar”, and states that “In Windows 11, Progressive Web Apps (PWAs) can define widgets, update them, and handle user interactions within them”. It names the Windows 11 Widgets Board as the widget host that widgets “currently” target, and notes “There may be other widget hosts in the future.”
• The PWA-driven Widgets explainer carries the document status “Active” with an expected venue of the “W3C Web Incubator Community Group” — so this is an incubation proposal, not a finished standard.

Neither source documents any other browser implementing the widgets member, and neither exposes a per-browser support table. Treat anything outside what Microsoft documents as undocumented rather than as supported or unsupported.

How to use it

Microsoft’s field table marks name, description, tag, ms_ac_template and screenshots as required, and short_name, icons, template, data, type, auth, update and multiple as optional:

{
  "widgets": [
    {
      "name": "PWAmp mini player",
      "description": "widget to control the PWAmp music player",
      "tag": "pwamp",
      "template": "pwamp-template",
      "ms_ac_template": "widgets/mini-player-template.json",
      "data": "widgets/mini-player-data.json",
      "type": "application/json",
      "screenshots": [
        { "src": "./screenshot-widget.png", "sizes": "600x400", "label": "The PWAmp mini-player widget" }
      ],
      "auth": false,
      "update": 86400
    }
  ]
}

Per the same guide, only custom Adaptive Cards templates are supported “for the time being”, supplied as a URL in ms_ac_template; the template field is “currently only informational and not used”.

How to detect it at runtime

Microsoft’s guide documents the runtime surface as a widgets attribute on the service worker global object (ServiceWorkerGlobalScope), exposing the Promise-based methods getByTag, getByInstanceId, getByHostId, matchAll, updateByInstanceId and updateByTag. It does not document a feature-detection recipe, so testing for that attribute and returning early is this entry’s own choice rather than a Microsoft-documented one:

// In the service worker (ServiceWorkerGlobalScope).
self.addEventListener("widgetinstall", (event) => {
  if (!("widgets" in self)) {
    // No widgets API in this browser — there is nothing to render.
    return;
  }
  event.waitUntil(renderWidget(event.widget));
});

async function renderWidget(widget) {
  const template = await (await fetch(widget.definition.msAcTemplate)).text();
  const data = await (await fetch(widget.definition.data)).text();
  await self.widgets.updateByTag(widget.definition.tag, { template, data });
}

Practical checklist

• A widget in the manifest is not a widget on screen. Per Microsoft’s guide, installing the PWA adds its widgets to the dashboard “but not installed yet” — a widget is only installed when the user adds it from the dashboard, and even then “it is not automatically rendered”. The service worker has to call widgets.updateByTag.
• update is a frequency in seconds, not an automatic refresh: Microsoft’s field table says “Code in your service worker must perform the updating; the widget is not updated automatically.”
• You cannot reuse the app’s own UI. The guide states an existing PWA “cannot simply be placed into the widget dashboard as-is” and that the Windows 11 Widgets Board “requires widgets to be built by using Adaptive Card templates instead of HTML and JavaScript”.
• Local development has prerequisites beyond a browser: the guide says to install WinAppSDK 1.2 and enable Developer Mode in Windows 11 to develop and test widgets on your own machine.
• Oversized art is ignored. Per the field table, widget icons larger than 1024x1024 “are ignored”, as are screenshots images larger than 1024x1024 pixels; a screenshot’s platform field supports the Windows and any values.
• Handle removal as well as installation: the documented service-worker events are widgetinstall, widgetuninstall, widgetresume and widgetclick.

Where to go next

• Manifest widgets: PWA content on the OS widgets board — the full field-by-field reference for this member.
• manifest: screenshots support — the top-level member a widget’s required screenshots array is analogous to.
• Periodic Background Sync support — the API Microsoft’s guide uses to refresh widgets on the update interval.

← Back to the Compatibility explorer.