--- title: Capacitor Contacts Plugin for Android, iOS & Web description: Capacitor plugin to read, write, or select device contacts with advanced features like filtering and pagination. tags: - Insiders - Android - iOS - Web search: boost: 2 faq: true github_repo: capawesome-team/capacitor-plugins --- # Capacitor Contacts Plugin Capacitor plugin to read, write, or select device contacts. Supports Android, iOS and Web with advanced features like contact groups, pagination, and native modals.
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features The Capacitor Contacts plugin is one of the most complete contact management solutions for Capacitor apps. Here are some of the key features: - 🖥️ **Cross-platform**: Supports Android, iOS and Web. - 📇 **Contacts**: Create, update, delete and retrieve device contacts. - 🔄 **Partial Updates**: Update only specific contact fields without affecting others - missing properties are preserved, null values delete fields. - 📌 **Groups**: Create, update, delete and retrieve contact groups on iOS. - 🎫 **Accounts**: Add contacts to specific accounts on Android. - 📖 **Pagination**: Paginate through contacts to avoid performance issues. - 🔍 **Filtering**: Filter contacts by ID, email, phone number, etc. (Coming soon!) - 📱 **Native Modals**: Create, update and display contacts in native modals. - 🎯 **Picking**: Let the user select a device contact. - 🖼️ **Photos**: Set, update and retrieve contact photos. - 🤝 **Compatibility**: Works alongside the [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/), [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins. - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. - 🔁 **Up-to-date**: Always supports the latest Capacitor version. - ⭐️ **Support**: Priority support from the Capawesome Team. - ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The Contacts plugin is typically used whenever an app needs to work with the device's address book, for example: - **Contact selection**: Let users pick one or more contacts from the device, for example to invite friends or share content. - **CRM and business apps**: Create, update, and delete contacts directly from your app, including photos, email addresses, phone numbers, and postal addresses. - **Contact syncing**: Read device contacts with pagination and keep them in sync with your backend. - **Contact organization**: Manage contact groups on iOS or add contacts to specific accounts on Android. - **Native contact forms**: Display, create, and update contacts in native modals without building your own UI. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | ## Guides - [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/) - [Announcing the Capacitor Contacts Plugin](https://capawesome.io/blog/announcing-the-capacitor-contacts-plugin/) - [Exploring the Capacitor Contacts API](https://capawesome.io/blog/exploring-the-capacitor-contacts-api/) - [Google Play Contacts Policy 2027 for Capacitor](https://capawesome.io/blog/capacitor-google-play-contacts-policy-2027/) ## Installation This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: ``` npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken ``` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-contacts` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome-team/capacitor-contacts npx cap sync ``` ### Android #### Permissions This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag: ```xml ``` `pickContacts(...)` requires the `READ_CONTACTS` permission below Android 17, because the contact picker grants access to the picked contact URI only, which does not expose any contact details. Pass the `property` option instead to let the user select a single phone number, email address or postal address, which never requires a permission. Apps that only need contact selection should use that option and omit `READ_CONTACTS`, as required by [Google Play's Contacts Permissions policy](https://support.google.com/googleplay/android-developer/answer/16926792). #### Proguard If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: ``` -keep class io.capawesome.capacitorjs.plugins.** { *; } ``` ### iOS #### Privacy Descriptions Add the `NSContactsUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts: ```xml NSContactsUsageDescription We need access to your contacts to display them in the app. ``` #### Entitlements To access the `note` field of a contact, your app must have the `com.apple.developer.contacts.notes` entitlement. Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.contacts.notes) for more information. If you don't need access to the `note` field, you can skip this step. ## Configuration No configuration required for this plugin. ## Usage The following examples show how to create, update, delete, pick, retrieve, and display contacts, manage contact groups and accounts, and check availability and permissions. ### Create a contact Create a new contact on the device with properties such as name, birthday, email addresses, phone numbers, and postal addresses. Only available on Android and iOS: ```typescript import { Contacts, EmailAddressType, PhoneNumberType, PostalAddressType } from '@capawesome-team/capacitor-contacts'; const createContact = async () => { return Contacts.createContact({ contact: { birthday: { day: 1, month: 1, year: 1990 }, givenName: 'John', familyName: 'Doe', emailAddresses: [ { value: 'mail@example.com', type: EmailAddressType.Home, isPrimary: true } ], phoneNumbers: [ { value: '1234567890', type: PhoneNumberType.Mobile, isPrimary: true } ], postalAddresses: [ { street: '123 Main St', city: 'Springfield', state: 'IL', postalCode: '62701', country: 'USA', type: PostalAddressType.Home, isPrimary: true } ] } }); }; ``` ### Update or delete a contact Update only specific fields of an existing contact without affecting others: missing properties are preserved, `null` values delete a field. You can also delete a contact by its ID. Only available on Android and iOS: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const updateContactById = async (id: string) => { await Contacts.updateContactById({ id, contact: { givenName: 'John', familyName: 'Doe', birthday: null, // This will remove the birthday field from the contact note: undefined // This will preserve the existing note field } }); }; const deleteContactById = async (id: string) => { await Contacts.deleteContactById({ id }); }; ``` ### Pick contacts Open the native contact picker and let the user select one or more contacts. Use the `fields` option to specify which contact properties should be returned: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const pickContacts = async () => { const { contacts } = await Contacts.pickContacts({ fields: [ 'id', 'givenName', 'familyName', 'emailAddresses', 'phoneNumbers', 'postalAddresses' ], multiple: true }); return contacts; }; ``` ### Retrieve contacts Fetch a single contact by its ID or retrieve a list of contacts. Use the `limit` and `offset` options to paginate through large address books and `countContacts()` to get the total number of contacts. Only available on Android and iOS: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const getContactById = async (id: string) => { const { contact } = await Contacts.getContactById({ id }); return contact; }; const getContacts = async () => { const { contacts } = await Contacts.getContacts({ fields: [ 'id', 'givenName', 'familyName', 'emailAddresses', 'phoneNumbers', 'postalAddresses' ], limit: 10, offset: 0 }); return contacts; }; const countContacts = async () => { const { total } = await Contacts.countContacts(); return total; }; ``` ### Display contacts in native modals Show or edit a contact in the native contact modal instead of building your own UI. Only available on Android and iOS: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const displayContactById = async (id: string) => { await Contacts.displayContactById({ id }); }; const displayUpdateContactById = async (id: string) => { await Contacts.displayUpdateContactById({ id }); }; ``` ### Manage contact groups Create, retrieve, and delete contact groups. Only available on iOS: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const createGroup = async () => { return Contacts.createGroup({ group: { name: 'My Group' } }); }; const deleteGroupById = async (id: string) => { await Contacts.deleteGroupById({ id }); }; const getGroupById = async (id: string) => { const { group } = await Contacts.getGroupById({ id }); return group; }; const getGroups = async () => { const { groups } = await Contacts.getGroups(); return groups; }; ``` ### Retrieve accounts Retrieve the accounts that contacts can be added to. Only available on Android: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const getAccounts = async () => { const { accounts } = await Contacts.getAccounts(); return accounts; }; ``` ### Check availability Check whether the contacts API is supported and available on the current device before using it: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const isAvailable = async () => { const { isAvailable } = await Contacts.isAvailable(); return isAvailable; }; const isSupported = async () => { const { isSupported } = await Contacts.isSupported(); return isSupported; }; ``` ### Check and request permissions Check and request permissions to access the device contacts. Only available on Android and iOS: ```typescript import { Contacts } from '@capawesome-team/capacitor-contacts'; const checkPermissions = async () => { return Contacts.checkPermissions(); }; const requestPermissions = async () => { return Contacts.requestPermissions(); }; ``` ## API * [`countContacts()`](#countcontacts) * [`createContact(...)`](#createcontact) * [`createGroup(...)`](#creategroup) * [`deleteContactById(...)`](#deletecontactbyid) * [`deleteGroupById(...)`](#deletegroupbyid) * [`displayContactById(...)`](#displaycontactbyid) * [`displayCreateContact(...)`](#displaycreatecontact) * [`displayUpdateContactById(...)`](#displayupdatecontactbyid) * [`getAccounts()`](#getaccounts) * [`getContactById(...)`](#getcontactbyid) * [`getContacts(...)`](#getcontacts) * [`getGroupById(...)`](#getgroupbyid) * [`getGroups()`](#getgroups) * [`isAvailable()`](#isavailable) * [`isSupported()`](#issupported) * [`openSettings()`](#opensettings) * [`pickContact(...)`](#pickcontact) * [`pickContacts(...)`](#pickcontacts) * [`updateContactById(...)`](#updatecontactbyid) * [`checkPermissions()`](#checkpermissions) * [`requestPermissions(...)`](#requestpermissions) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### countContacts() ```typescript countContacts() => Promise ``` Count the number of contacts on the device. Only available on Android and iOS. **Returns:** Promise<CountContactsResult> **Since:** 7.4.0 -------------------- ### createContact(...) ```typescript createContact(options: CreateContactOptions) => Promise ``` Create a new contact on the device. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------------- | | **`options`** | CreateContactOptions | **Returns:** Promise<CreateContactResult> **Since:** 7.0.0 -------------------- ### createGroup(...) ```typescript createGroup(options: CreateGroupOptions) => Promise ``` Create a new contact group on the device. Only available on iOS. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | CreateGroupOptions | **Returns:** Promise<CreateGroupResult> **Since:** 7.4.0 -------------------- ### deleteContactById(...) ```typescript deleteContactById(options: DeleteContactByIdOptions) => Promise ``` Delete a contact from the device. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------------- | | **`options`** | DeleteContactByIdOptions | **Since:** 7.0.0 -------------------- ### deleteGroupById(...) ```typescript deleteGroupById(options: DeleteGroupByIdOptions) => Promise ``` Delete a contact group from the device. Only available on iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------- | | **`options`** | DeleteGroupByIdOptions | **Since:** 7.4.0 -------------------- ### displayContactById(...) ```typescript displayContactById(options: DisplayContactByIdOptions) => Promise ``` Display an existing contact by identifier. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | DisplayContactByIdOptions | **Since:** 7.4.0 -------------------- ### displayCreateContact(...) ```typescript displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise ``` Open a native modal to create a new device contact. This allows the user to update the contact information before saving it and does not require any permissions. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | **`options`** | DisplayCreateContactOptions | **Returns:** Promise<DisplayCreateContactResult> **Since:** 7.2.0 -------------------- ### displayUpdateContactById(...) ```typescript displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise ``` Open a native modal to update a contact. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------------------------- | | **`options`** | DisplayUpdateContactByIdOptions | **Since:** 7.4.0 -------------------- ### getAccounts() ```typescript getAccounts() => Promise ``` List all accounts on the device. Only available on Android. **Returns:** Promise<GetAccountsResult> **Since:** 7.4.0 -------------------- ### getContactById(...) ```typescript getContactById(options: GetContactByIdOptions) => Promise ``` Find a contact by identifier. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | GetContactByIdOptions | **Returns:** Promise<GetContactByIdResult> **Since:** 7.0.0 -------------------- ### getContacts(...) ```typescript getContacts(options?: GetContactsOptions | undefined) => Promise ``` List all contacts on the device. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | GetContactsOptions | **Returns:** Promise<GetContactsResult> **Since:** 7.0.0 -------------------- ### getGroupById(...) ```typescript getGroupById(options: GetGroupByIdOptions) => Promise ``` Find a contact group by identifier. Only available on iOS. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | GetGroupByIdOptions | **Returns:** Promise<GetGroupByIdResult> **Since:** 7.4.0 -------------------- ### getGroups() ```typescript getGroups() => Promise ``` List all contact groups on the device. Only available on iOS. **Returns:** Promise<GetGroupsResult> **Since:** 7.4.0 -------------------- ### isAvailable() ```typescript isAvailable() => Promise ``` Check whether or not contacts is available on the device. **Returns:** Promise<IsAvailableResult> **Since:** 7.6.0 -------------------- ### isSupported() ```typescript isSupported() => Promise ``` Check if the contacts API is available on the device. **Returns:** Promise<IsSupportedResult> **Since:** 7.0.0 -------------------- ### openSettings() ```typescript openSettings() => Promise ``` Opens the native app settings page to allow the user to grant the app contacts permissions. Only available on Android and iOS. **Since:** 7.7.0 -------------------- ### pickContact(...) ```typescript pickContact(options?: PickContactsOptions | undefined) => Promise ``` Open the contact picker to select a contact from the device. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | PickContactsOptions | **Returns:** Promise<PickContactsResult> **Since:** 7.0.0 -------------------- ### pickContacts(...) ```typescript pickContacts(options?: PickContactsOptions | undefined) => Promise ``` Open the contact picker to select a contact from the device. On Android, reading the selected contact requires the `READ_CONTACTS` permission below Android 17. Set the `property` option to select a single contact property instead, which never requires a permission. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | PickContactsOptions | **Returns:** Promise<PickContactsResult> **Since:** 7.4.0 -------------------- ### updateContactById(...) ```typescript updateContactById(options: UpdateContactByIdOptions) => Promise ``` Update an existing contact on the device. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------------- | | **`options`** | UpdateContactByIdOptions | **Since:** 7.4.0 -------------------- ### checkPermissions() ```typescript checkPermissions() => Promise ``` Check permissions to access contacts. Only available on Android and iOS. **Returns:** Promise<PermissionStatus> **Since:** 7.0.0 -------------------- ### requestPermissions(...) ```typescript requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise ``` Request permissions to access contacts. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | RequestPermissionsOptions | **Returns:** Promise<PermissionStatus> **Since:** 7.0.0 -------------------- ### Interfaces #### CountContactsResult | Prop | Type | Description | Since | | ----------- | ------------------- | ----------------------- | ----- | | **`total`** | number | The number of contacts. | 7.4.0 | #### CreateContactResult | Prop | Type | Description | Since | | -------- | ------------------- | --------------------------------------- | ----- | | **`id`** | string | The identifier for the created contact. | 7.0.0 | #### CreateContactOptions | Prop | Type | Description | Since | | ------------- | ------------------------------------------------------------- | ---------------------- | ----- | | **`contact`** | Omit<Contact, 'id'> | The contact to create. | 7.0.0 | #### Contact | Prop | Type | Description | Since | | ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`account`** | Account | The account associated with the contact. Only available on Android. | 7.4.0 | | **`birthday`** | Birthday | The birthday of the contact. | 7.3.0 | | **`displayName`** | string | The formatted name of the contact as displayed by the device. This property is read-only and is ignored when creating or updating a contact. Only available on Android and iOS. | 8.1.0 | | **`emailAddresses`** | EmailAddress[] | The list of email addresses for the contact. | 7.0.0 | | **`familyName`** | string | The family name of the contact. Only available on Android and iOS. | 7.0.0 | | **`givenName`** | string | The given name of the contact. Only available on Android and iOS. | 7.0.0 | | **`groupIds`** | string[] | The identifier of the groups the contact belongs to. Only available on iOS. | 7.4.0 | | **`id`** | string | The identifier for the contact. Only available on Android and iOS. | 7.0.0 | | **`jobTitle`** | string | The job title of the contact. Only available on Android and iOS. | 7.0.0 | | **`middleName`** | string | The middle name of the contact. Only available on Android and iOS. | 7.0.0 | | **`fullName`** | string | The full name of the contact. Only available on Web. | 7.0.0 | | **`namePrefix`** | string | The name prefix of the contact. Only available on Android and iOS. | 7.0.0 | | **`nameSuffix`** | string | The name suffix of the contact. Only available on Android and iOS. | 7.0.0 | | **`note`** | string | A note about the contact. Only available on Android and iOS. | 7.0.0 | | **`organizationName`** | string | The organization name of the contact. Only available on Android and iOS. | 7.0.0 | | **`phoneNumbers`** | PhoneNumber[] | The list of phone numbers for the contact. | 7.0.0 | | **`photo`** | string | The photo of the contact as a base64 string. Only available on Android and iOS. | 7.0.0 | | **`postalAddresses`** | PostalAddress[] | The list of postal addresses for the contact. | 7.0.0 | | **`urlAddresses`** | UrlAddress[] | The list of URL addresses for the contact. Only available on Android and iOS. | 7.0.0 | #### Account | Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------------------- | ----- | | **`name`** | string | The account name. Only available on Android. | 7.4.0 | | **`type`** | string | The account type. Only available on Android. | 7.4.0 | #### Birthday | Prop | Type | Description | Since | | ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`day`** | number | The day of the birthdate. | 7.3.0 | | **`month`** | number | The month of the birthdate. | 7.3.0 | | **`year`** | number | The year of the birthdate. On **Android**, this must be provided if the `day` and `month` are provided when using the `displayCreateContact(...)` method. | 7.3.0 | #### EmailAddress | Prop | Type | Description | Default | Since | | --------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----- | | **`isPrimary`** | boolean | Whether this email address is the primary one for the contact. | false | 7.0.0 | | **`label`** | string | A custom label for the email address. On **iOS**, this label is only set if the type is `EmailAddressType.Custom`. | | 7.0.0 | | **`type`** | EmailAddressType | The type of email address. | EmailAddressType.Other | 7.0.0 | | **`value`** | string | The email address. | | 7.0.0 | #### PhoneNumber | Prop | Type | Description | Default | Since | | --------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----- | | **`isPrimary`** | boolean | Whether this email address is the primary one for the contact. | | 7.0.0 | | **`label`** | string | A custom label for the phone number. On **iOS**, this label is only set if the type is `PhoneNumberType.Custom`. | | 7.0.0 | | **`type`** | PhoneNumberType | The type of phone number. | PhoneNumberType.Other | 7.0.0 | | **`value`** | string | The phone number. | | | #### PostalAddress | Prop | Type | Description | Default | Since | | -------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----- | | **`city`** | string | The city for the postal address. | | 7.0.0 | | **`country`** | string | The country for the postal address. | | 7.0.0 | | **`formatted`** | string | The formatted postal address. | | 7.0.0 | | **`isoCountryCode`** | string | The ISO country code for the postal address. Only available on iOS. | | 7.0.0 | | **`isPrimary`** | boolean | Whether this postal address is the primary one for the contact. Only available on Android and iOS. | false | 7.0.0 | | **`label`** | string | A custom label for the postal address. On **iOS**, this label is only set if the type is `PostalAddressType.Custom`. Only available on Android and iOS. | | 7.0.0 | | **`neighborhood`** | string | The neighborhood for the postal address. Only available on Android and iOS. | | 7.0.0 | | **`postalCode`** | string | The postal code for the postal address. Only available on Android and iOS. | | 7.0.0 | | **`state`** | string | The state for the postal address. | | 7.0.0 | | **`street`** | string | The street for the postal address. Only available on Android and iOS. | | 7.0.0 | | **`type`** | PostalAddressType | The type of postal address. Only available on Android and iOS. | PostalAddressType.Other | 7.0.0 | #### UrlAddress | Prop | Type | Description | Default | Since | | ----------- | --------------------------------------------------------- | ----------------------------------- | --------------------------------- | ----- | | **`label`** | string | A custom label for the URL address. | | 7.5.0 | | **`type`** | UrlAddressType | The type of URL address. | UrlAddressType.Other | 7.5.0 | | **`value`** | string | The URL address. | | | #### CreateGroupResult | Prop | Type | Description | Since | | -------- | ------------------- | ------------------------------------- | ----- | | **`id`** | string | The identifier for the created group. | 7.4.0 | #### CreateGroupOptions | Prop | Type | Description | Since | | ----------- | --------------------------------------------------------- | -------------------- | ----- | | **`group`** | Omit<Group, 'id'> | The group to create. | 7.4.0 | #### Group | Prop | Type | Description | Since | | ---------- | ------------------- | ----------------------------- | ----- | | **`id`** | string | The identifier for the group. | 7.4.0 | | **`name`** | string | The name of the group. | 7.4.0 | #### DeleteContactByIdOptions | Prop | Type | Description | Since | | -------- | ------------------- | ------------------------------- | ----- | | **`id`** | string | The identifier for the contact. | 7.0.0 | #### DeleteGroupByIdOptions | Prop | Type | Description | Since | | -------- | ------------------- | ----------------------------- | ----- | | **`id`** | string | The identifier for the group. | 7.4.0 | #### DisplayContactByIdOptions | Prop | Type | Description | Since | | -------- | ------------------- | ----------------------------------------- | ----- | | **`id`** | string | The identifier of the contact to display. | 7.4.0 | #### DisplayCreateContactResult | Prop | Type | Description | Since | | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----- | | **`id`** | string | The identifier for the created contact. On **Android**, you need the `readContacts` permission to return the identifier. | 7.4.0 | #### DisplayCreateContactOptions | Prop | Type | Description | Since | | ------------- | ------------------------------------------------------------- | --------------------------------------------------- | ----- | | **`contact`** | Omit<Contact, 'id'> | The contact to display in the create contact modal. | 7.2.0 | #### DisplayUpdateContactByIdOptions | Prop | Type | Description | Since | | -------- | ------------------- | ---------------------------------------- | ----- | | **`id`** | string | The identifier of the contact to update. | 7.4.0 | #### GetAccountsResult | Prop | Type | Description | Since | | -------------- | ---------------------- | --------------------------------------------- | ----- | | **`accounts`** | Account[] | An array of available accounts on the device. | 7.4.0 | #### GetContactByIdResult | Prop | Type | | ------------- | --------------------------------------------------- | | **`contact`** | Contact \| null | #### GetContactByIdOptions | Prop | Type | Description | Default | Since | | ------------ | ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **`fields`** | (keyof Contact)[] | The fields to return for the contact. | ['birthday', 'displayName', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'] | 7.1.0 | | **`id`** | string | The identifier for the contact. | | 7.0.0 | #### GetContactsResult | Prop | Type | Description | Since | | -------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | ----- | | **`contacts`** | Contact[] | The list of contacts on the device. **Note**: No photos are returned to avoid performance issues. | 7.0.0 | #### GetContactsOptions | Prop | Type | Description | Default | Since | | ------------ | ----------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`fields`** | (keyof Contact)[] | The fields to return for the contact. | ['emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'] | 7.1.0 | | **`limit`** | number | Limit the number of contacts returned. | 20 | 7.4.0 | | **`offset`** | number | Offset the number of contacts returned. | 0 | 7.4.0 | #### GetGroupByIdResult | Prop | Type | Description | Since | | ----------- | ----------------------------------------------- | ---------------------------------------- | ----- | | **`group`** | Group \| null | The group with the specified identifier. | 7.4.0 | #### GetGroupByIdOptions | Prop | Type | Description | Since | | -------- | ------------------- | ----------------------------- | ----- | | **`id`** | string | The identifier for the group. | 7.4.0 | #### GetGroupsResult | Prop | Type | Description | Since | | ------------ | -------------------- | --------------------------------- | ----- | | **`groups`** | Group[] | The list of groups on the device. | 7.4.0 | #### IsAvailableResult | Prop | Type | Description | Since | | ----------------- | -------------------- | --------------------------------------------------- | ----- | | **`isAvailable`** | boolean | Whether or not contacts is available on the device. | 7.6.0 | #### IsSupportedResult | Prop | Type | Description | Since | | ----------------- | -------------------- | ---------------------------------------------------------------------------------------------- | ----- | | **`isSupported`** | boolean | Whether the contacts API is available on the device. This is always `true` on Android and iOS. | 7.0.0 | #### PickContactsResult | Prop | Type | Description | Since | | -------------- | ---------------------- | --------------------------------------------------- | ----- | | **`contacts`** | Contact[] | The selected contacts. Empty if none were selected. | 7.0.0 | #### PickContactsOptions | Prop | Type | Description | Default | Since | | -------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **`fields`** | (keyof Contact)[] | The fields to return for the contact. Only available on Android and iOS. | ['birthday', 'displayName', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'] | 7.4.0 | | **`multiple`** | boolean | Whether to allow selecting multiple contacts. Only available on Web. | false | 7.0.0 | | **`property`** | ContactProperty | The contact property to select. If set, the user selects a single property instead of a whole contact. The result then only contains the `id`, the `displayName` and the selected property, but no permissions are required to read it. Only available on Android and iOS. | | 8.1.0 | #### UpdateContactByIdOptions | Prop | Type | Description | Since | | ------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **`contact`** | Nullable<Omit<Contact, 'id'>> | The updated contact information. Missing properties are ignored and keep their existing values. Properties explicitly set to `null` (or empty arrays `[]`) will be deleted. | 8.0.0 | | **`id`** | string | The identifier for the contact. | 8.0.0 | #### PermissionStatus | Prop | Type | Description | Since | | ------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----- | | **`readContacts`** | ContactsPermissionState | Permission state for reading contacts. Only available on Android and iOS. | 7.0.0 | | **`writeContacts`** | ContactsPermissionState | Permission state for writing contacts. Only available on Android and iOS. | 7.0.0 | #### RequestPermissionsOptions | Prop | Type | Description | Default | Since | | ----------------- | ------------------------------------- | --------------------------- | ---------------------------------------------- | ----- | | **`permissions`** | ContactsPermissionType[] | The permissions to request. | ['readContacts', 'writeContacts'] | 7.0.0 | ### Type Aliases #### ContactField keyof Contact #### PickContactOptions PickContactsOptions #### PickContactResult PickContactsResult #### Nullable Makes all properties of T nullable. { [K in keyof T]: T[K] | null } #### ContactsPermissionState PermissionState | 'limited' #### PermissionState 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' #### ContactsPermissionType 'readContacts' | 'writeContacts' ### Enums #### EmailAddressType | Members | Value | Description | Since | | ------------ | --------------------- | -------------------------- | ----- | | **`Custom`** | 'CUSTOM' | | 7.0.0 | | **`Home`** | 'HOME' | | 7.0.0 | | **`ICloud`** | 'ICLOUD' | Only available on iOS. | 7.0.0 | | **`Mobile`** | 'MOBILE' | Only available on Android. | 7.0.0 | | **`Other`** | 'OTHER' | | 7.0.0 | | **`School`** | 'SCHOOL' | Only available on iOS. | 7.0.0 | | **`Work`** | 'WORK' | | 7.0.0 | #### PhoneNumberType | Members | Value | Description | Since | | ----------------- | --------------------------- | -------------------------- | ----- | | **`Assistant`** | 'ASSISTANT' | Only available on Android. | 7.0.0 | | **`Callback`** | 'CALLBACK' | Only available on Android. | 7.0.0 | | **`Car`** | 'CAR' | Only available on Android. | 7.0.0 | | **`CompanyMain`** | 'COMPANY_MAIN' | Only available on Android. | 7.0.0 | | **`Custom`** | 'CUSTOM' | | 7.0.0 | | **`FaxHome`** | 'FAX_HOME' | | 7.0.0 | | **`FaxOther`** | 'FAX_OTHER' | | 7.0.0 | | **`FaxWork`** | 'FAX_WORK' | | 7.0.0 | | **`Home`** | 'HOME' | | 7.0.0 | | **`IPhone`** | 'IPHONE' | Only available on iOS. | 7.0.0 | | **`Isdn`** | 'ISDN' | Only available on Android. | 7.0.0 | | **`Main`** | 'MAIN' | | 7.0.0 | | **`Mms`** | 'MMS' | Only available on Android. | 7.0.0 | | **`Mobile`** | 'MOBILE' | | 7.0.0 | | **`Other`** | 'OTHER' | | 7.0.0 | | **`Pager`** | 'PAGER' | | 7.0.0 | | **`Radio`** | 'RADIO' | Only available on Android. | 7.0.0 | | **`Telex`** | 'TELEX' | Only available on Android. | 7.0.0 | | **`TtyTdd`** | 'TTY_TDD' | Only available on Android. | 7.0.0 | | **`Work`** | 'WORK' | | 7.0.0 | | **`WorkMobile`** | 'WORK_MOBILE' | Only available on Android. | 7.0.0 | | **`WorkPager`** | 'WORK_PAGER' | Only available on Android. | 7.0.0 | #### PostalAddressType | Members | Value | Since | | ------------ | --------------------- | ----- | | **`Custom`** | 'CUSTOM' | 7.0.0 | | **`Home`** | 'HOME' | 7.0.0 | | **`Other`** | 'OTHER' | 7.0.0 | | **`Work`** | 'WORK' | 7.0.0 | #### UrlAddressType | Members | Value | Description | Since | | -------------- | ----------------------- | -------------------------- | ----- | | **`Blog`** | 'BLOG' | Only available on Android. | 7.5.0 | | **`Custom`** | 'CUSTOM' | | 7.5.0 | | **`Ftp`** | 'FTP' | Only available on Android. | 7.5.0 | | **`Home`** | 'HOME' | | 7.5.0 | | **`Homepage`** | 'HOMEPAGE' | | 7.5.0 | | **`Other`** | 'OTHER' | | 7.5.0 | | **`Profile`** | 'PROFILE' | Only available on Android. | 7.5.0 | | **`School`** | 'SCHOOL' | Only available on iOS. | 7.5.0 | | **`Work`** | 'WORK' | | 7.5.0 | #### ContactProperty | Members | Value | Description | Since | | ------------------- | ---------------------------- | --------------------------------------- | ----- | | **`EmailAddress`** | 'emailAddress' | A single email address of the contact. | 8.1.0 | | **`PhoneNumber`** | 'phoneNumber' | A single phone number of the contact. | 8.1.0 | | **`PostalAddress`** | 'postalAddress' | A single postal address of the contact. | 8.1.0 | ## FAQ ### Do I need any permissions to access contacts? It depends. `displayCreateContact(...)` never needs a permission, and neither does `pickContacts(...)` on iOS. On Android, `pickContacts(...)` needs the `READ_CONTACTS` permission below Android 17, unless you pass the `property` option to select a single contact property instead. Every other method needs access to the address book: on Android, add the `READ_CONTACTS` and/or `WRITE_CONTACTS` permissions to your `AndroidManifest.xml` file (see [Installation](#installation)); on iOS, add the `NSContactsUsageDescription` key to your `Info.plist` file. At runtime, use `checkPermissions()` and `requestPermissions()` to manage the permission state, and `openSettings()` to send the user to the native app settings if the permission was denied. ### How do I update only specific fields of a contact? The `updateContactById(...)` method supports partial updates. Properties that are missing from the contact object are preserved, while properties explicitly set to `null` are deleted from the contact. See the [usage example](#update-or-delete-a-contact) above. ### Are contact groups and accounts available on all platforms? No. Contact groups (`createGroup(...)`, `getGroups()`, `getGroupById(...)`, and `deleteGroupById(...)`) are only available on iOS. Accounts (`getAccounts()`) are only available on Android, where you can add contacts to a specific account. ### How do I handle large address books without performance issues? Use the `limit` and `offset` options of `getContacts(...)` to paginate through the contacts instead of loading all of them at once. Additionally, only request the contact properties you actually need via the `fields` option, and use `countContacts()` to determine the total number of contacts. ### How is this plugin different from the Capacitor Community Contacts plugin? This plugin offers advanced features such as partial updates, contact groups on iOS, accounts on Android, pagination, native modals, and contact photos, and comes with priority support from the Capawesome Team. You can find a detailed comparison in the guide [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/). ### Can I use this plugin with Ionic, React, Vue or Angular? Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins - [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/): Open the native email composer. - [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number. - [SIM](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information. - [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/CHANGELOG.md). ## Breaking Changes See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/BREAKING.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/LICENSE).