Expo Contacts

GitHub

npm

expo-contacts provides access to the device's system contacts, allowing you to get contact information as well as adding, editing, or removing contacts.

Platform Compatibility

Installation

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

import React, { useEffect } from 'react';
import { StyleSheet, 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={styles.container}>
      <Text>Contacts Module Example</Text>
    </View>
  );
}

%%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as Contacts from 'expo-contacts';

Methods

Contacts.isAvailableAsync()

Returns whether the Contacts API is enabled on the current device. This does not check the app permissions.

Returns

Async boolean, indicating whether the Contacts API is available on the current device. Currently this resolves to true on iOS and Android only.

Contacts.requestPermissionsAsync()

Asks the user to grant permissions for accessing contacts data.

Returns

A promise that resolves to an object of type PermissionResponse.

Contacts.getPermissionsAsync()

Checks user's permissions for accessing contacts data.

Returns

A promise that resolves to an object of type PermissionResponse.

Contacts.getContactsAsync(contactQuery)

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

Return a list of contacts that fit a given criteria. You can get all of the contacts by passing no criteria.

Parameters

Returns

Example

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>

Returns a contact matching the input id. Used for gathering precise data about a contact.

Parameters

Returns

Example

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>

Creates a new contact and adds it to the system.

Note: For Android users, the Expo Go 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.

Parameters

Returns

Example

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>

Mutate the information of an existing contact.

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>

Present a native form for manipulating contacts

Parameters

Example

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

Parameters

Returns

Example

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>

Delete a contact from the system.

Parameters

Example

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

Contacts.writeContactToFileAsync(contactQuery)

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

Query a set of contacts and write them to a local uri that can be used for sharing with ReactNative.Share.

Parameters

Returns

Example

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

IOS-Only Methods

iOS contacts have a multi-layered grouping system that you can access through this API.

Contacts.addExistingGroupToContainerAsync(groupId, containerId)

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

Add a group to a container.

Parameters

Example

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>

Create a group with a name, and add it to a container. If the container is undefined, the default container will be targeted.

Parameters

Returns

Example

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

Contacts.updateGroupNameAsync(groupName, groupId)

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

Change the name of an existing group.

Parameters

Example

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

Contacts.removeGroupAsync(groupId)

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

Delete a group from the device.

Parameters

Example

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

Contacts.addExistingContactToGroupAsync(contactId, groupId)

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

Add a contact as a member to a group. A contact can be a member of multiple groups.

Parameters

Example

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>

Remove a contact's membership from a given group. This will not delete the contact.

Parameters

Example

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

Contacts.getGroupsAsync(query)

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

Query and return a list of system groups.

Parameters

Returns

Example

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

Contacts.getDefaultContainerIdAsync()

Contacts.getDefaultContainerIdAsync(): Promise<string>

Get the default container's ID.

Returns

Example

const containerId = await Contacts.getDefaultContainerIdAsync();

Contacts.getContainersAsync(containerQuery)

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

Query a list of system containers.

Parameters

Returns

Example

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

Types

Contact

A set of fields that define information about a single entity.

*On iOS 13 and up, the note field requires your app to request additional entitlements. The Expo Go app does not contain those entitlements, so in order to test this feature you will need to request the entitlement from Apple here, set the ios.accessesContactNotes field in app.json to true, and build your app as a standalone app.

Group

iOS Only

A parent to contacts. A contact can belong to multiple groups. To get a group's children you can query with getContactsAsync({ groupId })

Here are some different query operations:

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

Container

iOS Only

A parent to contacts and groups. You can query the default container with getDefaultContainerIdAsync(). Here are some different query operations:

• 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

Information regarding thumbnail images.

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

FormOptions

Denotes the functionality of a native contact form.

ContactQuery

Used to query contacts from the user's device.

GroupQuery

iOS Only

Used to query native contact groups.

ContainerQuery

iOS Only

Used to query native contact containers.

ContactResponse

The return value for queried contact operations like getContactsAsync.

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;

This format denotes the common calendar format used to specify how a date is calculated in nonGregorianBirthday fields.

Contact Fields

Deprecated: Use Contacts.Fields

This table illustrates what fields will be added on demand to every contact.