Platform Compatibility

Installation

Configuration

Example Usage

import React, { useEffect } from 'react';
import { View, Text } from 'react-native';
import * as Contacts from 'expo-contacts';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Contacts.requestPermissionsAsync();
      if (status === 'granted') {
        const { data } = await Contacts.getContactsAsync({
          fields: [Contacts.Fields.Emails],
        });

        if (data.length > 0) {
          const contact = data[0];
          console.log(contact);
        }
      }
    })();
  }, []);

  return (
    <View
      style={{
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
      }}>
      <Text>Contacts Module Example</Text>
    </View>
  );
}

API

import * as Contacts from 'expo-contacts';

Methods

Contacts.requestPermissionsAsync()

Returns

Contacts.getPermissionsAsync()

Returns

Contacts.getContactsAsync(contactQuery)

Contacts.getContactsAsync(contactQuery: ContactQuery): Promise<ContactResponse>

const { data } = await Contacts.getContactsAsync({
  fields: [Contacts.Fields.Emails],
});

if (data.length > 0) {
  const contact = data[0];
  console.log(contact);
}

Contacts.getContactByIdAsync(contactId, fields)

Contacts.getContactByIdAsync(contactId: string, fields: FieldType[]): Promise<Contact>

const contact = await Contacts.getContactByIdAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
if (contact) {
  console.log(contact);
}

Contacts.addContactAsync(contact, containerId)

Contacts.addContactAsync(contact: Contact, containerId: string): Promise<string>

Note: For Android users, the Expo client App does not have the required WRITE_CONTACTS permission to write to Contacts. In order to do this, you must build a standalone app and add permission through there.

const contact = {
  [Contacts.Fields.FirstName]: 'Bird',
  [Contacts.Fields.LastName]: 'Man',
  [Contacts.Fields.Company]: 'Young Money',
};
const contactId = await Contacts.addContactAsync(contact);

Contacts.updateContactAsync(contact)

iOS Only - temporary

Contacts.updateContactAsync(contact: Contact): Promise<string>

On Android, you can use presentFormAsync to make edits to contacts. Due to an iOS bug, nonGregorianBirthday cannot be modified.

Contacts.presentFormAsync(contactId, contact, formOptions)

Contacts.presentFormAsync(contactId: string, contact: Contact, formOptions: FormOptions): Promise<any>

// Edit contact
await Contacts.presentFormAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');

const contact = {
  id: '161A368D-D614-4A15-8DC6-665FDBCFAE55',
  [Contacts.Fields.FirstName]: 'Drake',
  [Contacts.Fields.Company]: 'Young Money',
};
await Contacts.updateContactAsync(contact);

Contacts.removeContactAsync(contactId)

iOS Only - temporary

Contacts.removeContactAsync(contactId: string): Promise<any>

await Contacts.removeContactAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');

Contacts.writeContactToFileAsync(contactQuery)

Contacts.writeContactToFileAsync(contactQuery: ContactQuery): Promise<string>

const localUri = await Contacts.writeContactToFileAsync({
  id: '161A368D-D614-4A15-8DC6-665FDBCFAE55',
});
Share.share({ url: localUri, message: 'Call me!' });

IOS-Only Methods

Contacts.addExistingGroupToContainerAsync(groupId, containerId)

Contacts.addExistingGroupToContainerAsync(groupId: string, containerId: string): Promise<any>

await Contacts.addExistingGroupToContainerAsync(
  '161A368D-D614-4A15-8DC6-665FDBCFAE55',
  '665FDBCFAE55-D614-4A15-8DC6-161A368D'
);

Contacts.createGroupAsync(groupName, containerId?)

Contacts.createGroupAsync(groupName: string, containerId?: string): Promise<string>

const groupId = await Contacts.createGroupAsync('Sailor Moon');

Contacts.updateGroupNameAsync(groupName, groupId)

Contacts.updateGroupNameAsync(groupName: string, groupId: string): Promise<any>

await Contacts.updateGroupName('Sailor Moon', '161A368D-D614-4A15-8DC6-665FDBCFAE55');

Contacts.removeGroupAsync(groupId)

Contacts.removeGroupAsync(groupId: string): Promise<any>

await Contacts.removeGroupAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');

Contacts.addExistingContactToGroupAsync(contactId, groupId)

Contacts.addExistingContactToGroupAsync(contactId: string, groupId: string): Promise<any>

await Contacts.addExistingContactToGroupAsync(
  '665FDBCFAE55-D614-4A15-8DC6-161A368D',
  '161A368D-D614-4A15-8DC6-665FDBCFAE55'
);

Contacts.removeContactFromGroupAsync(contactId, groupId)

Contacts.removeContactFromGroupAsync(contactId: string, groupId: string): Promise<any>

await Contacts.removeContactFromGroupAsync(
  '665FDBCFAE55-D614-4A15-8DC6-161A368D',
  '161A368D-D614-4A15-8DC6-665FDBCFAE55'
);

Contacts.getGroupsAsync(query)

Contacts.getGroupsAsync(query: GroupQuery): Promise<Group[]>

const groups = await Contacts.getGroupsAsync({ groupName: 'sailor moon' });
const allGroups = await Contacts.getGroupsAsync({});

Contacts.getDefaultContainerIdAsync()

Contacts.getDefaultContainerIdAsync(): Promise<string>

const containerId = await Contacts.getDefaultContainerIdAsync();

Contacts.getContainersAsync(containerQuery)

Contacts.getContainersAsync(containerQuery: ContainerQuery): Promise<Container[]>

const allContainers = await Contacts.getContainersAsync({
  contactId: '665FDBCFAE55-D614-4A15-8DC6-161A368D',
});

Types

Contact

Group

iOS Only

• Child Contacts: getContactsAsync({ groupId })
• Groups From Container: getGroupsAsync({ containerId })
• Groups Named: getContainersAsync({ groupName })

Container

iOS Only

• Child Contacts: getContactsAsync({ containerId })
• Child Groups: getGroupsAsync({ containerId })
• Container from Contact: getContainersAsync({ contactId })
• Container from Group: getContainersAsync({ groupId })
• Container from ID: getContainersAsync({ containerId })

Date

Relationship

Email

PhoneNumber

Address

SocialProfile

iOS Only

InstantMessageAddress

UrlAddress

Image

Android: You can get dimensions using ReactNative.Image.getSize. Avoid using Base 64 in React Native

FormOptions

ContactQuery

GroupQuery

iOS Only

ContainerQuery

iOS Only

ContactResponse

Constants

Field

const contactField = Contact.Fields.FirstName;

FormType

const formType = Contacts.FormTypes.New;

ContactType

iOS Only

const contactType = Contacts.ContactTypes.Person;

SortType

const sortType = Contacts.SortTypes.FirstName;

ContainerType

iOS Only

const containerType = Contacts.ContainerTypes.CardDAV;

CalendarFormat

const calendarFormat = Contacts.CalendarFormats.Coptic;

Contact Fields

Deprecated: Use Contacts.Fields

Breaking Changes

SDK 29

• The thumbnail field has been deprecated, use image on both platforms instead.
• On iOS image is now rawImage. There is no Android version of rawImage.
• Images now return a localUri instead of Base64 string.
• Base64 string is now returned in a encodable format.
• Empty contact fields will no longer be returned as empty strings on iOS.
• Passing no fields will now return all contact information.