Announcing the Capacitor Contacts Plugin¶

Today we are excited to announce our brand new Capacitor Contacts plugin. This plugin allows you to access the device's contacts and provides cross-platform support for Android, iOS, and Web. The project is now available for all Capawesome Insiders.

Let's take a quick look at the API and how you can use the plugin to retrieve and manage contacts.

Installation¶

See Getting started with Insiders and follow the instructions to install the plugin. After that, follow the platform-specific instructions in the sections Android and iOS.

Usage¶

Let's take a look at the basic usage of the plugin. You can find the complete API reference in the API section of the documentation.

Create a contact¶

First, let's create a new contact. You can use the createContact(...) method to create a new contact:

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

const createContact = async () => {
  const createContact = async () => {
  return Contacts.createContact({
    contact: {
      givenName: 'John',
      familyName: 'Doe',
      emailAddresses: [
        {
          value: '[email protected]',
          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
        }
      ]
    }
  });
};

This method takes a Contact object as a parameter, which contains the contact's information such as name, email addresses, phone numbers, and postal addresses.

Retrieve contacts¶

You can retrieve contacts from the device's address book using the getContacts(...) method:

import { Contacts } from "@capawesome-team/capacitor-contacts";

const getContacts = async () => {
  const { contacts } = await Contacts.getContacts({
    fields: ['givenName', 'familyName', 'emailAddresses', 'phoneNumbers', 'postalAddresses'],
  });
  return contacts;
};

This method returns an array of contacts, each containing the requested fields. You can specify which fields you want to retrieve using the fields parameter. This is useful to limit the amount of data returned and improve performance.

There is also a getContactById(...) method that allows you to retrieve a contact by its ID:

import { Contacts } from "@capawesome-team/capacitor-contacts";

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

This method takes the contact ID as a parameter and returns the contact with the specified ID. This is useful if you want to retrieve a specific contact without having to search for it in the list of all contacts.

Delete a contact¶

You can delete a contact using the deleteContact(...) method:

import { Contacts } from "@capawesome-team/capacitor-contacts";

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

This method takes the contact ID as a parameter and deletes the contact with the specified ID. This is useful if you want to remove a contact from the device's address book.

Pick a contact¶

You can let the user pick a contact from the device's address book using the pickContact(...) method:

import { Contacts } from "@capawesome-team/capacitor-contacts";

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

This method opens the device's contact picker and returns the selected contact. This way, you can let the user select a contact while respecting their privacy and without having to implement your own contact picker UI.

Conclusion¶

We hope you are as excited as we are about the new Capacitor Contacts plugin. Be sure to check out the API Reference to see what else you can do with this plugin. If you are missing any features, just create a feature request in the GitHub repository. Make sure you follow us on X so you don't miss any future updates.