FileSystemFileHandle

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2023.

* Some parts of this feature may have varying levels of support.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is available in Web Workers.

The FileSystemFileHandle interface of the File System API represents a handle to a file system entry. The interface is accessed through the window.showOpenFilePicker() method.

Note that read and write operations depend on file-access permissions that do not persist after a page refresh if no other tabs for that origin remain open. The queryPermission method of the FileSystemHandle interface can be used to verify permission state before accessing a file.

FileSystemHandle FileSystemFileHandle

Instance properties

Inherits properties from its parent, FileSystemHandle.

Instance methods

Inherits methods from its parent, FileSystemHandle.

getFile()

Returns a Promise which resolves to a File object representing the state on disk of the entry represented by the handle.

createSyncAccessHandle()

Returns a Promise which resolves to a FileSystemSyncAccessHandle object that can be used to synchronously read from and write to a file. The synchronous nature of this method brings performance advantages, but it is only usable inside dedicated Web Workers.

createWritable()

Returns a Promise which resolves to a newly created FileSystemWritableFileStream object that can be used to write to a file.

Examples

Reading a File

The following asynchronous function presents a file picker and once a file is chosen, uses the getFile() method to retrieve the contents.

js
async function getTheFile() {
  const pickerOpts = {
    types: [
      {
        description: "Images",
        accept: {
          "image/*": [".png", ".gif", ".jpeg", ".jpg"],
        },
      },
    ],
    excludeAcceptAllOption: true,
    multiple: false,
  };

  // open file picker
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
  // get file contents
  const fileData = await fileHandle.getFile();
  return fileData;
}

Writing a File

The following asynchronous function writes the given contents to the file handle, and thus to disk.

js
async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();

  // Write the contents of the file to the stream.
  await writable.write(contents);

  // Close the file and write the contents to disk.
  await writable.close();
}

Synchronously reading and writing a file

The following asynchronous event handler function is contained inside a Web Worker. On receiving a message from the main thread it:

  • Creates a synchronous file access handle.
  • Gets the size of the file and creates an ArrayBuffer to contain it.
  • Reads the file contents into the buffer.
  • Encodes the message and writes it to the end of the file.
  • Persists the changes to disk and closes the access handle.
js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Get size of the file.
  const fileSize = accessHandle.getSize();
  // Read file content to a buffer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Write the message to the end of the file.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persist changes to disk.
  accessHandle.flush();

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

Note: In earlier versions of the spec, close(), flush(), getSize(), and truncate() were wrongly specified as asynchronous methods, and older versions of some browsers implement them in this way. However, all current browsers that support these methods implement them as synchronous methods.

Specifications

