FileSystemDirectoryHandle: getDirectoryHandle() method

Baseline 2023
Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

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 getDirectoryHandle() method of the FileSystemDirectoryHandle interface returns a FileSystemDirectoryHandle for a subdirectory with the specified name within the directory handle on which the method is called.

Syntax

js
getDirectoryHandle(name)
getDirectoryHandle(name, options)

Parameters

name

A string representing the FileSystemHandle.name of the subdirectory you wish to retrieve.

options Optional

An optional object containing options for the retrieved subdirectory. Options are as follows:

create Optional

A boolean value, which defaults to false. When set to true if the directory is not found, one with the specified name will be created and returned.

Return value

A Promise which resolves with a FileSystemDirectoryHandle.

Exceptions

NotAllowedError DOMException

Thrown if the PermissionStatus.state for the handle is not 'granted' in readwrite mode if the create option is set to true or in read mode if the create option is set to false.

TypeError

Thrown if the name specified is not a valid string or contains characters that would interfere with the native file system.

TypeMismatchError DOMException

Thrown if the returned entry is a file and not a directory.

NotFoundError DOMException

Thrown if the current entry is not found or if the target directory doesn't exist and the create option is set to false.

Examples

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

js
const dirName = "directoryToGetName";

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

Specifications

Specification
File System
# api-filesystemdirectoryhandle-getdirectoryhandle

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getDirectoryHandle

Legend

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

Full support
Full support
No support
No support

See also