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