kontacts

Fetches user contacts from Android and iOS with a compose-friendly API, offering names, initials, phone numbers, and avatars with minimal setup and integration.

#compose-multiplatform

Suggest an edit

Android JVMKotlin/Native

GitHub stars11

Authorsdev-bilal-azzam

Open issues1

LicenseApache License 2.0

Creation date6 months ago

Last activityabout 2 months ago

Latest release1.2.1 (about 2 months ago)

GitHub repository

Kontacts (Kotlin Multiplatform)

A Kotlin Multiplatform library to fetch user contacts from Android and iOS with a Compose-friendly API. Provides names, initials, phone numbers, and avatars, with minimal setup.

Features

Fetch contacts on Android (requires context) and iOS (no context required).
Provides Contact data class with:
- displayName
- initials
- phoneNumbers
- avatar (URI or ImageBitmap)
Compose-ready: use rememberContactsProvider() directly in your composable screen.
Works seamlessly in Kotlin Multiplatform projects.
Minimal setup : — no need to configure entry points manually. — ready to be injected via Dependency Injection Framework Koin.

Installation

Gradle

dependencies {
    implementation("io.github.dev-bilal-azzam:kontacts:$latest_version")
}

✨ What’s New in

1. Customizable Fields

Introduced custom field selection when fetching contacts.
Users can now specify exactly which fields they need:
- Phone numbers
- Names (first - last)
- Avatar
This avoids unnecessary queries and improves performance when only a subset of data is required.

contactsProvider.getAllContacts(
    fields = setOf(ContactField.ID, ContactField.FIRST_NAME)
)

2. 🚀 50× Performance Boost

Optimized how phone numbers are fetched
Results:
- Before: ~10 seconds for large contact lists with phone numbers.
- After: ~200 ms (same speed as fetching names only).

📊 Benefits

Faster: Large contact lists now load up to 50× faster when phone numbers are included.
Flexible: Apps can now fetch only the fields they actually need.

Usage

Compose-friendly API

@Composable
fun ContactsScreen() {
    val contactsProvider = rememberContactsProvider()
    var contacts by remember { mutableStateOf<List<Contact>>(emptyList()) }

    LaunchedEffect(Unit) {
        // Ensure permission is granted
        contacts = contactsProvider.getAllContacts(
            fields = setOf(
                ContactField.ID,
                ContactField.FIRST_NAME,
                ContactField.PHONE_NUMBERS
            )
        )
    }

    LazyColumn {
        items(contacts) { contact ->
            Text(text = contact.displayName)
        }
    }
}

Usage with Koin

// Common
import com.bilalazzam.contacts_provider.ContactsProvider
import org.koin.core.scope.Scope

// create an expect function to create ContactsProvider
expect fun Scope.createContactsProvider(): ContactsProvider

then create the actual implementation for each platform

// Android
import com.bilalazzam.contacts_provider.ContactsProviderFactory

actual fun Scope.createContactsProvider(): ContactsProvider {
    return ContactsProviderFactory(this.get()).createContactsProvider()
}


// Ios
actual fun Scope.createContactsProvider(): ContactsProvider {
    return ContactsProviderFactory().createContactsProvider()
}

then in koin module

import org.koin.dsl.module

val dataProviderModule = module {
    single { createContactsProvider() }
}

the just inject it to your Repository or Datasource

class ContactsRepositoryImpl(
    private val contactsProvider: ContactsProvider
) : ContactsRepository {
    private suspend fun getDeviceContacts(): List<DeviceContact> {
        return contactsProvider.getAllContacts(
            fields = setOf(ID, FIRST_NAME, LAST_NAME, PHONE_NUMBERS)
        )
    }
}

Needed Permissions

Android

<uses-permission android:name="android.permission.READ_CONTACTS" />

IOS

<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to display them in the app.</string>

License

This project is licensed under the MIT License.

See the LICENSE file for details.

💻 Contributors