@capgo/capacitor-contacts

Manage device contacts across iOS, Android, and the Web with a unified Capacitor API.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/contacts/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/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:

npm install @capgo/capacitor-contacts
npx cap sync

Android

Google Play's Contacts Permissions policy (effective 27 January 2027) allows READ_CONTACTS only when the Android Contact Picker cannot cover your core feature, for apps that target Android 17 (API 37) or later.

This plugin does not declare READ_CONTACTS or WRITE_CONTACTS. Add them in your app manifest only if you need them.

Pick a phone, email, or address without READ_CONTACTS:

import { CapacitorContacts, ContactProperty } from '@capgo/capacitor-contacts';

const { contacts } = await CapacitorContacts.pickContacts({
  property: ContactProperty.PhoneNumber,
});

const number = contacts[0]?.phoneNumbers?.[0]?.value;

property works on every Android version. The picker returns a data-row URI the plugin can read without a permission. The result contains id, displayName, and the selected property only.

Use ContactProperty.EmailAddress or ContactProperty.PostalAddress the same way.

When you still need READ_CONTACTS:

• pickContacts() / pickContact() without property (full contact record)
• getContacts(), getContactById(), countContacts(), getGroups(), getAccounts()
• Syncing, backing up, or matching the whole address book

Those APIs keep working as before once READ_CONTACTS is in the app manifest and granted. Pass property only if you want to drop the permission.

If full-address-book access is a core feature, add the permission and file the Play Console declaration before pre-review checks start on 27 October 2026:

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

WRITE_CONTACTS is unchanged by this policy. Add it only if you create or update contacts in code.

Without READ_CONTACTS, pickContacts() without property can still return id and displayName (and, on Android 17+, picker-granted fields). Use property to get a phone, email, or address with no permission on every Android version.

iOS

pickContact() / pickContacts() never require a contacts permission. Add NSContactsUsageDescription only if you call methods that read or write the address book (getContacts, createContact, and similar).

API

