Documentation

Hey friend! We are co-hosting a conference with Software Mansion, learn more.

Contacts

Provides access to the phone's system contacts.

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
NameTypeDescription
contactQueryContactQueryUsed to query contacts.
Returns
NameTypeDescription
contactResponseContactResponseContacts returned from the query.
Example
const { data } = await Contacts.getContactsAsync({
  fields: [Contacts.Fields.Emails],
});

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

getContactByIdAsync(contactId: string, fields: FieldType[]): Promise<Contact>
Returns a contact matching the input id. Used for gathering precise data about a contact.
Parameters
NameTypeDescription
contactIdstringThe ID of a system contact.
fieldsFieldType[]If available the fields defined will be returned. If nil then all fields will be returned.
Returns
NameTypeDescription
contactContactContact with an ID matching the input ID.
Example
const contact = await Contacts.getContactByIdAsync("161A368D-D614-4A15-8DC6-665FDBCFAE55");
if (contact) {
  console.log(contact);
}

iOS Only - temporary
addContactAsync(contact: Contact, containerId: string): Promise<string>
Creates a new contact and adds it to the system.
Parameters
NameTypeDescription
contactContactA contact with the changes you wish to persist. The id parameter will not be used.
containerIdstringIOS ONLY: The container that will parent the contact
Returns
NameTypeDescription
contactIdstringID of the new system contact.
Example
const contact = {
  [Contacts.Fields.FirstName]: "Bird",
  [Contacts.Fields.LastName]: "Man",
  [Contacts.Fields.Company]: "Young Money",
}
const contactId = await Contacts.addContactAsync(contact);

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
NameTypeDescription
contactContactA contact with the changes you wish to persist. The contact must contain a vaild id
Returns
NameTypeDescription
contactIdstringThe ID of a system contact.
Example
const contact = {
  id: "161A368D-D614-4A15-8DC6-665FDBCFAE55",
  [Contacts.Fields.FirstName]: "Drake",
  [Contacts.Fields.Company]: "Young Money",
}
await Contacts.updateContactAsync(contact);

iOS Only - temporary
removeContactAsync(contactId: string): Promise<any>
Delete a contact from the system.
Parameters
NameTypeDescription
contactIdstringID of the contact you want to delete.
Example
await Contacts.removeContactAsync("161A368D-D614-4A15-8DC6-665FDBCFAE55");

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
NameTypeDescription
contactQueryContactQueryUsed to query contacts you want to write.
Returns
NameTypeDescription
localUristringShareable local uri
Example
const localUri = await Contacts.writeContactToFileAsync({ id: "161A368D-D614-4A15-8DC6-665FDBCFAE55" });
Share.share({ url: localUri, message: "Call me!" });

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

presentFormAsync(contactId: string, contact: Contact, formOptions: FormOptions): Promise<any>
Present a native form for manipulating contacts
Parameters
NameTypeDescription
contactIdstringThe ID of a system contact.
contactContactA contact with the changes you wish to persist.
formOptionsFormOptionsOptions for the native editor
Example
// Edit contact
await Contacts.presentFormAsync("161A368D-D614-4A15-8DC6-665FDBCFAE55");

addExistingGroupToContainerAsync(groupId: string, containerId: string): Promise<any>
Add a group to a container.
Parameters
NameTypeDescription
groupIdstringThe group you wish to target.
containerIdstringThe container you to add membership to.
Example
await Contacts.addExistingGroupToContainerAsync("161A368D-D614-4A15-8DC6-665FDBCFAE55", "665FDBCFAE55-D614-4A15-8DC6-161A368D");

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
NameTypeDescription
namestringName of the new group.
containerIdstringThe container you to add membership to.
Returns
NameTypeDescription
groupIdstringID of the new group.
Example
const groupId = await Contacts.createGroupAsync("Sailor Moon");

updateGroupNameAsync(groupName: string, groupId: string): Promise<any>
Change the name of an existing group.
Parameters
NameTypeDescription
groupNamestringNew name for an existing group.
groupIdstringID for the group you want to edit.
Example
await Contacts.updateGroupName("Sailor Moon", "161A368D-D614-4A15-8DC6-665FDBCFAE55");

removeGroupAsync(groupId: string): Promise<any>
Delete a group from the device.
Parameters
NameTypeDescription
groupIdstringID of the group.
Example
await Contacts.removeGroupAsync("161A368D-D614-4A15-8DC6-665FDBCFAE55");

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
NameTypeDescription
contactIdstringID of the contact you want to edit.
groupIdstringID for the group you want to add membership to.
Example
await Contacts.addExistingContactToGroupAsync("665FDBCFAE55-D614-4A15-8DC6-161A368D", "161A368D-D614-4A15-8DC6-665FDBCFAE55");

