Expo Contacts

Contacts.addContactAsync(contact, containerId)

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. You will need to create a development build and add permission in there manually to use this method.

Example

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

Returns

• Promise<string>

A promise that fulfills with ID of the new system contact.

Contacts.addExistingContactToGroupAsync(contactId, groupId)

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

Example

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

Returns

• Promise<any>

Contacts.addExistingGroupToContainerAsync(groupId, containerId)

Add a group to a container.

Example

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

Returns

• Promise<any>

Contacts.createGroupAsync(name, containerId)

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

Example

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

Returns

• Promise<string>

A promise that fulfills with ID of the new group.

Contacts.getContactByIdAsync(id, fields)

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

Example

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

Returns

• Promise<Contact | undefined>

A promise that fulfills with Contact object with ID matching the input ID, or undefined if there is no match.

Contacts.getContactsAsync(contactQuery)

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

Example

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

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

Returns

• Promise<ContactResponse>

A promise that fulfills with ContactResponse object returned from the query.

Contacts.getContainersAsync(containerQuery)

Query a list of system containers.

Example

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

Returns

• Promise<Container[]>

A promise that fulfills with array of containers that fit the query.

Contacts.getDefaultContainerIdAsync()

Get the default container's ID.

Example

const containerId = await Contacts.getDefaultContainerIdAsync();

Returns

• Promise<string>

A promise that fulfills with default container ID.

Contacts.getGroupsAsync(groupQuery)

Query and return a list of system groups.

Example

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

Returns

• Promise<Group[]>

A promise that fulfills with array of groups that fit the query.

Contacts.getPagedContactsAsync(contactQuery)

Returns

• Promise<ContactResponse>

Contacts.getPermissionsAsync()

Checks user's permissions for accessing contacts data.

Returns

• Promise<PermissionResponse>

A promise that resolves to a PermissionResponse object.

Contacts.isAvailableAsync()

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

Returns

• Promise<boolean>

A promise that fulfills with a boolean, indicating whether the Contacts API is available on the current device. It always resolves to false on web.

Contacts.presentFormAsync(contactId, contact, formOptions)

Present a native form for manipulating contacts.

Example

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

Returns

• Promise<any>

Contacts.removeContactAsync(contactId)

Delete a contact from the system.

Example

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

Returns

• Promise<any>

Contacts.removeContactFromGroupAsync(contactId, groupId)

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

Example

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

Returns

• Promise<any>

Contacts.removeGroupAsync(groupId)

Delete a group from the device.

Example

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

Returns

• Promise<any>

Contacts.requestPermissionsAsync()

Asks the user to grant permissions for accessing contacts data.

Returns

• Promise<PermissionResponse>

A promise that resolves to a PermissionResponse object.

Contacts.shareContactAsync(contactId, message, shareOptions)

Returns

• Promise<any>

Contacts.updateContactAsync(contact)

Mutate the information of an existing contact. Due to an iOS bug, nonGregorianBirthday field cannot be modified.

On Android, you can use presentFormAsync to make edits to contacts.

Example

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

Returns

• Promise<string>

A promise that fulfills with ID of the updated system contact if mutation was successful.

Contacts.updateGroupNameAsync(groupName, groupId)

Change the name of an existing group.

Example

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

Returns

• Promise<any>

Contacts.writeContactToFileAsync(contactQuery)

Query a set of contacts and write them to a local URI that can be used for sharing.

Example

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

Returns

• Promise<string | undefined>

A promise that fulfills with shareable local URI, or undefined if there was no match.

PermissionResponse

An object obtained by permissions get and request functions.

PermissionResponse Properties