• countContacts()
• createContact(...)
• createGroup(...)
• deleteContactById(...)
• deleteGroupById(...)
• displayContactById(...)
• displayCreateContact(...)
• displayUpdateContactById(...)
• getAccounts()
• getContactById(...)
• getContacts(...)
• getGroupById(...)
• getGroups()
• isAvailable()
• isSupported()
• openSettings()
• pickContact(...)
• pickContacts(...)
• updateContactById(...)
• checkPermissions()
• requestPermissions(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

Capacitor Contacts Plugin interface for managing device contacts.

countContacts()

countContacts() => Promise<CountContactsResult>

Count the total number of contacts on the device.

Returns: Promise<CountContactsResult>

Since: 1.0.0

createContact(...)

createContact(options: CreateContactOptions) => Promise<CreateContactResult>

Create a new contact programmatically.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ----------------------------------- | | options | CreateContactOptions | - The contact information to create |

Returns: Promise<CreateContactResult>

Since: 1.0.0

createGroup(...)

createGroup(options: CreateGroupOptions) => Promise<CreateGroupResult>

Create a new contact group.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | --------------------------------- | | options | CreateGroupOptions | - The group information to create |

Returns: Promise<CreateGroupResult>

Since: 1.0.0

deleteContactById(...)

deleteContactById(options: DeleteContactByIdOptions) => Promise<void>

Delete a contact by ID.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | --------------------------------- | | options | DeleteContactByIdOptions | - The ID of the contact to delete |

Since: 1.0.0

deleteGroupById(...)

deleteGroupById(options: DeleteGroupByIdOptions) => Promise<void>

Delete a group by ID.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | ------------------------------- | | options | DeleteGroupByIdOptions | - The ID of the group to delete |

Since: 1.0.0

displayContactById(...)

displayContactById(options: DisplayContactByIdOptions) => Promise<void>

Display a contact using the native contact viewer.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------- | ---------------------------------- | | options | DisplayContactByIdOptions | - The ID of the contact to display |

Since: 1.0.0

displayCreateContact(...)

displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise<DisplayCreateContactResult>

Display the native create contact UI.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- | | options | DisplayCreateContactOptions | - Optional pre-filled contact information |

Returns: Promise<DisplayCreateContactResult>

Since: 1.0.0

displayUpdateContactById(...)

displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise<void>

Display the native update contact UI for a specific contact.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------------- | --------------------------------- | | options | DisplayUpdateContactByIdOptions | - The ID of the contact to update |

Since: 1.0.0

getAccounts()

getAccounts() => Promise<GetAccountsResult>

Get all accounts available on the device.

Returns: Promise<GetAccountsResult>

Since: 1.0.0

getContactById(...)

getContactById(options: GetContactByIdOptions) => Promise<GetContactByIdResult>

Get a specific contact by ID.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ---------------------------------------- | | options | GetContactByIdOptions | - The ID and optional fields to retrieve |

Returns: Promise<GetContactByIdResult>

Since: 1.0.0

getContacts(...)

getContacts(options?: GetContactsOptions | undefined) => Promise<GetContactsResult>

Get all contacts from the device.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | ----------------------------------------- | | options | GetContactsOptions | - Optional filters and pagination options |

Returns: Promise<GetContactsResult>

Since: 1.0.0

getGroupById(...)

getGroupById(options: GetGroupByIdOptions) => Promise<GetGroupByIdResult>

Get a specific group by ID.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | --------------------------------- | | options | GetGroupByIdOptions | - The ID of the group to retrieve |

Returns: Promise<GetGroupByIdResult>

Since: 1.0.0

getGroups()

getGroups() => Promise<GetGroupsResult>

Get all contact groups.

Returns: Promise<GetGroupsResult>

Since: 1.0.0

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check if contacts are available on the device.

Returns: Promise<IsAvailableResult>

Since: 1.0.0

isSupported()

isSupported() => Promise<IsSupportedResult>

Check if the plugin is supported on the current platform.

Returns: Promise<IsSupportedResult>

Since: 1.0.0

openSettings()

openSettings() => Promise<void>

Open the device's contacts settings.

Since: 1.0.0

pickContact(...)

pickContact(options?: PickContactsOptions | undefined) => Promise<PickContactResult>

Pick a single contact using the native contact picker.

Same options as {@link pickContacts}. Without property, Android still returns the full contact when READ_CONTACTS is granted.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ | | options | PickContactsOptions | - Optional fields to retrieve and picker configuration |

Returns: Promise<PickContactsResult>

Since: 1.0.0

pickContacts(...)

pickContacts(options?: PickContactsOptions | undefined) => Promise<PickContactsResult>

Pick one or more contacts using the native contact picker.

On iOS this never requires a contacts permission.

On Android, pickContacts() without property still returns the full contact when the app has READ_CONTACTS. Pass property only when you want a single phone number, email address, or postal address and can omit that permission (required to target Android 17 / API 37 without a Play Console contacts declaration).

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ | | options | PickContactsOptions | - Optional fields to retrieve and picker configuration |

Returns: Promise<PickContactsResult>

Since: 1.0.0

updateContactById(...)

updateContactById(options: UpdateContactByIdOptions) => Promise<void>

Update an existing contact by ID.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ---------------------------------------- | | options | UpdateContactByIdOptions | - The ID and updated contact information |

Since: 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the current permission status for contacts.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions(...)

requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>

Request permissions to access contacts.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------- | ------------------------------------------ | | options | RequestPermissionsOptions | - Optional specific permissions to request |

Returns: Promise<PermissionStatus>

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

CountContactsResult

Result from counting contacts.

| Prop | Type | Description | Since | | ----------- | ------------------- | ------------------------- | ----- | | count | number | Total number of contacts. | 1.0.0 |

CreateContactResult

Result from creating a contact.

| Prop | Type | Description | Since | | -------- | ------------------- | ------------------------------------ | ----- | | id | string | The ID of the newly created contact. | 1.0.0 |

CreateContactOptions

Options for creating a contact.

| Prop | Type | Description | Since | | ------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----- | | contact | Omit<Contact, 'id'> | Contact information to create. The 'id' field will be generated automatically. | 1.0.0 |

Contact

Contact information.

| Prop | Type | Description | Since | | ---------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | id | string | Unique identifier for the contact. | 1.0.0 | | displayName | string | Formatted name shown by the device for this contact. Derived from CNContactFormatter on iOS and DISPLAY_NAME on Android. Read-only: setting this when creating or updating a contact has no effect. Use givenName and familyName to write a name. | 8.1.0 | | account | Account | Account information for the contact. | 1.0.0 | | birthday | Birthday | Birthday information for the contact. | 1.0.0 | | emailAddresses | EmailAddress[] | Email addresses for the contact. | 1.0.0 | | familyName | string | Family name (last name) of the contact. | 1.0.0 | | fullName | string | Full name of the contact. | 1.0.0 | | givenName | string | Given name (first name) of the contact. | 1.0.0 | | groupIds | string[] | Group IDs the contact belongs to. | 1.0.0 | | jobTitle | string | Job title of the contact. | 1.0.0 | | middleName | string | Middle name of the contact. | 1.0.0 | | namePrefix | string | Name prefix (e.g., "Dr.", "Mr.", "Ms.") of the contact. | 1.0.0 | | nameSuffix | string | Name suffix (e.g., "Jr.", "Sr.", "III") of the contact. | 1.0.0 | | note | string | Notes about the contact. | 1.0.0 | | organizationName | string | Organization name of the contact. | 1.0.0 | | phoneNumbers | PhoneNumber[] | Phone numbers for the contact. | 1.0.0 | | photo | string | Base64-encoded photo of the contact. | 1.0.0 | | postalAddresses | PostalAddress[] | Postal addresses for the contact. | 1.0.0 | | urlAddresses | UrlAddress[] | URL addresses for the contact. | 1.0.0 |

Account

Account information for a contact.

| Prop | Type | Description | Since | | ---------- | ------------------- | ------------------------ | ----- | | name | string | The name of the account. | 1.0.0 | | type | string | The type of the account. | 1.0.0 |

Birthday

Birthday information for a contact.

| Prop | Type | Description | Since | | ----------- | ------------------- | ---------------------------- | ----- | | day | number | The day of the month (1-31). | 1.0.0 | | month | number | The month (1-12). | 1.0.0 | | year | number | The year. | 1.0.0 |

EmailAddress

Email address information for a contact.

| Prop | Type | Description | Since | | --------------- | ------------------------------------------------------------- | ------------------------------------------ | ----- | | value | string | The email address value. | 1.0.0 | | type | EmailAddressType | The type of email address. | 1.0.0 | | label | string | Custom label for the email address. | 1.0.0 | | isPrimary | boolean | Whether this is the primary email address. | 1.0.0 |

PhoneNumber

Phone number information for a contact.

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------------------- | ----------------------------------------- | ----- | | value | string | The phone number value. | 1.0.0 | | type | PhoneNumberType | The type of phone number. | 1.0.0 | | label | string | Custom label for the phone number. | 1.0.0 | | isPrimary | boolean | Whether this is the primary phone number. | 1.0.0 |

PostalAddress

Postal address information for a contact.

| Prop | Type | Description | Since | | -------------------- | --------------------------------------------------------------- | ------------------------------------------- | ----- | | city | string | The city name. | 1.0.0 | | country | string | The country name. | 1.0.0 | | formatted | string | The formatted address string. | 1.0.0 | | isoCountryCode | string | The ISO country code. | 1.0.0 | | isPrimary | boolean | Whether this is the primary postal address. | 1.0.0 | | label | string | Custom label for the postal address. | 1.0.0 | | neighborhood | string | The neighborhood name. | 1.0.0 | | postalCode | string | The postal code. | 1.0.0 | | state | string | The state or province name. | 1.0.0 | | street | string | The street address. | 1.0.0 | | type | PostalAddressType | The type of postal address. | 1.0.0 |

UrlAddress

URL address information for a contact.

| Prop | Type | Description | Since | | ----------- | --------------------------------------------------------- | ------------------------- | ----- | | value | string | The URL value. | 1.0.0 | | type | UrlAddressType | The type of URL. | 1.0.0 | | label | string | Custom label for the URL. | 1.0.0 |

CreateGroupResult

Result from creating a group.

| Prop | Type | Description | Since | | -------- | ------------------- | ---------------------------------- | ----- | | id | string | The ID of the newly created group. | 1.0.0 |

CreateGroupOptions

Options for creating a group.

| Prop | Type | Description | Since | | ----------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----- | | group | Omit<Group, 'id'> | Group information to create. The 'id' field will be generated automatically. | 1.0.0 |

Group

Contact group information.

| Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------- | ----- | | id | string | Unique identifier for the group. | 1.0.0 | | name | string | Name of the group. | 1.0.0 |

DeleteContactByIdOptions

Options for deleting a contact by ID.

| Prop | Type | Description | Since | | -------- | ------------------- | -------------------------------- | ----- | | id | string | The ID of the contact to delete. | 1.0.0 |

DeleteGroupByIdOptions

Options for deleting a group by ID.

| Prop | Type | Description | Since | | -------- | ------------------- | ------------------------------ | ----- | | id | string | The ID of the group to delete. | 1.0.0 |

DisplayContactByIdOptions

Options for displaying a contact by ID.

| Prop | Type | Description | Since | | -------- | ------------------- | --------------------------------- | ----- | | id | string | The ID of the contact to display. | 1.0.0 |

DisplayCreateContactResult

Result from displaying the native create contact UI.

| Prop | Type | Description | Since | | -------- | ------------------- | ----------------------------------------------------------------------------------- | ----- | | id | string | The ID of the created contact, if one was created. Undefined if the user cancelled. | 1.0.0 |

DisplayCreateContactOptions

Options for displaying the native create contact UI.

| Prop | Type | Description | Since | | ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----- | | contact | Omit<Contact, 'id'> | Optional pre-filled contact information for the create UI. | 1.0.0 |

DisplayUpdateContactByIdOptions

Options for displaying the native update contact UI.

| Prop | Type | Description | Since | | -------- | ------------------- | -------------------------------- | ----- | | id | string | The ID of the contact to update. | 1.0.0 |

GetAccountsResult

Result from getting accounts.

| Prop | Type | Description | Since | | -------------- | ---------------------- | ----------------------------------------- | ----- | | accounts | Account[] | List of accounts available on the device. | 1.0.0 |

GetContactByIdResult

Result from getting a contact by ID.

| Prop | Type | Description | Since | | ------------- | --------------------------------------------------- | ---------------------------------- | ----- | | contact | Contact | null | The contact, or null if not found. | 1.0.0 |

GetContactByIdOptions

Options for getting a contact by ID.

| Prop | Type | Description | Since | | ------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | id | string | The ID of the contact to retrieve. | 1.0.0 | | fields | (keyof Contact)[] | Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 |

GetContactsResult

Result from getting contacts.

| Prop | Type | Description | Since | | -------------- | ---------------------- | ----------------- | ----- | | contacts | Contact[] | List of contacts. | 1.0.0 |

GetContactsOptions

Options for getting contacts.

| Prop | Type | Description | Since | | ------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | fields | (keyof Contact)[] | Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 | | limit | number | Maximum number of contacts to return. | 1.0.0 | | offset | number | Number of contacts to skip before starting to return results. | 1.0.0 |

GetGroupByIdResult

Result from getting a group by ID.

| Prop | Type | Description | Since | | ----------- | ----------------------------------------------- | -------------------------------- | ----- | | group | Group | null | The group, or null if not found. | 1.0.0 |

GetGroupByIdOptions

Options for getting a group by ID.

| Prop | Type | Description | Since | | -------- | ------------------- | -------------------------------- | ----- | | id | string | The ID of the group to retrieve. | 1.0.0 |

GetGroupsResult

Result from getting groups.

| Prop | Type | Description | Since | | ------------ | -------------------- | --------------- | ----- | | groups | Group[] | List of groups. | 1.0.0 |

IsAvailableResult

Result from checking if contacts are available on the device.

| Prop | Type | Description | Since | | ----------------- | -------------------- | ---------------------------------------------- | ----- | | isAvailable | boolean | Whether contacts are available on this device. | 1.0.0 |

IsSupportedResult

Result from checking if the plugin is supported on the platform.

| Prop | Type | Description | Since | | ----------------- | -------------------- | ------------------------------------------------- | ----- | | isSupported | boolean | Whether the plugin is supported on this platform. | 1.0.0 |

PickContactsResult

Result from picking contacts.

| Prop | Type | Description | Since | | -------------- | ---------------------- | -------------------------- | ----- | | contacts | Contact[] | List of selected contacts. | 1.0.0 |

PickContactsOptions

Options for picking contacts using the native contact picker.

| Prop | Type | Description | Since | | -------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | fields | (keyof Contact)[] | Optional list of specific fields to retrieve. If not specified, all fields are returned. Ignored when {@link PickContactsOptions.property} is set. The result then contains only id, displayName, and the selected property. | 1.0.0 | | multiple | boolean | Whether to allow selecting multiple contacts. Default is false. Ignored when {@link PickContactsOptions.property} is set. Property picking always returns a single value. | 1.0.0 | | property | ContactProperty | Restrict the picker to a single contact property. On Android this launches the picker against the phone, email, or postal address table and reads the granted data row. That requires no READ_CONTACTS permission on any Android version, which is required for apps that only pick a contact detail and target Android 17 (API 37) or later under the Google Play Contacts Permissions policy. On iOS the picker lets the user choose one phone number, email address, or postal address. It never requires a contacts permission. | 8.1.0 |

UpdateContactByIdOptions

Options for updating a contact by ID.

| Prop | Type | Description | Since | | ------------- | --------------------------------------------------------------------------------- | -------------------------------- | ----- | | id | string | The ID of the contact to update. | 1.0.0 | | contact | Omit<Contact, 'id'> | Updated contact information. | 1.0.0 |

PermissionStatus

Status of contacts permissions.

| Prop | Type | Description | Since | | ------------------- | --------------------------------------------------------------------------- | -------------------------------------- | ----- | | readContacts | ContactsPermissionState | Permission state for reading contacts. | 1.0.0 | | writeContacts | ContactsPermissionState | Permission state for writing contacts. | 1.0.0 |

RequestPermissionsOptions

Options for requesting contacts permissions.

| Prop | Type | Description | Since | | ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------ | ----- | | permissions | ContactsPermissionType[] | Specific permissions to request. If not provided, all permissions will be requested. | 1.0.0 |

Type Aliases

Omit

Construct a type with the properties of T except for those in type K.

Pick<T, Exclude<keyof T, K>>

Pick

From T, pick a set of properties whose keys are in the union K

{ [P in K]: T[P]; }

Exclude

Exclude from T those types that are assignable to U

T extends U ? never : T

EmailAddressType

Type of email address.

'CUSTOM' | 'HOME' | 'ICLOUD' | 'OTHER' | 'WORK'

PhoneNumberType

Type of phone number.

'ASSISTANT' | 'CALLBACK' | 'CAR' | 'COMPANY_MAIN' | 'CUSTOM' | 'FAX_HOME' | 'FAX_WORK' | 'HOME' | 'HOME_FAX' | 'ISDN' | 'MAIN' | 'MMS' | 'MOBILE' | 'OTHER' | 'OTHER_FAX' | 'PAGER' | 'RADIO' | 'TELEX' | 'TTY_TDD' | 'WORK' | 'WORK_MOBILE' | 'WORK_PAGER'

PostalAddressType

Type of postal address.

'CUSTOM' | 'HOME' | 'OTHER' | 'WORK'

UrlAddressType

Type of URL address.

'BLOG' | 'CUSTOM' | 'FTP' | 'HOME' | 'HOMEPAGE' | 'OTHER' | 'PROFILE' | 'SCHOOL' | 'WORK'

ContactField

Field names available in a Contact object.

keyof Contact

PickContactOptions

Alias for PickContactsOptions.

PickContactsOptions

PickContactResult

Alias for PickContactsResult.

PickContactsResult

ContactsPermissionState

Permission state for contacts access, including the 'limited' state for iOS 18+.

PermissionState | 'limited'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ContactsPermissionType

Type of contacts permission to request.

'readContacts' | 'writeContacts'

Enums

ContactProperty

| Members | Value | Description | Since | | ------------------- | ---------------------------- | ------------------------ | ----- | | PhoneNumber | 'phoneNumber' | A single phone number. | 8.1.0 | | EmailAddress | 'emailAddress' | A single email address. | 8.1.0 | | PostalAddress | 'postalAddress' | A single postal address. | 8.1.0 |

Credit

This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader