@ethion/capacitor-contacts

Capacitor Plugin for accessing native Contacts on iOS and Android.

Features

• ✅ Read contacts from the device's address book
• ✅ Create contacts with full field support
• ✅ Delete contacts by ID
• ✅ Pick contacts using native UI picker
• ✅ Permission management with check and request methods
• ✅ Capacitor 6, 7, and 8 support
• ✅ Swift Package Manager (SPM) support for iOS
• ✅ CocoaPods support for iOS

Installation

npm install @ethion/capacitor-contacts
npx cap sync

Requirements

iOS

• iOS 15.0+ deployment target
• Xcode 15.0+
• Swift 5.9+

Android

• minSdk 24 (Android 7.0+)
• targetSdk 36
• Java 21

Setup

iOS

Add the following to your Info.plist:

<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to...</string>

Accessing notes in contact entries

To access notes in contact entries on iOS 13+, your app must have the com.apple.developer.contacts.notes entitlement. See Apple's documentation.

Android

Add the following permissions to your AndroidManifest.xml:

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

Quick Start

import { Contacts } from '@ethion/capacitor-contacts';

// Check permissions
const checkPermissions = async () => {
  const status = await Contacts.checkPermissions();
  console.log('Permission status:', status.contacts);
};

// Request permissions
const requestPermissions = async () => {
  const status = await Contacts.requestPermissions();
  console.log('Permission status:', status.contacts);
};

// Get all contacts
const getContacts = async () => {
  const result = await Contacts.getContacts({
    projection: {
      name: true,
      phones: true,
      emails: true,
    },
  });
  console.log('Contacts:', result.contacts);
};

// Create a contact
const createContact = async () => {
  const result = await Contacts.createContact({
    contact: {
      name: {
        given: 'John',
        family: 'Doe',
      },
      phones: [
        {
          type: 'mobile',
          number: '+1234567890',
        },
      ],
    },
  });
  console.log('Created contact ID:', result.contactId);
};

// Delete a contact
const deleteContact = async (contactId: string) => {
  await Contacts.deleteContact({ contactId });
};

// Pick a contact using native UI
const pickContact = async () => {
  const result = await Contacts.pickContact({
    projection: {
      name: true,
      phones: true,
    },
  });
  console.log('Picked contact:', result.contact);
};

API Reference

Methods

| Method | Description | |--------|-------------| | checkPermissions() | Check current permission status | | requestPermissions() | Request contacts permission | | getContact(options) | Get a single contact by ID | | getContacts(options) | Get all contacts matching projection | | createContact(options) | Create a new contact | | deleteContact(options) | Delete a contact by ID | | pickContact(options) | Open native contact picker |

Projection

Use projection to specify which contact fields to retrieve:

interface Projection {
  name?: boolean;        // Contact name fields
  organization?: boolean; // Company, job title, department
  birthday?: boolean;    // Birthday date
  note?: boolean;        // Contact notes
  phones?: boolean;      // Phone numbers
  emails?: boolean;      // Email addresses
  urls?: boolean;        // Website URLs
  postalAddresses?: boolean; // Physical addresses
  image?: boolean;       // Contact photo (base64)
}

Types

The plugin exports the following types:

• PhoneType - Phone number types (home, work, mobile, etc.)
• EmailType - Email types (home, work, etc.)
• PostalAddressType - Address types (home, work, etc.)
• ContactPayload - Contact data structure
• NamePayload, PhonePayload, EmailPayload, PostalAddressPayload, etc.

Breaking Changes in v8

• iOS: Requires iOS 15.0+ deployment target
• iOS: Full Swift Package Manager (SPM) support added
• Android: Requires minSdk 24, targetSdk/compileSdk 36
• Android: Gradle updated to 8.13.0, Gradle Wrapper to 8.14.3
• Node.js: Requires Node.js 22+ for Capacitor 8

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request at github.com/ethion-cloud/capacitor-contacts.