• Home
• All articles

Let web applications be file handlers

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

Oct 22, 2020 • Updated Jun 3, 2021

Thomas Steiner

• Twitter
• GitHub
• Glitch
• Blog

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 #

How to use the File Handling API #

Enabling via about://flags #

To experiment with the File Handling API locally, without an origin trial token, enable the #file-handling-api flag in about://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.

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.

Security #

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.

Permissions, permissions persistence, and file handler updates #

To ensure user trust and the safety of users' files when the File Handling API is used to open a file, a permission prompt will be shown before a PWA can view a file. This permission prompt will be shown right after either of the following scenarios:

• The user selects the PWA to open a file, so that the permission is tightly coupled to the action of opening a file using the PWA, making it more understandable and relevant.
• The site loads without the file, so that the user has an expectation of what the PWA is and why it would like to view the file.

This permission will show every time until the user clicks to Allow or Block file handling for the site, or ignores the prompt three times (after which Chromium will embargo and block this permission). The selected setting will persist across the PWA closing and reopening.

When the manifest updates and changes in the "file_handlers" section are detected, the permissions will be reset.

File-related challenges #

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.

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 using the hashtag #FileHandling and let us know where and how you are using it.

Helpful links #

• Public explainer
• File Handling API demo | File Handling API demo source
• Chromium tracking bug
• ChromeStatus.com entry
• Blink Component: UI>Browser>WebAppInstalls>FileHandling

Wanna go deeper #

• TAG Review
• Mozilla Standards Position

Acknowledgements #

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