Expo Docs

Hey friend! We are co-hosting a conference with Software Mansion, 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
NONGREGORIANBIRTHDAYnonGregorianBirthday (iOS only)
NAME_PREFIXnamePrefix
NAME_SUFFIXnameSuffix
PHONETICFIRSTNAMEphoneticFirstName
PHONETICMIDDLENAMEphoneticMiddleName
PHONETICLASTNAMEphoneticLastName
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.