ImagePickerKMP

Cross-platform Image Picker & Camera Library for Kotlin Multiplatform

Easily capture or select images on Android, iOS, Desktop, and Web — all with a single API.
Built with Compose Multiplatform, designed for simplicity, performance, and flexibility.

ImagePickerKMP saves you 2 weeks of native Android/iOS/Web integration work.
It's free and open source. If your app or company benefits from it, consider sponsoring to keep it maintained and updated with every new KMP/Compose release.
→ Become a sponsor

Example

Complete Example App

ImagePickerKMP-Example →

Full-featured sample application showcasing:

All library features and configurations

Quick Start

⚠️ Requirements

Requirement	Minimum version
Kotlin	2.3.20 (breaking change — see CHANGELOG)
Compose Multiplatform	1.10.3
Ktor	3.4.1
Android `minSdk`	24
Android `compileSdk`	36

Note: This library is compiled with Kotlin 2.3.20. Projects using Kotlin < 2.3.x will get an ABI incompatibility error at compile time. If you need Kotlin 2.1.x support, use a previous version of this library.

Installation

Kotlin Multiplatform:

dependencies {
    implementation("io.github.ismoy:imagepickerkmp:1.0.35-alpha1")
}

React/JavaScript:

npm install imagepickerkmp

New — `rememberImagePickerKMP` (recommended)

The modern, idiomatic Compose API. A single state holder — no manual booleans, no Render() call needed.

@Composable
fun basicUsageScreen() {
    val picker = rememberImagePickerKMP(
        config = ImagePickerKMPConfig(
            galleryConfig = GalleryConfig(
                allowMultiple = true,
                selectionLimit = 20
            )
        )
    )
    val result = picker.result

    Scaffold(
        modifier = Modifier
            .fillMaxSize(),
        topBar = {
            TopAppBar(
                title = { Text("Basic Usage") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Go back"
                        )
                    }
                }
            )
        },
        bottomBar = {
            BottomAppBar {
                Row(
                    modifier = Modifier
                        .fillMaxWidth()
                        .padding(horizontal = 16.dp),
                    horizontalArrangement = Arrangement.spacedBy(8.dp)
                ) {
                    Button(
                        onClick = { picker.launchCamera() },
                        modifier = Modifier.weight(1f)
                    ) {
                        Text("Camera")
                    }
                    Button(
                        onClick = { picker.launchGallery() },
                        modifier = Modifier.weight(1f)
                    ) {
                        Text("Gallery")
                    }
                }
            }
        }
    ){scaffoldPadding->
        Column(
            modifier = Modifier
                .padding(scaffoldPadding)
                .fillMaxSize()
        ) {
            Box(
                modifier = Modifier
                    .fillMaxWidth()
                    .weight(1f),
                contentAlignment = Alignment.Center
            ) {
                when (result) {

                    is ImagePickerResult.Loading -> {
                        Column(
                            horizontalAlignment = Alignment.CenterHorizontally,
                            modifier = Modifier.padding(16.dp)
                        ) {
                            CircularProgressIndicator()
                            Text(
                                text = "Loading...",
                                color = Color.Gray,
                                modifier = Modifier.padding(top = 12.dp)
                            )
                        }
                    }

                    is ImagePickerResult.Success -> {
                        // Result here
                    }

                    is ImagePickerResult.Error -> {
                        Text(
                            text = "Error: ${result.exception.message}",
                            color = Color.Red,
                            modifier = Modifier.padding(16.dp)
                        )
                    }

                    is ImagePickerResult.Dismissed -> {
                        Text("Selection cancelled", color = Color.Gray)
                    }

                    is ImagePickerResult.Idle -> {
                        Text("Press a button to get started", color = Color.Gray)
                    }
                }
            }
        }
    }
}

Per-launch overrides:

// Override gallery options for a single launch
picker.launchGallery(
    allowMultiple = true,
    selectionLimit = 5,
    mimeTypes = listOf(MimeType.IMAGE_JPEG),
    includeExif = true
)

