Guides
Plan-enterprise-icon
Expo Application Services
API Reference

Contacts

expo-contacts provides access to the device's system contacts, allowing you to get contact information as well as adding, editing, or removing contacts.
On iOS contacts have a multi-layered grouping system that you can also access through this API.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-failed-icon

Installation

Terminal
→ npx expo install expo-contacts

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

Usage

Basic Contacts 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.addContactAsync(contact, containerId)

NameTypeDescription
contactContact

A contact with the changes you wish to persist. The id parameter will not be used.

containerId
(optional)
stringOnly for: 
Apple-iconiOS

The container that will parent the contact.

Creates a new contact and adds it to the system.

Info-icon

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);
  • Undo-iconPromise<string>

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

Only for:
Apple-iconiOS

Contacts.addExistingContactToGroupAsync(contactId, groupId)

NameTypeDescription
contactIdstring

ID of the contact you want to edit.

groupIdstring

ID for the group you want to add membership to.

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'
);
Only for:
Apple-iconiOS

Contacts.addExistingGroupToContainerAsync(groupId, containerId)

NameTypeDescription
groupIdstring

The group you want to target.

containerIdstring

The container you want to add membership to.

Add a group to a container.

Example

await Contacts.addExistingGroupToContainerAsync(
  '161A368D-D614-4A15-8DC6-665FDBCFAE55',
  '665FDBCFAE55-D614-4A15-8DC6-161A368D'
);
Only for:
Apple-iconiOS

Contacts.createGroupAsync(name, containerId)

NameTypeDescription
name
(optional)
string

Name of the new group.

containerId
(optional)
string

The container you to add membership to.

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

A promise that fulfills with ID of the new group.

Contacts.getContactByIdAsync(id, fields)

NameTypeDescription
idstring

The ID of a system contact.

fields
(optional)
FieldType[]

If specified, the fields defined will be returned. When skipped, all fields will be returned.

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

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

Contacts.getContactsAsync(contactQuery)

NameTypeDescription
contactQuery
(optional)
ContactQuery

Object used to query contacts.

Default: {}

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

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

Only for:
Apple-iconiOS

Contacts.getContainersAsync(containerQuery)

NameTypeDescription
containerQueryContainerQuery

Information used to gather containers.

Query a list of system containers.

Example

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

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

Only for:
Apple-iconiOS

Contacts.getDefaultContainerIdAsync()

Get the default container's ID.

Example

const containerId = await Contacts.getDefaultContainerIdAsync();

A promise that fulfills with default container ID.

Only for:
Apple-iconiOS

Contacts.getGroupsAsync(groupQuery)

NameTypeDescription
groupQueryGroupQuery

Information regarding which groups you want to get.

Query and return a list of system groups.

Example

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

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

Contacts.getPermissionsAsync()

Checks user's permissions for accessing contacts data.

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.

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)

NameTypeDescription
contactId
(optional)
null | string

The ID of a system contact.

contact
(optional)
null | Contact

A contact with the changes you want to persist.

formOptions
(optional)
FormOptions

Options for the native editor.

Default: {}

Present a native form for manipulating contacts.

Example

await Contacts.presentFormAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Only for:
Apple-iconiOS

Contacts.removeContactAsync(contactId)

NameTypeDescription
contactIdstring

ID of the contact you want to delete.

Delete a contact from the system.

Example

await Contacts.removeContactAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Only for:
Apple-iconiOS

Contacts.removeContactFromGroupAsync(contactId, groupId)

NameTypeDescription
contactIdstring

ID of the contact you want to remove.

groupIdstring

ID for the group you want to remove membership of.

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'
);
Only for:
Apple-iconiOS

Contacts.removeGroupAsync(groupId)

NameTypeDescription
groupIdstring

ID of the group you want to remove.

Delete a group from the device.

Example

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

Contacts.requestPermissionsAsync()

Asks the user to grant permissions for accessing contacts data.

A promise that resolves to a PermissionResponse object.

Contacts.shareContactAsync(contactId, message, shareOptions)

NameTypeDescription
contactIdstring-
messagestring-
shareOptions
(optional)
object-
Only for:
Apple-iconiOS

Contacts.updateContactAsync(contact)

NameTypeDescription
contactContact

A contact object including the wanted changes.

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

Info-icon
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);

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

Only for:
Apple-iconiOS

Contacts.updateGroupNameAsync(groupName, groupId)

