A library that provides access to the phone's system 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.
-
npx expo install expo-contacts
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
You can configure expo-contacts
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
{
"expo": {
"plugins": [
[
"expo-contacts",
{
"contactsPermission": "Allow $(PRODUCT_NAME) to access your contacts."
}
]
]
}
}
Name | Default | Description |
---|---|---|
contactsPermission | "Allow $(PRODUCT_NAME) to access your contacts" | Only for: iOS A string to set the |
Learn how to configure the native projects in the installation instructions in the expo-contacts
repository.
import { 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>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
alignItems: 'center',
justifyContent: 'center',
},
});
import * as Contacts from 'expo-contacts';
Contacts.addContactAsync(contact, containerId)
Parameter | Type | Description |
---|---|---|
contact | Contact | A contact with the changes you wish to persist. The |
containerId (optional) | string | Only for: iOS The container that will parent the contact. |
Creates a new contact and adds it to the system.
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.
Promise<string>
A promise that fulfills with ID 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.addExistingContactToGroupAsync(contactId, groupId)
Parameter | Type | Description |
---|---|---|
contactId | string | ID of the contact you want to edit. |
groupId | string | 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.
Promise<any>
Example
await Contacts.addExistingContactToGroupAsync(
'665FDBCFAE55-D614-4A15-8DC6-161A368D',
'161A368D-D614-4A15-8DC6-665FDBCFAE55'
);
Contacts.addExistingGroupToContainerAsync(groupId, containerId)
Parameter | Type | Description |
---|---|---|
groupId | string | The group you want to target. |
containerId | string | The container you want to add membership to. |
Add a group to a container.
Promise<any>
Example
await Contacts.addExistingGroupToContainerAsync(
'161A368D-D614-4A15-8DC6-665FDBCFAE55',
'665FDBCFAE55-D614-4A15-8DC6-161A368D'
);
Contacts.createGroupAsync(name, containerId)
Parameter | Type | Description |
---|---|---|
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.
Promise<string>
A promise that fulfills with ID of the new group.
Example
const groupId = await Contacts.createGroupAsync('Sailor Moon');
Contacts.getContactByIdAsync(id, fields)
Parameter | Type | Description |
---|---|---|
id | string | 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
.
A promise that fulfills with Contact
object with ID matching the input ID, or undefined
if there is no match.
Example
const contact = await Contacts.getContactByIdAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
if (contact) {
console.log(contact);
}
Contacts.getContactsAsync(contactQuery)
Parameter | Type | Description |
---|---|---|
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.
A promise that fulfills with ContactResponse
object 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.getContainersAsync(containerQuery)
Parameter | Type | Description |
---|---|---|
containerQuery | ContainerQuery | Information used to gather containers. |
Query a list of system containers.
A promise that fulfills with array of containers that fit the query.
Example
const allContainers = await Contacts.getContainersAsync({
contactId: '665FDBCFAE55-D614-4A15-8DC6-161A368D',
});
Contacts.getDefaultContainerIdAsync()
Get the default container's ID.
Promise<string>
A promise that fulfills with default container ID.
Example
const containerId = await Contacts.getDefaultContainerIdAsync();
Contacts.getGroupsAsync(groupQuery)
Parameter | Type | Description |
---|---|---|
groupQuery | GroupQuery | Information regarding which groups you want to get. |
Query and return a list of system groups.
A promise that fulfills with array of groups that fit the query.
Example
const groups = await Contacts.getGroupsAsync({ groupName: 'sailor moon' });
const allGroups = await Contacts.getGroupsAsync({});
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.
Promise<boolean>
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.presentContactPickerAsync()
Presents a native contact picker to select a single contact from the system. On Android, the READ_CONTACTS
permission is required. You can
obtain this permission by calling the Contacts.requestPermissionsAsync()
method. On iOS, no permissions are
required to use this method.
A promise that fulfills with a single Contact
object if a contact is selected or null
if no contact is selected (when selection is canceled).
Contacts.presentFormAsync(contactId, contact, formOptions)
Parameter | Type | Description |
---|---|---|
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.
Promise<any>
Example
await Contacts.presentFormAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Contacts.removeContactAsync(contactId)
Parameter | Type | Description |
---|---|---|
contactId | string | ID of the contact you want to delete. |
Delete a contact from the system.
Promise<any>
Example
await Contacts.removeContactAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Contacts.removeContactFromGroupAsync(contactId, groupId)
Parameter | Type | Description |
---|---|---|
contactId | string | ID of the contact you want to remove. |
groupId | string | 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.
Promise<any>
Example
await Contacts.removeContactFromGroupAsync(
'665FDBCFAE55-D614-4A15-8DC6-161A368D',
'161A368D-D614-4A15-8DC6-665FDBCFAE55'
);
Contacts.removeGroupAsync(groupId)
Parameter | Type | Description |
---|---|---|
groupId | string | ID of the group you want to remove. |
Delete a group from the device.
Promise<any>
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)
Parameter | Type |
---|---|
contactId | string |
message | string |
shareOptions (optional) | ShareOptions |
Promise<any>
Contacts.updateContactAsync(contact)
Parameter | Type | Description |
---|---|---|
contact | Contact | A contact object including the wanted changes. |
Mutate the information of an existing contact. Due to an iOS bug, nonGregorianBirthday
field cannot be modified.
On Android, you can usepresentFormAsync
to make edits to contacts.
Promise<string>
A promise that fulfills with ID of the updated system contact if mutation was successful.
Example
const contact = {
id: '161A368D-D614-4A15-8DC6-665FDBCFAE55',
[Contacts.Fields.FirstName]: 'Drake',
[Contacts.Fields.Company]: 'Young Money',
};
await Contacts.updateContactAsync(contact);
Contacts.updateGroupNameAsync(groupName, groupId)
Parameter | Type | Description |
---|---|---|
groupName | string | New name for an existing group. |
groupId | string | ID of the group you want to edit. |
Change the name of an existing group.
Promise<any>
Example
await Contacts.updateGroupName('Expo Friends', '161A368D-D614-4A15-8DC6-665FDBCFAE55');
Contacts.writeContactToFileAsync(contactQuery)
Parameter | Type | Description |
---|---|---|
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.
Promise<string | undefined>
A promise that fulfills with shareable local URI, or undefined
if there was no match.
Example
const localUri = await Contacts.writeContactToFileAsync({
id: '161A368D-D614-4A15-8DC6-665FDBCFAE55',
});
Share.share({ url: localUri, message: 'Call me!' });
PermissionResponse
An object obtained by permissions get and request functions.
PermissionResponse Properties
Name | Type | Description |
---|---|---|
canAskAgain | boolean | Indicates 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. |
expires | PermissionExpiration | Determines time when the permission expires. |
granted | boolean | A convenience boolean that indicates if the permission is granted. |
status | PermissionStatus | Determines the status of the permission. |
Address
Name | Type | Description |
---|---|---|
city (optional) | string | City name. |
country (optional) | string | Country name |
id (optional) | string | Unique ID. This value will be generated by the OS. |
isoCountryCode (optional) | string | |
label | string | Localized display name. |
neighborhood (optional) | string | Neighborhood name. |
poBox (optional) | string | P.O. Box. |
postalCode (optional) | string | Local post code. |
region (optional) | string | Region or state name. |
street (optional) | string | Street name. |
Contact
A set of fields that define information about a single contact entity.
Name | Type | Description |
---|---|---|
addresses (optional) | Address[] | Locations. |
birthday (optional) | Date | Birthday information in Gregorian format. |
company (optional) | string | Organization the entity belongs to. |
contactType | ContactType | Denoting a person or company. |
dates (optional) | Date[] | A labeled list of other relevant user dates in Gregorian format. |
department (optional) | string | Job department. |
emails (optional) | Email[] | Email addresses. |
firstName (optional) | string | Given name. |
id (optional) | string | Immutable identifier used for querying and indexing. This value will be generated by the OS when the contact is created. |
image (optional) | Image | Thumbnail image. On iOS it size is set to 320×320px, on Android it may vary. |
imageAvailable (optional) | boolean | Used for efficient retrieval of images. |
instantMessageAddresses (optional) | InstantMessageAddress[] | Instant messaging connections. |
jobTitle (optional) | string | Job description. |
lastName (optional) | string | Last name. |
maidenName (optional) | string | Maiden name. |
middleName (optional) | string | Middle name |
name | string | Full name with proper format. |
namePrefix (optional) | string | Dr., Mr., Mrs., and so on. |
nameSuffix (optional) | string | Jr., Sr., an so on. |
nickname (optional) | string | An alias to the proper name. |
nonGregorianBirthday (optional) | Date | Only for: iOS Birthday that doesn't conform to the Gregorian calendar format, interpreted based on the calendar |
note (optional) | string | Additional information.
|
phoneNumbers (optional) | PhoneNumber[] | Phone numbers. |
phoneticFirstName (optional) | string | Pronunciation of the first name. |
phoneticLastName (optional) | string | Pronunciation of the last name. |
phoneticMiddleName (optional) | string | Pronunciation of the middle name. |
rawImage (optional) | Image | Raw image without cropping, usually large. |
relationships (optional) | Relationship[] | Names of other relevant user connections. |
socialProfiles (optional) | SocialProfile[] | Only for: iOS Social networks. |
urlAddresses (optional) | UrlAddress[] | Associated web URLs. |
ContactQuery
Used to query contacts from the user's device.
Name | Type | Description |
---|---|---|
containerId (optional) | string | Only for: iOS 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) | string | Only for: iOS 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) | string | Get all contacts whose name contains the provided string (not case-sensitive). |
pageOffset (optional) | number | The number of contacts to skip before gathering contacts. |
pageSize (optional) | number | The max number of contacts to return. If skipped or set to |
rawContacts (optional) | boolean | Only for: iOS Prevent unification of contacts when gathering. Default: false |
sort (optional) | ContactSort | Sort method used when gathering contacts. |
ContactResponse
The return value for queried contact operations like getContactsAsync
.
Name | Type | Description |
---|---|---|
data | Contact[] | An array of contacts that match a particular query. |
hasNextPage | boolean | This will be |
hasPreviousPage | boolean | This will be |
ContactSort
String union of SortTypes
values.
Container
Name | Type | Description |
---|---|---|
id | string | - |
name | string | - |
type | ContainerType | - |
ContainerQuery
Used to query native contact containers.
Name | Type | Description |
---|---|---|
contactId (optional) | string | Query 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) | string | Query all the containers that parent a group. |
Date
Name | Type | Description |
---|---|---|
day (optional) | number | Day. |
format (optional) | CalendarFormatType | Format for the input date. |
id (optional) | string | Unique ID. This value will be generated by the OS. |
label | string | Localized display name. |
month (optional) | number | Month - adjusted for JavaScript |
year (optional) | number | Year. |
Email
Name | Type | Description |
---|---|---|
email (optional) | string | Email address. |
id (optional) | string | Unique ID. This value will be generated by the OS. |
isPrimary (optional) | boolean | Flag signifying if it is a primary email address. |
label | string | Localized display name. |
FormOptions
Denotes the functionality of a native contact form.
Name | Type | Description |
---|---|---|
allowsActions (optional) | boolean | Actions like share, add, create. |
allowsEditing (optional) | boolean | Allows for contact mutation. |
alternateName (optional) | string | Used if contact doesn't have a name defined. |
cancelButtonTitle (optional) | string | The 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) | string | The parent group for a new contact. |
isNew (optional) | boolean | Present the new contact controller. If set to |
message (optional) | string | Controller title. |
preventAnimation (optional) | boolean | Prevents the controller from animating in. |
shouldShowLinkedContacts (optional) | boolean | Show or hide the similar contacts. |
Group
A parent to contacts. A contact can belong to multiple groups. Here are some query operations you can perform:
getContactsAsync({ groupId })
getGroupsAsync({ containerId })
getContainersAsync({ groupName })
Name | Type | Description |
---|---|---|
id (optional) | string | The editable name of a group. |
name (optional) | string | Immutable id representing the group. |
GroupQuery
Used to query native contact groups.
Name | Type | Description |
---|---|---|
containerId (optional) | string | Query all groups that belong to a certain container. |
groupId (optional) | string | Query the group with a matching ID. |
groupName (optional) | string | Query all groups matching a name. |
Image
Information regarding thumbnail images.
On Android you can get dimensions using
Image.getSize
method.
Name | Type | Description |
---|---|---|
base64 (optional) | string | Image as Base64 string. |
height (optional) | number | Only for: iOS Image height |
uri (optional) | string | A local image URI.
|
width (optional) | number | Only for: iOS Image width. |
InstantMessageAddress
Name | Type | Description |
---|---|---|
id (optional) | string | Unique ID. This value will be generated by the OS. |
label | string | Localized display name. |
localizedService (optional) | string | Localized name of app. |
service (optional) | string | Name of instant messaging app. |
username (optional) | string | Username in IM app. |
PermissionExpiration
Literal Type: multiple types
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never'
| number
PhoneNumber
Name | Type | Description |
---|---|---|
countryCode (optional) | string | Country code. Example
|
digits (optional) | string | Phone number without format. Example
|
id (optional) | string | Unique ID. This value will be generated by the OS. |
isPrimary (optional) | boolean | Flag signifying if it is a primary phone number. |
label | string | Localized display name. |
number (optional) | string | Phone number. |
Relationship
Name | Type | Description |
---|---|---|
id (optional) | string | Unique ID. This value will be generated by the OS. |
label | string | Localized display name. |
name (optional) | string | Name of related contact. |
SocialProfile
Name | Type | Description |
---|---|---|
id (optional) | string | Unique ID. This value will be generated by the OS. |
label | string | Localized display name. |
localizedProfile (optional) | string | Localized profile name. |
service (optional) | string | Name of social app. |
url (optional) | string | Web URL. |
userId (optional) | string | Username ID in social app. |
username (optional) | string | Username in social app. |
UrlAddress
Name | Type | Description |
---|---|---|
id (optional) | string | Unique ID. This value will be generated by the OS. |
label | string | Localized display name. |
url (optional) | string | Web URL. |
CalendarFormats
This format denotes the common calendar format used to specify how a date is calculated in nonGregorianBirthday
fields.
CalendarFormats Values
Gregorian
CalendarFormats.Gregorian = "gregorian"
ContactTypes
ContactTypes Values
Addresses
Fields.Addresses = "addresses"
Birthday
Fields.Birthday = "birthday"
Company
Fields.Company = "company"
ContactType
Fields.ContactType = "contactType"
Dates
Fields.Dates = "dates"
Department
Fields.Department = "department"
Emails
Fields.Emails = "emails"
ExtraNames
Fields.ExtraNames = "extraNames"
FirstName
Fields.FirstName = "firstName"
ID
Fields.ID = "id"
Image
Fields.Image = "image"
ImageAvailable
Fields.ImageAvailable = "imageAvailable"
InstantMessageAddresses
Fields.InstantMessageAddresses = "instantMessageAddresses"
JobTitle
Fields.JobTitle = "jobTitle"
LastName
Fields.LastName = "lastName"
MaidenName
Fields.MaidenName = "maidenName"
MiddleName
Fields.MiddleName = "middleName"
Name
Fields.Name = "name"
NamePrefix
Fields.NamePrefix = "namePrefix"
NameSuffix
Fields.NameSuffix = "nameSuffix"
Nickname
Fields.Nickname = "nickname"
Note
Fields.Note = "note"
PhoneNumbers
Fields.PhoneNumbers = "phoneNumbers"
PhoneticFirstName
Fields.PhoneticFirstName = "phoneticFirstName"
PhoneticLastName
Fields.PhoneticLastName = "phoneticLastName"
PhoneticMiddleName
Fields.PhoneticMiddleName = "phoneticMiddleName"
RawImage
Fields.RawImage = "rawImage"
Relationships
Fields.Relationships = "relationships"
UrlAddresses
Fields.UrlAddresses = "urlAddresses"
PermissionStatus
PermissionStatus Values
UNDETERMINED
PermissionStatus.UNDETERMINED = "undetermined"
User hasn't granted or denied the permission yet.
SortTypes
SortTypes Values
UserDefault
SortTypes.UserDefault = "userDefault"
The user default method of sorting.
You must add the following permissions to your app.json inside the expo.android.permissions
array.
Android Permission | Description |
---|---|
Allows an application to read the user's contacts data. | |
Allows an application to write the user's contacts data. |
The following usage description keys are used by this library:
Info.plist Key | Description |
---|---|
A message that tells the user why the app is requesting access to the user’s contacts. |