React Native Contacts

To contribute read CONTRIBUTING.md.

Ask questions on stackoverflow not the issue tracker.

Usage

getAll is a database intensive process, and can take a long time to complete depending on the size of the contacts list. Because of this, it is recommended you access the getAll method before it is needed, and cache the results for future use.

import Contacts from 'react-native-contacts';

Contacts.getAll((err, contacts) => {
  if (err) {
    throw err;
  }
  // contacts returned
})

See the full API for more methods.

Android permissions

On android you must request permissions beforehand

import { PermissionsAndroid } from 'react-native';
import Contacts from 'react-native-contacts';

PermissionsAndroid.request(
  PermissionsAndroid.PERMISSIONS.READ_CONTACTS,
  {
    'title': 'Contacts',
    'message': 'This app would like to view your contacts.'
  }
).then(() => {
  Contacts.getAll((err, contacts) => {
    if (err === 'denied'){
      // error
    } else {
      // contacts returned in Array
    }
  })
})

Installation

To use this module you have to install it and configure the permissions. Please read this entire section.

Automatic

with npm

npm install react-native-contacts --save

the --save is necessary for automatic linking

with yarn

yarn add react-native-contacts

and then do

react-native link

If you get an error about import Contacts from 'react-native-contacts'; is undefined. try manual linking below.

Manual

iOS

1. In XCode, in the project navigator, right click Libraries Add Files to [your project's name]
2. add ./node_modules/react-native-contacts/ios/RCTContacts.xcodeproj
3. In the XCode project navigator, select your project, select the Build Phases tab and in the Link Binary With Libraries section add libRCTContacts.a

Android

1. In android/settings.gradle

...
include ':react-native-contacts'
project(':react-native-contacts').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-contacts/android')

3. In android/app/build.gradle

...
dependencies {
    ...
    implementation project(':react-native-contacts')
}

4. register module (in MainApplication.java)

import com.rt2zz.reactnativecontacts.ReactNativeContacts; // <--- import

public class MainActivity extends ReactActivity {
  ......

  @Override
  protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            new ReactNativeContacts()); // <------ add this
  }
  ......
}

ProGuard

If you use Proguard, the snippet below on proguard-rules.pro Without it, your apk release version could failed

-keep class com.rt2zz.reactnativecontacts.** {*;}
-keepclassmembers class com.rt2zz.reactnativecontacts.** {*;}

Permissions

iOS

Add kit specific "permission" keys to your Xcode Info.plist file, in order to make requestPermission work. Otherwise your app crashes when requesting the specific permission.

Open Xcode > open ios/yourApp.xcodeproj > Info.plist > Add key Privacy - Contacts Usage Description with your kit specific permission. The value for the key is optional in development. If you submit to the App Store the value must explain why you need this permission.

Android

API 23+

Android requires allowing permissions with https://facebook.github.io/react-native/docs/permissionsandroid.html The READ_CONTACTS permission is automatically added to AndroidManifest.xml, so you just need request it. If your app creates contacts add WRITE_CONTACTS permission to AndroidManifest.xml and request the permission at runtime.

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

API 22 and below

Add READ_PROFILE and/or WRITE_PROFILE permissions to AndroidManifest.xml

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

API

• getAll (callback) - returns all contacts as an array of objects
• getAllWithoutPhotos - same as getAll on Android, but on iOS it will not return uris for contact photos (because there's a significant overhead in creating the images)
• getPhotoForId(contactId, callback) - returns a URI (or null) for a contacts photo
• addContact (contact, callback) - adds a contact to the AddressBook.
• openContactForm (contact, callback) - create a new contact and display in contactsUI.
• openExistingContact (contact, callback) - where contact is an object with a valid recordID
• updateContact (contact, callback) - where contact is an object with a valid recordID
• deleteContact (contact, callback) - where contact is an object with a valid recordID
• getContactsMatchingString (string, callback) - where string is any string to match a name (first, middle, family) to
• checkPermission (callback) - checks permission to access Contacts ios only
• requestPermission (callback) - request permission to access Contacts ios only
• writePhotoToPath (callback) - writes the contact photo to a given path android only

Callbacks follow node-style:

callback <Function>
  err <Error>
  response <Object>

Example Contact Record

{
  recordID: '6b2237ee0df85980',
  company: "",
  emailAddresses: [{
    label: "work",
    email: "[email protected]",
  }],
  familyName: "Jung",
  givenName: "Carl",
  jobTitle: "",
  note: 'some text',
  urlAddresses: [{
    label: "home",
    url: "www.jung.com",
  }],
  middleName: "",
  phoneNumbers: [{
    label: "mobile",
    number: "(555) 555-5555",
  }],
  hasThumbnail: true,
  thumbnailPath: 'content://com.android.contacts/display_photo/3',
  postalAddresses: [
    {
      street: '123 Fake Street',
      city: 'Sample City',
      state: 'CA',
      region: 'CA',
      postCode: '90210',
      country: 'USA',
      label: 'home'
    }
  ],
  birthday: {"year": 1988, "month": 0, "day": 1 }
}

NOTE

• on Android versions below 8 the entire display name is passed in the givenName field. middleName and familyName will be "".

Adding Contacts

Currently all fields from the contact record except for thumbnailPath are supported for writing

var newPerson = {
  emailAddresses: [{
    label: "work",
    email: "[email protected]",
  }],
  familyName: "Nietzsche",
  givenName: "Friedrich",
}

Contacts.addContact(newPerson, (err) => {
  if (err) throw err;
  // save successful
})

Open Contact Form

Currently all fields from the contact record except for thumbnailPath are supported for writing

var newPerson = {
  emailAddresses: [{
    label: "work",
    email: "[email protected]",
  }],
  familyName: "Nietzsche",
  givenName: "Friedrich",
}

Contacts.openContactForm(newPerson, (err, contact) => {
  if (err) throw err;
  // contact has been saved
})

You may want to edit the contact before saving it into your phone book. So using openContactForm allow you to prompt default phone create contacts UI and the new to-be-added contact will be display on the contacts UI view. Click save or cancel button will exit the contacts UI view.

Updating Contacts

Example

Contacts.getAll((err, contacts) => {
  if (err) {
    throw err;
  }

  // update the first record
  let someRecord = contacts[0]
  someRecord.emailAddresses.push({
    label: "junk",
    email: "[email protected]",
  })
  Contacts.updateContact(someRecord, (err) => {
    if (err) throw err;
    // record updated
  })
})

Update reference contacts by their recordID (as returned by the OS in getContacts). Apple does not guarantee the recordID will not change, e.g. it may be reassigned during a phone migration. Consequently you should always grab a fresh contact list with getContacts before performing update operations.

Bugs

There are issues with updating contacts on Android:

1. custom labels get overwritten to "Other",
2. postal address update code doesn't exist. (it exists for addContact) See morenoh149#332 (comment) for current discussions.

Delete Contacts

You can delete a record using only it's recordID

Contacts.deleteContact({recordID: 1}, (err, recordId) => {
  if (err) {
    throw err;
  }
  // contact deleted
})

Or by passing the full contact object with a recordID field.

Contacts.deleteContact(contact, (err, recordId) => {
  if (err) {
    throw err;
  }
  // contact deleted
})

Displaying Thumbnails

The thumbnailPath is the direct URI for the temp location of the contact's cropped thumbnail image.

<Image source={{uri: contact.thumbnailPath}} />

Permissions Methods (optional)

checkPermission (callback) - checks permission to access Contacts.
requestPermission (callback) - request permission to access Contacts.

Usage as follows:

Contacts.checkPermission((err, permission) => {
  if (err) throw err;

  // Contacts.PERMISSION_AUTHORIZED || Contacts.PERMISSION_UNDEFINED || Contacts.PERMISSION_DENIED
  if (permission === 'undefined') {
    Contacts.requestPermission((err, permission) => {
      // ...
    })
  }
  if (permission === 'authorized') {
    // yay!
  }
  if (permission === 'denied') {
    // x.x
  }
})

These methods are only useful on iOS. For Android you'll have to use https://facebook.github.io/react-native/docs/permissionsandroid.html

These methods do not re-request permission if permission has already been granted or denied. This is a limitation in iOS, the best you can do is prompt the user with instructions for how to enable contacts from the phone settings page Settings > [app name] > contacts.

Maintainers

Harry Moreno

LICENSE

MIT License