@omarsdev/react-native-contacts

Contacts at scale for React Native, with fast first-run paging and efficient “delta since last sync” on Android and iOS.

Why this library

• Large address books without jank: fetch 10k+ contacts in pages (200–500) to keep UI responsive.
• Real delta sync: only fetch contacts that changed since your last run.
• Native tokens, minimal JS state: tokens are persisted natively to avoid storing massive lists in JS.
• Android sorted by last updated: newest changes first for better UX.
• iOS resilient strategy: uses Contacts change history when available, and a native fingerprint snapshot fallback when it isn’t.

Install

# with Yarn
yarn add @omarsdev/react-native-contacts

# with npm
npm install @omarsdev/react-native-contacts

Permissions

• Android: request READ_CONTACTS at runtime before usage.

  • Optional (manifest) — if you prefer declaring in your app too:

    <!-- android/app/src/main/AndroidManifest.xml -->
    <manifest ...>
      <uses-permission android:name="android.permission.READ_CONTACTS" />
    </manifest>

  • Runtime request (JS):

    import { PermissionsAndroid, Platform } from 'react-native';
    
    export async function ensureContactsPermission() {
      if (Platform.OS !== 'android') return true;
      const res = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.READ_CONTACTS
      );
      return res === PermissionsAndroid.RESULTS.GRANTED;
    }

• iOS: add usage description to your app Info.plist and rebuild pods.

  • Info.plist:

    <key>NSContactsUsageDescription</key>
    <string>This app needs access to your contacts to sync changes.</string>

  • iOS will show the permission prompt the first time you access contacts.

Type shapes

type Contact = {
  id: string;
  displayName: string;
  phoneNumbers: string[];
  givenName?: string | null;
  familyName?: string | null;
  // Android only; iOS sets null
  lastUpdatedAt?: number | null;
};

type PhoneNumberUpdate = {
  previous: string;
  current: string;
};

type PhoneNumberChanges = {
  created: string[];
  deleted: string[];
  updated: PhoneNumberUpdate[];
};

type ContactChange = Contact & {
  changeType: 'created' | 'updated' | 'deleted';
  isDeleted: boolean;
  phoneNumberChanges: PhoneNumberChanges;
  previous?: {
    displayName?: string | null;
    givenName?: string | null;
    familyName?: string | null;
    phoneNumbers: string[];
  } | null;
};

type UpdatedPageBase = {
  nextSince: string;
  totalContacts: number;
};

type UpdatedPage = UpdatedPageBase & {
  mode: 'delta' | 'full';
  items: ContactChange[];
};

API reference & examples

Types

Type	Description
type Contact	Normalised contact record returned by all APIs. Includes optional givenName, familyName, and lastUpdatedAt (Android only).
type PhoneNumberUpdate	Represents an individual phone number that changed within a contact delta (previous → current).
type PhoneNumberChanges	Buckets the numbers added/removed/updated in a ContactChange. Useful when reconciling diffs.
type ContactChange	Extends Contact with delta metadata (changeType, isDeleted, phoneNumberChanges, and an optional previous snapshot).
type UpdatedPage	Page returned by paging APIs (mode, items, nextSince, and totalContacts so you know the device book size). Items are always ContactChange[].

Functions (promise / async)

• getById(id: string): Promise<Contact | null>

  • Look up a single contact by its native identifier. Resolves to null if the contact no longer exists or the identifier was empty.

  const maybeAlice = await getById('42');
  if (maybeAlice) {
    console.log('Found contact', maybeAlice.displayName);
  }

• getPersistedSince(): Promise<string>

  • Reads the last token that was committed natively (empty string if nothing has been stored yet). Handy when resuming delta sync in a fresh JS session.

  const lastToken = await getPersistedSince();
  console.log('Native token:', lastToken);

• commitPersisted(nextSince: string): Promise<void>

  • Persists the supplied token on the native side so subsequent delta calls start from that point. On iOS this also rebuilds the fingerprint snapshot.

  await commitPersisted(nextToken);

• getAll(): Promise<Contact[]>

  • Convenience helper that returns the full native contact list in one call.

  const everyone = await getAll();
  console.log('Fetched contacts', everyone.length);

• getUpdatedSincePaged(since: string, offset: number, limit: number): Promise<UpdatedPage>

  • Fetch a delta page using an explicit token. When native change tracking is available the result is { mode: 'delta' } with changed contacts and the next token. If the platform cannot supply a delta token—or you pass an empty token on first synchronisation—it returns { mode: 'full' } so you can re-sync ordinary contact pages (still respecting offset/limit). Token format differs by platform: Android always returns a millisecond timestamp, while iOS may return a base64-encoded CNChangeHistory token (e.g. YnBsaXN0…) or, when history is unavailable, a synthetic fp:<timestamp> token.

  const page = await getUpdatedSincePaged(lastToken, 0, 200);
  if (page.mode === 'full') {
    page.items.forEach((change) => console.log('Full contact', change.id));
  } else {
    page.items.forEach((change) => console.log(change.changeType, change.id));
  }
  console.log('Total contacts on device', page.totalContacts);

  • Need to walk every page? Use getUpdatedSincePaged.listen to stream until exhaustion (return false from the handler to stop early). pageSize is optional and defaults to 300.

  await getUpdatedSincePaged.listen(
    { since: lastToken, pageSize: 250 },
    async (page) => {
      console.log(
        `Page mode=${page.mode} size=${page.items.length} total=${page.totalContacts}`
      );
    }
  );

  • Streaming signature: getUpdatedSincePaged.listen(handler, options?) or getUpdatedSincePaged.listen(options, handler). The handler can be async and should return false to stop fetching. options accepts { since?: string; offset?: number; pageSize?: number }.