// Override camera options for a single launch
picker.launchCamera(
    cameraCaptureConfig = CameraCaptureConfig(compressionLevel = CompressionLevel.HIGH),
    enableCrop = false
)

New API vs Legacy API — Migration Guide

TL;DR: Use rememberImagePickerKMP for all new code. The legacy ImagePickerLauncher / GalleryPickerLauncher are deprecated and will be removed in a future major release.

Side-by-side comparison

	Legacy API (v1) — Deprecated	New API (v2) — Recommended
Camera	`ImagePickerLauncher(config = ...)`	`picker.launchCamera()`
Gallery	`GalleryPickerLauncher(...)`	`picker.launchGallery()`
Result handling	Callbacks (`onPhotoCaptured`, `onDismiss`, `onError`)	Reactive `when (picker.result)`
State management	Manual `showCamera`, `showGallery` booleans	Automatic via `ImagePickerKMPState`
Per-launch config	Not supported	Override any param on each `launch*()` call
Reset	Call `onDismiss` callback	`picker.reset()`
Configuration	`ImagePickerConfig` + `GalleryPickerConfig`	`ImagePickerKMPConfig` (unified)

Migration table

Legacy pattern	New API equivalent
`showCamera = true`	`picker.launchCamera()`
`showGallery = true`	`picker.launchGallery()`
`onPhotoCaptured = { result -> ... }`	`is ImagePickerResult.Success -> result.photos`
`onDismiss = { showCamera = false }`	`is ImagePickerResult.Dismissed -> ...`
`onError = { e -> ... }`	`is ImagePickerResult.Error -> result.exception`
`ImagePickerConfig(cameraCaptureConfig = ...)`	`ImagePickerKMPConfig(cameraCaptureConfig = ...)`
`GalleryPickerConfig(includeExif = true)`	`ImagePickerKMPConfig(galleryConfig = GalleryConfig(includeExif = true))`
`allowMultiple = true` in `GalleryPickerLauncher`	`picker.launchGallery(allowMultiple = true)`

Legacy API (still functional, migration recommended)

The legacy API still works and will not break existing apps. You will see a compiler warning recommending migration to rememberImagePickerKMP.

Camera Capture (legacy):

var showCamera by remember { mutableStateOf(false) }
var capturedPhoto by remember { mutableStateOf<PhotoResult?>(null) }

if (showCamera) {
    ImagePickerLauncher(  // Deprecated — migrate to rememberImagePickerKMP
        config = ImagePickerConfig(
            onPhotoCaptured = { result ->
                capturedPhoto = result
                showCamera = false
            },
            onError = { showCamera = false },
            onDismiss = { showCamera = false }
        )
    )
}

Button(onClick = { showCamera = true }) {
    Text("Take Photo")
}

Gallery Selection (legacy):

var showGallery by remember { mutableStateOf(false) }
var selectedImages by remember { mutableStateOf<List<PhotoResult>>(emptyList()) }

if (showGallery) {
    GalleryPickerLauncher(  // Deprecated — migrate to rememberImagePickerKMP
        config = GalleryPickerConfig(includeExif = true),
        onPhotosSelected = { photos ->
            selectedImages = photos
            showGallery = false
        },
        onError = { showGallery = false },
        onDismiss = { showGallery = false },
        allowMultiple = true
    )
}

Button(onClick = { showGallery = true }) {
    Text("Choose from Gallery")
}

⚠️ Important Usage Note

Camera Preview Not Showing? Some developers have reported that the camera usage indicator appears, but the preview doesn't show up. This happens when ImagePickerLauncher is not placed inside a visible container composable.

✅ Correct usage:

Box(modifier = Modifier.fillMaxSize()) {
    if (showCamera) {
        ImagePickerLauncher(
            config = ImagePickerConfig(
                onPhotoCaptured = { /* handle image */ },
                onDismiss = { showCamera = false }
            )
        )
    }
}

❌ Incorrect usage:

if (showCamera) {
    ImagePickerLauncher(
        config = ImagePickerConfig(
            onPhotoCaptured = { /* handle image */ },
            onDismiss = { showCamera = false }
        )
    )
}

