@capgo/capacitor-contacts

Read, create, update and delete device contacts and groups from your Capacitor app, or open the native contact screens. One API for iOS and Android.

• Read contacts: getContacts(), getContactById() and countContacts().
• Write contacts: createContact(), updateContactById() and deleteContactById().
• Native screens: displayContactById(), displayCreateContact() and displayUpdateContactById() open the system UI.
• Groups and accounts: getGroups(), createGroup(), deleteGroupById() and getAccounts().
• Permissions: checkPermissions(), requestPermissions() and openSettings().
• Platforms: iOS and Android. iOS uses the Contacts framework, Android uses ContactsContract. Not available on web.

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

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.

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

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.

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).

• 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() => Promise<CountContactsResult>

Count the total number of contacts on the device.

Returns: Promise<CountContactsResult>

Since: 1.0.0

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

Create a new contact programmatically.

Returns: Promise<CreateContactResult>

Since: 1.0.0

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

Create a new contact group.

Returns: Promise<CreateGroupResult>

Since: 1.0.0

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

Delete a contact by ID.

Since: 1.0.0

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

Delete a group by ID.

Since: 1.0.0

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

Display a contact using the native contact viewer.

Since: 1.0.0

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

Display the native create contact UI.

Returns: Promise<DisplayCreateContactResult>

Since: 1.0.0

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

Display the native update contact UI for a specific contact.

Since: 1.0.0

getAccounts() => Promise<GetAccountsResult>

Get all accounts available on the device.

Returns: Promise<GetAccountsResult>

Since: 1.0.0

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

Get a specific contact by ID.

Returns: Promise<GetContactByIdResult>

Since: 1.0.0

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

Get all contacts from the device.

Returns: Promise<GetContactsResult>

Since: 1.0.0

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

Get a specific group by ID.

Returns: Promise<GetGroupByIdResult>

Since: 1.0.0

getGroups() => Promise<GetGroupsResult>

Get all contact groups.

Returns: Promise<GetGroupsResult>

Since: 1.0.0

isAvailable() => Promise<IsAvailableResult>

Check if contacts are available on the device.

Returns: Promise<IsAvailableResult>

Since: 1.0.0

isSupported() => Promise<IsSupportedResult>

Check if the plugin is supported on the current platform.

Returns: Promise<IsSupportedResult>

Since: 1.0.0

openSettings() => Promise<void>

Open the device's contacts settings.

Since: 1.0.0

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.

Returns: Promise<PickContactsResult>

Since: 1.0.0

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).

Returns: Promise<PickContactsResult>

Since: 1.0.0

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

Update an existing contact by ID.

Since: 1.0.0

checkPermissions() => Promise<PermissionStatus>

Check the current permission status for contacts.

Returns: Promise<PermissionStatus>

Since: 1.0.0

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

Request permissions to access contacts.

Returns: Promise<PermissionStatus>

Since: 1.0.0

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

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Result from counting contacts.

Result from creating a contact.

Options for creating a contact.

Contact information.

Account information for a contact.

Birthday information for a contact.

Email address information for a contact.

Phone number information for a contact.

Postal address information for a contact.

URL address information for a contact.

Result from creating a group.

Options for creating a group.

Contact group information.

Options for deleting a contact by ID.

Options for deleting a group by ID.

Options for displaying a contact by ID.

Result from displaying the native create contact UI.

Options for displaying the native create contact UI.

Options for displaying the native update contact UI.

Result from getting accounts.

Result from getting a contact by ID.

Options for getting a contact by ID.

Result from getting contacts.

Options for getting contacts.

Result from getting a group by ID.

Options for getting a group by ID.

Result from getting groups.

Result from checking if contacts are available on the device.

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

Result from picking contacts.

Options for picking contacts using the native contact picker.

Options for updating a contact by ID.

Status of contacts permissions.

Options for requesting contacts permissions.

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

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

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

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

Exclude from T those types that are assignable to U

T extends U ? never : T

Type of email address.

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

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'

Type of postal address.

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

Type of URL address.

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

Field names available in a Contact object.

keyof Contact

Alias for PickContactsOptions.

PickContactsOptions

Alias for PickContactsResult.

PickContactsResult

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

PermissionState | 'limited'

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

Type of contacts permission to request.

'readContacts' | 'writeContacts'

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