React Native Contacts

Common errors

• Invariant Violation: Module AppRegistry is not a registered callable module (calling runApplication)

  cause This error frequently indicates a linking issue where native modules are not correctly registered with the JavaScript bridge.
  fix Ensure `react-native-contacts` is properly linked for your React Native version and platform. For RN 0.60+, run `cd ios && pod install` after adding the pod line. For Android, verify `settings.gradle` and `app/build.gradle` configurations. Clean caches: `watchman watch-del-all && rm -rf node_modules && npm install && cd ios && pod install && cd .. && npm start -- --reset-cache`.

• Execution failed for task ':app:processDebugMainManifest'. > Manifest merger failed with multiple errors, see logs.

  cause This often occurs on Android when `react-native-contacts` versions 5.x+ are used with a React Native project that has not migrated to AndroidX (typically RN < 0.60).
  fix Migrate your React Native project to AndroidX if using RN 0.60+. If you must use RN < 0.60, downgrade `react-native-contacts` to a `4.x.x` version by running `npm install react-native-contacts@4`.

• error: library not found for -lRCTContacts

  cause This iOS build error indicates that the `RCTContacts` native library could not be found, typically due to incorrect or missing linking.
  fix For React Native 0.60+, ensure `pod 'react-native-contacts', :path => '../node_modules/react-native-contacts'` is added to your `ios/Podfile` inside your target, then run `cd ios && pod install`. For older RN versions, verify manual linking steps (dragging `RCTContacts.xcodeproj` to `Libraries` and linking `libRCTContacts.a` in Build Phases).

Warnings

• breaking Starting with v7.0.0, manual linking (e.g., `react-native link`) and including a manual pod line in the `Podfile` for iOS projects are no longer needed due to autolinking support. Retaining the old pod line can cause build failures.
  Fix: Remove `pod 'react-native-contacts'` from your `ios/Podfile` if it exists. Run `npx react-native unlink react-native-contacts` if previously linked, then `npm install react-native-contacts` and `cd ios && pod install`.
• breaking Version 8.0.0 introduced initial support for the new React Native architecture (TurboModules and Fabric). While aiming for backward compatibility, projects migrating to the new architecture or using React Native versions that leverage it should follow specific installation and linking steps.
  Fix: For React Native 0.60+ (and especially with new architecture enabled), ensure `pod 'react-native-contacts', :path => '../node_modules/react-native-contacts'` is present in your `ios/Podfile` and run `pod install`. For Android, ensure `android/settings.gradle` and `android/app/build.gradle` are correctly configured for autolinking or manual linking if below RN 0.60.
• breaking For React Native versions 0.60 and above, AndroidX support is required. `react-native-contacts` versions 5.x+ include AndroidX support. If you are using React Native 0.59 or below, you must use `react-native-contacts` versions 4.x or older to avoid Android build conflicts.
  Fix: If using RN 0.60+, ensure your project has migrated to AndroidX. If using RN < 0.60, downgrade `react-native-contacts` to `4.x.x` (e.g., `npm install react-native-contacts@4`).
• gotcha The `Contacts.getAll()` method is a database-intensive process, and its execution time can be significant, especially with large contact lists. Calling it frequently or synchronously can degrade app performance.
  Fix: It is highly recommended to call `getAll()` before the data is critically needed and cache the results for subsequent uses. Consider implementing a loading state or background process for contact retrieval.
• gotcha On iOS, you must add 'Privacy - Contacts Usage Description' (NSContactsUsageDescription) key to your `Info.plist` file with a descriptive string, otherwise your app will crash when attempting to access contacts.
  Fix: Add the `NSContactsUsageDescription` key and a user-facing message to your `Info.plist` file in Xcode.

Install

• npm install react-native-contacts npm
• yarn add react-native-contacts yarn
• pnpm add react-native-contacts pnpm

Imports

• Contacts
  wrong:

  const Contacts = require('react-native-contacts');

  correct:

  import Contacts from 'react-native-contacts';

  Primarily designed for ESM. CommonJS `require` can lead to issues with newer React Native architectures or build systems.
• Contact

  import type { Contact } from 'react-native-contacts';

  Type import for TypeScript users to define contact shape.
• { getAll }
  wrong:

  import { getAll } from 'react-native-contacts';

  correct:

  import Contacts from 'react-native-contacts';
  // then use: Contacts.getAll()

  `getAll` is a method of the default `Contacts` object, not a named export. Attempting to destructure it directly will result in an undefined function.

Quickstart

This quickstart demonstrates how to request Android runtime permissions for contacts and then fetch all contacts using `Contacts.getAll()`.

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

const fetchContacts = async () => {
  try {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.READ_CONTACTS,
      {
        title: 'Contacts',
        message: 'This app would like to view your contacts.',
        buttonPositive: 'Please accept bare mortal',
      }
    );
    if (granted === PermissionsAndroid.RESULTS.GRANTED) {
      console.log('Contacts permission granted.');
      const contacts = await Contacts.getAll();
      console.log('Fetched contacts:', contacts.slice(0, 3)); // Log first 3 contacts
      // Example: Access a specific contact's phone number
      if (contacts.length > 0 && contacts[0].phoneNumbers && contacts[0].phoneNumbers.length > 0) {
        console.log('First contact phone number:', contacts[0].phoneNumbers[0].number);
      }
    } else {
      console.log('Contacts permission denied.');
    }
  } catch (err) {
    console.error('Error fetching contacts:', err);
  }
};

fetchContacts();