@capgo/capacitor-contacts

May 11, 2026 · View on GitHub

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

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

npm install @capgo/capacitor-contacts
npx cap sync

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

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

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

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

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

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

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

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.

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.

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

Returns: Promise<PickContactsResult>

Since: 1.0.0

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

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
`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.	1.0.0
`multiple`	`boolean`	Whether to allow selecting multiple contacts. Default is false.	1.0.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