NameTypeDescription
groupNamestring

New name for an existing group.

groupIdstring

ID of the group you want to edit.

Change the name of an existing group.

Example

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

Contacts.writeContactToFileAsync(contactQuery)

NameTypeDescription
contactQuery
(optional)
ContactQuery

Used to query contact you want to write.

Default: {}

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!' });
  • Undo-iconPromise<string | undefined>

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

Interfaces

PermissionResponse

An object obtained by permissions get and request functions.

NameTypeDescription
canAskAgainbooleanIndicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expiresPermissionExpirationDetermines time when the permission expires.
grantedbooleanA convenience boolean that indicates if the permission is granted.
statusPermissionStatusDetermines the status of the permission.

Types

Address

NameTypeDescription
city
(optional)
stringCity name.
country
(optional)
stringCountry name
idstringUnique ID.
isoCountryCode
(optional)
stringStandard country code.
labelstringLocalized display name.
neighborhood
(optional)
stringNeighborhood name.
poBox
(optional)
stringP.O. Box.
postalCode
(optional)
stringLocal post code.
region
(optional)
stringRegion or state name.
street
(optional)
stringStreet name.

CalendarFormatType

Acceptable values are: CalendarFormats.

Contact

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

NameTypeDescription
addresses
(optional)
Address[]Locations.
birthday
(optional)
DateBirthday information in Gregorian format.
company
(optional)
stringOrganization the entity belongs to.
contactTypeContactTypeDenoting a person or company.
dates
(optional)
Date[]A labeled list of other relevant user dates in Gregorian format.
department
(optional)
stringJob department.
emails
(optional)
Email[]Email addresses.
firstName
(optional)
stringGiven name.
idstringImmutable identifier used for querying and indexing.
image
(optional)
ImageThumbnail image. On iOS it size is set to 320×320px, on Android it may vary.
imageAvailable
(optional)
booleanUsed for efficient retrieval of images.
instantMessageAddresses
(optional)
InstantMessageAddress[]Instant messaging connections.
jobTitle
(optional)
stringJob description.
lastName
(optional)
stringLast name.
maidenName
(optional)
stringMaiden name.
middleName
(optional)
stringMiddle name
namestringFull name with proper format.
namePrefix
(optional)
stringDr. Mr. Mrs. ect…
nameSuffix
(optional)
stringJr. Sr. ect…
nickname
(optional)
stringAn alias to the proper name.
nonGregorianBirthday
(optional)
DateOnly for:
Apple-iconiOS

Birthday that doesn't conform to the Gregorian calendar format, interpreted based on the calendar format setting.
note
(optional)
stringAdditional information.
Info-icon
On iOS 13+, 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, set the ios.accessesContactNotes field in app.json to true, and create your development build.
phoneNumbers
(optional)
PhoneNumber[]Phone numbers.
phoneticFirstName
(optional)
stringPronunciation of the first name.
phoneticLastName
(optional)
stringPronunciation of the last name.
phoneticMiddleName
(optional)
stringPronunciation of the middle name.
rawImage
(optional)
ImageRaw image without cropping, usually large.
relationships
(optional)
Relationship[]Names of other relevant user connections.
socialProfiles
(optional)
SocialProfile[]Only for:
Apple-iconiOS

Social networks.
urlAddresses
(optional)
UrlAddress[]Associated web URLs.

ContactQuery

Used to query contacts from the user's device.

NameTypeDescription
containerId
(optional)
stringOnly for:
Apple-iconiOS

Get all contacts that belong to the container matching this ID.
fields
(optional)
FieldType[]If specified, the defined fields will be returned. If skipped, all fields will be returned.
groupId
(optional)
stringOnly for:
Apple-iconiOS

Get all contacts that belong to the group matching this ID.
id
(optional)
string | string[]Get contacts with a matching ID or array of IDs.
name
(optional)
stringGet all contacts whose name contains the provided string (not case-sensitive).
pageOffset
(optional)
numberThe number of contacts to skip before gathering contacts.
pageSize
(optional)
numberThe max number of contacts to return. If skipped or set to 0 all contacts will be returned.
rawContacts
(optional)
booleanOnly for:
Apple-iconiOS

Prevent unification of contacts when gathering.
Default: false
sort
(optional)
ContactSortSort method used when gathering contacts.

ContactResponse

The return value for queried contact operations like getContactsAsync.

