@umituz/react-native-contacts

Device contacts access for React Native apps - Privacy-first design with permission management.

Features

• ✅ Contact Access - Read device contacts with permission management
• ✅ Contact Search - Search contacts by name, company, nickname
• ✅ Contact Picker - iOS contact picker (no permission needed)
• ✅ Contact CRUD - Create, update, delete contacts (requires WRITE permission)
• ✅ Phone/Email Extraction - Get primary phone numbers and emails
• ✅ Contact Utilities - Format, sort, group, and validate contacts
• ✅ Privacy-First - Explicit permission handling

Installation

npm install @umituz/react-native-contacts

Peer Dependencies

npm install expo-contacts

Usage

Basic Contact Access

import { useContacts } from '@umituz/react-native-contacts';

function MyComponent() {
  const {
    permission,
    isPermissionGranted,
    contacts,
    isLoading,
    requestPermission,
    loadContacts,
  } = useContacts();

  useEffect(() => {
    requestPermission().then(perm => {
      if (perm.status === 'granted') {
        loadContacts();
      }
    });
  }, []);

  if (!isPermissionGranted) {
    return <Button title="Request Permission" onPress={requestPermission} />;
  }

  return (
    <FlatList
      data={contacts}
      renderItem={({ item }) => <Text>{item.name}</Text>}
    />
  );
}

Contact Search

const { searchContacts, contacts } = useContacts();

const handleSearch = (query: string) => {
  searchContacts(query);
};

iOS Contact Picker (No Permission Needed)

const { presentContactPicker } = useContacts();

const handlePicker = async () => {
  const contact = await presentContactPicker(['phoneNumbers', 'emails']);
  if (contact) {
    console.log('Selected:', contact);
  }
};

Contact Utilities

import { ContactUtils } from '@umituz/react-native-contacts';

// Get display name
const name = ContactUtils.getDisplayName(contact);

// Get primary phone/email
const phone = ContactUtils.getPrimaryPhone(contact);
const email = ContactUtils.getPrimaryEmail(contact);

// Format phone number
const formatted = ContactUtils.formatPhone('1234567890'); // "(123) 456-7890"

// Get initials
const initials = ContactUtils.getInitials(contact); // "JD"

// Group by first letter
const groups = ContactUtils.groupByFirstLetter(contacts);

API Reference

useContacts()

React hook for contacts management.

Returns:

• permission - Current permission status
• isPermissionGranted - Boolean permission status
• contacts - Array of contacts
• isLoading - Loading state
• requestPermission() - Request contacts permission
• loadContacts(query?) - Load all contacts
• searchContacts(query, options?) - Search contacts
• presentContactPicker(fields?) - iOS contact picker
• createContact(contact) - Create new contact
• updateContact(id, contact) - Update contact
• deleteContact(id) - Delete contact

ContactsService

Static service class for contacts operations.

Methods:

• requestPermission() - Request permission
• getAllContacts(query?) - Get all contacts
• searchContacts(query, options?) - Search contacts
• getContactById(id, fields?) - Get contact by ID
• presentContactPicker(fields?) - iOS contact picker
• createContact(contact) - Create contact
• updateContact(id, contact) - Update contact
• deleteContact(id) - Delete contact

ContactUtils

Utility class for contact operations.

Methods:

• getDisplayName(contact) - Get display name
• getPrimaryPhone(contact) - Get primary phone
• getPrimaryEmail(contact) - Get primary email
• formatPhone(phone) - Format phone number
• getInitials(contact) - Get contact initials
• groupByFirstLetter(contacts) - Group by first letter
• searchByName(contacts, query) - Search by name
• sortByName(contacts, order?) - Sort by name

Privacy

This package requires explicit user permission:

• Android: READ_CONTACTS permission
• iOS: NSContactsUsageDescription in Info.plist

For iOS, you can use presentContactPicker() without full permission - it's more privacy-friendly.

License

MIT

Author

Ümit UZ [email protected]