Manifest member in Manifest
file_handlers manifest member
Published Updated
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.
Member
Section titled “Member”| 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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- Handle files
- File System Access API: read and write local files
- launch_handler manifest member
- scope manifest member
- Manifest Incubations: file_handlers member (wicg.github.io)
- Let installed web applications be file handlers (developer.chrome.com)
- Handle files in Progressive Web Apps (learn.microsoft.com)
Specifications
| Specification | Status |
|---|---|
| manifest: file_handlers | Reference |
| Manifest Incubations: file_handlers member | WICG draft |
| Web App Launch Handler API | WICG draft |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 102 | high | source | — |
| Chrome (Android)# | No | — | high | source | 1 |
| Edge (Desktop)# | Yes | 102 | high | source | 2 |
| Firefox (Desktop)# | No | — | high | source | 3 |
| Firefox (Android)# | No | — | high | source | 45 |
| Safari (macOS)# | No | — | high | source | 6 |
| Safari (iOS)# | No | — | high | source | 78 |
| Samsung Internet# | No | — | high | source | 910 |
| WebView (Android)# | No | — | high | source | 1112 |
- No Chrome Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- No Samsung Internet support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.
- No WebView Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Chrome Android.
Try it
Run this capability in the OpenPWA demo app: /demo/#file-handling