NameTypeDescription
dataContact[]An array of contacts that match a particular query.
hasNextPagebooleanThis will be true if there are more contacts to retrieve beyond what is returned.
hasPreviousPagebooleanThis will be true if there are previous contacts that weren't retrieved due to pageOffset` limit.

ContactType

Acceptable values are: ContactTypes.

Container

NameTypeDescription
idstring-
namestring-
typeContainerType-

ContainerQuery

Only for:
Apple-iconiOS

Used to query native contact containers.

NameTypeDescription
contactId
(optional)
stringQuery all the containers that parent a contact.
containerId
(optional)
string | string[]Query all the containers that matches ID or an array od IDs.
groupId
(optional)
stringQuery all the containers that parent a group.

ContainerType

Acceptable values are: ContainerTypes.

Date

NameTypeDescription
day
(optional)
numberDay.
format
(optional)
CalendarFormatTypeFormat for the input date.
idstringUnique ID.
labelstringLocalized display name.
month
(optional)
numberMonth - adjusted for JavaScript Date which starts at 0.
year
(optional)
numberYear.

Email

NameTypeDescription
email
(optional)
stringEmail address.
idstringUnique ID.
isPrimary
(optional)
booleanFlag signifying if it is a primary email address.
labelstringLocalized display name.

FieldType

Acceptable values are: Fields.

FormOptions

Denotes the functionality of a native contact form.

NameTypeDescription
allowsActions
(optional)
booleanActions like share, add, create.
allowsEditing
(optional)
booleanAllows for contact mutation.
alternateName
(optional)
stringUsed if contact doesn't have a name defined.
cancelButtonTitle
(optional)
stringThe name of the left bar button.
displayedPropertyKeys
(optional)
FieldType[]The properties that will be displayed. On iOS those properties does nothing while in editing mode.
groupId
(optional)
stringThe parent group for a new contact.
isNew
(optional)
booleanPresent the new contact controller. If set to false the unknown controller will be shown.
message
(optional)
stringController title.
preventAnimation
(optional)
booleanPrevents the controller from animating in.
shouldShowLinkedContacts
(optional)
booleanShow or hide the similar contacts.

Group

Only for:
Apple-iconiOS

A parent to contacts. A contact can belong to multiple groups. Here are some query operations you can perform:

  • Child Contacts: getContactsAsync({ groupId })
  • Groups From Container: getGroupsAsync({ containerId })
  • Groups Named: getContainersAsync({ groupName })
NameTypeDescription
id
(optional)
stringThe editable name of a group.
name
(optional)
stringImmutable id representing the group.

GroupQuery

Only for:
Apple-iconiOS

Used to query native contact groups.

NameTypeDescription
containerId
(optional)
stringQuery all groups that belong to a certain container.
groupId
(optional)
stringQuery the group with a matching ID.
groupName
(optional)
stringQuery all groups matching a name.

Image

Information regarding thumbnail images.

Info-icon

On Android you can get dimensions using Image.getSize method.

NameTypeDescription
base64
(optional)
stringImage as Base64 string.
height
(optional)
numberOnly for:
Apple-iconiOS

Image height
uri
(optional)
string-
width
(optional)
numberOnly for:
Apple-iconiOS

Image width.

InstantMessageAddress

NameTypeDescription
idstringUnique ID.
labelstringLocalized display name.
localizedService
(optional)
stringLocalized name of app.
service
(optional)
stringName of instant messaging app.
username
(optional)
stringUsername in IM app.

PhoneNumber

NameTypeDescription
countryCode
(optional)
stringCountry code.
Example
+1
digits
(optional)
stringPhone number without format.
Example
8674305
idstringUnique ID.
isPrimary
(optional)
booleanFlag signifying if it is a primary phone number.
labelstringLocalized display name.
number
(optional)
stringPhone number.

Relationship

NameTypeDescription
idstringUnique ID.
labelstringLocalized display name.
name
(optional)
stringName of related contact.

SocialProfile

Only for:
Apple-iconiOS

NameTypeDescription
idstringUnique ID.
labelstringLocalized display name.
localizedProfile
(optional)
stringLocalized profile name.
service
(optional)
stringName of social app.
url
(optional)
stringWeb URL.
userId
(optional)
stringUsername ID in social app.
username
(optional)
stringUsername in social app.

UrlAddress

NameTypeDescription
idstringUnique ID.
labelstringLocalized display name.
url
(optional)
stringWeb URL.