Specification
File System
# api-filesystemfilehandle

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
FileSystemFileHandle
Chrome – Full support
Chrome 86 (Release date: 2020-10-20)
footnote Full support
Edge – Full support
Edge 86 (Release date: 2020-10-09)
footnote Full support
Firefox – Full support
Firefox 111 (Release date: 2023-03-14)
footnote Full support
Opera – Full support
Opera 72 (Release date: 2020-10-21)
footnote Full support
Safari – Full support
Safari 15.2 (Release date: 2021-12-13)
footnote Full support
Chrome Android – Full support
Chrome Android 109 (Release date: 2023-01-10)
footnote Full support
Firefox for Android – Full support
Firefox for Android 111 (Release date: 2023-03-14)
footnote Full support
Opera Android – Full support
Opera Android 74 (Release date: 2023-03-13)
footnote Full support
Safari on iOS – Full support
Safari on iOS 15.2 (Release date: 2021-12-13)
footnote Full support
Samsung Internet – Full support
Samsung Internet 21 (Release date: 2023-05-19)
footnote Full support
WebView Android – Full support
WebView Android 109 (Release date: 2023-01-10)
footnote Full support
WebView on iOS – Full support
WebView on iOS 15.2 (Release date: 2021-12-13)
footnote Full support
createSyncAccessHandle
Chrome – Full support
Chrome 102 (Release date: 2022-05-24)
footnote Full support
Edge – Full support
Edge 102 (Release date: 2022-05-31)
footnote Full support
Firefox – Full support
Firefox 111 (Release date: 2023-03-14)
footnote Full support
Opera – Full support
Opera 88 (Release date: 2022-06-08)
footnote Full support
Safari – Full support
Safari 15.2 (Release date: 2021-12-13)
footnote Full support
Chrome Android – Full support
Chrome Android 109 (Release date: 2023-01-10)
footnote Full support
Firefox for Android – Full support
Firefox for Android 111 (Release date: 2023-03-14)
footnote Full support
Opera Android – Full support
Opera Android 74 (Release date: 2023-03-13)
footnote Full support
Safari on iOS – Full support
Safari on iOS 15.2 (Release date: 2021-12-13)
footnote Full support
Samsung Internet – Full support
Samsung Internet 21 (Release date: 2023-05-19)
footnote Full support
WebView Android – Full support
WebView Android 109 (Release date: 2023-01-10)
footnote Full support
WebView on iOS – Full support
WebView on iOS 15.2 (Release date: 2021-12-13)
footnote Full support
mode option
Experimental Non-standard
Chrome – Full support
Chrome 121 (Release date: 2024-01-23)
footnote Full support
Edge – Full support
Edge 121 (Release date: 2024-01-25)
footnote Full support
Firefox – No support
Firefox
footnote No support
Opera – Full support
Opera 107 (Release date: 2024-02-07)
footnote Full support
Safari – No support
Safari
footnote No support
Chrome Android – Full support
Chrome Android 121 (Release date: 2024-01-23)
footnote Full support
Firefox for Android – No support
Firefox for Android
footnote No support
Opera Android – Full support
Opera Android 81 (Release date: 2024-03-14)
footnote Full support
Safari on iOS – No support
Safari on iOS
footnote No support
Samsung Internet – Full support
Samsung Internet 25 (Release date: 2024-04-24)
footnote Full support
WebView Android – Full support
WebView Android 121 (Release date: 2024-01-23)
footnote Full support
WebView on iOS – No support
WebView on iOS
footnote No support
createWritable
Chrome – Full support
Chrome 86 (Release date: 2020-10-20)
footnote Full support
Edge – Full support
Edge 86 (Release date: 2020-10-09)
footnote Full support
Firefox – Full support
Firefox 111 (Release date: 2023-03-14)
footnote Full support
Opera – Full support
Opera 72 (Release date: 2020-10-21)
footnote Full support
Safari – Full support
Safari 26 (Release date: 2025-09-15)
footnote Full support
Chrome Android – Full support
Chrome Android 109 (Release date: 2023-01-10)
footnote Full support
Firefox for Android – Full support
Firefox for Android 111 (Release date: 2023-03-14)
footnote Full support
Opera Android – Full support
Opera Android 74 (Release date: 2023-03-13)
footnote Full support
Safari on iOS – Full support
Safari on iOS 26 (Release date: 2025-09-15)
footnote Full support
Samsung Internet – Full support
Samsung Internet 21 (Release date: 2023-05-19)
footnote Full support
WebView Android – Full support
WebView Android 109 (Release date: 2023-01-10)
footnote Full support
WebView on iOS – Full support
WebView on iOS 26 (Release date: 2025-09-15)
footnote Full support
mode option
Experimental Non-standard
Chrome – Full support
Chrome 121 (Release date: 2024-01-23)
footnote Full support
Edge – Full support
Edge 121 (Release date: 2024-01-25)
footnote Full support
Firefox – No support
Firefox
footnote No support
Opera – Full support
Opera 107 (Release date: 2024-02-07)
footnote Full support
Safari – No support
Safari
footnote No support
Chrome Android – Full support
Chrome Android 121 (Release date: 2024-01-23)
footnote Full support
Firefox for Android – No support
Firefox for Android
footnote No support
Opera Android – Full support
Opera Android 81 (Release date: 2024-03-14)
footnote Full support
Safari on iOS – No support
Safari on iOS
footnote No support
Samsung Internet – Full support
Samsung Internet 25 (Release date: 2024-04-24)
footnote Full support
WebView Android – No support
WebView Android
footnote No support
WebView on iOS – No support
WebView on iOS
footnote No support
getFile
Chrome – Full support
Chrome 86 (Release date: 2020-10-20)
footnote Full support
Edge – Full support
Edge 86 (Release date: 2020-10-09)
footnote Full support
Firefox – Full support
Firefox 111 (Release date: 2023-03-14)
footnote Full support
Opera – Full support
Opera 72 (Release date: 2020-10-21)
footnote Full support
Safari – Full support
Safari 15.2 (Release date: 2021-12-13)
footnote Full support
Chrome Android – Full support
Chrome Android 109 (Release date: 2023-01-10)
footnote Full support
Firefox for Android – Full support
Firefox for Android 111 (Release date: 2023-03-14)
footnote Full support
Opera Android – Full support
Opera Android 74 (Release date: 2023-03-13)
footnote Full support
Safari on iOS – Full support
Safari on iOS 15.2 (Release date: 2021-12-13)
footnote Full support
Samsung Internet – Full support
Samsung Internet 21 (Release date: 2023-05-19)
footnote Full support
WebView Android – Full support
WebView Android 109 (Release date: 2023-01-10)
footnote Full support
WebView on iOS – Full support
WebView on iOS 15.2 (Release date: 2021-12-13)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.

See also