> ## 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.

# File picker dialog

> Open a file picker dialog in a Kotlin Multiplatform project

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

## Quick start

The file picker component provides a native interface for users to browse and select files from their device. It supports various file types and offers customization options to fit different use cases.

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

  ```kotlin filekit-dialogs-compose theme={null}
  val launcher = rememberFilePickerLauncher { file ->
      // Handle the file
  }

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

<Warning>
  On iOS, remember FileKit Compose launchers from a stable/root Compose scope, not
  inside transient surfaces such as `ModalBottomSheet`, dialogs, popups, or
  dropdowns. [Learn more in GitHub issue #547](https://github.com/vinceglb/FileKit/issues/547).
</Warning>

## Selection mode

Select one or multiple files using the `mode` parameter. FileKit provides four different selection modes:

### Basic modes

* `Single` - Allows the user to select a single file (default).
* `Multiple()` - Allows the user to select multiple files.

<CodeGroup>
  ```kotlin filekit-dialogs theme={null}
  // Single file selection
  val file = FileKit.openFilePicker(mode = FileKitMode.Single)

  // Multiple file selection
  val files = FileKit.openFilePicker(mode = FileKitMode.Multiple())

  // Multiple with max limit
  val files = FileKit.openFilePicker(mode = FileKitMode.Multiple(maxItems = 5))
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  // Single file selection
  val singleLauncher = rememberFilePickerLauncher(
      mode = FileKitMode.Single
  ) { file ->
      // Handle single file: PlatformFile?
  }

  // Multiple file selection
  val multipleLauncher = rememberFilePickerLauncher(
      mode = FileKitMode.Multiple(maxItems = 10)
  ) { files ->
      // Handle multiple files: List<PlatformFile>?
  }
  ```
</CodeGroup>

### State-tracking modes

For advanced use cases where you need to track the selection progress:

* `SingleWithState` - Single file selection with state tracking.
* `MultipleWithState()` - Multiple file selection with state tracking.

<CodeGroup>
  ```kotlin filekit-dialogs theme={null}
  // Single file with state tracking
  val stateFlow = FileKit.openFilePicker(mode = FileKitMode.MultipleWithState())
  stateFlow.collect { state ->
      when (state) {
          is FileKitPickerState.Started -> println("Selection started with ${state.total} files")
          is FileKitPickerState.Progress -> println("Processing: ${state.processed.size} / ${state.total}")
          is FileKitPickerState.Completed -> println("Completed: ${state.result.size} files selected")
          is FileKitPickerState.Failed -> println("Selection failed: ${state.cause.message}")
          is FileKitPickerState.Cancelled -> println("Selection cancelled")
      }
  }
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  // Single file with state tracking
  val stateLauncher = rememberFilePickerLauncher(
      mode = FileKitMode.MultipleWithState()
  ) { state ->
      when (state) {
          is FileKitPickerState.Started -> {
              // Show loading indicator
              println("Selection started with ${state.total} files")
          }
          is FileKitPickerState.Progress -> {
              // Update progress for: state.processed
              println("Processing: ${state.processed.size} / ${state.total}")
          }
          is FileKitPickerState.Completed -> {
              // Handle selected file: state.result
              println("Completed: ${state.result.size} files selected")
          }
          is FileKitPickerState.Failed -> {
              // Handle picker failure
              println("Selection failed: ${state.cause.message}")
          }
          is FileKitPickerState.Cancelled -> {
              // Handle cancellation
              println("Selection cancelled")
          }
      }
  }
  ```
</CodeGroup>

<Info>
  The `Multiple` and `MultipleWithState` modes support a `maxItems` parameter (1-50 files). If not specified, there's no limit.

  FileKit treats `maxItems` as an output contract across platforms:

  * **UI-enforced limit**: on pickers that natively support max selection (for example gallery pickers on Android and iOS).
  * **Output-enforced limit**: when native picker APIs do not support max selection (for example generic file/document pickers), FileKit truncates the result to the first `maxItems` files in platform-returned order.
</Info>

## Filter by type

Filter the files by their type using the `type` parameter. You can pick different types of files with `FileKitType`:

* `Image`: Pick an image file.
* `Video`: Pick a video file.
* `ImageAndVideo`: Pick an image or a video file.
* `File()`: Pick any file. It is the default type. It's possible to specify a list of extensions.

<CodeGroup>
  ```kotlin filekit-dialogs theme={null}
  val file = FileKit.openFilePicker(type = FileKitType.File(listOf("pdf", "docx")))
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  val launcher = rememberFilePickerLauncher(
      type = FileKitType.File(extensions = listOf("pdf", "docx"))
  ) { file ->
      // Handle the pdf or docx file
  }
  ```
</CodeGroup>

<Info>On Android and iOS, using Image, Video or ImageAndVideo FileKitType will open a gallery picker. [Read more here.](/dialogs/gallery-picker)</Info>

## 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 file = FileKit.openFilePicker(
      directory = PlatformFile("/custom/initial/path"),
      dialogSettings = FileKitDialogSettings.createDefault(),
  )
  ```

  ```kotlin filekit-dialogs-compose theme={null}
  val launcher = rememberFilePickerLauncher(
      directory = PlatformFile("/custom/initial/path"),
      dialogSettings = FileKitDialogSettings.createDefault(),
  ) { file ->
      // Handle the file
  }
  ```
</CodeGroup>

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

<Note>
  **macOS System Appearance**

  On macOS, to ensure the file 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>