Quickstart

Pick, read, and save your first file with FileKit in a few minutes

This guide opens a native file picker, reads the selected file, and saves a new file to a location the user chooses.

Want to see FileKit before installing it? Try it in your browser: the FileKit sample app runs live, with no install.

1. Add the dependency

   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:

   build.gradle.kts

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

   Both artifacts include filekit-core. For Compose apps, add filekit-dialogs-compose. To call the dialogs from ViewModels or non-Compose code, filekit-dialogs is enough. See Installation for every module.

2. Initialize FileKit where needed

   Most targets work without setup. Android (without Compose), desktop JVM, and Linux or Windows native need one line at startup.

   Android

   If you only use Compose launchers (remember…Launcher), nothing to do.

   If you call the suspend dialog APIs (FileKit.openFilePicker()…), register your activity so FileKit can launch dialogs:

   MainActivity.kt

   class MainActivity : ComponentActivity() {
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           FileKit.init(this)
       }
   }
   

   JVM desktop

   Give FileKit your application ID before showing UI. It is used for the app’s files and cache directories.

   main.kt

   fun main() {
       FileKit.init(appId = "com.example.myapp")
   
       application {
           Window(onCloseRequest = ::exitApplication) { App() }
       }
   }
   

   On Linux, packaged apps also need the jdk.security.auth module. See Dialogs setup.

   Linux & Windows native

   main.kt

   fun main() {
       FileKit.init(appId = "com.example.myapp")
   }
   

   On Linux, dialogs use the XDG Desktop Portal and link against libdbus-1. See Dialogs setup.

   iOS, macOS, JS, Wasm

   Nothing to do. FileKit works out of the box.

3. Pick a file

   Compose

   val launcher = rememberFilePickerLauncher(
       onError = { failure -> println("Picker failed: ${failure.message}") },
   ) { file ->
       // file is a PlatformFile, or null when the user cancelled
       println("Picked ${file?.name}")
   }
   
   Button(onClick = { launcher.launch() }) {
       Text("Pick a file")
   }
   

   Restrict the selection with type = FileKitType.Image, FileKitType.Video, or FileKitType.File(extensions = listOf("pdf")). Pick several files with mode = FileKitMode.Multiple(). See File picker for all options.

4. Read it

   PlatformFile exposes the same read API on every platform. Read the file once the picker returns it: inside onResult (with scope.launch) in Compose, or after openFilePicker() returns a non-null file:

   suspend fun readPicked(file: PlatformFile) {
       val name: String = file.name
       val size: Long = file.size()
   
       val text: String = file.readString()
       val bytes: ByteArray = file.readBytes()
   }
   

   For an image in Compose, call file.toImageBitmap() or use Coil.

5. Save a file

   Ask the user where to save, then write to the returned file:

   Compose

   val scope = rememberCoroutineScope()
   val saver = rememberFileSaverLauncher(
       dialogSettings = FileKitDialogSettings.createDefault(),
       onError = { failure -> println("Saver failed: ${failure.message}") },
   ) { file ->
       scope.launch { file?.writeString("Hello FileKit!") }
   }
   
   Button(onClick = { saver.launch(suggestedName = "hello", defaultExtension = "txt") }) {
       Text("Save")
   }
   

   The file saver is available on Android, iOS, macOS, JVM, and Linux and Windows native, so call it from a non-web source set. Browsers don’t let you choose a save location, so on JS and Wasm use FileKit.download(bytes, fileName) instead. See Files on the web.

That’s a complete round trip. FileKit uses each platform’s native dialog, so the picker looks and behaves the way your users expect.

Where to go next

File operations

List, walk, copy, move, and delete files and folders.

Reading and writing

Text, bytes, and streaming with kotlinx-io for large files.

Gallery and camera

Native photo pickers on Android and iOS, plus camera capture.

Directories

Let users pick a folder and keep access with bookmarks.

Image utilities

Compress and resize images, and save them to the gallery.

Platform support

Check which features each platform supports.