💡 Always wrap the camera launcher inside a composable container (Box, Column, Row) and control its visibility with state.

Thanks to @rnstewart and other contributors for pointing this out! 🙏

Key Features

rememberImagePickerKMP — New idiomatic API: single state holder, launchCamera() / launchGallery() with per-launch overrides, reactive result via ImagePickerResult (Idle → Loading → Success/Dismissed/Error). No Render(), no manual booleans.
Cross-platform — Android, iOS, Desktop, Web
Camera & Gallery — Direct access with unified API
Image Cropping — Built-in crop functionality
Smart Compression — Configurable quality levels
EXIF Metadata — GPS, camera info, timestamps (Android/iOS)
PDF Support — Select PDF documents alongside images
Extension Functions — Easy image processing (loadPainter(), loadBytes(), loadBase64())
Permission Handling — Automatic permission management
Async Processing — Non-blocking UI with coroutines
Format Support — JPEG, PNG, HEIC, HEIF, WebP, GIF, BMP, PDF

Platform Support

Platform	Minimum Version	Camera	Gallery	Crop	EXIF	Status
Android	API 21+	✅	✅	✅	✅	✅
iOS	iOS 12.0+	✅	✅	✅	✅	✅
Desktop	JDK 11+	❌	✅	✅	❌	✅
JS/Web	Modern Browsers	❌	✅	✅	❌	✅
Wasm/Web	Modern Browsers	✅

Live Demos

Online Demos

View Interactive Demos →

Experience ImagePickerKMP in action:

Mobile Demos - Android & iOS camera/gallery functionality
Desktop Demo - File picker and image processing
Web Demo - React integration with WebRTC camera
Crop Demo - Interactive image cropping across platforms

Documentation

Complete Guides

Resource	Description
Integration Guide	Complete setup and configuration
Customization Guide	UI customization and theming
React Guide	Web development setup
Permissions Guide	Platform permissions
API Reference	Complete API documentation

Advanced Configuration

Image Compression

ImagePickerLauncher(
    config = ImagePickerConfig(
        cameraCaptureConfig = CameraCaptureConfig(
            compressionLevel = CompressionLevel.HIGH, // LOW, MEDIUM, HIGH
            skipConfirmation = true
        )
    )
)

EXIF Metadata Extraction

ImagePickerLauncher(
    config = ImagePickerConfig(
        onPhotoCaptured = { result ->
            result.exif?.let { exif ->
                println(" Location: ${exif.latitude}, ${exif.longitude}")
                println(" Camera: ${exif.cameraModel}")
                println(" Taken: ${exif.dateTaken}")
            }
        },
        cameraCaptureConfig = CameraCaptureConfig(
            includeExif = true  // Android/iOS only
        )
    )
)

EXIF Metadata Extraction

GalleryPickerLauncher(
    allowMultiple = true,
    mimeTypes = listOf(MimeType.IMAGE_JPEG, MimeType.IMAGE_PNG),
    includeExif = true  // Android/iOS only
)

Multiple Selection with Filtering

// Images only
GalleryPickerLauncher(
    allowMultiple = true,
    mimeTypes = listOf(MimeType.IMAGE_JPEG, MimeType.IMAGE_PNG),
    enableCrop = true
)

// Images and PDFs
GalleryPickerLauncher(
    allowMultiple = true,
    mimeTypes = listOf(
        MimeType.IMAGE_JPEG,
        MimeType.IMAGE_PNG,
        MimeType.APPLICATION_PDF  // PDF support
    )
)

iOS Permissions Setup

Add to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access needed to take photos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access needed to select images</string>

Extension Functions

Process images easily with built-in extension functions:

ImagePickerLauncher(
    config = ImagePickerConfig(
        onPhotoCaptured = { result ->
            val imageBytes = result.loadBytes()        // ByteArray for file operations
            val imagePainter = result.loadPainter()    // Painter for Compose UI
            val imageBitmap = result.loadImageBitmap() // ImageBitmap for graphics
            val imageBase64 = result.loadBase64()      // Base64 string for APIs
        }
    )
)

React/Web Integration

ImagePickerKMP is available as an NPM package for web development:

npm install imagepickerkmp

Features:

WebRTC Camera Access - Mobile & desktop camera support
TypeScript Support - Full type definitions included
Drag & Drop - File picker with drag and drop
React Components - Ready-to-use React components
Cross-Framework - Works with React, Vue, Angular, Vanilla JS

Smart Gallery vs File Explorer Detection

Images: Opens native Android gallery for photos
PDFs: Opens file explorer for document access
Mixed Types: Automatically chooses best picker for content type
Automatic Detection: No configuration needed - works out of the box!

Complete React Integration Guide →

⚠️ Known Issues & Troubleshooting

iOS build fails with `_OBJC_CLASS_$_CLLocation` linker error

If your iOS build fails with:

ld: Undefined symbols: _OBJC_CLASS_$_CLLocation
linker command failed with exit code 1

Android and JVM Desktop work fine, but iOS fails during the linking phase.

Fix: Add CoreLocation.framework manually in Xcode:

Select your app target → Build Phases → Link Binary With Libraries
Click +, search for CoreLocation, and click Add
Clean (⇧⌘K) and rebuild

No code changes needed. See FAQ and Integration Guide for full details.

Support & Contributing

Sponsors & Backers

ImagePickerKMP is free and open source. Maintaining it across Android, iOS, Desktop, Web and WASM with every Kotlin/Compose Multiplatform release takes real time and effort.

If this library saves you time or money in production, please consider supporting it:

Tier	Amount	Benefit
☕ Coffee	$5/mo	Name in the backers list
🥈 Silver	$25/mo	Logo in README + priority issue response

Current Sponsors

_{james-codersHT}

Sponsors get their name/logo displayed here. → Become a sponsor

Contributors

Thanks to these wonderful people (emoji key):

_ismoy
💻 📖 🚧 🎨 🤔

_medAndro
💻 🐛

_{daniil-pastuhov}
💻

_YaminMahdi
💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Made with ❤️ for the Kotlin Multiplatform community
Star this repo if it helped you!

Name		Name	Last commit message	Last commit date
Latest commit History 270 Commits
.github		.github
docs		docs
gradle		gradle
kotlin		kotlin
library		library
.all-contributorsrc		.all-contributorsrc
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
Podfile		Podfile
REACT_INTEGRATION_GUIDE.md		REACT_INTEGRATION_GUIDE.md
README.es.md		README.es.md
README.md		README.md
build-and-bundle.sh		build-and-bundle.sh
build.gradle.kts		build.gradle.kts
codecov.yml		codecov.yml
create-bundle.js		create-bundle.js
demo_video_library.gif		demo_video_library.gif
detekt.yml		detekt.yml
gradle.properties		gradle.properties
gradlew		gradlew
library.podspec		library.podspec
settings.gradle.kts		settings.gradle.kts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ImagePickerKMP

Example

Complete Example App

Quick Start

⚠️ Requirements

Installation

New — rememberImagePickerKMP (recommended)

New API vs Legacy API — Migration Guide

Side-by-side comparison

Migration table

Legacy API (still functional, migration recommended)

⚠️ Important Usage Note

Key Features

Platform Support

Live Demos

Online Demos

Documentation

Complete Guides

Advanced Configuration

Image Compression

EXIF Metadata Extraction

EXIF Metadata Extraction

Multiple Selection with Filtering

iOS Permissions Setup

Extension Functions

React/Web Integration

Smart Gallery vs File Explorer Detection

⚠️ Known Issues & Troubleshooting

iOS build fails with _OBJC_CLASS_$_CLLocation linker error

Support & Contributing

Sponsors & Backers

Current Sponsors

Contributors

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 25

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

New — `rememberImagePickerKMP` (recommended)

iOS build fails with `_OBJC_CLASS_$_CLLocation` linker error

Packages