Enums

CalendarFormats

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

Only for:
Apple-iconiOS

CalendarFormats.Buddhist = "buddhist"
Only for:
Apple-iconiOS

CalendarFormats.Chinese = "chinese"
Only for:
Apple-iconiOS

CalendarFormats.Coptic = "coptic"
Only for:
Apple-iconiOS

CalendarFormats.EthiopicAmeteAlem = "ethiopicAmeteAlem"
Only for:
Apple-iconiOS

CalendarFormats.EthiopicAmeteMihret = "ethiopicAmeteMihret"
CalendarFormats.Gregorian = "gregorian"
Only for:
Apple-iconiOS

CalendarFormats.Hebrew = "hebrew"
Only for:
Apple-iconiOS

CalendarFormats.ISO8601 = "iso8601"
Only for:
Apple-iconiOS

CalendarFormats.Indian = "indian"
Only for:
Apple-iconiOS

CalendarFormats.Islamic = "islamic"
Only for:
Apple-iconiOS

CalendarFormats.IslamicCivil = "islamicCivil"
Only for:
Apple-iconiOS

CalendarFormats.IslamicTabular = "islamicTabular"
Only for:
Apple-iconiOS

CalendarFormats.IslamicUmmAlQura = "islamicUmmAlQura"
Only for:
Apple-iconiOS

CalendarFormats.Japanese = "japanese"
Only for:
Apple-iconiOS

CalendarFormats.Persian = "persian"
Only for:
Apple-iconiOS

CalendarFormats.RepublicOfChina = "republicOfChina"

ContactTypes

ContactTypes.Company = "company"

Contact is group or company.

ContactTypes.Person = "person"

Contact is a human.

Only for:
Apple-iconiOS

ContainerTypes

ContainerTypes.CardDAV = "cardDAV"

With cardDAV protocol used for sharing.

ContainerTypes.Exchange = "exchange"

In association with email server.

ContainerTypes.Local = "local"

A local non-iCloud container.

ContainerTypes.Unassigned = "unassigned"

Unknown container.

Fields

Possible fields to retrieve for a contact.

Fields.Addresses = "addresses"
Fields.Birthday = "birthday"
Fields.Company = "company"
Fields.ContactType = "contactType"
Fields.Dates = "dates"
Fields.Department = "department"
Fields.Emails = "emails"
Fields.ExtraNames = "extraNames"
Fields.FirstName = "firstName"
Fields.ID = "id"
Fields.Image = "image"
Fields.ImageAvailable = "imageAvailable"
Fields.InstantMessageAddresses = "instantMessageAddresses"
Fields.JobTitle = "jobTitle"
Fields.LastName = "lastName"
Fields.MaidenName = "maidenName"
Fields.MiddleName = "middleName"
Fields.Name = "name"
Fields.NamePrefix = "namePrefix"
Fields.NameSuffix = "nameSuffix"
Fields.Nickname = "nickname"
Only for:
Apple-iconiOS

Fields.NonGregorianBirthday = "nonGregorianBirthday"
Fields.Note = "note"
Fields.PhoneNumbers = "phoneNumbers"
Fields.PhoneticFirstName = "phoneticFirstName"
Fields.PhoneticLastName = "phoneticLastName"
Fields.PhoneticMiddleName = "phoneticMiddleName"
Fields.RawImage = "rawImage"
Fields.Relationships = "relationships"
Only for:
Apple-iconiOS

Fields.SocialProfiles = "socialProfiles"
Fields.UrlAddresses = "urlAddresses"

PermissionStatus

PermissionStatus.DENIED = "denied"

User has denied the permission.

PermissionStatus.GRANTED = "granted"

User has granted the permission.

PermissionStatus.UNDETERMINED = "undetermined"

User hasn't granted or denied the permission yet.

SortTypes

SortTypes.FirstName = "firstName"

Sort by first name in ascending order.

SortTypes.LastName = "lastName"

Sort by last name in ascending order.

SortTypes.None = "none"

No sorting should be applied.

Only for:
Android-iconAndroid

SortTypes.UserDefault = "userDefault"

The user default method of sorting.

  • Message-iconAsk a question on the forums about Contacts
  • Github-iconView open bug reports for Contacts
  • Code-iconView source code for Contacts
  • Build-iconView package in npm Registry
  • Edit-iconEdit this page

Was this doc helpful?