iOS tokens:

• Real change-history tokens look like long base64 strings (YnBsaXN0MDD…).
• Fallback fingerprints use the fp:<timestamp> format when history is disabled or unchanged.

Quick start

import {
  commitPersisted,
  getPersistedSince,
  getUpdatedSincePaged,
} from '@omarsdev/react-native-contacts';
import { ensureContactsPermission } from './permissions'; // from snippet above

// Delta or baseline sync (falls back to full pages when native tokens are unavailable)
if (await ensureContactsPermission()) {
  const persistedSince = await getPersistedSince();
  const pageSize = 300;
  let nextSince: string | undefined = persistedSince;
  let usedFullFallback = false;

  await getUpdatedSincePaged.listen(
    { since: persistedSince, pageSize },
    (page) => {
      if (page.nextSince) nextSince = page.nextSince;
      if (!page.items.length) return false;
      const label = page.mode === 'full' ? 'Contacts page' : 'Delta page';
      console.log(
        `${label}: ${page.items.length} items (total contacts ${page.totalContacts})`
      );
      if (page.mode === 'full') usedFullFallback = true;
      return page.items.length >= pageSize;
    }
  );

  if (nextSince && nextSince !== persistedSince) {
    await commitPersisted(nextSince);
  } else if (usedFullFallback && !nextSince) {
    console.log('Full snapshot processed; no token persisted yet.');
  }
}

Example scenarios

The example app in example/src/screens/ContactsDemoScreen.tsx walks through the most common flows. The snippets below highlight the key cases in isolation:

import {
  commitPersisted,
  getById,
  getPersistedSince,
  getUpdatedSincePaged,
} from '@omarsdev/react-native-contacts';
import type { Contact, ContactChange } from '@omarsdev/react-native-contacts';

// 1. Request permission on Android before touching contacts.
await ensureContactsPermission();

// 2. Pull the delta (or fallback full pages) since the last committed token and persist progress.
const persistedSince = await getPersistedSince();
const pageSize = 300;
let sessionToken = persistedSince;
let totalContacts: number | undefined;
const delta: ContactChange[] = [];
let fullFallback: Contact[] = [];

await getUpdatedSincePaged.listen(
  { since: persistedSince, pageSize },
  (page) => {
    if (page.nextSince) sessionToken = page.nextSince;
    if (!page.items.length) return false;
    totalContacts = page.totalContacts;
    if (page.mode === 'delta') {
      delta.push(...page.items);
    } else {
      fullFallback = fullFallback.concat(page.items);
    }
    return page.items.length >= pageSize;
  }
);

if (sessionToken && sessionToken !== persistedSince) {
  await commitPersisted(sessionToken);
}

console.log('Total contacts reported by native layer', totalContacts ?? 'unknown');

// 3. Full fallback pages can be handled like a baseline rebuild.
console.log('Full snapshot contacts (if fallback)', fullFallback.length);

// 4. Look up a single contact by identifier (helpful after any baseline rebuild).
const singleContact = await getById('12345'); // returns `null` if the contact was deleted

Platform details

• Android
  • Uses ContactsContract.Contacts.CONTACT_LAST_UPDATED_TIMESTAMP for sorting and delta (timestamp filter).
  • lastUpdatedAt is set from this value.
• iOS
  • Change history: uses CNContactStore change-history tokens when available.
  • Fingerprint fallback: when change history is unavailable or returns no events, a native snapshot (id → fingerprint of name + normalized numbers) detects adds/edits; snapshot updates on commitPersisted.
  • Synthetic tokens: when the system token doesn’t advance, we synthesize fp:<timestamp> to ensure forward progress.
  • Delta payloads include changeType, a previous snapshot (when available), and phoneNumberChanges summarising added, updated, and deleted numbers.

Recommended paging & usage

• Page size 200–500 works well for large books.
• Always commit a delta token after finishing a delta session.
• First run: do a full fetch; then do a delta to seed/commit a token.

Build & development

• Prereqs: Node 20+, Yarn 3 (Berry).
• Install deps and build the lib:
  • yarn (at repo root)
  • yarn prepare (runs bob/codegen; generates lib/ and TS types)
• Example app — Android:
  • cd example && yarn android
• Example app — iOS:
  • cd example/ios && pod install
  • cd .. && yarn ios
• Using in your app:
  • yarn add @omarsdev/react-native-contacts
  • iOS: cd ios && pod install
  • Rebuild the app

Why install

• You need to sync very large contact sets without freezing the UI.
• You want reliable “delta since last run” on both Android and iOS.
• You don’t want to persist huge JS arrays; tokens are handled natively.
• You want Android sorted by latest updates and an iOS strategy that works even when change history is unavailable.

License

MIT

Contributing

• See CONTRIBUTING.md for development workflow and conventions.