W3cubDocs

/Web APIs

FileSystemDirectoryHandle

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

The FileSystemDirectoryHandle interface of the File System API provides a handle to a file system directory.

The interface can be accessed via the window.showDirectoryPicker(), StorageManager.getDirectory(), DataTransferItem.getAsFileSystemHandle(), and FileSystemDirectoryHandle.getDirectoryHandle() methods.

Instance properties

Inherits properties from its parent, FileSystemHandle.

Instance methods

Inherits methods from its parent, FileSystemHandle.

Regular methods:

FileSystemDirectoryHandle.getDirectoryHandle(): Returns a Promise fulfilled with a FileSystemDirectoryHandle for a subdirectory with the specified name within the directory handle on which the method is called.
FileSystemDirectoryHandle.getFileHandle(): Returns a Promise fulfilled with a FileSystemFileHandle for a file with the specified name, within the directory the method is called.
FileSystemDirectoryHandle.removeEntry(): Attempts to asynchronously remove an entry if the directory handle contains a file or directory called the name specified.
FileSystemDirectoryHandle.resolve(): Returns a Promise fulfilled with an Array of directory names from the parent handle to the specified child entry, with the name of the child entry as the last array item.

Asynchronous iterator methods:

FileSystemDirectoryHandle.entries(): Returns a new async iterator of a given object's own enumerable property [key, value] pairs.
FileSystemDirectoryHandle.keys(): Returns a new async iterator containing the keys for each item in FileSystemDirectoryHandle.
FileSystemDirectoryHandle.values(): Returns a new async iterator containing the values for each index in the FileSystemDirectoryHandle object.
FileSystemDirectoryHandle[@@asyncIterator](): Returns the entries function by default.

Examples

Return directory handle

The following example returns a directory handle with the specified name; if the directory does not already exist it is created.

const dirName = "directoryToGetName";

// assuming we have a directory handle: 'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });

Return file path

The following asynchronous function uses resolve() to find the path to a chosen file, relative to a specified directory handle.

async function returnPathDirectories(directoryHandle) {
  // Get a file handle by showing a file picker:
  const handle = await self.showOpenFilePicker();
  if (!handle) {
    // User cancelled, or otherwise failed to open a file.
    return;
  }

  // Check if handle exists inside our directory handle
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePath === null) {
    // Not inside directory handle
  } else {
    // relativePath is an array of names, giving the relative path

    for (const name of relativePaths) {
      // log each entry
      console.log(name);
    }
  }
}

Return handles for all files in a directory

The following example scans recursively through a directory to return FileSystemFileHandle objects for each file in that directory:

async function* getFilesRecursively(entry) {
  if (entry.kind === "file") {
    const file = await entry.getFile();
    if (file !== null) {
      file.relativePath = getRelativePath(entry);
      yield file;
    }
  } else if (entry.kind === "directory") {
    for await (const handle of entry.values()) {
      yield* getFilesRecursively(handle);
    }
  }
}
for await (const fileHandle of getFilesRecursively(directoryHandle)) {
  console.log(fileHandle);
}

Specifications

Specification
File System Standard # api-filesystemdirectoryhandle

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
`@@asyncIterator`	86	86	111	No	72	16.4	No	86	111	61	16.4	14.0
`FileSystemDirectoryHandle`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`entries`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`getDirectoryHandle`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`getFileHandle`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`keys`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`removeEntry`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`resolve`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0
`values`	86	86	111	No	72	15.2	No	86	111	61	15.2	14.0