--- modificationDate: January 27, 2026 title: Contacts (next) description: A library that provides access to the phone's system contacts. sourceCodeUrl: 'https://github.com/expo/expo/tree/main/packages/expo-contacts' packageName: 'expo-contacts' iconUrl: '/static/images/packages/expo-contacts.png' platforms: ['android', 'ios', 'expo-go'] isNew: true --- ## Submitting Feedback If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved: curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/versions/unversioned/sdk/contacts-next/","feedback":"🤖 Agent feedback: "}' Only submit when you have something specific and actionable to report. > This is documentation for the next SDK version. For up-to-date documentation, see the [latest version](/versions/latest/sdk/contacts-next) (SDK 55). # Expo Contacts (next) A library that provides access to the phone's system contacts. Android, iOS, Included in Expo Go > For the complete documentation index, see [llms.txt](/llms.txt). Use this file to discover all available pages. `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 ```sh npx expo install expo-contacts ``` If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project. ## Configuration in app config You can configure `expo-contacts` using its built-in [config plugin](/config-plugins/introduction) if you use config plugins in your project ([Continuous Native Generation (CNG)](/workflow/continuous-native-generation)). 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 ```json { "expo": { "plugins": [ [ "expo-contacts", { "contactsPermission": "Allow $(PRODUCT_NAME) to access your contacts." } ] ] } } ``` ### Configurable properties | Name | Default | Description | | --- | --- | --- | | `contactsPermission` | `"Allow $(PRODUCT_NAME) to access your contacts"` | Only for: iOS. A string to set the [`NSContactsUsageDescription`](#ios) permission message. | Are you using this library in an existing React Native app? If you're not using Continuous Native Generation ([CNG](/workflow/continuous-native-generation)) (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_CONTACTS` and `android.permission.WRITE_CONTACTS` permissions to your project's **android/app/src/main/AndroidManifest.xml**: ```xml ``` - For iOS, add the `NSContactsUsageDescription` key to your project's **ios/[app]/Info.plist**: ```xml NSContactsUsageDescription Allow $(PRODUCT_NAME) to access your contacts ``` ## Usage Contacts Manipulations ```tsx const contact = await Contact.create({ givenName: 'John', familyName: 'Doe' }); // { givenName: "John", familyName: "Doe"} await contact.setGivenName('Andrew'); // { givenName: "Andrew", familyName: "Doe"} await contact.addPhone({ label: 'work', number: '+12345678912' }); // { givenName: "Andrew", familyName: "Doe", phones: [{label: "work", number: "+12345678912"}]} const phones = await contact.getPhones(); // Changes only the defined fields, leaves the rest unchanged await contact.patch({ phones: [...phones, { label: 'home', number: '+98765432198' }] }); /* { givenName: "Andrew", familyName: "Doe", phones: [ {label: "work", number: "+12345678912"}, {label: "home", number: "+98765432198"} ] } */ // Replaces all fields with the ones defined in the object await contact.update({ givenName: 'John', familyName: 'Doe' }); // { givenName: "John", familyName: "Doe"} ``` Retrieving contacts ```tsx const contactDetails = await Contact.getAllDetails([ContactField.FULL_NAME, ContactField.PHONES], { limit: 20, offset: 10, sortOrder: ContactsSortOrder.GivenName, }); // Contact instance can be created from fetched details const contacts = contactDetails.map(item => new Contact(item.id)); const contactsFromGetAll = await Contact.getAll({ limit: 20, offset: 10, sortOrder: ContactsSortOrder.GivenName, }); ``` Contacts infinite scroll example ```tsx import { Contact, ContactField, PartialContactDetails } from 'expo-contacts/next'; import { useEffect, useState } from 'react'; import { FlatList, Text, View } from 'react-native'; const FIELDS = [ContactField.FULL_NAME, ContactField.PHONES] as const; export default function InfiniteContacts() { const [contactDetails, setContactDetails] = useState[]>([]); useEffect(() => { loadMore(); }, []); const loadMore = async () => { const newBatch = await Contact.getAllDetails(FIELDS, { limit: 20, offset: contactDetails.length, }); setContactDetails(prev => [...prev, ...newBatch]); }; return ( item.id} onEndReached={loadMore} onEndReachedThreshold={0.5} renderItem={({ item }) => ( {item.fullName} {item.phones[0]?.number ?? 'No phone number'} )} /> ); } ``` Edit contact form example ```tsx import { Contact, ContactField, ContactPatch } from 'expo-contacts/next'; import { useEffect, useState } from 'react'; import { Alert, Button, ScrollView, Text, TextInput, View } from 'react-native'; export default function ContactForm() { const [contact, setContact] = useState(null); const [contactPatch, setContactPatch] = useState({}); const [newPhoneInput, setNewPhoneInput] = useState(''); useEffect(() => { Contact.getAll({ limit: 1 }).then(async ([first]) => { if (first) { setContact(first); setContactPatch(await first.getDetails([ContactField.GIVEN_NAME, ContactField.PHONES])); } }); }, []); if (!contactPatch && contact) { return Loading details...; } const handleChangeName = (text: string) => setContactPatch(prev => ({ ...prev, givenName: text })); const handleAddPhone = () => { if (!newPhoneInput) { return; } setContactPatch(prev => ({ ...prev, phones: [...(prev.phones || []), { label: 'mobile', number: newPhoneInput }], })); setNewPhoneInput(''); }; const handleRemovePhone = (idx: number) => setContactPatch(prev => ({ ...prev, phones: prev.phones?.filter((_, i) => i !== idx), })); const handlePatch = async () => { if (contact) { await contact.patch(contactPatch); } Alert.alert('Contact patched successfully'); }; if (!contact) { return Loading...; } return ( Edit ID: {contact.id} Name: Phones: {contactPatch.phones?.map((phone, index) => ( {phone.number}