@capawesome-team/capacitor-contacts¶

Capacitor plugin to read, write, or select device contacts.

Features¶

We are proud to offer one of the most complete and feature-rich Capacitor plugins for contacts. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS and Web.
📇 Contacts: Create, update, delete and retrieve device contacts.
📌 Groups: Create, update, delete and retrieve contact groups on iOS.
🎫 Accounts: Add contacts to specific accounts on Android.
📖 Pagination: Paginate through contacts to avoid performance issues.
🔍 Filtering: Filter contacts by ID, email, phone number, etc. (Coming soon!)
📱 Native Modals: Create, update and display contacts in native modals.
🎯 Picking: Let the user select a device contact.
🖼️ Photos: Set, update and retrieve contact photos.
📦 SPM: Supports Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.
⭐️ Support: Priority support from the Capawesome Team.

Missing a feature? Just open an issue and we'll add it for you!

Compatibility¶

Plugin Version	Capacitor Version	Status
7.x.x	>=7.x.x	Active support

Installation¶

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, install the package:

npm install @capawesome-team/capacitor-contacts
npx cap sync

Android¶

Permissions¶

This API requires the following permissions be added to your AndroidManifest.xml before or after the application tag:

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

Proguard¶

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

iOS¶

Privacy Descriptions¶

Add the NSContactsUsageDescription key to the ios/App/App/Info.plist file, which tells the user why your app needs access to the user's contacts:

<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to display them in the app.</string>

Entitlements¶

To access the note field of a contact, your app must have the com.apple.developer.contacts.notes entitlement. Check out the Apple documentation for more information.

If you don't need access to the note field, you can skip this step.

Configuration¶

No configuration required for this plugin.

Usage¶

import { 
  Contacts,
  EmailAddressType,
  PhoneNumberType,
  PostalAddressType
} from '@capawesome-team/capacitor-contacts';

const countContacts = async () => {
  const { total } = await Contacts.countContacts();
  return total;
};

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      birthday: {
        day: 1,
        month: 1,
        year: 1990
      },
      givenName: 'John',
      familyName: 'Doe',
      emailAddresses: [
        {
          value: 'mail@example.com',
          type: EmailAddressType.Home,
          isPrimary: true
        }
      ],
      phoneNumbers: [
        {
          value: '1234567890',
          type: PhoneNumberType.Mobile,
          isPrimary: true
        }
      ],
      postalAddresses: [
        {
          street: '123 Main St',
          city: 'Springfield',
          state: 'IL',
          postalCode: '62701',
          country: 'USA',
          type: PostalAddressType.Home,
          isPrimary: true
        }
      ]
    }
  });
};

const createGroup = async () => {
  return Contacts.createGroup({
    group: {
      name: 'My Group'
    }
  });
};

const deleteContactById = async (id: string) => {
  await Contacts.deleteContactById({ id });
};

const deleteGroupById = async (id: string) => {
  await Contacts.deleteGroupById({ id });
};

const displayContactById = async (id: string) => {
  await Contacts.displayContactById({ id });
};

const displayCreateContact = async () => {
  const { id } = await Contacts.displayCreateContact({
    contact: {
      givenName: 'John',
      familyName: 'Doe'
    }
  });
  return id;
};

const displayUpdateContactById = async (id: string) => {
  await Contacts.displayUpdateContactById({ id });
};

const getAccounts = async () => {
  const { accounts } = await Contacts.getAccounts();
  return accounts;
};

const getContactById = async (id: string) => {
  const { contact } = await Contacts.getContactById({ id });
  return contact;
};

const getContacts = async () => {
  const { contacts } = await Contacts.getContacts();
  return contacts;
};

const getGroupById = async (id: string) => {
  const { group } = await Contacts.getGroupById({ id });
  return group;
};

const getGroups = async () => {
  const { groups } = await Contacts.getGroups();
  return groups;
};

const isSupported = async () => {
  const { isSupported } = await Contacts.isSupported();
  return isSupported;
};

const pickContacts = async () => {
  const { contacts } = await Contacts.pickContacts();
  return contacts;
};

const updateContactById = async (id: string) => {
  await Contacts.updateContactById({
    id,
    contact: {
      givenName: 'John',
      familyName: 'Doe'
    }
  });
};

const checkPermissions = async () => {
  return Contacts.checkPermissions();
};

