Expo

Documentation

Hi friend! Meet us at App.js Conf in Krakow, Poland on April 4th and 5th with workshops and talks. Learn more

Contacts

Provides access to the phone's system contacts.

Get a list of all entries in the system contacts. This returns a set of data related to contact entries.

A map of options:
  • fields (array) -- An array describing fields to retrieve per contact. Each element must be one of constants listed in the table below.
  • pageSize (number) -- The number of contacts per page that will be returned. Defaults to 100.
  • pageOffset (number) -- The number of contacts to skip before those that will be returned. Defaults to 0.

A pagination object that contains the following fields.
  • data (array) -- An array of objects of the form { id, name, firstName, middleName, lastName, nickname, jobTitle, company, department, imageAvailable¬† }. iOS also includes previousLastName. The additional fields are listed in the table below.
  • hasNextPage (boolean) -- If there is more contacts available.
  • hasPreviousPage (boolean) -- If there was contacts skipped. Will be true when passing a pageOffset greater than 0.
  • total (number) -- The total number of contacts available.

Get a single contact from system contacts associated to specified id.

A map of options:
  • id (string) - ID of the contact to fetch.
  • fields (array) -- An array describing fields to retrieve. Each element must be one of constants listed in the table below.

An object of the form { id, name, firstName, middleName, lastName, nickname, jobTitle, company, department, imageAvailable  }. iOS also includes previousLastName. The additional fields are listed in the table below.

This table illustrates what fields will be added on demand to every contact. Sample usage: Expo.Contacts.EMAILS.
ConstantName of returned field
PHONE_NUMBERSphoneNumbers
EMAILSemails
ADDRESSESaddresses
IMAGEimage : iOS only
THUMBNAILthumbnail
NOTEnote
NON_GREGORIAN_BIRTHDAYnonGregorianBirthday : iOS only
NAME_PREFIXnamePrefix
NAME_SUFFIXnameSuffix
PHONETIC_FIRST_NAMEphoneticFirstName
PHONETIC_MIDDLE_NAMEphoneticMiddleName
PHONETIC_LAST_NAMEphoneticLastName
SOCIAL_PROFILESsocialProfiles : iOS only
IM_ADDRESSESinstantMessageAddresses
URLSurlAddresses
DATESdates

async function showFirstContactAsync() {
  // Ask for permission to query contacts.
  const permission = await Expo.Permissions.askAsync(Expo.Permissions.CONTACTS);
  if (permission.status !== 'granted') {
    // Permission was denied...
    return;
  }
  const contacts = await Expo.Contacts.getContactsAsync({
    fields: [
      Expo.Contacts.PHONE_NUMBERS,
      Expo.Contacts.EMAILS,
    ],
    pageSize: 10,
    pageOffset: 0,
  });
  if (contacts.total > 0) {
    Alert.alert(
      'Your first contact is...',
      `Name: ${contacts.data[0].name}
` +
      `Phone numbers: ${JSON.stringify(contacts.data[0].phoneNumbers)}
` +
      `Emails: ${JSON.stringify(contacts.data[0].emails)}`
    );
  }
}
This function will display the first entry in the user's contacts.

phoneNumbers -- An array containing phone numbers data of a contact.
Fields: { number, digits, primary (boolean), countryCode }
emails -- An array containing emails data of a contact.
Fields: { email, primary (boolean) }
addresses -- An array containing postal addresses data of a contact.
Fields: { street, city, country, region, neighborhood, postalCode, poBox, isoCountryCode }
socialProfiles -- An array containing social profiles (Facebook, Twitter, etc.) data of a contact.
Fields: { service, localizedProfile, url, username, userId }
instantMessageAddresses -- An array containing IM addresses (Skype, Google Hangouts, etc.) data of a contact.
Fields: { service, username, localizedService }
urlAddresses -- An array containing website urls of a contact.
Fields: { url }
dates -- An array containing dates assigned to a contact.
Fields: { day, month, year }
relationships -- An array containing relationships assigned a contact.
Fields: { name }
Moreover every entry in arrays above contains parameters id and label.
birthday, nonGregorianBirthday - Gregorian and non-Gregorian representation of contact's birthday.
Fields: { day, month, year }
thumbnail, image - thumbnail and original image of a contact picture.
Fields: { uri } -- use this uri as <Image> component's source prop to display the picture. Mind that fetching these is time and resource-consuming on iOS and should not be used when fetching all contacts.