Manifest member in Manifest
widgets manifest member
Published Updated
The widgets manifest member defines widgets that an installed PWA offers on the operating
system’s widget surface. Each definition names an Adaptive Cards template and, optionally, a JSON data URL;
the widget host (today the Windows 11 Widgets Board) draws the card, and the app’s service worker fills and refreshes it in response to
widget lifecycle events, with no page open.
Microsoft Edge on Windows 11 is the implementation Microsoft documents, and its widget host is the Windows 11 Widgets Board (Microsoft Edge documentation, “Display a PWA widget in the Windows Widgets Board”). The member is defined in a Microsoft explainer that names WICG as its expected venue; no W3C or WICG draft exists yet. No other browser documents support, and a browser that does not know the member ignores it.
Member
Section titled “Member”| Property | Value |
|---|---|
| Type | array of widget-definition objects. Required keys in Edge: name, description, tag (the string the service worker uses to address the widget), ms_ac_template (URL of the Adaptive Cards template), and screenshots. Optional keys: short_name, data (URL of the JSON the template is bound to; when present it must return valid JSON), template (informational only in Edge; Microsoft’s field table lists it as optional while its template section calls it required), type (MIME type of the data), icons, auth (boolean), multiple (boolean, default true), and update (refresh period in seconds). |
| Default | absent. Without the member the app offers nothing on the Widgets Board. |
| Example value | [{ "name": "Open tasks", "description": "Your open tasks", "tag": "tasks", "ms_ac_template": "/widgets/tasks.json", "data": "/widgets/tasks-data.json", "screenshots": [{ "src": "/widgets/tasks.png", "sizes": "600x400" }] }]. |
Installing the app only lists its widgets in the board’s Add widgets picker. A widget
becomes active when the user adds it, which fires widgetinstall in the service worker; the
worker then calls self.widgets.updateByTag(tag, { template, data }) to render it. Further
events are widgetuninstall, widgetresume (the board became visible again), and
widgetclick (an Adaptive Cards action the user triggered, with the action verb on
event.action). The same object offers self.widgets.getByTag(), getByInstanceId(), and
matchAll() to enumerate what is installed.
Examples
Section titled “Examples”The examples describe one task-list widget on an app installed from https://tasks.example/.
Declaring a widget with its template, data, and refresh period
Section titled “Declaring a widget with its template, data, and refresh period”Service-worker calls identify the widget by tag, so keep it stable across releases.
update: 900 declares a fifteen-minute refresh period in seconds. Edge does not refresh the
widget by itself; the service worker has to do it, for example on a periodicsync event.
{ "widgets": [ { "name": "Open tasks", "short_name": "Tasks", "description": "Your open tasks, at a glance", "tag": "open-tasks", "template": "open-tasks", "ms_ac_template": "/widgets/open-tasks.ac.json", "data": "/widgets/open-tasks-data.json", "type": "application/json", "update": 900, "icons": [{ "src": "/widgets/icon-96.png", "sizes": "96x96" }], "screenshots": [ { "src": "/widgets/open-tasks-wide.png", "sizes": "600x400", "label": "Open tasks widget listing three tasks" } ] } ]}The picker displays screenshots. Use an image of the rendered card instead of the app.
Rendering on install and refreshing on resume
Section titled “Rendering on install and refreshing on resume”The service worker fetches the template and data named in the widget’s definition and hands
both to updateByTag(). The same function runs for widgetresume, which is the hook for
data that has gone stale while the board was hidden.
async function renderWidget(widget) { const definition = widget.definition; const template = await (await fetch(definition.msAcTemplate)).text(); const data = await (await fetch(definition.data)).text(); await self.widgets.updateByTag(definition.tag, { template, data });}
self.addEventListener('widgetinstall', (event) => { event.waitUntil(renderWidget(event.widget));});
self.addEventListener('widgetresume', (event) => { event.waitUntil(renderWidget(event.widget));});Edge exposes the definition on event.widget.definition, where ms_ac_template is read as
msAcTemplate.
Detecting the API and handling a card action
Section titled “Detecting the API and handling a card action”self.widgets exists only where widgets are implemented, so a service worker shared across
browsers checks for support before calling it. The widgetclick handler receives the action verb declared in
the Adaptive Cards template and can update the card in place.
if ('widgets' in self) { self.addEventListener('widgetclick', (event) => { if (event.action !== 'complete-task') return; event.waitUntil( fetch('/api/tasks/complete', { method: 'POST', body: JSON.stringify(event.data) }) .then(() => renderWidget(event.widget)), ); });} else { // No widget surface in this browser; the app keeps its in-page task list only.}Where self.widgets is missing, the else branch runs and the worker registers no listeners.
See also
Section titled “See also”- widgets browser support
- PWAs on Microsoft Edge (sidebar, store)
- PWAs on Windows
- icons manifest member
- screenshots manifest member
- Display a PWA widget in the Windows Widgets Board (learn.microsoft.com)
- PWA-driven Widgets explainer (microsoftedge.github.io)
Specifications
| Specification | Status |
|---|---|
| PWA-driven Widgets explainer | Community draft |