expo-contacts v12.8.2

expo-contacts

Installation

iOS (Cocoapods)

If you're using Cocoapods, add the dependency to your Podfile:

pod 'EXContacts'

and run pod install.

iOS (no Cocoapods)

1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
2. Go to node_modules ➜ expo-contacts and add EXContacts.xcodeproj
3. In XCode, in the project navigator, select your project. Add libEXContacts.a to your project's Build Phases ➜ Link Binary With Libraries
4. Run your project (Cmd+R).

Android

1. Append the following lines to android/settings.gradle:

   include ':expo-contacts'
   project(':expo-contacts').projectDir = new File(rootProject.projectDir, '../node_modules/expo-contacts/android')

   and if not already included

   include ':expo-permissions-interface'
   project(':expo-permissions-interface').projectDir = new File(rootProject.projectDir, '../node_modules/expo-permissions-interface/android')
   
      include ':expo-filesystem-interface'
   project(':expo-filesystem-interface').projectDir = new File(rootProject.projectDir, '../node_modules/expo-filesystem-interface/android')

2. Insert the following lines inside the dependencies block in android/app/build.gradle:

   compile project(':expo-contacts')

   and if not already included

   compile project(':expo-permissions-interface')
   compile project(':expo-filesystem-interface')

Introduction

Provides access to the phone's system contacts.

Methods

getContactsAsync

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);
}

getContactByIdAsync

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);
}

addContactAsync

iOS Only - temporary

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

Creates a new contact and adds it to the system.

Parameters

Returns

Example

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

updateContactAsync

iOS Only - temporary

updateContactAsync(contact: Contact): Promise<string>

Mutate the information of an existing contact.

On Android, you can use presentFormAsync to make edits to contacts. Do to an error with the Apple API, nonGregorianBirthday cannot be modified.

Parameters

Returns

Example

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

removeContactAsync

iOS Only - temporary

removeContactAsync(contactId: string): Promise<any>

Delete a contact from the system.

Parameters

Example

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

writeContactToFileAsync

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 Functions

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

presentFormAsync

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');

addExistingGroupToContainerAsync

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'
);

createGroupAsync

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');

updateGroupNameAsync

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');

removeGroupAsync

removeGroupAsync(groupId: string): Promise<any>

Delete a group from the device.

Parameters

Example

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

addExistingContactToGroupAsync

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'
);

removeContactFromGroupAsync

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'
);

getGroupsAsync

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({});

getDefaultContainerIdAsync

getDefaultContainerIdAsync(): Promise<string>

Get the default container's ID.

Returns

Example

const containerId = await Contacts.getDefaultContainerIdAsync();

getContainersAsync

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

Query a list of system containers.

Parameters

Returns

Example

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

Types

Contact

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

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

Fields

const contactField = Contact.Fields.FirstName;

FormTypes

const formType = Contacts.FormTypes.New;

ContactTypes

iOS Only

const contactType = Contacts.ContactTypes.Person;

SortTypes

const sortType = Contacts.SortTypes.FirstName;

ContainerTypes

iOS Only

const containerType = Contacts.ContainerTypes.CardDAV;

CalendarFormats

const calendarFormat = Contacts.CalendarFormats.Coptic;

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