const requestPermissions = async () => {
  return Contacts.requestPermissions();
};

API¶

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

countContacts()¶

countContacts() => Promise<CountContactsResult>

Count the number of contacts on the device.

Only available on Android and iOS.

Returns: Promise<CountContactsResult>

Since: 7.4.0

createContact(...)¶

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

Create a new contact on the device.

Only available on Android and iOS.

Param	Type
`options`	`CreateContactOptions`

Returns: Promise<CreateContactResult>

Since: 7.0.0

createGroup(...)¶

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

Create a new contact group on the device.

Only available on iOS.

Param	Type
`options`	`CreateGroupOptions`

Returns: Promise<CreateGroupResult>

Since: 7.4.0

deleteContactById(...)¶

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

Delete a contact from the device.

Only available on Android and iOS.

Param	Type
`options`	`DeleteContactByIdOptions`

Since: 7.0.0

deleteGroupById(...)¶

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

Delete a contact group from the device.

Only available on iOS.

Param	Type
`options`	`DeleteGroupByIdOptions`

Since: 7.4.0

displayContactById(...)¶

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

Display an existing contact by identifier.

Only available on Android and iOS.

Param	Type
`options`	`DisplayContactByIdOptions`

Since: 7.4.0

displayCreateContact(...)¶

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

Open a native modal to create a new device contact.

This allows the user to update the contact information before saving it and does not require any permissions.

Only available on Android and iOS.

Param	Type
`options`	`DisplayCreateContactOptions`

Returns: Promise<DisplayCreateContactResult>

Since: 7.2.0

displayUpdateContactById(...)¶

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

Open a native modal to update a contact.

Only available on Android and iOS.

Param	Type
`options`	`DisplayUpdateContactByIdOptions`

Since: 7.4.0

getAccounts()¶

getAccounts() => Promise<GetAccountsResult>

List all accounts on the device.

Only available on Android.

Returns: Promise<GetAccountsResult>

Since: 7.4.0

getContactById(...)¶

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

Find a contact by identifier.

Only available on Android and iOS.

Param	Type
`options`	`GetContactByIdOptions`

Returns: Promise<GetContactByIdResult>

Since: 7.0.0

getContacts(...)¶

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

List all contacts on the device.

Only available on Android and iOS.

Param	Type
`options`	`GetContactsOptions`

Returns: Promise<GetContactsResult>

Since: 7.0.0

getGroupById(...)¶

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

Find a contact group by identifier.

Only available on iOS.

Param	Type
`options`	`GetGroupByIdOptions`

Returns: Promise<GetGroupByIdResult>

Since: 7.4.0

getGroups()¶

getGroups() => Promise<GetGroupsResult>

List all contact groups on the device.

Only available on iOS.

Returns: Promise<GetGroupsResult>

Since: 7.4.0

isSupported()¶

isSupported() => Promise<IsSupportedResult>

Check if the contacts API is available on the device.

Returns: Promise<IsSupportedResult>

Since: 7.0.0

pickContact(...)¶

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

Open the contact picker to select a contact from the device.

Param	Type
`options`	`PickContactsOptions`

Returns: Promise<PickContactsResult>

Since: 7.0.0

pickContacts(...)¶

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

Open the contact picker to select a contact from the device.

Param	Type
`options`	`PickContactsOptions`

Returns: Promise<PickContactsResult>

Since: 7.4.0

updateContactById(...)¶

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

Update an existing contact on the device.

Only available on Android and iOS.

Param	Type
`options`	`UpdateContactByIdOptions`

Since: 7.4.0

checkPermissions()¶

checkPermissions() => Promise<PermissionStatus>

Check permissions to access contacts.

Only available on Android and iOS.

Returns: Promise<PermissionStatus>

Since: 7.0.0

requestPermissions(...)¶

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

Request permissions to access contacts.

Only available on Android and iOS.

Param	Type
`options`	`RequestPermissionsOptions`

Returns: Promise<PermissionStatus>

Since: 7.0.0

Interfaces¶

CountContactsResult¶

Prop	Type	Description	Since
`total`	`number`	The number of contacts.	7.4.0

CreateContactResult¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the created contact.	7.0.0

CreateContactOptions¶

Prop	Type	Description	Since
`contact`	`Omit<Contact, 'id'>`	The contact to create.	7.0.0

Contact¶

Prop	Type	Description	Since
`account`	`Account`	The account associated with the contact. Only available on Android.	7.4.0
`birthday`	`Birthday`	The birthday of the contact.	7.3.0
`emailAddresses`	`EmailAddress[]`	The list of email addresses for the contact.	7.0.0
`familyName`	`string`	The family name of the contact. Only available on Android and iOS.	7.0.0
`givenName`	`string`	The given name of the contact. Only available on Android and iOS.	7.0.0
`groupIds`	`string[]`	The identifier of the groups the contact belongs to. Only available on iOS.	7.4.0
`id`	`string`	The identifier for the contact. Only available on Android and iOS.	7.0.0
`jobTitle`	`string`	The job title of the contact. Only available on Android and iOS.	7.0.0
`middleName`	`string`	The middle name of the contact. Only available on Android and iOS.	7.0.0
`fullName`	`string`	The full name of the contact. Only available on Web.	7.0.0
`namePrefix`	`string`	The name prefix of the contact. Only available on Android and iOS.	7.0.0
`nameSuffix`	`string`	The name suffix of the contact. Only available on Android and iOS.	7.0.0
`note`	`string`	A note about the contact. Only available on Android and iOS.	7.0.0
`organizationName`	`string`	The organization name of the contact. Only available on Android and iOS.	7.0.0
`phoneNumbers`	`PhoneNumber[]`	The list of phone numbers for the contact.	7.0.0
`photo`	`string`	The photo of the contact as a base64 string. Only available on Android and iOS.	7.0.0
`postalAddresses`	`PostalAddress[]`	The list of postal addresses for the contact.	7.0.0
`urlAddresses`	`UrlAddress[]`	The list of URL addresses for the contact. Only available on Android and iOS.	7.0.0

Account¶

Prop	Type	Description	Since
`name`	`string`	The account name. Only available on Android.	7.4.0
`type`	`string`	The account type. Only available on Android.	7.4.0

Birthday¶

Prop	Type	Description	Since
`day`	`number`	The day of the birthdate.	7.3.0
`month`	`number`	The month of the birthdate.	7.3.0
`year`	`number`	The year of the birthdate. On Android, this must be provided if the `day` and `month` are provided when using the `displayCreateContact(...)` method.	7.3.0

EmailAddress¶

Prop	Type	Description	Default	Since
`isPrimary`	`boolean`	Whether this email address is the primary one for the contact.	`false`	7.0.0
`label`	`string`	A custom label for the email address. On iOS, this label is only set if the type is `EmailAddressType.Custom`.		7.0.0
`type`	`EmailAddressType`	The type of email address.	`EmailAddressType.Other`	7.0.0
`value`	`string`	The email address.		7.0.0

PhoneNumber¶

Prop	Type	Description	Default	Since
`isPrimary`	`boolean`	Whether this email address is the primary one for the contact.		7.0.0
`label`	`string`	A custom label for the phone number. On iOS, this label is only set if the type is `PhoneNumberType.Custom`.		7.0.0
`type`	`PhoneNumberType`	The type of phone number.	`PhoneNumberType.Other`	7.0.0
`value`	`string`	The phone number.

PostalAddress¶

Prop	Type	Description	Default	Since
`city`	`string`	The city for the postal address.		7.0.0
`country`	`string`	The country for the postal address.		7.0.0
`formatted`	`string`	The formatted postal address.		7.0.0
`isoCountryCode`	`string`	The ISO country code for the postal address. Only available on iOS.		7.0.0
`isPrimary`	`boolean`	Whether this postal address is the primary one for the contact. Only available on Android and iOS.	`false`	7.0.0
`label`	`string`	A custom label for the postal address. On iOS, this label is only set if the type is `PostalAddressType.Custom`. Only available on Android and iOS.		7.0.0
`neighborhood`	`string`	The neighborhood for the postal address. Only available on Android and iOS.		7.0.0
`postalCode`	`string`	The postal code for the postal address. Only available on Android and iOS.		7.0.0
`state`	`string`	The state for the postal address.		7.0.0
`street`	`string`	The street for the postal address. Only available on Android and iOS.		7.0.0
`type`	`PostalAddressType`	The type of postal address. Only available on Android and iOS.	`PostalAddressType.Other`	7.0.0

UrlAddress¶

