Register an app as a file handler with the operating system.
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.
Examples of sites that may use this API include:
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 |
To experiment with the File Handling API locally, without an origin trial token, enable the #file-handling-api
flag in chrome://flags
.
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:
To check if the File Handling API is supported, use:
if ('launchQueue' in window) {
// The File Handling API is supported.
}
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:
"action"
property that points to a URL within the scope of the app as its value."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.
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.
}
});
}
There is no DevTools support at the time of this writing, but I have filed a feature request for support to be added.
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.
.excalidraw
files.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.
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.
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.
All operating systems allow users to change the present file associations. This is outside the scope of the browser.
The Chrome team wants to hear about your experiences with the File Handling API.
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?
Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?
UI>Browser>WebAppInstalls>FileHandling
in the Components box. Glitch works great for sharing quick and easy repros.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.
#FileHandling
and let us know where and how you are using it.UI>Browser>WebAppInstalls>FileHandling
The File Handling API was specified by Eric Willigers, Jay Harris, and Raymes Khoury. This article was reviewed by Joe Medley.