This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Contacts (next)
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 add, edit, or remove contacts.
On iOS, contacts have a multi-layered grouping system that you can also access through this API.
Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Configuration in app config
You can configure expo-contacts using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
Example app.json with config plugin
Configurable properties
Are you using this library in an existing React Native app?
If you're not using Continuous Native Generation (CNG) (you're using native android and ios projects manually), then you need to configure following permissions in your native projects:
-
For Android, add
android.permission.READ_CONTACTSandandroid.permission.WRITE_CONTACTSpermissions to your project's android/app/src/main/AndroidManifest.xml:<uses-permission android:name="android.permission.READ_CONTACTS" /> <uses-permission android:name="android.permission.WRITE_CONTACTS" /> -
For iOS, add the
NSContactsUsageDescriptionkey to your project's ios/[app]/Info.plist:<key>NSContactsUsageDescription</key> <string>Allow $(PRODUCT_NAME) to access your contacts</string>
Usage
API
import { Contact } from 'expo-contacts/next';
Component
Type: React.PureComponent<ContactAccessButtonProps>
Creates a contact access button to quickly add contacts under limited-access authorization.
For more details, you can read the Apple docs about the underlying ContactAccessButton SwiftUI view.
ColorValueA color of the button's background. Provided color should not be transparent, otherwise it may not satisfy platform requirements for button legibility.
stringWhen the query produces a single result, the contact access button shows the caption under the matching contact name. It can be nothing (default), email address or phone number.
Acceptable values are: 'default' | 'email' | 'phone'
string[]An array of email addresses. The search omits contacts matching query that also match any email address in this array.
string[]An array of phone numbers. The search omits contacts matching query that also match any phone number in this set.
stringA string to match against contacts not yet exposed to the app. You typically get this value from a search UI that your app presents, like a text field.
ColorValueA color of the button's title. Slightly dimmed version of this color is used for the caption text. Make sure there is a good contrast between the text and the background, otherwise platform requirements for button legibility may not be satisfied.
ColorValueA tint color of the button and the modal that is presented when there is more than one match.
Static methods
Returns a boolean whether the ContactAccessButton is available on the platform.
This is true only on iOS 18.0 and newer.
booleanClasses
Type: Class extends Contact
Represents a contact in the device's address book.
-
Data Retrieval: Contact details can be accessed using the
getDetailsmethod or via specific getters such asgetEmailsandgetPhones. -
Modification: To update the contact, use bulk operations via
patchorupdate, or specific modifiers likeaddEmailanddeletePhone.
Example
const contact = await Contact.create({ givenName: 'John', familyName: 'Doe', phones: [{ label: 'mobile', number: '+12123456789' }] });
Contact Properties
Contact Methods
Adds a new postal address to the contact.
Promise<string>a promise resolving to the ID of the newly added address.
Example
await contact.addAddress({ label: 'home', street: '123 Main St', city: 'London' });
Adds a new date (e.g., anniversary, birthday) to the contact.
Promise<string>a promise resolving to the ID of the newly added date.
Example
await contact.addDate({ label: 'anniversary', date: { day: 1, month: 1 } });
Adds a new email address to the contact.
Promise<string>a promise resolving to the ID of the newly added email.
Example
const newEmailId = await contact.addEmail({ label: 'work', address: 'work@example.com' });
Adds a new extra name (e.g., nickname, maiden name) to the contact.
Promise<string>a promise resolving to the ID of the newly added extra name.
Example
await contact.addExtraName({ label: 'nickname', name: 'Johnny' });
Adds a new instant messaging address to the contact.
Promise<string>a promise resolving to the ID of the newly added IM address.
Example
await contact.addImAddress({ service: 'Skype', username: 'user123' });
Adds a new phone number to the contact.
Promise<string>a promise resolving to the ID of the newly added phone number.
Example
const newPhoneId = await contact.addPhone({ label: 'home', number: '+12123456789' });
Adds a new relationship (e.g., brother, sister) to the contact.
Promise<string>a promise resolving to the ID of the newly added relation.
Example
await contact.addRelation({ label: 'brother', name: 'Mark' });
Adds a new social profile to the contact.
Promise<string>a promise resolving to the ID of the newly added social profile.
Example
await contact.addSocialProfile({ service: 'twitter', username: 'myhandle' });
Adds a new URL/website to the contact.
Promise<string>a promise resolving to the ID of the newly added URL.
Example
await contact.addUrlAddress({ label: 'blog', url: '[https://myblog.com](https://myblog.com)' });
A static method that creates a new contact.
a promise resolving to the newly created Contact instance.
Example
const newContactDetails: CreateContactRecord = { givenName: 'Jane', familyName: 'Doe', phones: [{ label: 'mobile', number: '+12123456789' }] }; const newContact = await Contact.create(newContactDetails);
Deletes the contact from the device's address book.
Promise<void>a promise that resolves when the contact is successfully deleted.
Example
await contact.delete();
Deletes a specific postal address from the contact.
Promise<void>Example
await contact.deleteAddress(existingAddress);
Deletes a specific date from the contact.
Promise<void>Example
await contact.deleteDate(existingDate);
Deletes a specific email address from the contact.
Promise<void>Example
await contact.deleteEmail(existingEmail);
Deletes a specific extra name from the contact.
Promise<void>Example
await contact.deleteExtraName(existingExtraName);
Deletes a specific instant messaging address from the contact.
Promise<void>Example
await contact.deleteImAddress(existingImAddress);
Deletes a specific phone number from the contact.
Promise<void>Example
await contact.deletePhone(existingPhone);
Deletes a specific relation from the contact.
Promise<void>Example
await contact.deleteRelation(existingRelation);
Deletes a specific social profile from the contact.
Promise<void>Example
await contact.deleteSocialProfile(existingSocialProfile);
Deletes a specific URL address from the contact.
Promise<void>Example
await contact.deleteUrlAddress(existingUrlAddress);
Opens the native contact editor for this contact.
Promise<boolean>a promise resolving to true if changes were saved, false otherwise.
Retrieves all postal addresses associated with the contact.
Promise<ExistingAddress[]>a promise resolving to an array of existing addresses.
Example
const addresses = await contact.getAddresses();
A static method that retrieves specific fields for all contacts or a subset of contacts.
This is an optimized method for fetching bulk data; it avoids creating full Contact instances.
Promise<PartialContactDetails[]>a promise resolving to an array of partial contact details objects.
Example
const allDetails = await Contact.getAllDetails(['givenName', 'phones'], { limit: 10, name: 'John' });
Retrieves the birthday of the contact.
Promise<ContactDate | null>a promise resolving to the ContactDate object or null if not set.
Example
const birthday = await contact.getBirthday();
Retrieves the company name.
Promise<string | null>a promise resolving to the company name string or null if not set.
Example
const company = await contact.getCompany(); // 'Example Inc.'
A static method that retrieves the total count of contacts in the address book.
Promise<number>a promise resolving to the count of contacts.
Example
const contactCount = await Contact.getCount(); // 42
Retrieves all dates associated with the contact.
Promise<ExistingDate[]>a promise resolving to an array of existing dates.
Example
const dates = await contact.getDates();
Retrieves the department name.
Promise<string | null>a promise resolving to the department name string or null if not set.
Example
const department = await contact.getDepartment(); // 'Sales'
Retrieves specific details for the contact. This method is useful when you want to retrieve only certain fields of the contact.
Promise<PartialContactDetails<T>>a promise resolving to an object containing the requested details.
Example
const details = await contact.getDetails([ContactField.GivenName, ContactField.Phones]); details.givenName; // 'John' details.familyName; // undefined details.phones; // [{ label: 'mobile', number: '+12123456789' }]
Retrieves all email addresses associated with the contact.
Promise<ExistingEmail[]>a promise resolving to an array of existing emails.
Example
const emails = await contact.getEmails();
Retrieves all extra names associated with the contact.
Promise<ExistingExtraName[]>a promise resolving to an array of existing extra names.
Example
const extraNames = await contact.getExtraNames();
Retrieves the family name.
Promise<string | null>a promise resolving to the family name string or null if not set.
Example
const familyName = await contact.getFamilyName(); // 'Doe'
Retrieves the full name of the contact. The shape of the full name depends on the platform. This field is read-only and cannot be set directly. To modify name components, use the respective setters.
Promise<string>a promise resolving to the full name string.
Example
const fullName = await contact.getFullName(); // 'John Doe'
Retrieves the given name.
Promise<string | null>a promise resolving to the given name string or null if not set.
Example
const givenName = await contact.getGivenName(); // 'John'
Retrieves all instant messaging addresses associated with the contact.
Promise<ExistingImAddress[]>a promise resolving to an array of existing IM addresses.
Example
const ims = await contact.getImAddresses();
Retrieves the URI of the contact's full-resolution image.
Promise<string | null>a promise resolving to the image URI string or null if not set.
Example
const imageUri = await contact.getImage();
Retrieves whether the contact is marked as a favorite.
Promise<boolean>a promise resolving boolean indicating whether the contact is a favorite.
Example
const isFavourite = await contact.getIsFavourite() // true
Retrieves the job title.
Promise<string | null>a promise resolving to the job title string or null if not set.
Example
const jobTitle = await contact.getJobTitle(); // 'Software Engineer'
Retrieves the maiden name.
Promise<string | null>a promise resolving to the maiden name string or null if not set.
Example
const maidenName = await contact.getMaidenName();
Retrieves the middle name.
Promise<string | null>a promise resolving to the middle name string or null if not set.
Example
const middleName = await contact.getMiddleName(); // 'Marie'
Retrieves the nickname.
Promise<string | null>a promise resolving to the nickname string or null if not set.
Example
const nickname = await contact.getNickname(); // 'Johnny'
Retrieves the non-Gregorian birthday of the contact.
Promise<NonGregorianBirthday | null>a promise resolving to the NonGregorianBirthday object or null if not set.
Example
const nonGregorianBirthday = await contact.getNonGregorianBirthday();
Retrieves the note associated with the contact.
On iOS the
notefield 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 theios.accessesContactNotesfield in app config totrue, and create your development build.
Promise<string | null>a promise resolving to the note string or null if not set.
Example
const note = await contact.getNote(); // 'Met at the conference'
Retrieves all phone numbers associated with the contact.
Promise<ExistingPhone[]>a promise resolving to an array of existing phone numbers.
Example
const phones = await contact.getPhones();
Retrieves the phonetic representation of the company name.
Promise<string | null>a promise resolving to the phonetic company name string or null if not set.
Example
const phoneticCompanyName = await contact.getPhoneticCompanyName(); // 'Ekzampl Inc.'
Retrieves the phonetic representation of the family name.
Promise<string | null>a promise resolving to the phonetic family name string or null if not set.
Example
const phoneticFamilyName = await contact.getPhoneticFamilyName(); // 'Smyth'
Retrieves the phonetic representation of the given name.
Promise<string | null>a promise resolving to the phonetic given name string or null if not set.
Example
const phoneticGivenName = await contact.getPhoneticGivenName(); // 'Jon'
Retrieves the phonetic representation of the middle name.
Promise<string | null>a promise resolving to the phonetic middle name string or null if not set.
Example
const phoneticMiddleName = await contact.getPhoneticMiddleName(); // 'Maree'
Retrieves the name prefix.
Promise<string | null>a promise resolving to the prefix string or null if not set.
Example
const prefix = await contact.getPrefix(); // 'Dr.'
Retrieves all relations associated with the contact.
Promise<ExistingRelation[]>a promise resolving to an array of existing relations.
Example
const relations = await contact.getRelations();
Retrieves all social profiles associated with the contact.
Promise<ExistingSocialProfile[]>a promise resolving to an array of existing social profiles.
Example
const profiles = await contact.getSocialProfiles();
Retrieves the name suffix.
Promise<string | null>a promise resolving to the suffix string or null if not set.
Example
const suffix = await contact.getSuffix(); // 'Jr.'
Retrieves the URI of the contact's thumbnail image. This field is read-only and is derived from the full-resolution image.
Promise<string | null>a promise resolving to the thumbnail URI string or null if not set.
Example
const thumbnailUri = await contact.getThumbnail();
Retrieves all URL addresses associated with the contact.
Promise<ExistingUrlAddress[]>a promise resolving to an array of existing URL addresses.
Example
const urls = await contact.getUrlAddresses();
A static method that checks if there are any contacts in the address book.
Promise<boolean>a promise resolving to true if at least one contact exists.
Example
const hasContacts = await Contact.hasAny(); // true
Applies partial updates to the contact. Undefined fields are ignored.
Lists like emails or phones are entirely replaced if provided.
If you want to overwrite the entire contact, use the update method instead.
Promise<void>Example
const details = await contact.getDetails([ContactField.GivenName, ContactField.FamilyName, ContactField.Phones]); details.givenName = 'Jane'; // updates the given name details.familyName = null; // clears the family name details.phones = [ ...details.phones, // keeps existing phone numbers { label: 'newPhone', number: '+12123456789' } // adds a new phone number ]; await contact.patch(details);
A static method that presents a system dialog to request access to contacts if not already granted.
Promise<boolean>a promise resolving to true if access is granted, false otherwise.
Example
const accessGranted = await Contact.presentAccessPicker();
A static method that opens the native "Create Contact" form.
Promise<boolean>a promise resolving to true if a contact was created, false otherwise.
Example
const wasCreated = await Contact.createWithForm({ givenName: 'Jane', familyName: 'Doe' });
A static method that requests permissions to access contacts.
Promise<{
granted: boolean
}>a promise resolving to an object indicating if permission was granted.
Example
const { granted } = await Contact.requestPermissionsAsync();
Sets the birthday of the contact. To set a birthday on Android, use the addDate method with the label 'birthday'.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setBirthday({ year: '1990', month: '1', day: '1' });
Sets the company name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setCompany('Example Inc.');
Sets the department name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setDepartment('Sales');
Sets the family name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setFamilyName('Smith');
Sets the given name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setGivenName('Jane');
Sets the contact's image.
Note: If you have a remote URI, you have to download the image to a local file first.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setImage('file:///path/to/new/image.jpg');
Sets the favorite status of the contact.
Promise<boolean>a promise resolving to boolean indicating whether the operation was successful.
Example
await contact.setIsFavourite(true);
Sets the job title.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setJobTitle('Product Manager');
Sets the maiden name. To set a maiden name on Android, use the addExtraName method with the label 'maidenname'.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setMaidenName('Johnson');
Sets the middle name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setMiddleName('Lee');
Sets the nickname. To set a nickname on Android, use the addExtraName method with the label 'nickname'.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setNickname('Jojo');
Sets the non-Gregorian birthday of the contact.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setNonGregorianBirthday({ year: '2563', month: '5', day: '15', calendar: NonGregorianCalendar.buddhist });
Sets the note for the contact.
On iOS the
notefield 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 theios.accessesContactNotesfield in app config totrue, and create your development build.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setNote('Remember to call back');
Sets the phonetic company name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setPhoneticCompanyName('Ekzampl Inc.');
Sets the phonetic family name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setPhoneticFamilyName('Smyth');
Sets the phonetic given name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setPhoneticGivenName('Jon');
Sets the phonetic middle name.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setPhoneticMiddleName('Maree');
Sets the name prefix.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setPrefix('Ms.');
Sets the name suffix.
Promise<boolean>a promise resolving to a boolean indicating whether the operation was successful.
Example
await contact.setSuffix('Jr.');
Overwrites the contact data with the provided record.
If you want to apply partial updates, use the patch method instead.
Promise<void>Example
const newDetails: CreateContactRecord = { givenName: 'Jane', familyName: 'Doe', phones: [{ label: 'mobile', number: '+12123456789' }] }; await contact.update(newDetails);
Updates an existing postal address.
Promise<void>Example
const addresses = await contact.getAddresses(); const addressToUpdate = addresses[0]; addressToUpdate.city = 'New York'; await contact.updateAddress(addressToUpdate);
Updates an existing date.
Promise<void>Example
const dates = await contact.getDates(); const dateToUpdate = dates[0]; dateToUpdate.label = 'birthday'; await contact.updateDate(dateToUpdate);
Updates an existing email address.
Promise<void>Example
const emails = await contact.getEmails(); const emailToUpdate = emails[0]; emailToUpdate.address = 'new@example.com'; await contact.updateEmail(emailToUpdate);
Updates an existing extra name.
Promise<void>Example
const names = await contact.getExtraNames(); const nameToUpdate = names[0]; nameToUpdate.name = 'Jojo'; await contact.updateExtraName(nameToUpdate);
Updates an existing instant messaging address.
Promise<void>Example
const ims = await contact.getImAddresses(); const imToUpdate = ims[0]; imToUpdate.username = 'user456'; await contact.updateImAddress(imToUpdate);
Updates an existing phone number.
Promise<void>Example
const phones = await contact.getPhones(); const phoneToUpdate = phones[0]; phoneToUpdate.number = '+19876543210'; await contact.updatePhone(phoneToUpdate);
Updates an existing relation.
Promise<void>Example
const relations = await contact.getRelations(); const relationToUpdate = relations[0]; relationToUpdate.name = 'Marcus'; await contact.updateRelation(relationToUpdate);
Updates an existing social profile.
Promise<void>Example
const profiles = await contact.getSocialProfiles(); const profileToUpdate = profiles[0]; profileToUpdate.username = 'newhandle'; await contact.updateSocialProfile(profileToUpdate);
Updates an existing URL address.
Promise<void>Example
const urls = await contact.getUrlAddresses(); const urlToUpdate = urls[0]; urlToUpdate.url = '[https://updated-blog.com](https://updated-blog.com)'; await contact.updateUrlAddress(urlToUpdate);
Type: Class extends Container<this>
Represents a container for contacts. A container (often called an "Account" in UI terms) is a source of contacts, such as a local device storage, iCloud, Google, or Exchange account.
Container Properties
Container Methods
A static method that retrieves all contact containers available on the device.
Promise<Container[]>a promise resolving to an array of Container instances.
Example
const containers = await Container.getAll();
A static method that retrieves the default container. The default container is where new contacts are added if no specific container is specified.
a promise resolving to the default Container instance or null if not found.
Example
const defaultContainer = await Container.getDefault();
Retrieves the name of the container.
Promise<string | null>a promise resolving to the container name string (for example, "iCloud", "Gmail") or null if not available.
Example
const name = await container.getName(); // 'iCloud'
Retrieves the type of the container.
Promise<ContainerType | null>a promise resolving to the [ContainerType](contacts/#containertype (for example, 'cardDAV', 'exchange') or null.
Example
const type = await container.getType(); // 'cardDAV'
Type: Class extends Group<this>
Represents a group of contacts (for example, "Family", "Coworkers"). Groups belong to a specific Container and can contain multiple Contacts.
Group Properties
Group Methods
Adds a contact to the group.
Promise<void>a promise that resolves when the contact is successfully added.
Example
await group.addContact(contact);
Deletes the group from the device.
Note: This usually deletes the group definition but leaves the contacts themselves intact in the address book.
Promise<void>a promise that resolves when the group is successfully deleted.
Example
await group.delete();
Retrieves the name of the group.
Promise<string | null>a promise resolving to the group name string or null if not set.
Example
const name = await group.getName(); // 'Family'
Removes a contact from the group.
Promise<void>a promise that resolves when the contact is successfully removed.
Example
await group.removeContact(contact);
Renames the group.
Promise<void>a promise that resolves when the group is successfully renamed.
Example
await group.setName('Close Friends');
Types
Represents the full details of an existing contact.
This object is returned by Contact.getContact or similar methods.
Represents a set of fields to be patched on a contact. Undefined fields will be ignored. To remove a value, set the field to null.
Represents an existing email associated with a contact.
This object can be obtained from Contact.getEmails or 'contact.getDetails' methods.
Type: NewEmail extended by:
Represents an existing extra name associated with a contact.
This object can be obtained from Contact.getExtraNames or 'contact.getDetails' methods.
Type: NewExtraName extended by:
Represents an existing instant messaging address associated with a contact.
Type: NewImAddress extended by:
Enums
Enum representing the various fields of a contact. These fields can be used to specify which details to retrieve from a contact.
Enum representing the sort order options for querying contacts.
Enum representing non-Gregorian calendar types.
Permissions
Android
This library automatically adds READ_CONTACTS and WRITE_CONTACTS permissions to your app:
iOS
The following usage description keys are used by this library: