Necessary Package Manager

    react-native-contacts
    TypeScript icon, indicating that this package has built-in type declarations

    7.0.4 • Public • Published

    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().then(contacts => {
      // 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.',
        'buttonPositive': 'Please accept bare mortal'
      }
    )
      .then(Contacts.getAll()
        .then((contacts) => {
            // work with contacts
              console.log(contacts)
            })
              .catch((e) => {
                  console.log(e)
              }))

    Installation

    Please read this entire section.

    npm

    npm install react-native-contacts --save
    

    yarn

    yarn add react-native-contacts
    

    You no longer need to include the pod line in the PodFile since V7.0.0+, we now support autolinking!

    If you were previously using manually linking follow these steps to upgrade

    react-native unlink react-native-contacts
    npm install latest version of react-native-contacts
    Your good to go!
    

    react native version 60 and above

    If you are using react native version 0.60 or above you do not have to link this library.

    ios

    Starting with 0.60 on iOS you have to do the following:

    • Add the following line inside ios/Podfile
    target 'app' do
      ...
      pod 'react-native-contacts', :path => '../node_modules/react-native-contacts' <-- add me
      ...
    end
    
    • Run pod install in folder ios

    react native below 60

    iOS

    Using the same instructions as https://facebook.github.io/react-native/docs/linking-libraries-ios.html

    1. open in xcode open ios/yourProject.xcodeproj/
    2. drag ./node_modules/react-native-contacts/ios/RCTContacts.xcodeproj to Libraries in your project view.
    3. In the XCode project navigator, select your project, select the Build Phases tab drag Libraries > RCTContacts.xcodeproj > Products > libRCTContacts.a into the Link Binary With Libraries section. Video to clarify Adding Camera Roll to an ios project in React Native.

    Run the app via the Run button in xcode or react-native run-ios in the terminal.

    Android

    For react native versions 0.60 and above you have to use Android X. Android X support was added to react-native-contacts in version 5.x+. If you are using rn 0.59 and below install rnc versions 4.x instead.

    1. In android/settings.gradle
    ...
    include ':react-native-contacts'
    project(':react-native-contacts').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-contacts/android')
    1. In android/app/build.gradle
    ...
    dependencies {
        ...
        implementation project(':react-native-contacts')
    }
    1. register module
    //  MainApplication.java
    import com.rt2zz.reactnativecontacts.ReactNativeContacts; // <--- import
    
    public class MainApplication extends Application implements ReactApplication {
      ......
    
      @Override
      protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new ReactNativeContacts()); // <------ add this
      }
      ......
    }

    Permissions

    API 23+

    Android requires allowing permissions with https://facebook.github.io/react-native/docs/permissionsandroid.html The READ_CONTACTS permission must be added to your main application's AndroidManifest.xml. 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" />
    ...

    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.** {*;}
    

    All RN versions

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

    screen shot 2016-09-21 at 13 13 21

    Accessing note filed on iOS 13 (optional)

    If you'd like to read/write the contact's notes, call the iosEnableNotesUsage(true) method before accessing the contact infos. Also, a com.apple.developer.contacts.notes entitlement must be added to the project. Before submitting your app to the AppStore, the permission for using the entitlement has to be granted as well. You can find a more detailed explanation here.

    API

    • getAll: Promise<Contact[]> - 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)
    • getContactById(contactId): Promise - returns contact with defined contactId (or null if it doesn't exist)
    • getCount(): Promise - returns the number of contacts
    • getPhotoForId(contactId): Promise - returns a URI (or null) for a contacts photo
    • addContact(contact): Promise - adds a contact to the AddressBook.
    • openContactForm(contact) - create a new contact and display in contactsUI.
    • openExistingContact(contact) - open existing contact (edit mode), where contact is an object with a valid recordID
    • viewExistingContact(contact) - open existing contact (view mode), where contact is an object with a valid recordID
    • editExistingContact(contact): Promise - add numbers to the contact, where the contact is an object with a valid recordID and an array of phoneNumbers
    • updateContact(contact): Promise - where contact is an object with a valid recordID
    • deleteContact(contact) - where contact is an object with a valid recordID
    • getContactsMatchingString(string): Promise<Contact[]> - where string is any string to match a name (first, middle, family) to
    • getContactsByPhoneNumber(string): Promise<Contact[]> - where string is a phone number to match to.
    • getContactsByEmailAddress(string): Promise<Contact[]> - where string is an email address to match to.
    • checkPermission(): Promise - checks permission to access Contacts ios only
    • requestPermission(): Promise - request permission to access Contacts ios only
    • writePhotoToPath() - writes the contact photo to a given path android only

    Example Contact Record

    {
      recordID: '6b2237ee0df85980',
      backTitle: '',
      company: '',
      emailAddresses: [{
        label: 'work',
        email: 'carl-jung@example.com',
      }],
      familyName: 'Jung',
      givenName: 'Carl',
      middleName: '',
      jobTitle: '',
      phoneNumbers: [{
        label: 'mobile',
        number: '(555) 555-5555',
      }],
      hasThumbnail: true,
      thumbnailPath: 'content://com.android.contacts/display_photo/3',
      postalAddresses: [{
        label: 'home',
        formattedAddress: '',
        street: '123 Fake Street',
        pobox: '',
        neighborhood: '',
        city: 'Sample City',
        region: 'CA',
        state: 'CA',
        postCode: '90210',
        country: 'USA',
      }],
      prefix: 'MR',
      suffix: '',
      department: '',
      birthday: {'year': 1988, 'month': 1, 'day': 1 },
      imAddresses: [
        { username: '0123456789', service: 'ICQ'},
        { username: 'johndoe123', service: 'Facebook'}
      ]
    }

    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: "mrniet@example.com",
      }],
      familyName: "Nietzsche",
      givenName: "Friedrich",
    }
    
    Contacts.addContact(newPerson)

    Open Contact Form

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

    var newPerson = {
      emailAddresses: [{
        label: "work",
        email: "mrniet@example.com",
      }],
      displayName: "Friedrich Nietzsche"
    }
    
    Contacts.openContactForm(newPerson).then(contact => {
      // 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().then(contacts => {
      // update the first record
      let someRecord = contacts[0]
      someRecord.emailAddresses.push({
        label: "junk",
        email: "mrniet+junkmail@test.com",
      })
      Contacts.updateContact(someRecord).then(() => {
        // 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.

    Add numbers to an existing contact

    Example

    var newPerson = { 
      recordID: '6b2237ee0df85980',
      phoneNumbers: [{
        label: 'mobile',
        number: '(555) 555-5555',
      }, ...
      ]
    }
    
    Contacts.editExistingContact(newPerson).then(contact => {
        //contact updated
    });

    Add one or more phone numbers to an existing contact. On Android the edited page will be opened. On iOS the already edited contact will be opened with the possibility of further modification.

    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 https://github.com/rt2zz/react-native-contacts/issues/332#issuecomment-455675041 for current discussions.

    Delete Contacts

    You can delete a record using only it's recordID

    Contacts.deleteContact({recordID: 1}).then(recordId => {
      // contact deleted
    })

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

    Contacts.deleteContact(contact).then((recordId) => {
      // 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 - checks permission to access Contacts.
    requestPermission - request permission to access Contacts.

    Usage as follows:

    Contacts.checkPermission().then(permission => {
      // Contacts.PERMISSION_AUTHORIZED || Contacts.PERMISSION_UNDEFINED || Contacts.PERMISSION_DENIED
      if (permission === 'undefined') {
        Contacts.requestPermission().then(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.

    Example

    You can find an example app/showcase here

    react-native-contacts example

    Maintainers

    If your business needs premium react native support please reach out to the maintainer.

    harrymoreno.com
    Harry Moreno

    LICENSE

    MIT License

    Install

    npm i react-native-contacts

    DownloadsWeekly Downloads

    37,084

    Version

    7.0.4

    License

    MIT

    Unpacked Size

    240 kB

    Total Files

    23

    Last publish

    Collaborators

    • rt2zz
    • morenoh149
    • npomfret