> ## Documentation Index
> Fetch the complete documentation index at: https://filekit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory picker dialog

> Open a folder picker dialog in a Kotlin Multiplatform project

<Check>Supported on Android, iOS, macOS, JVM, JS and WASM targets</Check>

## Quick start

Easily open a folder picker dialog to let users select a directory.

<CodeGroup>
  ```kotlin filekit-dialogs theme={null}
  val directory = FileKit.openDirectoryPicker()
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  val launcher = rememberDirectoryPickerLauncher(
      onError = { failure ->
          // A valid directory operation could not be completed
          showError(failure.message)
      },
      onResult = { directory ->
          if (directory == null) {
              // The user cancelled the picker
          } else {
              // Handle the selected directory
          }
      },
  )

  Button(onClick = { launcher.launch() }) {
      Text("Pick a directory")
  }
  ```
</CodeGroup>

`onError` receives a `FileKitDialogException` only when FileKit cannot complete a valid directory operation. User cancellation is not a failure: it invokes `onResult(null)`. Coroutine cancellation, invalid invocation, and unexpected defects continue to propagate normally.

The compatibility overload without `onError` remains available and ignores normalized operational failures without logging. New integrations should use explicit error handling.

See [dialog error handling](/dialogs/error-handling) for the complete callback and propagation matrix.

## Customizing the dialog

You can customize the dialog by setting the initial directory and platform-specific `dialogSettings`, such as a title on supported platforms.

<CodeGroup>
  ```kotlin filekit-dialogs theme={null}
  val directory = FileKit.openDirectoryPicker(
      directory = PlatformFile("/custom/initial/path"),
      dialogSettings = FileKitDialogSettings.createDefault(),
  )
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  val launcher = rememberDirectoryPickerLauncher(
      directory = PlatformFile("/custom/initial/path"),
      dialogSettings = FileKitDialogSettings.createDefault(),
      onError = { failure -> showError(failure.message) },
      onResult = { directory ->
          // Handle the selected directory, or null when the user cancelled
      },
  )
  ```
</CodeGroup>

Read more about [dialog settings](/dialogs/dialog-settings) to customize the dialog for each platform.

<Note>
  On JS and WASM, directory picking uses the browser `webkitdirectory` input behavior. Browsers expose the selected directory as a flat list of files, so FileKit rebuilds a virtual directory tree from their relative paths. Empty directories are not available, and directory `lastModified()` values are synthetic.
</Note>

<Note>
  **macOS System Appearance**

  On macOS, to ensure the directory picker dialog uses the system's theme (light or dark), you may need to set a system property at the start of your application:

  ```kotlin theme={null}
  System.setProperty("apple.awt.application.appearance", "system")
  ```

  This is typically done in your `main` function, before the application window is created.
</Note>