Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This module allows you to easily use the Native File System API on supporting browsers, with a transparent fallback to the <input type="file"> and <a download> legacy methods. This library is a ponyfill.

Read more on the background of this module in my post Progressive Enhancement In the Age of Fugu APIs.

Live Demo

See the library in action:

Origin Trial

⚠️ In order to use the Native File System API, you need to quickly request an origin trial token for your application and communicate it to the browser via a meta tag or an HTTP header.

Usage Example

The module feature-detects support for the Native File System API and only loads the actually relevant code.

// The imported methods will use the Native
// File System API or a fallback implementation.
import {
} from '';

(async () => {
  // Open a file.
  const blob = await fileOpen({
    mimeTypes: ['image/*'],

  // Open multiple files.
  const blobs = await fileOpen({
    mimeTypes: ['image/*'],
    multiple: true,

  // Open all files in a directory,
  // recursively including subdirectories.
  const blobsInDirectory = await directoryOpen({
    recursive: true,

  // Save a file.
  await fileSave(blob, {
    fileName: 'Untitled.png',
    extensions: ['png'],

API Documentation

Opening files:

// Options are optional.
const options = {
  // List of allowed MIME types, defaults to `*/*`.
  mimeTypes: ['image/*'],
  // List of allowed file extensions, defaults to `''`.
  extensions: ['png', 'jpg', 'jpeg', 'webp'],
  // Set to `true` for allowing multiple files, defaults to `false`.
  multiple: true,
  // Textual description for file dialog , defaults to `''`.
  description: 'Image files',

const blobs = await fileOpen(options);

Opening directories:

// Options are optional.
const options = {
  // Set to `true` to recursively open files in all subdirectories,
  // defaults to `false`.
  recursive: true,

const blobs = await directoryOpen(options);

The module also polyfills a webkitRelativePath property on returned files in a consistent way, regardless of the underlying implementation.

Saving files:

// Options are optional.
const options = {
  // Suggested file name to use, defaults to `''`.
  fileName: 'Untitled.txt',
  // Suggested file extensions, defaults to `''`.
  extensions: ['txt'],

// Optional file handle to save back to an existing file.
// This will only work with the Native File System API.
// Get a `FileHandle` from the `handle` property of the `Blob`
// you receive from `fileOpen()` (this is non-standard).
const handle = previouslyOpenedBlob.handle;

await fileSave(someBlob, options, handle);

Browser-NativeFS in Action

You can see the module in action in the Excalidraw drawing app.



A similar, but more extensive library called native-file-system-adapter is provided by @jimmywarting.


Thanks to @developit for improving the dynamic module loading and @dwelle for the helpful feedback, issue reports, and the Windows build fix. Directory operations were made consistent regarding webkitRelativePath and parallelized and sped up significantly by @RReverser. The TypeScript type annotations were provided by @nanaian.

License and Note

Apache 2.0.

This is not an official Google product.

You can’t perform that action at this time.