removeContactFromGroupAsync(contactId: string, groupId: string): Promise<any>
Remove a contact's membership from a given group. This will not delete the contact.
Parameters
NameTypeDescription
contactIdstringID of the contact you want to remove.
groupIdstringID for the group you want to remove membership of.
Example
await Contacts.removeContactFromGroupAsync("665FDBCFAE55-D614-4A15-8DC6-161A368D", "161A368D-D614-4A15-8DC6-665FDBCFAE55");

getGroupsAsync(query: GroupQuery): Promise<Group[]>
Query and return a list of system groups.
Parameters
NameTypeDescription
queryGroupQueryInformation regarding which groups you want to get.
Returns
NameTypeDescription
groupsGroup[]Collection of groups that fit query.
Example
const groups = await Contacts.getGroupsAsync({ groupName: "sailor moon" });
const allGroups = await Contacts.getGroupsAsync({});

getDefaultContainerIdAsync(): Promise<string>
Get the default container's ID.
Returns
NameTypeDescription
containerIdstringDefault container ID.
Example
const containerId = await Contacts.getDefaultContainerIdAsync();

getContainersAsync(containerQuery: ContainerQuery): Promise<Container[]>
Query a list of system containers.
Parameters
NameTypeDescription
containerQueryContainerQueryInformation used to gather containers.
Returns
NameTypeDescription
containerIdstringCollection of containers that fit query.
Example
const allContainers = await getContainersAsync({ contactId: "665FDBCFAE55-D614-4A15-8DC6-161A368D" });

A set of fields that define information about a single entity.
NameTypeDescriptioniOSAndroid
idstringImmutable identifier used for querying and indexing.
namestringFull name with proper format.
firstNamestringGiven name.
middleNamestringMiddle name.
lastNamestringFamily name.
maidenNamestringMaiden name.
namePrefixstringDr. Mr. Mrs. Ect…
nameSuffixstringJr. Sr. Ect…
nicknamestringAn alias to the proper name.
phoneticFirstNamestringPronunciation of the first name.
phoneticMiddleNamestringPronunciation of the middle name.
phoneticLastNamestringPronunciation of the last name.
companystringOrganization the entity belongs to.
jobTitlestringJob description.
departmentstringJob department.
notestringAdditional information.
imageAvailablebooleanUsed for efficient retrieval of images.
imageImageThumbnail image (ios: 320x320)
rawImageImageRaw image without cropping, usually large.
contactTypeContactTypeDenoting a person or company.
birthdayDateBirthday information in JS format.
datesDate[]A list of other relevant user dates.
relationshipsRelationship[]Names of other relevant user connections
emailsEmail[]Email addresses
phoneNumbersPhoneNumber[]Phone numbers
addressesAddress[]Locations
instantMessageAddressesInstantMessageAddress[]IM connections
urlAddressesUrlAddress[]Web Urls
nonGregorianBirthdayDateBirthday that doesn't conform to the Gregorian calendar format
socialProfilesSocialProfile[]Social networks
thumbnailImageDeprecated: Use image
previousLastNamestringDeprecated: Use maidenName

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 })
NameTypeDescription
idstringImmutable id representing the group
namestringThe editable name of a group

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 })
NameTypeDescription
idstringImmutable id representing the group
namestringThe editable name of a group

NameTypeDescription
daynumberDay.
monthnumberMonth - adjusted for JS Date which starts at 0.
yearnumberYear.
formatCalendarFormatTypeFormat for input date.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
namestringName of related contact.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
emailstringemail address.
isPrimarybooleanPrimary email address.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
numberstringPhone number.
isPrimarybooleanPrimary phone number.
digitsstringPhone number without format, ex: 8674305.
countryCodestringCountry code, ex: +1.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
streetstringStreet name.
citystringCity name.
countrystringCountry name.
regionstringRegion or state name.
neighborhoodstringNeighborhood name.
postalCodestringLocal post code.
poBoxstringP.O. Box.
isoCountryCodestringStandard code.
idstringUnique ID.
labelstringLocalized display name.

iOS Only
NameTypeDescription
servicestringName of social app.
usernamestringUsername in social app.
localizedProfilestringLocalized name.
urlstringWeb URL.
userIdstringUID for social app.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
servicestringName of social app.
usernamestringUsername in IM app.
localizedServicestringLocalized name of app.
idstringUnique ID.
labelstringLocalized display name.

NameTypeDescription
urlstringWeb URL
idstringUnique ID.
labelstringLocalized display name.

Information regarding thumbnail images.
NameTypeiOSAndroid
uristring
widthnumber
heightnumber
base64string
Android: You can get dimensions using ReactNative.Image.getSize. Avoid using Base 64 in React Native

Denotes the functionality of a native contact form.
NameTypeDescription
displayedPropertyKeysFieldType[]The properties that will be displayed. iOS: Does nothing in editing mode.
messagestringController title.
alternateNamestringUsed if contact doesn't have a name defined.
cancelButtonTitlestringThe name of the left bar button.
groupIdstringThe parent group for a new contact.
allowsEditingbooleanAllows for contact mutation.
allowsActionsbooleanActions like share, add, create.
shouldShowLinkedContactsbooleanShows similar contacts.
isNewbooleanPresent the new contact controller - if false the unknown controller will be shown.
preventAnimationbooleanPrevents the controller from animating in.

