Handle files
Published
The file_handlers manifest member associates file types with an installed PWA, so a desktop user can open a .csv file by double-clicking it or choosing the app under “Open with”. The browser reads the association when the PWA is installed, and page JavaScript reads the file through window.launchQueue. An in-app file picker provides the same import on Android, Firefox, and Safari.
You need an installable PWA (see Getting started), Chrome or Edge 102 or later on Windows, macOS, Linux, or ChromeOS, and a file type to own.
Declare the handler in the manifest
Section titled “Declare the handler in the manifest”Each entry in file_handlers needs an action URL inside the app’s navigation scope and an
accept map from MIME type to file extensions (MDN marks both as required). Chrome also
reads an optional icons array, which lets the OS show a file-type icon instead of the app
icon, and launch_type:
{ "file_handlers": [ { "action": "/open", "accept": { "text/csv": [".csv"] }, "icons": [ { "src": "/icons/csv-file.png", "sizes": "256x256", "type": "image/png" } ], "launch_type": "single-client" } ]}launch_type defaults to "single-client": opening several matching files at once produces
one launch whose LaunchParams.files holds every file. With "multiple-clients" Chrome
launches the app once per file and each launch’s files array has one element. Reinstall
the PWA after changing this member; the OS association is written at install time, and Chrome
resets the file-handling permission whenever file_handlers changes.
- 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.
Chrome’s capability article states that File Handling is “limited to desktop operating systems”, so the handler does nothing on Android even though the manifest is accepted there.
Consume the launch in the page
Section titled “Consume the launch in the page”When the OS opens a file with the app, Chrome navigates to action and enqueues a
LaunchParams object on window.launchQueue; Chrome’s launch-handler documentation
describes the queue as holding launches “until they are handled by the specified consumer”,
so a consumer registered after the page has booted still receives the launch. Register it once,
at top level, before any async startup work:
window.launchQueue.setConsumer(async (launchParams) => { if (!launchParams.files || launchParams.files.length === 0) return; for (const handle of launchParams.files) { const file = await handle.getFile(); renderCsv(file.name, await file.text()); }});Each entry in files is a file handle rather than a File, which is why the consumer calls
getFile() before reading.
Detect support and fall back to a picker
Section titled “Detect support and fall back to a picker”Chrome’s article gives the detection as 'launchQueue' in window && 'files' in LaunchParams.prototype; the second half matters because a browser could ship launchQueue
for launch_handler navigation without the files member. When the check fails, show a
standard file input so the feature still exists, without OS integration:
function supportsFileHandling() { return 'launchQueue' in window && 'files' in LaunchParams.prototype;}
const picker = document.querySelector('#open-file-input'); // <input type="file" accept=".csv">
if (supportsFileHandling()) { window.launchQueue.setConsumer(async (launchParams) => { for (const handle of launchParams.files ?? []) { const file = await handle.getFile(); renderCsv(file.name, await file.text()); } });} else { picker.hidden = false; picker.addEventListener('change', async () => { const [file] = picker.files; if (file) renderCsv(file.name, await file.text()); });}Keep the picker reachable on desktop too: a user who has not installed the app, or who opens the app first and then wants a file, has no OS launch to rely on.
Verify the association
Section titled “Verify the association”Install the PWA, then open a .csv from the OS file manager. The first launch shows Chrome’s
permission prompt before the app can read the file; grant it and the consumer runs with one
entry in files.
See also
Section titled “See also”file_handlersmanifest memberfile_handlerscompatibility- Receive shared content (share target)
- File System Access
- Let installed web applications be file handlers (developer.chrome.com)
file_handlers(developer.mozilla.org)