@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/

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

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.

| 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

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

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'

Credit

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