File saver dialog

Open a file saver dialog in a Kotlin Multiplatform project

Supported on Android, iOS, macOS and JVM targets

Quick start

The file saver component provides a native interface for users to choose where to save a file on their device.

The file saver dialog returns a PlatformFile object representing where the user wants to save the file. Note that the file is not created automatically - it’s the developer’s responsibility to write the actual data to the file location using methods like write().

Here’s a basic example:

filekit-dialogs

// Open file saver dialog
val file = FileKit.openFileSaver(
    suggestedName = "document",
    defaultExtension = "pdf",
)

// Write your data to the file
if (file != null) {
    file.write(bytes)
}

onError receives a FileKitDialogException only when FileKit cannot complete a valid file-saving operation. User cancellation is not a failure: it invokes onResult(null). Coroutine cancellation, invalid arguments or unsupported argument combinations, 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 for the complete callback and propagation matrix.

Parameters

The file saver can be customized with several parameters:

• suggestedName: The default name for the file without extension
• defaultExtension: The default file extension without the dot (e.g., “pdf”, “txt”)
• allowedExtensions: The allowed save extensions without dots (e.g., setOf("txt", "md")). This is a native dialog hint, not a validation guarantee.
• directory: The starting directory for the save dialog
• dialogSettings: Platform-specific settings for customizing the dialog behavior

filekit-dialogs

val file = FileKit.openFileSaver(
    suggestedName = "my-document",
    defaultExtension = "pdf",
    allowedExtensions = setOf("pdf", "txt"),
    directory = PlatformFile("/custom/initial/path"),
    dialogSettings = FileKitDialogSettings.createDefault()
)

Use defaultExtension for the default file name and default extension. Use allowedExtensions when the native save dialog should offer specific save types. Filtering is applied where the platform supports it; apps that require a specific output format should still validate the returned file extension.

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

Writing data

The file saver returns a PlatformFile object representing the selected save location. You can write data to this file using the write() extension function:

val file = FileKit.openFileSaver(suggestedName = "document", defaultExtension = "pdf")

if (file != null) {
    // Write bytes to the file
    file.write(bytes)
}

For more information about writing files, see the write file guide.

Download file on the web

On web targets (JS and WASM), instead of using a file saver dialog, you can directly download a file using FileKit.download():

// Download bytes
FileKit.download(
    bytes = "Hello, World!".encodeToByteArray(),
    fileName = "hello.txt"
)

// Download from a PlatformFile
val file: PlatformFile = ...
FileKit.download(file, fileName = "document.pdf")

This will trigger the browser’s native download behavior, saving the file to the user’s default downloads directory.

On web targets, the file saver dialog is not supported due to browser security restrictions. Instead, use FileKit.download() to download files directly.

For more information about writing files on different platforms, see the write file guide.