File picker dialog

Open a file picker dialog in a Kotlin Multiplatform project

Supported on Android, iOS, macOS, JVM, JS and WASM targets

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.

filekit-dialogs

val file = FileKit.openFilePicker()

On iOS with Compose Multiplatform 1.10+, launching a picker while a Compose modal surface such as ModalBottomSheet, dialog, or dropdown is closing can cause the native picker to open and immediately disappear. Dismiss the Compose surface first, then launch FileKit after the modal state is closed.

Show workaround template

This workaround is related to GitHub issue #547.

filekit-dialogs-compose

var showSheet by remember { mutableStateOf(false) }
var launchPickerAfterSheetDismiss by remember { mutableStateOf(false) }

val sheetState = rememberModalBottomSheetState()
val coroutineScope = rememberCoroutineScope()
val launcher = rememberFilePickerLauncher { file ->
    // Handle the file
}

LaunchedEffect(showSheet, launchPickerAfterSheetDismiss) {
    if (!showSheet && launchPickerAfterSheetDismiss) {
        launchPickerAfterSheetDismiss = false
        launcher.launch()
    }
}

if (showSheet) {
    ModalBottomSheet(
        sheetState = sheetState,
        onDismissRequest = { showSheet = false },
    ) {
        Button(
            onClick = {
                launchPickerAfterSheetDismiss = true
                coroutineScope.launch {
                    sheetState.hide()
                    showSheet = false
                }
            },
        ) {
            Text("Pick a file")
        }
    }
}

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.

filekit-dialogs

// 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))

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.

filekit-dialogs

// 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")
    }
}

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.

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.

filekit-dialogs

val file = FileKit.openFilePicker(type = FileKitType.File(listOf("pdf", "docx")))

On Android and iOS, using Image, Video or ImageAndVideo FileKitType will open a gallery picker. Read more here.

Customizing the dialog

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

filekit-dialogs

val file = FileKit.openFilePicker(
    directory = PlatformFile("/custom/initial/path"),
    dialogSettings = FileKitDialogSettings.createDefault(),
)

Read more about dialog settings to customize the dialog for each platform.

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:

System.setProperty("apple.awt.application.appearance", "system")

This is typically done in your main function, before the application window is created.