Skip to content

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.

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.

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.

Specifications

SpecificationStatus
PWA-driven Widgets explainerCommunity draft