---
title: Announcing the Capacitor Contacts Plugin
description: Capacitor plugin to read, write, or select device contacts with advanced features like filtering and pagination. 
date: 
  created: 2025-03-24
  updated: 2026-07-14
authors:
  - robingenz
categories:
  - Announcements
  - Capacitor
  - SDKs
links:
  - Capacitor Contacts: sdks/capacitor/contacts.md
faq: true
---

# Capacitor Contacts Plugin for iOS & Android

Reading, creating, and updating a user's contacts from a Capacitor app usually means wiring up two very different native APIs. The [Capacitor Contacts plugin](../../sdks/capacitor/contacts.md) gives you a single API to access the device's contacts — including a native contact picker, accounts, and groups — with cross-platform support for Android, iOS, and Web. It's available to all Capawesome [Insiders](../../insiders/index.md).

<!-- more -->

Let's take a quick look at the [API](../../sdks/capacitor/contacts.md#api) and how you can use the plugin to retrieve and manage contacts.

## Installation

To install the Capacitor Contacts plugin, please refer to the [Installation](../../sdks/capacitor/contacts.md/#installation) section in the plugin documentation.

## Usage

Let's take a look at the basic usage of the plugin. You can find the complete API reference in the [API](../../sdks/capacitor/contacts.md#api) section of the documentation.

### Create a contact

First, let's create a new contact. You can use the [`createContact(...)`](../../sdks/capacitor/contacts.md#createcontact) method to create a new contact:

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

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      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
        }
      ]
    }
  });
};
```

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(...)`](../../sdks/capacitor/contacts.md#getcontacts) method:

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

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

### Update a contact

To update an existing contact, you can use the [`updateContact(...)`](../../sdks/capacitor/contacts.md#updatecontact) method:

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

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

This method takes the contact ID and a `Contact` object as parameters. You can update the contact's information such as name, email addresses, phone numbers, and postal addresses. This is useful if you want to modify an existing contact's information.

???+ warning "All contact fields are required"

    All contact fields are required to be provided, even if they are not updated. Fields that are not provided will be removed from the contact. This bevavior will be changed in v8.0.0 of the plugin. From then on, only the fields that are provided will be updated, and the other fields will remain unchanged. If you want to remove a field, you can set it to `null`.

### Delete a contact

You can delete a contact using the [`deleteContact(...)`](../../sdks/capacitor/contacts.md#deletecontact) method:

```typescript
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(...)`](../../sdks/capacitor/contacts.md#pickcontact) method:

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

### Accounts

On Android, you can retrieve the accounts associated with the device using the [`getAccounts(...)`](../../sdks/capacitor/contacts.md#getaccounts) method:

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

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

You can then create a contact and associate it with an account using the `account` property of the `Contact` object:

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

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      account: {
        name: 'john@doe.tld',
        type: 'com.google'
      },
      givenName: 'John',
      familyName: 'Doe'
    },
  });
};
```

### Groups

On iOS, you can retrieve the groups associated with the device using the [`getGroups(...)`](../../sdks/capacitor/contacts.md#getgroups) method:

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

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

Just like with accounts, you can create a contact and associate it with one (or more) group(s) using the `groupIds` property of the `Contact` object:

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

const createContact = async () => {
  return Contacts.createContact({
    contact: {
      groupIds: ['904DE809-D144-4562-8552-DFEB91F0E4BD:ABGroup'],
      givenName: 'John',
      familyName: 'Doe'
    },
  });
};
```

You can even create a new group using the [`createGroup(...)`](../../sdks/capacitor/contacts.md#creategroup) method:

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

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

## FAQ

### Which platforms does the Capacitor Contacts plugin support?

The plugin provides cross-platform support for Android, iOS, and the Web through a single API.

### Can I let users pick a contact without reading their whole address book?

Yes. `pickContact()` opens the device's native contact picker and returns only the contact the user selects, so you can respect their privacy without requesting access to the full address book.

### Can I limit which contact fields are returned?

Yes. `getContacts(...)` takes a `fields` array, so you only fetch the fields you need (for example `givenName`, `phoneNumbers`, or `emailAddresses`). This reduces the amount of data returned and improves performance.

### Does the plugin support Android accounts and iOS groups?

Yes. On Android you can read accounts with `getAccounts()` and associate a new contact with one; on iOS you can read groups with `getGroups()`, create groups with `createGroup()`, and add contacts to them.

### How do I call, text, or email a contact?

The Contacts plugin gives you the contact's details; to act on them, hand the phone number or email address to one of the composer plugins. The [Capacitor Phone Dialer plugin](../../sdks/capacitor/phone-dialer.md) opens the native dialer prefilled with a number, the [Capacitor SMS Composer plugin](../../sdks/capacitor/sms-composer.md) opens the SMS composer with recipients and a message body, and the [Capacitor Mail Composer plugin](../../sdks/capacitor/mail-composer.md) opens the email composer prefilled with recipients, subject, body, and attachments. Each one hands control to the user's own app, so nothing is sent without their confirmation.

## Related Posts

- [Alternative to the Capacitor Community Contacts plugin](./alternative-to-capacitor-community-contacts-plugin.md)
- [Exploring the Capacitor Contacts API](./exploring-the-capacitor-contacts-api.md)

## Conclusion

The [Capacitor Contacts plugin](../../sdks/capacitor/contacts.md) gives you full create, read, update, and delete access to device contacts — plus a native picker, accounts, and groups — behind one cross-platform API for Android, iOS, and Web.

**Missing a feature?** [Create a feature request](https://github.com/capawesome-team/capacitor-plugins/issues/new/choose){:target="_blank"} in our [GitHub repository](https://github.com/capawesome-team/capacitor-plugins){:target="_blank"}. You can also explore the full [API Reference](../../sdks/capacitor/contacts.md#api).

Join the Capawesome [Discord](https://discord.gg/VCXxSVjefW){:target="_blank"} server for questions and subscribe to the Capawesome [newsletter](https://capawesome.io/newsletter/){:target="_blank"} to stay updated.