{"id":4560,"url":"https://github.com/morenoh149/react-native-contacts","last_synced_at":"2026-01-26T08:02:22.484Z","repository":{"id":37819124,"uuid":"44366842","full_name":"morenoh149/react-native-contacts","owner":"morenoh149","description":"React Native Contacts","archived":false,"fork":false,"pushed_at":"2025-03-20T00:26:15.000Z","size":9254,"stargazers_count":1664,"open_issues_count":12,"forks_count":568,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-27T12:03:08.008Z","etag":null,"topics":["contacts","mobile","phone","react-native","react-native-component"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/morenoh149.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-16T06:35:30.000Z","updated_at":"2025-03-20T00:26:20.000Z","dependencies_parsed_at":"2023-02-04T14:02:04.125Z","dependency_job_id":"360786d4-5a7d-43fd-b7e9-1ac6f906403e","html_url":"https://github.com/morenoh149/react-native-contacts","commit_stats":{"total_commits":497,"total_committers":160,"mean_commits":3.10625,"dds":0.7243460764587526,"last_synced_commit":"6ef00ab42ea80cb019b9af5ddc34f8932aeebbb7"},"previous_names":["rt2zz/react-native-contacts"],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morenoh149%2Freact-native-contacts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morenoh149%2Freact-native-contacts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morenoh149%2Freact-native-contacts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morenoh149%2Freact-native-contacts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/morenoh149","download_url":"https://codeload.github.com/morenoh149/react-native-contacts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247005345,"owners_count":20868017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contacts","mobile","phone","react-native","react-native-component"],"created_at":"2024-01-05T20:17:16.285Z","updated_at":"2026-01-26T08:02:17.437Z","avatar_url":"https://github.com/morenoh149.png","language":"Java","funding_links":[],"categories":["Components","Java"],"sub_categories":["System"],"readme":"![react-native-contacts](https://github.com/rt2zz/react-native-contacts/raw/master/example/logo.png)\n\nTo contribute read [CONTRIBUTING.md](CONTRIBUTING.md).\n\nAsk questions on [stackoverflow](https://stackoverflow.com/questions/tagged/react-native-contacts) not the issue tracker.\n\n## Usage\n`getAll` is a database intensive process, and can take a long time to complete depending on the size of the contacts list. Because of this, it is recommended you access the `getAll` method before it is needed, and cache the results for future use.\n```js\nimport Contacts from 'react-native-contacts';\n\nContacts.getAll().then(contacts =\u003e {\n  // contacts returned\n})\n```\nSee the full [API](#api) for more methods.\n\n### Android permissions\nOn android you must request permissions beforehand\n```js\nimport { PermissionsAndroid } from 'react-native';\nimport Contacts from 'react-native-contacts';\n\nPermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.READ_CONTACTS, {\n        title: 'Contacts',\n        message: 'This app would like to view your contacts.',\n        buttonPositive: 'Please accept bare mortal',\n    })\n        .then((res) =\u003e {\n            console.log('Permission: ', res);\n            Contacts.getAll()\n                .then((contacts) =\u003e {\n                    // work with contacts\n                    console.log(contacts);\n                })\n                .catch((e) =\u003e {\n                    console.log(e);\n                });\n        })\n        .catch((error) =\u003e {\n            console.error('Permission error: ', error);\n        });\n```\n\n## Installation\n_Please read this entire section._\n\n### npm\n\n```\nnpm install react-native-contacts --save\n```\n\n### yarn\n\n```\nyarn add react-native-contacts\n```\n## You no longer need to include the pod line in the PodFile since V7.0.0+, we now support autolinking!\nIf you were previously using manually linking follow these steps to upgrade\n```\nreact-native unlink react-native-contacts\nnpm install latest version of react-native-contacts\nYou're good to go!\n```\n### react native version 60 and above\n\nIf you are using react native version 0.60 or above you do not have to link this library.\n\n#### ios\nStarting with 0.60 on iOS you have to do the following:\n\n- Add the following line inside `ios/Podfile`\n\n```\ntarget 'app' do\n  ...\n  pod 'react-native-contacts', :path =\u003e '../node_modules/react-native-contacts' \u003c-- add me\n  ...\nend\n```\n\n- Run `pod install` in folder `ios`\n\n\n### react native below 60\n\n#### iOS\n\nUsing the same instructions as https://facebook.github.io/react-native/docs/linking-libraries-ios.html\n1. open in xcode `open ios/yourProject.xcodeproj/`\n1. drag `./node_modules/react-native-contacts/ios/RCTContacts.xcodeproj` to `Libraries` in your project view.\n1. In the XCode project navigator, select your project,\nselect the `Build Phases` tab drag `Libraries \u003e RCTContacts.xcodeproj \u003e Products \u003e libRCTContacts.a` into the `Link Binary With Libraries` section. Video to clarify \n  [Adding Camera Roll to an ios project in React Native](https://www.youtube.com/watch?v=e3ReNbQu79c).\n\nRun the app via the Run button in xcode or `react-native run-ios` in the terminal.\n\n### Android\nFor react native versions 0.60 and above you have to use Android X. Android X support was added to react-native-contacts in version 5.x+. If you are using rn 0.59 and below install rnc versions 4.x instead.\n\n1. In `android/settings.gradle`\n\n```gradle\n...\ninclude ':react-native-contacts'\nproject(':react-native-contacts').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-contacts/android')\n```\n\n2. In `android/app/build.gradle`\n\n```gradle\n...\ndependencies {\n    ...\n    implementation project(':react-native-contacts')\n}\n```\n\n3. register module\n\n```java\n//  MainApplication.java\nimport com.rt2zz.reactnativecontacts.ReactNativeContacts; // \u003c--- import\n\npublic class MainApplication extends Application implements ReactApplication {\n  ......\n\n  @Override\n  protected List\u003cReactPackage\u003e getPackages() {\n    return Arrays.\u003cReactPackage\u003easList(\n            new MainReactPackage(),\n            new ReactNativeContacts()); // \u003c------ add this\n  }\n  ......\n}\n```\n\n#### Permissions\n##### API 23+\nAndroid requires allowing permissions with https://facebook.github.io/react-native/docs/permissionsandroid.html\nThe `READ_CONTACTS` permission must be added to your main application's `AndroidManifest.xml`. If your app creates contacts add `WRITE_CONTACTS` permission to `AndroidManifest.xml` and request the permission at runtime.\n```xml\n...\n\u003cuses-permission android:name=\"android.permission.WRITE_CONTACTS\" /\u003e\n...\n```\n\n##### API 22 and below\nAdd `READ_PROFILE` and/or `WRITE_PROFILE` permissions to `AndroidManifest.xml`\n```xml\n...\n\u003cuses-permission android:name=\"android.permission.READ_PROFILE\" /\u003e\n...\n```\n\n#### ProGuard\n\nIf you use Proguard, the snippet below on proguard-rules.pro \nWithout it, your apk release version could failed\n\n```\n-keep class com.rt2zz.reactnativecontacts.** {*;}\n-keepclassmembers class com.rt2zz.reactnativecontacts.** {*;}\n```\n\n### All RN versions\n\n#### ios\nAdd kit specific \"permission\" keys to your Xcode `Info.plist` file, in order to make `requestPermission` work. Otherwise your app crashes when requesting the specific permission. Open `Info.plist`. Add key `Privacy - Contacts Usage Description` with your kit specific permission. The value for the key is optional in development. If you submit to the App Store the value must explain why you need this permission.\n\n\u003cimg width=\"338\" alt=\"screen shot 2016-09-21 at 13 13 21\" src=\"https://cloud.githubusercontent.com/assets/5707542/18704973/3cde3b44-7ffd-11e6-918b-63888e33f983.png\"\u003e\n\n##### Accessing note filed on iOS 13 (optional)\nIf you'd like to read/write the contact's notes, call the `iosEnableNotesUsage(true)` method before accessing the contact infos. Also, a `com.apple.developer.contacts.notes` entitlement must be added to the project. Before submitting your app to the AppStore, the permission for using the entitlement has to be granted as well. You can find a more detailed explanation [here](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_contacts_notes?language=objc).\n\n## API\n * `getAll`: Promise\u003cContact[]\u003e - returns *all* contacts as an array of objects\n * `getAllWithoutPhotos` - same as `getAll` on Android, but on iOS it will not return uris for contact photos (because there's a significant overhead in creating the images)\n * `getContactById(contactId)`: Promise\u003cContact\u003e - returns contact with defined contactId (or null if it doesn't exist)\n * `getCount()`: Promise\u003cnumber\u003e - returns the number of contacts\n * `getPhotoForId(contactId)`: Promise\u003cstring\u003e - returns a URI (or null) for a contacts photo\n * `addContact(contact)`: Promise\u003cContact\u003e - adds a contact to the AddressBook.  \n * `openContactForm(contact)` - create a new contact and display in contactsUI. \n * `openExistingContact(contact)` - open existing contact (edit mode), where contact is an object with a valid recordID\n * `viewExistingContact(contact)` - open existing contact (view mode), where contact is an object with a valid recordID\n * `editExistingContact(contact)`: Promise\u003cContact\u003e - add numbers to the contact, where the contact is an object with a valid recordID and an array of phoneNumbers\n * `updateContact(contact)`: Promise\u003cContact\u003e - where contact is an object with a valid recordID  \n * `deleteContact(contact)` - where contact is an object with a valid recordID  \n * `getContactsMatchingString(string)`: Promise\u003cContact[]\u003e - where string is any string to match a name (first, middle, family) to\n * `getContactsByPhoneNumber(string)`: Promise\u003cContact[]\u003e - where string is a phone number to match to.\n * `getContactsByEmailAddress(string)`: Promise\u003cContact[]\u003e - where string is an email address to match to.\n * `checkPermission()`: Promise\u003cstring\u003e - checks permission to access Contacts _ios only_\n * `requestPermission()`: Promise\u003cstring\u003e - request permission to access Contacts _ios only_\n * `writePhotoToPath()` - writes the contact photo to a given path _android only_\n\n ### ios group specific functions\n * `getGroups()`: Promise - returns an array of all groups. Each group contains `{ identifier: string; name: string;}`\n * `getGroup: (identifier: string)`: Promise - returns the group matching the provided group identifier.\n * `deleteGroup(identifier: string)`: Promise - deletes a group by group identifier.\n * `updateGroup(identifier: string, groupData: Pick\u003cGroup, 'name'\u003e`: Promise - updates an existing group's details. You can only change the group name.\n * `addGroup(group: Pick\u003cGroup, 'name'\u003e)`: Promise - adds a new group. Group name should be provided.\n * `contactsInGroup(identifier: string)`: Promise - retrieves all contacts within a specified group.\n * `addContactsToGroup(groupIdentifier: string, contactIdentifiers: string[])`: Promise - adds contacts to a group. Only contacts with id that has `:ABperson` as suffix can be added.\n * `removeContactsFromGroup(groupIdentifier: string, contactIdentifiers: string[])`: Promise - removes specified contacts from a group.\n\n## Example Contact Record\n```js\n{\n  recordID: '6b2237ee0df85980',\n  backTitle: '',\n  company: '',\n  emailAddresses: [{\n    label: 'work',\n    email: 'carl-jung@example.com',\n  }],\n  familyName: 'Jung',\n  givenName: 'Carl',\n  middleName: '',\n  jobTitle: '',\n  phoneNumbers: [{\n    label: 'mobile',\n    number: '(555) 555-5555',\n  }],\n  hasThumbnail: true,\n  thumbnailPath: 'content://com.android.contacts/display_photo/3',\n  postalAddresses: [{\n    label: 'home',\n    formattedAddress: '',\n    street: '123 Fake Street',\n    pobox: '',\n    neighborhood: '',\n    city: 'Sample City',\n    region: 'CA',\n    state: 'CA',\n    postCode: '90210',\n    country: 'USA',\n  }],\n  prefix: 'MR',\n  suffix: '',\n  department: '',\n  birthday: {'year': 1988, 'month': 1, 'day': 1 },\n  imAddresses: [\n    { username: '0123456789', service: 'ICQ'},\n    { username: 'johndoe123', service: 'Facebook'}\n  ],\n  isStarred: false,\n}\n```\n\n### Android only\n\n* on Android versions below 8 the entire display name is passed in the `givenName` field. `middleName` and `familyName` will be `\"\"`.\n* isStarred field\n* writePhotoToPath() - writes the contact photo to a given path\n\n## iOS only\n\ncheckPermission(): Promise - checks permission to access Contacts\nrequestPermission(): Promise - request permission to access Contacts\n\n## Adding Contacts\nCurrently all fields from the contact record except for thumbnailPath are supported for writing\n```js\nvar newPerson = {\n  emailAddresses: [{\n    label: \"work\",\n    email: \"mrniet@example.com\",\n  }],\n  familyName: \"Nietzsche\",\n  givenName: \"Friedrich\",\n}\n\nContacts.addContact(newPerson)\n```\n\n## Open Contact Form\nCurrently all fields from the contact record except for thumbnailPath are supported for writing\n```js\nvar newPerson = {\n  emailAddresses: [{\n    label: \"work\",\n    email: \"mrniet@example.com\",\n  }],\n  displayName: \"Friedrich Nietzsche\"\n}\n\nContacts.openContactForm(newPerson).then(contact =\u003e {\n  // contact has been saved\n})\n```\nYou may want to edit the contact before saving it into your phone book. So using `openContactForm` allow you to prompt default phone create contacts UI and the new to-be-added contact will be display on the contacts UI view. Click save or cancel button will exit the contacts UI view.\n\n## Updating Contacts\nExample\n```js\nContacts.getAll().then(contacts =\u003e {\n  // update the first record\n  let someRecord = contacts[0]\n  someRecord.emailAddresses.push({\n    label: \"junk\",\n    email: \"mrniet+junkmail@test.com\",\n  })\n  Contacts.updateContact(someRecord).then(() =\u003e {\n    // record updated\n  })\n})\n```\nUpdate reference contacts by their recordID (as returned by the OS in getContacts). Apple does not guarantee the recordID will not change, e.g. it may be reassigned during a phone migration. Consequently you should always grab a fresh contact list with `getContacts` before performing update operations.\n\n## Add numbers to an existing contact\nExample\n```js\nvar newPerson = { \n  recordID: '6b2237ee0df85980',\n  phoneNumbers: [{\n    label: 'mobile',\n    number: '(555) 555-5555',\n  }, ...\n  ]\n}\n\nContacts.editExistingContact(newPerson).then(contact =\u003e {\n    //contact updated\n});\n```\nAdd one or more phone numbers to an existing contact. \nOn Android the edited page will be opened. \nOn iOS the already edited contact will be opened with the possibility of further modification.\n\n### Bugs\nThere are issues with updating contacts on Android:\n1. custom labels get overwritten to \"Other\",\n1. postal address update code doesn't exist. (it exists for addContact)\nSee https://github.com/rt2zz/react-native-contacts/issues/332#issuecomment-455675041 for current discussions.\n\n## Delete Contacts\nYou can delete a record using only it's recordID\n```js\nContacts.deleteContact({recordID: 1}).then(recordId =\u003e {\n  // contact deleted\n})\n```\nOr by passing the full contact object with a `recordID` field.\n```js\nContacts.deleteContact(contact).then((recordId) =\u003e {\n  // contact deleted\n})\n```\n\n## Displaying Thumbnails\n\nThe thumbnailPath is the direct URI for the temp location of the contact's cropped thumbnail image.\n\n```js\n\u003cImage source={{uri: contact.thumbnailPath}} /\u003e\n```\n\n## Permissions Methods (optional)\n`checkPermission` - checks permission to access Contacts.  \n`requestPermission` - request permission to access Contacts.  \n\nUsage as follows:\n```js\nContacts.checkPermission().then(permission =\u003e {\n  // Contacts.PERMISSION_AUTHORIZED || Contacts.PERMISSION_UNDEFINED || Contacts.PERMISSION_LIMITED || Contacts.PERMISSION_DENIED\n  if (permission === 'undefined') {\n    Contacts.requestPermission().then(permission =\u003e {\n      // ...\n    })\n  }\n  if (permission === 'authorized') {\n    // yay!\n  }\n  if (permission === 'limited') {\n    // ...\n  }\n  if (permission === 'denied') {\n    // x.x\n  }\n})\n```\n\nThese methods are only useful on iOS. For Android you'll have to use https://facebook.github.io/react-native/docs/permissionsandroid.html\n\nThese methods do **not** re-request permission if permission has already been granted or denied. This is a limitation in iOS, the best you can do is prompt the user with instructions for how to enable contacts from the phone settings page `Settings \u003e [app name] \u003e contacts`.\n\n## Example\nYou can find an example app/showcase [here](https://github.com/rt2zz/react-native-contacts/tree/master/example)\n\n![react-native-contacts example](https://github.com/rt2zz/react-native-contacts/raw/master/example/react-native-contacts.gif)\n\n\n\u003ch2 align=\"center\"\u003eMaintainers\u003c/h2\u003e\n\u003cp\u003eIf your business needs premium react native support please reach out to the maintainer.\u003c/p\u003e\n\u003ca href=\"https://harrymoreno.com/hire-me\"\u003eharrymoreno.com\u003c/a\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://harrymoreno.com/hire-me\"\u003e\n          \u003cimg width=\"150\" height=\"150\" src=\"https://github.com/morenoh149.png?size=150\"\u003e\n          \u003c/br\u003e\n          Harry Moreno\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n\n## LICENSE\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorenoh149%2Freact-native-contacts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorenoh149%2Freact-native-contacts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorenoh149%2Freact-native-contacts/lists"}