Prop	Type	Description
`value`	`string`	The URL address.

CreateGroupResult¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the created group.	7.4.0

CreateGroupOptions¶

Prop	Type	Description	Since
`group`	`Omit<Group, 'id'>`	The group to create.	7.4.0

Group¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the group.	7.4.0
`name`	`string`	The name of the group.	7.4.0

DeleteContactByIdOptions¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the contact.	7.0.0

DeleteGroupByIdOptions¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the group.	7.4.0

DisplayContactByIdOptions¶

Prop	Type	Description	Since
`id`	`string`	The identifier of the contact to display.	7.4.0

DisplayCreateContactResult¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the created contact. On Android, you need the `readContacts` permission to return the identifier.	7.4.0

DisplayCreateContactOptions¶

Prop	Type	Description	Since
`contact`	`Omit<Contact, 'id'>`	The contact to display in the create contact modal.	7.2.0

DisplayUpdateContactByIdOptions¶

Prop	Type	Description	Since
`id`	`string`	The identifier of the contact to update.	7.4.0

GetAccountsResult¶

Prop	Type	Description	Since
`accounts`	`Account[]`	An array of available accounts on the device.	7.4.0

GetContactByIdResult¶

Prop	Type
`contact`	`Contact \| null`

GetContactByIdOptions¶

Prop	Type	Description	Default	Since
`fields`	`(keyof Contact)[]`	The fields to return for the contact.	`['birthday', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']`	7.1.0
`id`	`string`	The identifier for the contact.		7.0.0

GetContactsResult¶

Prop	Type	Description	Since
`contacts`	`Contact[]`	The list of contacts on the device. Note: No photos are returned to avoid performance issues.	7.0.0

GetContactsOptions¶

Prop	Type	Description	Default	Since
`fields`	`(keyof Contact)[]`	The fields to return for the contact.	`['emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']`	7.1.0
`limit`	`number`	Limit the number of contacts returned.	`1000`	7.4.0
`offset`	`number`	Offset the number of contacts returned.	`0`	7.4.0

GetGroupByIdResult¶

Prop	Type	Description	Since
`group`	`Group \| null`	The group with the specified identifier.	7.4.0

GetGroupByIdOptions¶

Prop	Type	Description	Since
`id`	`string`	The identifier for the group.	7.4.0

GetGroupsResult¶

Prop	Type	Description	Since
`groups`	`Group[]`	The list of groups on the device.	7.4.0

IsSupportedResult¶

Prop	Type	Description	Since
`isSupported`	`boolean`	Whether the contacts API is available on the device. This is always `true` on Android and iOS.	7.0.0

PickContactsResult¶

Prop	Type	Description	Since
`contacts`	`Contact[]`	The selected contacts. Empty if none were selected.	7.0.0

PickContactsOptions¶

Prop	Type	Description	Default	Since
`fields`	`(keyof Contact)[]`	The fields to return for the contact. Only available on Android and iOS.	`['birthday', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses']`	7.4.0
`multiple`	`boolean`	Whether to allow selecting multiple contacts. Only available on Web.	`false`	7.0.0

UpdateContactByIdOptions¶

Prop	Type	Description	Since
`contact`	`Omit<Contact, 'id'>`	The updated contact information. Attention: All fields are required to be provided, even if they are not updated. Fields that are not provided will be removed from the contact.	7.4.0
`id`	`string`	The identifier for the contact.	7.4.0

PermissionStatus¶

Prop	Type	Description	Since
`readContacts`	`ContactsPermissionState`	Permission state for reading contacts. Only available on Android and iOS.	7.0.0
`writeContacts`	`ContactsPermissionState`	Permission state for writing contacts. Only available on Android and iOS.	7.0.0

RequestPermissionsOptions¶

Prop	Type	Description	Default	Since
`permissions`	`ContactsPermissionType[]`	The permissions to request.	`['readContacts', 'writeContacts']`	7.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

{

}

Exclude¶

Exclude from T those types that are assignable to U

T extends U ? never : T

ContactField¶

keyof Contact

PermissionState¶

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

ContactsPermissionType¶

'readContacts' | 'writeContacts'

Enums¶

EmailAddressType¶

Members	Value	Description	Since
`Custom`	`'CUSTOM'`		7.0.0
`Home`	`'HOME'`		7.0.0
`ICloud`	`'ICLOUD'`	Only available on iOS.	7.0.0
`Mobile`	`'MOBILE'`	Only available on Android.	7.0.0
`Other`	`'OTHER'`		7.0.0
`School`	`'SCHOOL'`	Only available on iOS.	7.0.0
`Work`	`'WORK'`		7.0.0

PhoneNumberType¶

Members	Value	Description	Since
`Assistant`	`'ASSISTANT'`	Only available on Android.	7.0.0
`Callback`	`'CALLBACK'`	Only available on Android.	7.0.0
`Car`	`'CAR'`	Only available on Android.	7.0.0
`CompanyMain`	`'COMPANY_MAIN'`	Only available on Android.	7.0.0
`Custom`	`'CUSTOM'`		7.0.0
`FaxHome`	`'FAX_HOME'`		7.0.0
`FaxOther`	`'FAX_OTHER'`		7.0.0
`FaxWork`	`'FAX_WORK'`		7.0.0
`Home`	`'HOME'`		7.0.0
`IPhone`	`'IPHONE'`	Only available on iOS.	7.0.0
`Isdn`	`'ISDN'`	Only available on Android.	7.0.0
`Main`	`'MAIN'`		7.0.0
`Mms`	`'MMS'`	Only available on Android.	7.0.0
`Mobile`	`'MOBILE'`		7.0.0
`Other`	`'OTHER'`		7.0.0
`Pager`	`'PAGER'`		7.0.0
`Radio`	`'RADIO'`	Only available on Android.	7.0.0
`Telex`	`'TELEX'`	Only available on Android.	7.0.0
`TtyTdd`	`'TTY_TDD'`	Only available on Android.	7.0.0
`Work`	`'WORK'`		7.0.0
`WorkMobile`	`'WORK_MOBILE'`	Only available on Android.	7.0.0
`WorkPager`	`'WORK_PAGER'`	Only available on Android.	7.0.0

PostalAddressType¶

Members	Value	Since
`Custom`	`'CUSTOM'`	7.0.0
`Home`	`'HOME'`	7.0.0
`Other`	`'OTHER'`	7.0.0
`Work`	`'WORK'`	7.0.0

Changelog¶

See CHANGELOG.md.

Breaking Changes¶

See BREAKING.md.

License¶

See LICENSE.

@capawesome-team/capacitor-contacts¶

Features¶

Compatibility¶

Installation¶

Android¶

Permissions¶

Proguard¶

iOS¶

Privacy Descriptions¶

Entitlements¶

Configuration¶

Usage¶

API¶

countContacts()¶

createContact(...)¶

createGroup(...)¶

deleteContactById(...)¶

deleteGroupById(...)¶

displayContactById(...)¶

displayCreateContact(...)¶

displayUpdateContactById(...)¶

getAccounts()¶

getContactById(...)¶

getContacts(...)¶

getGroupById(...)¶

getGroups()¶

isSupported()¶

pickContact(...)¶

pickContacts(...)¶

updateContactById(...)¶

checkPermissions()¶

requestPermissions(...)¶

Interfaces¶

CountContactsResult¶

CreateContactResult¶

CreateContactOptions¶

Contact¶

Account¶

Birthday¶

EmailAddress¶

PhoneNumber¶

PostalAddress¶

UrlAddress¶

CreateGroupResult¶

CreateGroupOptions¶

Group¶

DeleteContactByIdOptions¶

DeleteGroupByIdOptions¶

DisplayContactByIdOptions¶

DisplayCreateContactResult¶

DisplayCreateContactOptions¶

DisplayUpdateContactByIdOptions¶

GetAccountsResult¶

GetContactByIdResult¶

GetContactByIdOptions¶

GetContactsResult¶

GetContactsOptions¶

GetGroupByIdResult¶

GetGroupByIdOptions¶

GetGroupsResult¶

IsSupportedResult¶

PickContactsResult¶

PickContactsOptions¶

UpdateContactByIdOptions¶

PermissionStatus¶

RequestPermissionsOptions¶

Type Aliases¶

Omit¶

Pick¶

Exclude¶

ContactField¶

PickContactOptions¶

PickContactResult¶

ContactsPermissionState¶

PermissionState¶

ContactsPermissionType¶

Enums¶

EmailAddressType¶

PhoneNumberType¶

PostalAddressType¶