Used to query contacts from the user's device.
NameTypeDescriptioniOSAndroid
fieldsFieldType[]If available the fields defined will be returned. If nil then all fields will be returned.
pageSizenumberThe max number of contacts to return. If nil or 0 then all contacts will be returned.
pageOffsetnumberThe number of contacts to skip before gathering contacts.
idstringGet contacts with a matching ID .
sortSortTypeSort method used when gathering contacts.
namestringQuery contacts matching this name.
groupIdstringGet all contacts that belong to the group matching this ID.
containerIdstringGet all contacts that belong to the container matching this ID.
rawContactsbooleanPrevent unification of contacts when gathering. Default: false.

iOS Only
Used to query native contact groups.
NameTypeDescription
groupNamestringQuery all groups matching a name.
groupIdstringQuery the group with a matching ID.
containerIdstringQuery all groups that belong to a certain container.

iOS Only
Used to query native contact containers.
NameTypeDescription
contactIdstringQuery all the containers that parent a contact.
groupIdstringQuery all the containers that parent a group.
containerIdstringQuery a container from it's ID.

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.
hasPreviousPagebooleantrue if there are previous contacts that weren't retrieved due to pageOffset.
~~total~~numberDeprecated: use data.length to get the number of contacts returned.

const contactField = Contact.Fields.FirstName;
NameValueiOSAndroid
ID'id'
Name'name'
FirstName'firstName'
MiddleName'middleName'
LastName'lastName'
NamePrefix'namePrefix'
NameSuffix'nameSuffix'
PhoneticFirstName'phoneticFirstName'
PhoneticMiddleName'phoneticMiddleName'
PhoneticLastName'phoneticLastName'
Birthday'birthday'
Emails'emails'
PhoneNumbers'phoneNumbers'
Addresses'addresses'
InstantMessageAddresses'instantMessageAddresses'
UrlAddresses'urlAddresses'
Company'company'
JobTitle'jobTitle'
Department'department'
ImageAvailable'imageAvailable'
Image'image'
Note'note'
Dates'dates'
Relationships'relationships'
Nickname'nickname'
RawImage'rawImage'
MaidenName'maidenName'
ContactType'contactType'
SocialProfiles'socialProfiles'
NonGregorianBirthday'nonGregorianBirthday'
ThumbnailDeprecated: use Image
PreviousLastNameDeprecated: use MaidenName

const formType = Contacts.FormTypes.New;
NameValueDescription
New'new'Creating a contact
Unknown'unknown'Displaying a contact with actions
Default'default'Information regarding a contact

iOS Only
const contactType = Contacts.ContactTypes.Person;
NameValueDescription
Person'person'Contact is a human
Company'company'Contact is group or company

const sortType = Contacts.SortTypes.FirstName;
NameValueDescriptioniOSAndroid
FirstName'firstName'Sort by first name in ascending order
LastName'lastName'Sort by last name in ascending order
UserDefault'userDefault'The user default method of sorting

iOS Only
const containerType = Contacts.ContainerTypes.CardDAV;
NameValueDescription
Local'local'A local non-iCloud container
Exchange'exchange'In association with Email
CardDAV'cardDAV'cardDAV protocol used for sharing
Unassigned'unassigned'Unknown

const calendarFormat = Contacts.CalendarFormats.Coptic;
This format denotes the common calendar format used to specify how a date is calculated in nonGregorianBirthday fields.
ConstantvalueiOSAndroid
Gregorian'gregorian'
Chinese'chinese'
Hebrew'hebrew'
Islamic'islamic'

Deprecated: Use Contacts.Fields
This table illustrates what fields will be added on demand to every contact.
ConstantvalueiOSAndroid
PHONE_NUMBERS'phoneNumbers'
EMAILS'emails'
ADDRESSES'addresses'
IMAGE'image'
NOTE'note'
NAME_PREFIX'namePrefix'
NAME_SUFFIX'nameSuffix'
PHONETICFIRSTNAME'phoneticFirstName'
PHONETICMIDDLENAME'phoneticMiddleName'
PHONETICLASTNAME'phoneticLastName'
IM_ADDRESSES'instantMessageAddresses'
URLS'urlAddresses'
DATES'dates'
NONGREGORIANBIRTHDAY'nonGregorianBirthday'
SOCIAL_PROFILES'socialProfiles'
RAW_IMAGE'rawImage'
THUMBNAIL'thumbnail'DeprecatedDeprecated
PREVIOUSLASTNAME'previousLastName'DeprecatedDeprecated

  • The thumnail field has been deprecated, use image on both platforms instead.
  • On iOS image is now rawImage. There is no Android version of rawImage.
  • Images now return a localUri instead of Base64 string.
  • Base64 string is now returned in a encodable format.
  • Empty contact fields will no longer be returned as empty strings on iOS.
  • Passing no fields will now return all contact information.