Skip to content

Manifest member in Manifest

file_handlers manifest member

Published Updated

Limited availabilityNot supported in Chrome (Android), Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)Reference

The file_handlers manifest member registers an installed PWA with the operating system as an opener for specified MIME types and extensions. Its value is an array of handler objects. Opening a matching file from Finder, Explorer, or the Files app launches the app at the handler’s action URL, and the page reads the file through window.launchQueue. The manifest member only creates the registration; the page still has to consume the file in JavaScript.

Chrome 102 and Edge 102 process the member on Windows, macOS, Linux, and ChromeOS (BCD manifests.webapp.file_handlers). Chrome for Android, Safari 27, Firefox 157, and Samsung Internet drop it, so a file association from a PWA exists on desktop Chromium only.

Property Value
Type array of objects. Each object has action (string URL), accept (object mapping a MIME type to an array of extensions), optional icons (array of image resources shown by the OS for files of that type), and optional launch_type ("single-client" or "multiple-clients").
Default no registration. When the member is absent, or when the OS-level association is removed by the user, opening a file does not launch the app.
Example value [{ "action": "/open", "accept": { "text/markdown": [".md"] } }].

Chromium validates each handler on its own. action must be a URL inside the manifest’s scope; an out-of-scope or unparsable action drops that handler with the parser message FileHandler ignored. Property 'action' is invalid., and an accept that leaves no valid MIME type to extension mapping drops it with FileHandler ignored. Property 'accept' is invalid. (Chromium manifest_parser.cc). A single malformed mapping or extension is skipped with its own message while the rest of the handler survives. Extensions must start with a dot. The manifest supplies both because platforms register differently: Linux uses the MIME type together with the extension, Windows uses extensions only and ignores the MIME type (Manifest Incubations). So text/markdown with [".md", ".markdown"] declares both suffixes.

launch_type defaults to "single-client": opening several files at once delivers them to one window as one LaunchParams with several entries in files. With "multiple-clients" each file gets its own launch and files holds one handle. Windows ignores the distinction and launches the app once per file regardless (developer.chrome.com, “Handle files in Progressive Web Apps”).

The first time a file is opened through a handler, Chromium shows a permission dialog before the page sees the file. The Allow or Block choice persists for the site, and Chromium resets it when a manifest update changes file_handlers; ignoring the prompt three times blocks it (developer.chrome.com). On Windows and macOS the association competes with native apps for the same extension, so the user may still have to pick the PWA from the “Open with” menu.

The two example manifests register a Markdown editor. Its script receives the file handle and also covers what happens when no file arrives.

Registering a Markdown editor for two extensions

Section titled “Registering a Markdown editor for two extensions”

One handler claims both .md and .markdown, routes every launch to /editor, and supplies an icon the OS can show on files of that type. scope is set explicitly so the action URL is unambiguously inside it.

{
"name": "Draft",
"start_url": "/",
"scope": "/",
"display": "standalone",
"file_handlers": [
{
"action": "/editor",
"accept": {
"text/markdown": [".md", ".markdown"],
"text/plain": [".txt"]
},
"icons": [{ "src": "/icons/markdown-file.png", "sizes": "256x256", "type": "image/png" }],
"launch_type": "single-client"
}
]
}

After installation on Chrome 102+ the OS lists Draft as an opener for .md, .markdown, and .txt. A browser that ignores the member simply skips it, and installability does not depend on file_handlers.

Consuming the launch and falling back to a file picker

Section titled “Consuming the launch and falling back to a file picker”

The page at /editor installs a launchQueue consumer on load. Launches that arrive before the consumer is set stay queued, and each one is delivered once a consumer exists (developer.chrome.com). When launchQueue is absent (any browser other than desktop Chromium), the same function is wired to a button that opens <input type="file">.

async function openHandle(handle) {
const file = await handle.getFile();
editor.value = await file.text();
document.title = `${file.name} - Draft`;
}
if ('launchQueue' in window) {
window.launchQueue.setConsumer(async (launchParams) => {
if (!launchParams.files.length) return; // Launched from the icon, not from a file.
for (const handle of launchParams.files) await openHandle(handle);
});
} else {
// No file-handling launch is possible here; offer the picker instead.
openButton.hidden = false;
openButton.addEventListener('click', () => picker.click());
picker.addEventListener('change', async () => {
const [file] = picker.files;
if (file) editor.value = await file.text();
});
}

launchParams.files holds FileSystemFileHandle objects, so the same handle can later be passed to createWritable() to save back to the opened file without a save dialog; the <input type="file"> fallback yields plain File objects and cannot write back.

Checking the registration from the OS side

Section titled “Checking the registration from the OS side”

launchQueue and LaunchParams only deliver launches; neither reports whether the OS association exists. Verify it from the operating system after install: on Windows, right-click a matching file in File Explorer and look for the app under Open with; on macOS select a matching file in Finder and use File > Get Info > Open with. If the app is absent, check DevTools > Application > Manifest for an Errors and warnings line about the handler.

{
"file_handlers": [
{
"action": "https://other.example/open",
"accept": { "text/markdown": [".md"] }
}
]
}

This handler is dropped because action points at a different origin than the manifest’s scope; the console shows Manifest: FileHandler ignored. Property 'action' is invalid. and the OS is not told about the type.

Specifications

SpecificationStatus
manifest: file_handlersReference
Manifest Incubations: file_handlers memberWICG draft
Web App Launch Handler APIWICG draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes102highsource—
Chrome (Android)#No—highsource1
Edge (Desktop)#Yes102highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#No—highsource910
WebView (Android)#No—highsource1112
  1. No Chrome Android support is recorded in browser-compat-data.
  2. Derived by browser-compat-data mirroring from Chrome.
  3. No Firefox support is recorded in browser-compat-data.
  4. No Firefox for Android support is recorded in browser-compat-data.
  5. Derived by browser-compat-data mirroring from Firefox.
  6. No Safari support is recorded in browser-compat-data.
  7. No Safari on iOS support is recorded in browser-compat-data.
  8. Derived by browser-compat-data mirroring from Safari.
  9. No Samsung Internet support is recorded in browser-compat-data.
  10. Derived by browser-compat-data mirroring from Chrome Android.
  11. No WebView Android support is recorded in browser-compat-data.
  12. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/manifest-file-handlers.json · Global usage: 39 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)