Contacts expo-contacts
Platform Compatibility Android Device Android Emulator iOS Device iOS Simulator Web
In Managed apps, Contacts requires Permissions.CONTACTS.
import React , { useEffect } from 'react' ;
import { 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= { {
flex: 1 ,
backgroundColor: '#fff' ,
alignItems: 'center' ,
justifyContent: 'center' ,
} } >
< Text > Contacts Module Example < / Text >
< / View >
) ;
}
import * as Contacts from 'expo-contacts' ;
Asks the user to grant permissions for accessing contacts data. Alias for Permissions.askAsync(Permissions.CONTACTS).
Checks user's permissions for accessing contacts data. Alias for Permissions.getAsync(Permissions.CONTACTS).
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
Name Type Description contactQuery ContactQueryUsed to query contacts.
Returns
Name Type Description contactResponse ContactResponseContacts 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) ;
}
Contacts . getContactByIdAsync ( contactId: string, fields: FieldType [ ] ) : Promise < Contact >
Returns a contact matching the input id. Used for gathering precise data about a contact.
Parameters
Name Type Description contactId stringThe ID of a system contact. fields FieldType[]If available the fields defined will be returned. If nil then all fields will be returned.
Returns
Name Type Description contact ContactContact with an ID matching the input ID.
Example
const contact = await Contacts . getContactByIdAsync ( '161A368D-D614-4A15-8DC6-665FDBCFAE55' ) ;
if ( contact) {
console . log ( contact) ;
}
Contacts . addContactAsync ( contact: Contact , containerId: string) : Promise < string>
Creates a new contact and adds it to the system.
Note : For Android users, the Expo client App does not have the required
WRITE_CONTACTS permission to write to Contacts. In order to do this, you must build a
standalone app and add permission through there.
Parameters
Name Type Description contact ContactA contact with the changes you wish to persist. The id parameter will not be used. containerId stringIOS ONLY: The container that will parent the contact
Returns
Name Type Description contactId stringID 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) ;
Contacts . updateContactAsync ( contact: Contact ) : Promise < string>
Mutate the information of an existing contact.
On Android, you can use presentFormAsync to make edits to contacts.
Due to an iOS bug, nonGregorianBirthday cannot be modified.
Contacts . presentFormAsync ( contactId: string, contact: Contact , formOptions: FormOptions ) : Promise < any>
Present a native form for manipulating contacts
Parameters
Name Type Description contactId stringThe ID of a system contact. contact ContactA contact with the changes you wish to persist. formOptions FormOptionsOptions for the native editor
Example
await Contacts . presentFormAsync ( '161A368D-D614-4A15-8DC6-665FDBCFAE55' ) ;
Parameters
Name Type Description contact ContactA contact with the changes you wish to persist. The contact must contain a vaild id
Returns
Name Type Description contactId stringThe 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) ;
Contacts . removeContactAsync ( contactId: string) : Promise < any>
Delete a contact from the system.
Parameters
Name Type Description contactId stringID of the contact you want to delete.
Example
await Contacts . removeContactAsync ( '161A368D-D614-4A15-8DC6-665FDBCFAE55' ) ;
Contacts . 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
Name Type Description contactQuery ContactQueryUsed to query contacts you want to write.
Returns
Name Type Description localUri stringShareable 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.
Contacts . addExistingGroupToContainerAsync ( groupId: string, containerId: string) : Promise < any>
Add a group to a container.
Parameters
Name Type Description groupId stringThe group you wish to target. containerId stringThe container you to add membership to.
Example
await Contacts . addExistingGroupToContainerAsync (
'161A368D-D614-4A15-8DC6-665FDBCFAE55' ,
'665FDBCFAE55-D614-4A15-8DC6-161A368D'
) ;
Contacts . 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
Name Type Description name stringName of the new group. containerId stringThe container you to add membership to.
Returns
Name Type Description groupId stringID of the new group.
Example
const groupId = await Contacts . createGroupAsync ( 'Sailor Moon' ) ;
Contacts . updateGroupNameAsync ( groupName: string, groupId: string) : Promise < any>
Change the name of an existing group.
Parameters
Name Type Description groupName stringNew name for an existing group. groupId stringID for the group you want to edit.
Example
await Contacts . updateGroupName ( 'Sailor Moon' , '161A368D-D614-4A15-8DC6-665FDBCFAE55' ) ;
Contacts . removeGroupAsync ( groupId: string) : Promise < any>
Delete a group from the device.
Parameters
Name Type Description groupId stringID of the group.
Example
await Contacts . removeGroupAsync ( '161A368D-D614-4A15-8DC6-665FDBCFAE55' ) ;
Contacts . 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
Name Type Description contactId stringID of the contact you want to edit. groupId stringID for the group you want to add membership to.
Example
await Contacts . addExistingContactToGroupAsync (
'665FDBCFAE55-D614-4A15-8DC6-161A368D' ,
'161A368D-D614-4A15-8DC6-665FDBCFAE55'
) ;
Contacts . removeContactFromGroupAsync ( contactId: string, groupId: string) : Promise < any>
Remove a contact's membership from a given group. This will not delete the contact.
Parameters
Name Type Description contactId stringID of the contact you want to remove. groupId stringID for the group you want to remove membership of.
Example
await Contacts . removeContactFromGroupAsync (
'665FDBCFAE55-D614-4A15-8DC6-161A368D' ,
'161A368D-D614-4A15-8DC6-665FDBCFAE55'
) ;
Contacts . getGroupsAsync ( query: GroupQuery ) : Promise < Group [ ] >
Query and return a list of system groups.
Parameters
Name Type Description query GroupQueryInformation regarding which groups you want to get.
Returns
Name Type Description groups Group[]Collection of groups that fit query.
Example
const groups = await Contacts . getGroupsAsync ( { groupName: 'sailor moon' } ) ;
const allGroups = await Contacts . getGroupsAsync ( { } ) ;
Contacts . getDefaultContainerIdAsync ( ) : Promise < string>
Get the default container's ID.
Returns
Name Type Description containerId stringDefault container ID.
Example
const containerId = await Contacts . getDefaultContainerIdAsync ( ) ;
Contacts . getContainersAsync ( containerQuery: ContainerQuery ) : Promise < Container [ ] >
Query a list of system containers.
Parameters
Name Type Description containerQuery ContainerQueryInformation used to gather containers.
Returns
Name Type Description containerId stringCollection of containers that fit query.
Example
const allContainers = await Contacts . getContainersAsync ( {
contactId: '665FDBCFAE55-D614-4A15-8DC6-161A368D' ,
} ) ;
A set of fields that define information about a single entity.
Name Type Description iOS Android id stringImmutable identifier used for querying and indexing. ✅ ✅ name stringFull name with proper format. ✅ ✅ firstName stringGiven name. ✅ ✅ middleName stringMiddle name. ✅ ✅ lastName stringFamily name. ✅ ✅ maidenName stringMaiden name. ✅ ✅ namePrefix stringDr. Mr. Mrs. Ect... ✅ ✅ nameSuffix stringJr. Sr. Ect... ✅ ✅ nickname stringAn alias to the proper name. ✅ ✅ phoneticFirstName stringPronunciation of the first name. ✅ ✅ phoneticMiddleName stringPronunciation of the middle name. ✅ ✅ phoneticLastName stringPronunciation of the last name. ✅ ✅ company stringOrganization the entity belongs to. ✅ ✅ jobTitle stringJob description. ✅ ✅ department stringJob department. ✅ ✅ note stringAdditional information. ✅ ✅ imageAvailable booleanUsed for efficient retrieval of images. ✅ ✅ image ImageThumbnail image (ios: 320x320) ✅ ✅ rawImage ImageRaw image without cropping, usually large. ✅ ✅ contactType ContactTypeDenoting a person or company. ✅ ✅ birthday DateBirthday information in JS format. ✅ ✅ dates Date[]A list of other relevant user dates. ✅ ✅ relationships Relationship[]Names of other relevant user connections ✅ ✅ emails Email[]Email addresses ✅ ✅ phoneNumbers PhoneNumber[]Phone numbers ✅ ✅ addresses Address[]Locations ✅ ✅ instantMessageAddresses InstantMessageAddress[]IM connections ✅ ✅ urlAddresses UrlAddress[]Web Urls ✅ ✅ nonGregorianBirthday DateBirthday that doesn't conform to the Gregorian calendar format ✅ ❌ socialProfiles SocialProfile[]Social networks ✅ ❌ thumbnail ImageDeprecated: Use image ❌ ❌ previousLastName stringDeprecated: Use maidenName ❌ ❌
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 }) Name Type Description id stringImmutable id representing the group name stringThe editable name of a group
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 }) Name Type Description id stringImmutable id representing the group name stringThe editable name of a group
Name Type Description day numberDay. month numberMonth - adjusted for JS Date which starts at 0. year numberYear. format CalendarFormatTypeFormat for input date. id stringUnique ID. label stringLocalized display name.
Name Type Description name stringName of related contact. id stringUnique ID. label stringLocalized display name.
Name Type Description email stringemail address. isPrimary booleanPrimary email address. id stringUnique ID. label stringLocalized display name.
Name Type Description number stringPhone number. isPrimary booleanPrimary phone number. digits stringPhone number without format, ex: 8674305. countryCode stringCountry code, ex: +1. id stringUnique ID. label stringLocalized display name.
Name Type Description street stringStreet name. city stringCity name. country stringCountry name. region stringRegion or state name. neighborhood stringNeighborhood name. postalCode stringLocal post code. poBox stringP.O. Box. isoCountryCode stringStandard code .id stringUnique ID. label stringLocalized display name.
Name Type Description service stringName of social app. username stringUsername in social app. localizedProfile stringLocalized name. url stringWeb URL. userId stringUID for social app. id stringUnique ID. label stringLocalized display name.
Name Type Description service stringName of social app. username stringUsername in IM app. localizedService stringLocalized name of app. id stringUnique ID. label stringLocalized display name.
Name Type Description url stringWeb URL id stringUnique ID. label stringLocalized display name.
Information regarding thumbnail images.
Name Type iOS Android uri string✅ ✅ width number✅ ❌ height number✅ ❌ base64 string✅ ❌
Android: You can get dimensions using ReactNative.Image.getSize. Avoid using Base 64 in React Native
Denotes the functionality of a native contact form.
Name Type Description displayedPropertyKeys FieldType[]The properties that will be displayed. iOS: Does nothing in editing mode. message stringController title. alternateName stringUsed if contact doesn't have a name defined. cancelButtonTitle stringThe name of the left bar button. groupId stringThe parent group for a new contact. allowsEditing booleanAllows for contact mutation. allowsActions booleanActions like share, add, create. shouldShowLinkedContacts booleanShows similar contacts. isNew booleanPresent the new contact controller - if false the unknown controller will be shown. preventAnimation booleanPrevents the controller from animating in.
Used to query contacts from the user's device.
Name Type Description iOS Android fields FieldType[]If available the fields defined will be returned. If nil then all fields will be returned. ✅ ✅ pageSize numberThe max number of contacts to return. If nil or 0 then all contacts will be returned. ✅ ✅ pageOffset numberThe number of contacts to skip before gathering contacts. ✅ ✅ id stringGet contacts with a matching ID . ✅ ✅ sort SortTypeSort method used when gathering contacts. ❌ ✅ name stringQuery contacts matching this name. ✅ ❌ groupId stringGet all contacts that belong to the group matching this ID. ✅ ❌ containerId stringGet all contacts that belong to the container matching this ID. ✅ ❌ rawContacts booleanPrevent unification of contacts when gathering. Default: false. ✅ ❌
Used to query native contact groups.
Name Type Description groupName stringQuery all groups matching a name. groupId stringQuery the group with a matching ID. containerId stringQuery all groups that belong to a certain container.
Used to query native contact containers.
Name Type Description contactId stringQuery all the containers that parent a contact. groupId stringQuery all the containers that parent a group. containerId stringQuery a container from it's ID.
The return value for queried contact operations like getContactsAsync.
Name Type Description data Contact[]An array of contacts that match a particular query. hasNextPage booleanThis will be true if there are more contacts to retrieve beyond what is returned. hasPreviousPage booleantrue if there are previous contacts that weren't retrieved due to pageOffset. totalnumberDeprecated: use data.length to get the number of contacts returned.
const contactField = Contact . Fields . FirstName ;
Name Value iOS Android 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'✅ ❌ Thumbnail Deprecated: use Image ❌ ❌ PreviousLastName Deprecated: use MaidenName ❌ ❌
const formType = Contacts . FormTypes . New ;
Name Value Description New 'new'Creating a contact Unknown 'unknown'Displaying a contact with actions Default 'default'Information regarding a contact
const contactType = Contacts . ContactTypes . Person ;
Name Value Description Person 'person'Contact is a human Company 'company'Contact is group or company
const sortType = Contacts . SortTypes . FirstName ;
Name Value Description iOS Android 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 ✅ ❌
const containerType = Contacts . ContainerTypes . CardDAV ;
Name Value Description 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.
Constant value iOS Android 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.
Constant value iOS Android PHONE_NUMBERS 'phoneNumbers'✅ ✅ EMAILS 'emails'✅ ✅ ADDRESSES 'addresses'✅ ✅ IMAGE 'image'✅ ✅ NOTE 'note'✅ ✅ NAME_PREFIX 'namePrefix'✅ ✅ NAME_SUFFIX 'nameSuffix'✅ ✅ PHONETIC_FIRST_NAME 'phoneticFirstName'✅ ✅ PHONETIC_MIDDLE_NAME 'phoneticMiddleName'✅ ✅ PHONETIC_LAST_NAME 'phoneticLastName'✅ ✅ IM_ADDRESSES 'instantMessageAddresses'✅ ✅ URLS 'urlAddresses'✅ ✅ DATES 'dates'✅ ✅ NON_GREGORIAN_BIRTHDAY 'nonGregorianBirthday'✅ ❌ SOCIAL_PROFILES 'socialProfiles'✅ ❌ RAW_IMAGE 'rawImage'✅ ❌ THUMBNAIL 'thumbnail'Deprecated Deprecated PREVIOUS_LAST_NAME 'previousLastName'Deprecated Deprecated
The thumbnail 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.