@capgo/capacitor-contacts
v8.0.7TypeScript
Work with device contacts using Capacitor APIs
0/weekUpdated 3 days agoMPL-2.0Unpacked: 303.9 KB
Published by Cap-go
npm install @capgo/capacitor-contacts@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
``bash`
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.
$3
`typescript`
countContacts() => Promise
Count the total number of contacts on the device.
Returns: Promise<CountContactsResult>
Since: 1.0.0
--------------------
$3
`typescript`
createContact(options: CreateContactOptions) => Promise
Create a new contact programmatically.
| Param | Type | Description |
| ------------- | --------------------------------------------------------------------- | ----------------------------------- |
| options | CreateContactOptions | - The contact information to create |
Returns: Promise<CreateContactResult>
Since: 1.0.0
--------------------
$3
`typescript`
createGroup(options: CreateGroupOptions) => Promise
Create a new contact group.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------- | --------------------------------- |
| options | CreateGroupOptions | - The group information to create |
Returns: Promise<CreateGroupResult>
Since: 1.0.0
--------------------
$3
`typescript`
deleteContactById(options: DeleteContactByIdOptions) => Promise
Delete a contact by ID.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------------- | --------------------------------- |
| options | DeleteContactByIdOptions | - The ID of the contact to delete |
Since: 1.0.0
--------------------
$3
`typescript`
deleteGroupById(options: DeleteGroupByIdOptions) => Promise
Delete a group by ID.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------- | ------------------------------- |
| options | DeleteGroupByIdOptions | - The ID of the group to delete |
Since: 1.0.0
--------------------
$3
`typescript`
displayContactById(options: DisplayContactByIdOptions) => Promise
Display a contact using the native contact viewer.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------------- | ---------------------------------- |
| options | DisplayContactByIdOptions | - The ID of the contact to display |
Since: 1.0.0
--------------------
$3
`typescript`
displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise
Display the native create contact UI.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
| options | DisplayCreateContactOptions | - Optional pre-filled contact information |
Returns: Promise<DisplayCreateContactResult>
Since: 1.0.0
--------------------
$3
`typescript`
displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise
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
--------------------
$3
`typescript`
getAccounts() => Promise
Get all accounts available on the device.
Returns: Promise<GetAccountsResult>
Since: 1.0.0
--------------------
$3
`typescript`
getContactById(options: GetContactByIdOptions) => Promise
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
--------------------
$3
`typescript`
getContacts(options?: GetContactsOptions | undefined) => Promise
Get all contacts from the device.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------- | ----------------------------------------- |
| options | GetContactsOptions | - Optional filters and pagination options |
Returns: Promise<GetContactsResult>
Since: 1.0.0
--------------------
$3
`typescript`
getGroupById(options: GetGroupByIdOptions) => Promise
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
--------------------
$3
`typescript`
getGroups() => Promise
Get all contact groups.
Returns: Promise<GetGroupsResult>
Since: 1.0.0
--------------------
$3
`typescript`
isAvailable() => Promise
Check if contacts are available on the device.
Returns: Promise<IsAvailableResult>
Since: 1.0.0
--------------------
$3
`typescript`
isSupported() => Promise
Check if the plugin is supported on the current platform.
Returns: Promise<IsSupportedResult>
Since: 1.0.0
--------------------
$3
`typescript`
openSettings() => Promise
Open the device's contacts settings.
Since: 1.0.0
--------------------
$3
`typescript`
pickContact(options?: PickContactsOptions | undefined) => Promise
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
--------------------
$3
`typescript`
pickContacts(options?: PickContactsOptions | undefined) => Promise
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
--------------------
$3
`typescript`
updateContactById(options: UpdateContactByIdOptions) => Promise
Update an existing contact by ID.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------------- | ---------------------------------------- |
| options | UpdateContactByIdOptions | - The ID and updated contact information |
Since: 1.0.0
--------------------
$3
`typescript`
checkPermissions() => Promise
Check the current permission status for contacts.
Returns: Promise<PermissionStatus>
Since: 1.0.0
--------------------
$3
`typescript`
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise
Request permissions to access contacts.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------ |
| options | RequestPermissionsOptions | - Optional specific permissions to request |
Returns: Promise<PermissionStatus>
Since: 1.0.0
--------------------
$3
`typescript`
getPluginVersion() => Promise<{ version: string; }>
Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 1.0.0
--------------------
$3
#### 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 |
$3
#### Omit
Construct a type with the properties of T except for those in type 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.
#### PickContactResult
Alias for 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'
$3
This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader