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

# Set up FileKit Dialogs

> Add FileKit Dialogs, register your Android activity, and prepare Linux and desktop builds

[See the platform support matrix](https://filekit.mintlify.site/platform-support.md#filekit-dialogs)

FileKit Dialogs opens native file, folder, gallery, and save dialogs and returns the result as a `PlatformFile`. Most targets need no setup beyond the dependency.

## Installation

FileKit can helps you to display dialogs to the user like file, directory and photo pickers, save dialogs, camera and more. FileKit dialogs are available in two flavors:

```kotlin build.gradle.kts theme={null}
// Enables FileKit dialogs without Compose dependencies
implementation("io.github.vinceglb:filekit-dialogs:0.17.0")

// Enables FileKit dialogs with Composable utilities
implementation("io.github.vinceglb:filekit-dialogs-compose:0.17.0")
```

```toml libs.versions.toml theme={null}
[versions]
filekit = "0.17.0"

[libraries]
filekit-dialogs = { module = "io.github.vinceglb:filekit-dialogs", version.ref = "filekit" }
filekit-dialogs-compose = { module = "io.github.vinceglb:filekit-dialogs-compose", version.ref = "filekit" }
```

Both artifacts include `filekit-core`. Check the [platform support matrix](https://filekit.mintlify.site/platform-support.md#filekit-dialogs) for the dialogs available on each target.

## Android setup

Only Android needs an init step for dialogs, and only when you call the suspend APIs (`FileKit.openFilePicker()`…). Compose launchers register the activity for you, but a suspend call made before any launcher is composed throws `FileKitNotInitializedException`. Register your activity so FileKit can reach its `ActivityResultRegistry`:

```kotlin MainActivity.kt theme={null}
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        FileKit.init(this)
    }
}
```

With `filekit-dialogs-compose`, the launchers find the registry themselves. On JVM, Linux native, and Windows native, `FileKit.init(appId)` is not needed for dialogs: it only configures app directories such as `filesDir` and `cacheDir`. See [Core setup](https://filekit.mintlify.site/core/setup.md).

## Linux setup

> [tab] JVM on Linux
>
> Packaged Compose Desktop apps need the `jdk.security.auth` module, otherwise dialogs can fail with a `NoClassDefFoundError` ([issue #107](https://github.com/vinceglb/FileKit/issues/107)):
>
> ```kotlin build.gradle.kts theme={null}
> compose.desktop {
>     application {
>         nativeDistributions {
>             linux {
>                 modules("jdk.security.auth")
>             }
>         }
>     }
> }
> ```
>
> Dialogs use the XDG Desktop Portal when it is running and fall back to AWT/Swing dialogs otherwise.

> [tab] Linux native
>
> On `linuxX64` and `linuxArm64`, dialogs go through the XDG Desktop Portal (`org.freedesktop.portal.Desktop`), which runs by default on GNOME, KDE, and most modern desktops. There is no fallback dialog and no parent window.
>
> Your binary links against `libdbus-1`:
>
> * **To build**, install the D-Bus development package for the target architecture (`libdbus-1-dev` on Debian/Ubuntu). It provides the unversioned `libdbus-1.so` linker file.
> * **To run**, the runtime library is enough.
>
> If the library directory is outside Kotlin/Native's linker search paths, add it to your target:
>
> ```kotlin build.gradle.kts theme={null}
> kotlin {
>     linuxX64 {
>         binaries.all {
>             linkerOpts("-L/usr/lib/x86_64-linux-gnu")
>         }
>     }
> }
> ```
>
> On a Linux build machine, `pkg-config --variable=libdir dbus-1` prints the directory to use. Cross-compiling requires the libraries of the target architecture.

## Compose launchers

`remember…Launcher` functions capture platform context when they are remembered, not when you call `launch()`. A few platforms care about where that happens.

| Platform | What to do |
| - | - |
| iOS | Remember launchers in a stable scope, such as your screen's root. A launcher remembered inside a `ModalBottomSheet`, dialog, popup, or dropdown keeps that transient view controller as its presenter ([issue #547](https://github.com/vinceglb/FileKit/issues/547)). |
| JVM | Called with a `WindowScope` receiver (directly inside `Window { }` content), the launchers parent the dialog to that window. Elsewhere, pass `FileKitDialogSettings(parent = FileKitDialogParent.awt(window))`. See [Dialog settings](https://filekit.mintlify.site/dialogs/dialog-settings.md). |
| JVM on macOS | To make dialogs follow the system light or dark theme, set `apple.awt.application.appearance` before creating any window (snippet below). |

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

    application {
        Window(onCloseRequest = ::exitApplication) { App() }
    }
}
```

## ProGuard

If you shrink or obfuscate your JVM app, add the JNA and D-Bus keep rules from [Core setup](https://filekit.mintlify.site/core/setup.md#proguard).

## Related

* [File picker](https://filekit.mintlify.site/dialogs/file-picker.md) to open your first dialog.
* [Results and errors](https://filekit.mintlify.site/dialogs/error-handling.md) for cancellation and failure handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.