@capawesome-team/capacitor-contacts¶

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

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. (Coming soon!)
🎫 Accounts: Add contacts to specific accounts on Android. (Coming soon!)
📖 Pagination: Paginate through contacts to avoid performance issues. (Coming soon!)
🔍 Filtering: Filter contacts by ID, email, phone number, etc. (Coming soon!)
📱 Native Modals: Create, update and display contacts in native modals. (Coming soon!)
🎯 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: First-class support from the Capawesome Team.

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 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 getContacts = async () => {
  const { contacts } = await Contacts.getContacts();
  return contacts;
};

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

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

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

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

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

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

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

displayCreateContact(...)¶

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

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`

Since: 7.2.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

isSupported()¶

isSupported() => Promise<IsSupportedResult>

Check if the contacts API is available on the device.

Returns: Promise<IsSupportedResult>

Since: 7.0.0

pickContact(...)¶

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

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

Only available on web.

Param	Type
`options`	`PickContactOptions`

Returns: Promise<PickContactResult>

Since: 7.0.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¶

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

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.

DeleteContactByIdOptions¶

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

DisplayCreateContactOptions¶

Prop	Type	Description	Since
`contact`	`Omit<Contact, 'id'>`	The contact to display in the create contact modal.	7.2.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

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

PickContactResult¶

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

PickContactOptions¶

Prop	Type	Description	Default	Since
`multiple`	`boolean`	Whether to allow selecting multiple contacts. Only available on Web.	`false`	7.0.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

ContactsPermissionState¶

PermissionState | 'limited'

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.

License¶

See LICENSE.