Learn Measure Blog Live About
Binders in many colors.

Let web applications be file handlers

Let web applications be file handlers

Register an app as a file handler with the operating system.

Updated

The File Handling API is part of the capabilities project and is currently in development. This post will be updated as the implementation progresses.

Now that web apps are capable of reading and writing files, the next logical step is to let developers declare these very web apps as file handlers for the files their apps can create and process. The File Handling API allows you to do exactly this. After registering a text editor app as a file handler, you can right-click a .txt file on macOS and select "Get Info" to then instruct the OS that it should always open .txt files with this app as default.

Suggested use cases for the File Handling API

Examples of sites that may use this API include:

  • Office applications like text editors, spreadsheet apps, and slideshow creators.
  • Graphics editors and drawing tools.
  • Video game level editor tools.

Current status

Step Status
1. Create explainer Complete
2. Create initial draft of specification Not started
3. Gather feedback & iterate on design In progress
4. Origin trial Not started
5. Launch Not started

How to use the File Handling API

Enabling via chrome://flags

To experiment with the File Handling API locally, without an origin trial token, enable the #file-handling-api flag in chrome://flags.

Progressive enhancement

The File Handling API per se cannot be polyfilled. The functionality of opening files with a web app, however, can be achieved through two other means:

  • The Web Share Target API lets developers specify their app as a share target so files can be opened from the operating system's share sheet.
  • The File System Access API can be integrated with file drag and drop, so developers can handle dropped files in the already opened app.

Feature detection

To check if the File Handling API is supported, use:

if ('launchQueue' in window) {
// The File Handling API is supported.
}

The declarative part of the File Handling API

As a first step, web apps need to declaratively describe in their Web App Manifest what kind of files they can handle. The File Handling API extends Web App Manifest with a new property called "file_handlers" that accepts an array of, well, file handlers. A file handler is an object with two properties:

  • An "action" property that points to a URL within the scope of the app as its value.
  • An "accept" property with an object of MIME-types as keys and lists of file extensions as their values.

The example below, showing only the relevant excerpt of the Web App Manifest, should make it clearer:

{

"file_handlers": [
{
"action": "/open-csv",
"accept": {
"text/csv": [".csv"]
}
},
{
"action": "/open-svg",
"accept": {
"image/svg+xml": ".svg"
}
},
{
"action": "/open-graf",
"accept": {
"application/vnd.grafr.graph": [".grafr", ".graf"],
"application/vnd.alternative-graph-app.graph": ".graph"
}
}
],

}

This is for a hypothetical application that handles comma-separated value (.csv) files at /open-csv, scalable vector graphics (.svg) files at /open-svg, and a made-up Grafr file format with any of .grafr, .graf, or .graph as the extension at /open-graf.

For this declaration to have any effect, the application must be installed. You can learn more in an article series on this very site on making your app installable.

The imperative part of the File Handling API

Now that the app has declared what files it can handle at which in-scope URL in theory, it needs to imperatively do something with incoming files in practice. This is where the launchQueue comes into play. To access launched files, a site needs to specify a consumer for the window.launchQueue object. Launches are queued until they are handled by the specified consumer, which is invoked exactly once for each launch. In this manner, every launch is handled, regardless of when the consumer was specified.

if ('launchQueue' in window) {
launchQueue.setConsumer((launchParams) => {
// Nothing to do when the queue is empty.
if (!launchParams.files.length) {
return;
}
for (const fileHandle of launchParams.files) {
// Handle the file.
}
});
}

DevTools support

There is no DevTools support at the time of this writing, but I have filed a feature request for support to be added.

Demo

I have added file handling support to Excalidraw, a cartoon-style drawing app. When you create a file with it and store it somewhere on your file system, you can open the file via a double click, or a right click and then select "Excalidraw" in the context menu. You can check out the implementation in the source code.

The macOS finder window with an Excalidraw file.
Double click or right click a file in your operating system's file explorer.
The context menu that appears when right clicking a file with the 'Open with… Excalidraw' item highlighted.
Excalidraw is the default file handler for .excalidraw files.

Security and permissions

The Chrome team has designed and implemented the File Handling API using the core principles defined in Controlling Access to Powerful Web Platform Features, including user control, transparency, and ergonomics.

There is a large category of attack vectors that are opened by allowing websites access to files. These are outlined in the article on the File System Access API. The additional security-pertinent capability that the File Handling API provides over the File System Access API is the ability to grant access to certain files through the operating system's built-in UI, as opposed to through a file picker shown by a web application. Any restrictions as to the files and folders that can be opened via the picker will also be applied to the files and folders opened via the operating system.

There is still a risk that users may unintentionally grant a web application access to a file by opening it. However, it is generally understood that opening a file allows the application it is opened with to read and/or manipulate that file. Therefore, a user's explicit choice to open a file in an installed application, such as via an "Open with…" context menu, can be read as a sufficient signal of trust in the application.

Default handler challenges

The exception to this is when there are no applications on the host system for a given file type. In this case, some host operating systems may automatically promote the newly registered handler to the default handler for that file type, silently and without any intervention by the user. This would mean if the user double clicks a file of that type, it would automatically open in the registered web app. On such host operating systems, when the user agent determines that there is no existing default handler for the file type, an explicit permission prompt might be necessary to avoid accidentally sending the contents of a file to a web application without the user's consent.

User control

The spec states that browsers should not register every site that can handle files as a file handler. Instead, file handling registration should be gated behind installation and never happen without explicit user confirmation, especially if a site is to become the default handler. Rather than hijacking existing extensions like .json that the user probably already has a default handler registered for, sites should consider crafting their own extensions.

Transparency

All operating systems allow users to change the present file associations. This is outside the scope of the browser.

Feedback

The Chrome team wants to hear about your experiences with the File Handling API.

Tell us about the API design

Is there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model?

  • File a spec issue on the corresponding GitHub repo, or add your thoughts to an existing issue.

Report a problem with the implementation

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?

  • File a bug at new.crbug.com. Be sure to include as much detail as you can, simple instructions for reproducing, and enter UI>Browser>WebAppInstalls>FileHandling in the Components box. Glitch works great for sharing quick and easy repros.

Show support for the API

Are you planning to use the File Handling API? Your public support helps the Chrome team to prioritize features and shows other browser vendors how critical it is to support them.

Share how you plan to use it on the WICG Discourse thread Send a Tweet to @ChromiumDev with the #FileHandling hashtag and let us know where and how you are using it.

Helpful links

Acknowledgements

The File Handling API was specified by Eric Willigers, Jay Harris, and Raymes Khoury. This article was reviewed by Joe Medley.

Last updated: Improve article