W3cubDocs

/Web APIs

FileSystemHandle

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

The FileSystemHandle interface of the File System API is an object which represents a file or directory entry. Multiple handles can represent the same entry. For the most part you do not work with FileSystemHandle directly but rather its child interfaces FileSystemFileHandle and FileSystemDirectoryHandle.

Interfaces based on FileSystemHandle

Below is a list of interfaces based on the FileSystemHandle interface.

FileSystemFileHandle

Represents a handle to a file entry.

FileSystemDirectoryHandle

Provides a handle to a directory entry.

Instance properties

kind Read only

Returns the type of entry. This is 'file' if the associated entry is a file or 'directory'.

name Read only

Returns the name of the associated entry.

Instance methods

isSameEntry()

Compares two handles to see if the associated entries (either a file or directory) match.

queryPermission() Experimental

Queries the current permission state of the current handle.

remove() Experimental Non-standard

Requests removal of the entry represented by the handle from the underlying file system.

requestPermission() Experimental

Requests read or readwrite permissions for the file handle.

Examples

Checking Type

The below code allows the user to choose a file from the file picker and then tests to see whether the handle returned is a file or directory

js

// store a reference to our file handle
let fileHandle;

async function getFile() {
  // open file picker
  [fileHandle] = await window.showOpenFilePicker();

  if (fileHandle.kind === "file") {
    // run file code
  } else if (fileHandle.kind === "directory") {
    // run directory code
  }
}

Query/Request Permissions

The following asynchronous function returns true if user has granted read or readwrite permissions to the file handle. Permission is requested if not.

js

// fileHandle is a FileSystemFileHandle
// withWrite is a boolean set to true if write

async function verifyPermission(fileHandle, withWrite) {
  const opts = {};
  if (withWrite) {
    opts.mode = "readwrite";
  }

  // Check if we already have permission, if so, return true.
  if ((await fileHandle.queryPermission(opts)) === "granted") {
    return true;
  }

  // Request permission to the file, if the user grants permission, return true.
  if ((await fileHandle.requestPermission(opts)) === "granted") {
    return true;
  }

  // The user did not grant permission, return false.
  return false;
}

Comparing Entries

The following function compares a single entry with an array of entries, and returns a new array with any matching entries removed.

js

function removeMatches(fileEntry, entriesArr) {
  const newArr = entriesArr.filter((entry) => !fileEntry.isSameEntry(entry));

  return newArr;
}

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
FileSystemHandle 86 86 111 No 72 15.2 No 86 111 61 15.2 14.0
isSameEntry 86 86 111 No 72 15.2 No 86 111 61 15.2 14.0
kind 86 86 111 No 72 15.2 No 86 111 61 15.2 14.0
move No No 111 No No No No No 111 No No No
name 86 86 111 No 72 15.2 No 86 111 61 15.2 14.0
queryPermission 86 86 No No 72 No No 86 No 61 No 14.0
remove 110 110 No No 96 No No 110 No 74 No 21.0
requestPermission 86 86 No No 72 No No 86 No 61 No 14.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle