--- description: Capacitor plugin to read, write, or select device contacts with advanced features like filtering and pagination. title: Capacitor Contacts Plugin for Android, iOS & Web - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/contacts.png --- [Skip to content ](#capacitor-contacts-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Crisp ](/docs/sdks/capacitor/crisp/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Electron ](/docs/sdks/capacitor/electron/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor Contacts Plugin[ΒΆ](#capacitor-contacts-plugin "Permanent link") Capacitor plugin to read, write, or select device contacts. Supports Android, iOS and Web with advanced features like contact groups, pagination, and native modals. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") The Capacitor Contacts plugin is one of the most complete contact management solutions for Capacitor apps. Here are some of the key features: * πŸ–₯️ **Cross-platform**: Supports Android, iOS and Web. * πŸ“‡ **Contacts**: Create, update, delete and retrieve device contacts. * πŸ”„ **Partial Updates**: Update only specific contact fields without affecting others - missing properties are preserved, null values delete fields. * πŸ“Œ **Groups**: Create, update, delete and retrieve contact groups on iOS. * 🎫 **Accounts**: Add contacts to specific accounts on Android. * πŸ“– **Pagination**: Paginate through contacts to avoid performance issues. * πŸ” **Filtering**: Filter contacts by ID, email, phone number, etc. (Coming soon!) * πŸ“± **Native Modals**: Create, update and display contacts in native modals. * 🎯 **Picking**: Let the user select a device contact. * πŸ–ΌοΈ **Photos**: Set, update and retrieve contact photos. * 🀝 **Compatibility**: Works alongside the [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/), [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/) and [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. * ⭐️ **Support**: Priority support from the Capawesome Team. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") The Contacts plugin is typically used whenever an app needs to work with the device's address book, for example: * **Contact selection**: Let users pick one or more contacts from the device, for example to invite friends or share content. * **CRM and business apps**: Create, update, and delete contacts directly from your app, including photos, email addresses, phone numbers, and postal addresses. * **Contact syncing**: Read device contacts with pagination and keep them in sync with your backend. * **Contact organization**: Manage contact groups on iOS or add contacts to specific accounts on Android. * **Native contact forms**: Display, create, and update contacts in native modals without building your own UI. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | \>=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | ## Guides[ΒΆ](#guides "Permanent link") * [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/) * [Announcing the Capacitor Contacts Plugin](https://capawesome.io/blog/announcing-the-capacitor-contacts-plugin/) * [Exploring the Capacitor Contacts API](https://capawesome.io/blog/exploring-the-capacitor-contacts-api/) ## Installation[ΒΆ](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-contacts` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-contacts [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Permissions[ΒΆ](#permissions "Permanent link") This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag: `[](#%5F%5Fcodelineno-4-1) [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3) [](#%5F%5Fcodelineno-4-4) ` #### Proguard[ΒΆ](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-5-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` ### iOS[ΒΆ](#ios "Permanent link") #### Privacy Descriptions[ΒΆ](#privacy-descriptions "Permanent link") Add the `NSContactsUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the user's contacts: `[](#%5F%5Fcodelineno-6-1)NSContactsUsageDescription [](#%5F%5Fcodelineno-6-2)We need access to your contacts to display them in the app. ` #### Entitlements[ΒΆ](#entitlements "Permanent link") To access the `note` field of a contact, your app must have the `com.apple.developer.contacts.notes` entitlement. Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.contacts.notes) for more information. If you don't need access to the `note` field, you can skip this step. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to create, update, delete, pick, retrieve, and display contacts, manage contact groups and accounts, and check availability and permissions. ### Create a contact[ΒΆ](#create-a-contact "Permanent link") Create a new contact on the device with properties such as name, birthday, email addresses, phone numbers, and postal addresses. Only available on Android and iOS: `[](#%5F%5Fcodelineno-7-1)import { Contacts, EmailAddressType, PhoneNumberType, PostalAddressType } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const createContact = async () => { [](#%5F%5Fcodelineno-7-4) return Contacts.createContact({ [](#%5F%5Fcodelineno-7-5) contact: { [](#%5F%5Fcodelineno-7-6) birthday: { [](#%5F%5Fcodelineno-7-7) day: 1, [](#%5F%5Fcodelineno-7-8) month: 1, [](#%5F%5Fcodelineno-7-9) year: 1990 [](#%5F%5Fcodelineno-7-10) }, [](#%5F%5Fcodelineno-7-11) givenName: 'John', [](#%5F%5Fcodelineno-7-12) familyName: 'Doe', [](#%5F%5Fcodelineno-7-13) emailAddresses: [ [](#%5F%5Fcodelineno-7-14) { [](#%5F%5Fcodelineno-7-15) value: 'mail@example.com', [](#%5F%5Fcodelineno-7-16) type: EmailAddressType.Home, [](#%5F%5Fcodelineno-7-17) isPrimary: true [](#%5F%5Fcodelineno-7-18) } [](#%5F%5Fcodelineno-7-19) ], [](#%5F%5Fcodelineno-7-20) phoneNumbers: [ [](#%5F%5Fcodelineno-7-21) { [](#%5F%5Fcodelineno-7-22) value: '1234567890', [](#%5F%5Fcodelineno-7-23) type: PhoneNumberType.Mobile, [](#%5F%5Fcodelineno-7-24) isPrimary: true [](#%5F%5Fcodelineno-7-25) } [](#%5F%5Fcodelineno-7-26) ], [](#%5F%5Fcodelineno-7-27) postalAddresses: [ [](#%5F%5Fcodelineno-7-28) { [](#%5F%5Fcodelineno-7-29) street: '123 Main St', [](#%5F%5Fcodelineno-7-30) city: 'Springfield', [](#%5F%5Fcodelineno-7-31) state: 'IL', [](#%5F%5Fcodelineno-7-32) postalCode: '62701', [](#%5F%5Fcodelineno-7-33) country: 'USA', [](#%5F%5Fcodelineno-7-34) type: PostalAddressType.Home, [](#%5F%5Fcodelineno-7-35) isPrimary: true [](#%5F%5Fcodelineno-7-36) } [](#%5F%5Fcodelineno-7-37) ] [](#%5F%5Fcodelineno-7-38) } [](#%5F%5Fcodelineno-7-39) }); [](#%5F%5Fcodelineno-7-40)}; ` ### Update or delete a contact[ΒΆ](#update-or-delete-a-contact "Permanent link") Update only specific fields of an existing contact without affecting others: missing properties are preserved, `null` values delete a field. You can also delete a contact by its ID. Only available on Android and iOS: `[](#%5F%5Fcodelineno-8-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const updateContactById = async (id: string) => { [](#%5F%5Fcodelineno-8-4) await Contacts.updateContactById({ [](#%5F%5Fcodelineno-8-5) id, [](#%5F%5Fcodelineno-8-6) contact: { [](#%5F%5Fcodelineno-8-7) givenName: 'John', [](#%5F%5Fcodelineno-8-8) familyName: 'Doe', [](#%5F%5Fcodelineno-8-9) birthday: null, // This will remove the birthday field from the contact [](#%5F%5Fcodelineno-8-10) note: undefined // This will preserve the existing note field [](#%5F%5Fcodelineno-8-11) } [](#%5F%5Fcodelineno-8-12) }); [](#%5F%5Fcodelineno-8-13)}; [](#%5F%5Fcodelineno-8-14) [](#%5F%5Fcodelineno-8-15)const deleteContactById = async (id: string) => { [](#%5F%5Fcodelineno-8-16) await Contacts.deleteContactById({ id }); [](#%5F%5Fcodelineno-8-17)}; ` ### Pick contacts[ΒΆ](#pick-contacts "Permanent link") Open the native contact picker and let the user select one or more contacts. Use the `fields` option to specify which contact properties should be returned: `[](#%5F%5Fcodelineno-9-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const pickContacts = async () => { [](#%5F%5Fcodelineno-9-4) const { contacts } = await Contacts.pickContacts({ [](#%5F%5Fcodelineno-9-5) fields: [ [](#%5F%5Fcodelineno-9-6) 'id', [](#%5F%5Fcodelineno-9-7) 'givenName', [](#%5F%5Fcodelineno-9-8) 'familyName', [](#%5F%5Fcodelineno-9-9) 'emailAddresses', [](#%5F%5Fcodelineno-9-10) 'phoneNumbers', [](#%5F%5Fcodelineno-9-11) 'postalAddresses' [](#%5F%5Fcodelineno-9-12) ], [](#%5F%5Fcodelineno-9-13) multiple: true [](#%5F%5Fcodelineno-9-14) }); [](#%5F%5Fcodelineno-9-15) return contacts; [](#%5F%5Fcodelineno-9-16)}; ` ### Retrieve contacts[ΒΆ](#retrieve-contacts "Permanent link") Fetch a single contact by its ID or retrieve a list of contacts. Use the `limit` and `offset` options to paginate through large address books and `countContacts()` to get the total number of contacts. Only available on Android and iOS: `[](#%5F%5Fcodelineno-10-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const getContactById = async (id: string) => { [](#%5F%5Fcodelineno-10-4) const { contact } = await Contacts.getContactById({ id }); [](#%5F%5Fcodelineno-10-5) return contact; [](#%5F%5Fcodelineno-10-6)}; [](#%5F%5Fcodelineno-10-7) [](#%5F%5Fcodelineno-10-8)const getContacts = async () => { [](#%5F%5Fcodelineno-10-9) const { contacts } = await Contacts.getContacts({ [](#%5F%5Fcodelineno-10-10) fields: [ [](#%5F%5Fcodelineno-10-11) 'id', [](#%5F%5Fcodelineno-10-12) 'givenName', [](#%5F%5Fcodelineno-10-13) 'familyName', [](#%5F%5Fcodelineno-10-14) 'emailAddresses', [](#%5F%5Fcodelineno-10-15) 'phoneNumbers', [](#%5F%5Fcodelineno-10-16) 'postalAddresses' [](#%5F%5Fcodelineno-10-17) ], [](#%5F%5Fcodelineno-10-18) limit: 10, [](#%5F%5Fcodelineno-10-19) offset: 0 [](#%5F%5Fcodelineno-10-20) }); [](#%5F%5Fcodelineno-10-21) return contacts; [](#%5F%5Fcodelineno-10-22)}; [](#%5F%5Fcodelineno-10-23) [](#%5F%5Fcodelineno-10-24)const countContacts = async () => { [](#%5F%5Fcodelineno-10-25) const { total } = await Contacts.countContacts(); [](#%5F%5Fcodelineno-10-26) return total; [](#%5F%5Fcodelineno-10-27)}; ` ### Display contacts in native modals[ΒΆ](#display-contacts-in-native-modals "Permanent link") Show or edit a contact in the native contact modal instead of building your own UI. Only available on Android and iOS: `[](#%5F%5Fcodelineno-11-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-11-2) [](#%5F%5Fcodelineno-11-3)const displayContactById = async (id: string) => { [](#%5F%5Fcodelineno-11-4) await Contacts.displayContactById({ id }); [](#%5F%5Fcodelineno-11-5)}; [](#%5F%5Fcodelineno-11-6) [](#%5F%5Fcodelineno-11-7)const displayUpdateContactById = async (id: string) => { [](#%5F%5Fcodelineno-11-8) await Contacts.displayUpdateContactById({ id }); [](#%5F%5Fcodelineno-11-9)}; ` ### Manage contact groups[ΒΆ](#manage-contact-groups "Permanent link") Create, retrieve, and delete contact groups. Only available on iOS: `[](#%5F%5Fcodelineno-12-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-12-2) [](#%5F%5Fcodelineno-12-3)const createGroup = async () => { [](#%5F%5Fcodelineno-12-4) return Contacts.createGroup({ [](#%5F%5Fcodelineno-12-5) group: { [](#%5F%5Fcodelineno-12-6) name: 'My Group' [](#%5F%5Fcodelineno-12-7) } [](#%5F%5Fcodelineno-12-8) }); [](#%5F%5Fcodelineno-12-9)}; [](#%5F%5Fcodelineno-12-10) [](#%5F%5Fcodelineno-12-11)const deleteGroupById = async (id: string) => { [](#%5F%5Fcodelineno-12-12) await Contacts.deleteGroupById({ id }); [](#%5F%5Fcodelineno-12-13)}; [](#%5F%5Fcodelineno-12-14) [](#%5F%5Fcodelineno-12-15)const getGroupById = async (id: string) => { [](#%5F%5Fcodelineno-12-16) const { group } = await Contacts.getGroupById({ id }); [](#%5F%5Fcodelineno-12-17) return group; [](#%5F%5Fcodelineno-12-18)}; [](#%5F%5Fcodelineno-12-19) [](#%5F%5Fcodelineno-12-20)const getGroups = async () => { [](#%5F%5Fcodelineno-12-21) const { groups } = await Contacts.getGroups(); [](#%5F%5Fcodelineno-12-22) return groups; [](#%5F%5Fcodelineno-12-23)}; ` ### Retrieve accounts[ΒΆ](#retrieve-accounts "Permanent link") Retrieve the accounts that contacts can be added to. Only available on Android: `[](#%5F%5Fcodelineno-13-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-13-2) [](#%5F%5Fcodelineno-13-3)const getAccounts = async () => { [](#%5F%5Fcodelineno-13-4) const { accounts } = await Contacts.getAccounts(); [](#%5F%5Fcodelineno-13-5) return accounts; [](#%5F%5Fcodelineno-13-6)}; ` ### Check availability[ΒΆ](#check-availability "Permanent link") Check whether the contacts API is supported and available on the current device before using it: `[](#%5F%5Fcodelineno-14-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-14-2) [](#%5F%5Fcodelineno-14-3)const isAvailable = async () => { [](#%5F%5Fcodelineno-14-4) const { isAvailable } = await Contacts.isAvailable(); [](#%5F%5Fcodelineno-14-5) return isAvailable; [](#%5F%5Fcodelineno-14-6)}; [](#%5F%5Fcodelineno-14-7) [](#%5F%5Fcodelineno-14-8)const isSupported = async () => { [](#%5F%5Fcodelineno-14-9) const { isSupported } = await Contacts.isSupported(); [](#%5F%5Fcodelineno-14-10) return isSupported; [](#%5F%5Fcodelineno-14-11)}; ` ### Check and request permissions[ΒΆ](#check-and-request-permissions "Permanent link") Check and request permissions to access the device contacts. Only available on Android and iOS: `[](#%5F%5Fcodelineno-15-1)import { Contacts } from '@capawesome-team/capacitor-contacts'; [](#%5F%5Fcodelineno-15-2) [](#%5F%5Fcodelineno-15-3)const checkPermissions = async () => { [](#%5F%5Fcodelineno-15-4) return Contacts.checkPermissions(); [](#%5F%5Fcodelineno-15-5)}; [](#%5F%5Fcodelineno-15-6) [](#%5F%5Fcodelineno-15-7)const requestPermissions = async () => { [](#%5F%5Fcodelineno-15-8) return Contacts.requestPermissions(); [](#%5F%5Fcodelineno-15-9)}; ` ## API[ΒΆ](#api "Permanent link") * [countContacts()](#countcontacts) * [createContact(...)](#createcontact) * [createGroup(...)](#creategroup) * [deleteContactById(...)](#deletecontactbyid) * [deleteGroupById(...)](#deletegroupbyid) * [displayContactById(...)](#displaycontactbyid) * [displayCreateContact(...)](#displaycreatecontact) * [displayUpdateContactById(...)](#displayupdatecontactbyid) * [getAccounts()](#getaccounts) * [getContactById(...)](#getcontactbyid) * [getContacts(...)](#getcontacts) * [getGroupById(...)](#getgroupbyid) * [getGroups()](#getgroups) * [isAvailable()](#isavailable) * [isSupported()](#issupported) * [openSettings()](#opensettings) * [pickContact(...)](#pickcontact) * [pickContacts(...)](#pickcontacts) * [updateContactById(...)](#updatecontactbyid) * [checkPermissions()](#checkpermissions) * [requestPermissions(...)](#requestpermissions) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### countContacts()[ΒΆ](#countcontacts "Permanent link") `[](#%5F%5Fcodelineno-16-1)countContacts() => Promise ` Count the number of contacts on the device. Only available on Android and iOS. **Returns:** `Promise<[CountContactsResult](#countcontactsresult)>` **Since:** 7.4.0 --- ### createContact(...)[ΒΆ](#createcontact "Permanent link") `[](#%5F%5Fcodelineno-17-1)createContact(options: CreateContactOptions) => Promise ` Create a new contact on the device. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------- | | **options** | [CreateContactOptions](#createcontactoptions) | **Returns:** `Promise<[CreateContactResult](#createcontactresult)>` **Since:** 7.0.0 --- ### createGroup(...)[ΒΆ](#creategroup "Permanent link") `[](#%5F%5Fcodelineno-18-1)createGroup(options: CreateGroupOptions) => Promise ` Create a new contact group on the device. Only available on iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [CreateGroupOptions](#creategroupoptions) | **Returns:** `Promise<[CreateGroupResult](#creategroupresult)>` **Since:** 7.4.0 --- ### deleteContactById(...)[ΒΆ](#deletecontactbyid "Permanent link") `[](#%5F%5Fcodelineno-19-1)deleteContactById(options: DeleteContactByIdOptions) => Promise ` Delete a contact from the device. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------------------- | | **options** | [DeleteContactByIdOptions](#deletecontactbyidoptions) | **Since:** 7.0.0 --- ### deleteGroupById(...)[ΒΆ](#deletegroupbyid "Permanent link") `[](#%5F%5Fcodelineno-20-1)deleteGroupById(options: DeleteGroupByIdOptions) => Promise ` Delete a contact group from the device. Only available on iOS. | Param | Type | | ----------- | ------------------------------------------------- | | **options** | [DeleteGroupByIdOptions](#deletegroupbyidoptions) | **Since:** 7.4.0 --- ### displayContactById(...)[ΒΆ](#displaycontactbyid "Permanent link") `[](#%5F%5Fcodelineno-21-1)displayContactById(options: DisplayContactByIdOptions) => Promise ` Display an existing contact by identifier. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [DisplayContactByIdOptions](#displaycontactbyidoptions) | **Since:** 7.4.0 --- ### displayCreateContact(...)[ΒΆ](#displaycreatecontact "Permanent link") `[](#%5F%5Fcodelineno-22-1)displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise ` Open a native modal to create a new device contact. This allows the user to update the contact information before saving it and does not require any permissions. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------------------------- | | **options** | [DisplayCreateContactOptions](#displaycreatecontactoptions) | **Returns:** `Promise<[DisplayCreateContactResult](#displaycreatecontactresult)>` **Since:** 7.2.0 --- ### displayUpdateContactById(...)[ΒΆ](#displayupdatecontactbyid "Permanent link") `[](#%5F%5Fcodelineno-23-1)displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise ` Open a native modal to update a contact. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------------------------- | | **options** | [DisplayUpdateContactByIdOptions](#displayupdatecontactbyidoptions) | **Since:** 7.4.0 --- ### getAccounts()[ΒΆ](#getaccounts "Permanent link") `[](#%5F%5Fcodelineno-24-1)getAccounts() => Promise ` List all accounts on the device. Only available on Android. **Returns:** `Promise<[GetAccountsResult](#getaccountsresult)>` **Since:** 7.4.0 --- ### getContactById(...)[ΒΆ](#getcontactbyid "Permanent link") `[](#%5F%5Fcodelineno-25-1)getContactById(options: GetContactByIdOptions) => Promise ` Find a contact by identifier. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------------- | | **options** | [GetContactByIdOptions](#getcontactbyidoptions) | **Returns:** `Promise<[GetContactByIdResult](#getcontactbyidresult)>` **Since:** 7.0.0 --- ### getContacts(...)[ΒΆ](#getcontacts "Permanent link") `[](#%5F%5Fcodelineno-26-1)getContacts(options?: GetContactsOptions | undefined) => Promise ` List all contacts on the device. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [GetContactsOptions](#getcontactsoptions) | **Returns:** `Promise<[GetContactsResult](#getcontactsresult)>` **Since:** 7.0.0 --- ### getGroupById(...)[ΒΆ](#getgroupbyid "Permanent link") `[](#%5F%5Fcodelineno-27-1)getGroupById(options: GetGroupByIdOptions) => Promise ` Find a contact group by identifier. Only available on iOS. | Param | Type | | ----------- | ------------------------------------------- | | **options** | [GetGroupByIdOptions](#getgroupbyidoptions) | **Returns:** `Promise<[GetGroupByIdResult](#getgroupbyidresult)>` **Since:** 7.4.0 --- ### getGroups()[ΒΆ](#getgroups "Permanent link") `[](#%5F%5Fcodelineno-28-1)getGroups() => Promise ` List all contact groups on the device. Only available on iOS. **Returns:** `Promise<[GetGroupsResult](#getgroupsresult)>` **Since:** 7.4.0 --- ### isAvailable()[ΒΆ](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-29-1)isAvailable() => Promise ` Check whether or not contacts is available on the device. **Returns:** `Promise<[IsAvailableResult](#isavailableresult)>` **Since:** 7.6.0 --- ### isSupported()[ΒΆ](#issupported "Permanent link") `[](#%5F%5Fcodelineno-30-1)isSupported() => Promise ` Check if the contacts API is available on the device. **Returns:** `Promise<[IsSupportedResult](#issupportedresult)>` **Since:** 7.0.0 --- ### openSettings()[ΒΆ](#opensettings "Permanent link") `[](#%5F%5Fcodelineno-31-1)openSettings() => Promise ` Opens the native app settings page to allow the user to grant the app contacts permissions. Only available on Android and iOS. **Since:** 7.7.0 --- ### pickContact(...)[ΒΆ](#pickcontact "Permanent link") `[](#%5F%5Fcodelineno-32-1)pickContact(options?: PickContactsOptions | undefined) => Promise ` Open the contact picker to select a contact from the device. | Param | Type | | ----------- | ------------------------------------------- | | **options** | [PickContactsOptions](#pickcontactsoptions) | **Returns:** `Promise<[PickContactsResult](#pickcontactsresult)>` **Since:** 7.0.0 --- ### pickContacts(...)[ΒΆ](#pickcontacts "Permanent link") `[](#%5F%5Fcodelineno-33-1)pickContacts(options?: PickContactsOptions | undefined) => Promise ` Open the contact picker to select a contact from the device. | Param | Type | | ----------- | ------------------------------------------- | | **options** | [PickContactsOptions](#pickcontactsoptions) | **Returns:** `Promise<[PickContactsResult](#pickcontactsresult)>` **Since:** 7.4.0 --- ### updateContactById(...)[ΒΆ](#updatecontactbyid "Permanent link") `[](#%5F%5Fcodelineno-34-1)updateContactById(options: UpdateContactByIdOptions) => Promise ` Update an existing contact on the device. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------------------- | | **options** | [UpdateContactByIdOptions](#updatecontactbyidoptions) | **Since:** 7.4.0 --- ### checkPermissions()[ΒΆ](#checkpermissions "Permanent link") `[](#%5F%5Fcodelineno-35-1)checkPermissions() => Promise ` Check permissions to access contacts. Only available on Android and iOS. **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 7.0.0 --- ### requestPermissions(...)[ΒΆ](#requestpermissions "Permanent link") `[](#%5F%5Fcodelineno-36-1)requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise ` Request permissions to access contacts. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [RequestPermissionsOptions](#requestpermissionsoptions) | **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 7.0.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### CountContactsResult[ΒΆ](#countcontactsresult "Permanent link") | Prop | Type | Description | Since | | --------- | ------ | ----------------------- | ----- | | **total** | number | The number of contacts. | 7.4.0 | #### CreateContactResult[ΒΆ](#createcontactresult "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | --------------------------------------- | ----- | | **id** | string | The identifier for the created contact. | 7.0.0 | #### CreateContactOptions[ΒΆ](#createcontactoptions "Permanent link") | Prop | Type | Description | Since | | ----------- | ------------------------------- | ---------------------- | ----- | | **contact** | Omit<[Contact](#contact), 'id'> | The contact to create. | 7.0.0 | #### Contact[ΒΆ](#contact "Permanent link") | Prop | Type | Description | Since | | -------------------- | --------------------- | ------------------------------------------------------------------------------- | ----- | | **account** | [Account](#account) | The account associated with the contact. Only available on Android. | 7.4.0 | | **birthday** | [Birthday](#birthday) | The birthday of the contact. | 7.3.0 | | **emailAddresses** | EmailAddress\[\] | The list of email addresses for the contact. | 7.0.0 | | **familyName** | string | The family name of the contact. Only available on Android and iOS. | 7.0.0 | | **givenName** | string | The given name of the contact. Only available on Android and iOS. | 7.0.0 | | **groupIds** | string\[\] | The identifier of the groups the contact belongs to. Only available on iOS. | 7.4.0 | | **id** | string | The identifier for the contact. Only available on Android and iOS. | 7.0.0 | | **jobTitle** | string | The job title of the contact. Only available on Android and iOS. | 7.0.0 | | **middleName** | string | The middle name of the contact. Only available on Android and iOS. | 7.0.0 | | **fullName** | string | The full name of the contact. Only available on Web. | 7.0.0 | | **namePrefix** | string | The name prefix of the contact. Only available on Android and iOS. | 7.0.0 | | **nameSuffix** | string | The name suffix of the contact. Only available on Android and iOS. | 7.0.0 | | **note** | string | A note about the contact. Only available on Android and iOS. | 7.0.0 | | **organizationName** | string | The organization name of the contact. Only available on Android and iOS. | 7.0.0 | | **phoneNumbers** | PhoneNumber\[\] | The list of phone numbers for the contact. | 7.0.0 | | **photo** | string | The photo of the contact as a base64 string. Only available on Android and iOS. | 7.0.0 | | **postalAddresses** | PostalAddress\[\] | The list of postal addresses for the contact. | 7.0.0 | | **urlAddresses** | UrlAddress\[\] | The list of URL addresses for the contact. Only available on Android and iOS. | 7.0.0 | #### Account[ΒΆ](#account "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | -------------------------------------------- | ----- | | **name** | string | The account name. Only available on Android. | 7.4.0 | | **type** | string | The account type. Only available on Android. | 7.4.0 | #### Birthday[ΒΆ](#birthday "Permanent link") | Prop | Type | Description | Since | | --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **day** | number | The day of the birthdate. | 7.3.0 | | **month** | number | The month of the birthdate. | 7.3.0 | | **year** | number | The year of the birthdate. On **Android**, this must be provided if the day and month are provided when using the displayCreateContact(...) method. | 7.3.0 | #### EmailAddress[ΒΆ](#emailaddress "Permanent link") | Prop | Type | Description | Default | Since | | ------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- | | **isPrimary** | boolean | Whether this email address is the primary one for the contact. | false | 7.0.0 | | **label** | string | A custom label for the email address. On **iOS**, this label is only set if the type is [EmailAddressType.Custom](#emailaddresstype). | | 7.0.0 | | **type** | [EmailAddressType](#emailaddresstype) | The type of email address. | EmailAddressType.Other | 7.0.0 | | **value** | string | The email address. | | 7.0.0 | #### PhoneNumber[ΒΆ](#phonenumber "Permanent link") | Prop | Type | Description | Default | Since | | ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----- | | **isPrimary** | boolean | Whether this email address is the primary one for the contact. | | 7.0.0 | | **label** | string | A custom label for the phone number. On **iOS**, this label is only set if the type is [PhoneNumberType.Custom](#phonenumbertype). | | 7.0.0 | | **type** | [PhoneNumberType](#phonenumbertype) | The type of phone number. | PhoneNumberType.Other | 7.0.0 | | **value** | string | The phone number. | | | #### PostalAddress[ΒΆ](#postaladdress "Permanent link") | Prop | Type | Description | Default | Since | | ------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----- | | **city** | string | The city for the postal address. | | 7.0.0 | | **country** | string | The country for the postal address. | | 7.0.0 | | **formatted** | string | The formatted postal address. | | 7.0.0 | | **isoCountryCode** | string | The ISO country code for the postal address. Only available on iOS. | | 7.0.0 | | **isPrimary** | boolean | Whether this postal address is the primary one for the contact. Only available on Android and iOS. | false | 7.0.0 | | **label** | string | A custom label for the postal address. On **iOS**, this label is only set if the type is [PostalAddressType.Custom](#postaladdresstype). Only available on Android and iOS. | | 7.0.0 | | **neighborhood** | string | The neighborhood for the postal address. Only available on Android and iOS. | | 7.0.0 | | **postalCode** | string | The postal code for the postal address. Only available on Android and iOS. | | 7.0.0 | | **state** | string | The state for the postal address. | | 7.0.0 | | **street** | string | The street for the postal address. Only available on Android and iOS. | | 7.0.0 | | **type** | [PostalAddressType](#postaladdresstype) | The type of postal address. Only available on Android and iOS. | PostalAddressType.Other | 7.0.0 | #### UrlAddress[ΒΆ](#urladdress "Permanent link") | Prop | Type | Description | Default | Since | | --------- | --------------------------------- | ----------------------------------- | -------------------- | ----- | | **label** | string | A custom label for the URL address. | | 7.5.0 | | **type** | [UrlAddressType](#urladdresstype) | The type of URL address. | UrlAddressType.Other | 7.5.0 | | **value** | string | The URL address. | | | #### CreateGroupResult[ΒΆ](#creategroupresult "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ------------------------------------- | ----- | | **id** | string | The identifier for the created group. | 7.4.0 | #### CreateGroupOptions[ΒΆ](#creategroupoptions "Permanent link") | Prop | Type | Description | Since | | --------- | --------------------------- | -------------------- | ----- | | **group** | Omit<[Group](#group), 'id'> | The group to create. | 7.4.0 | #### Group[ΒΆ](#group "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | ----------------------------- | ----- | | **id** | string | The identifier for the group. | 7.4.0 | | **name** | string | The name of the group. | 7.4.0 | #### DeleteContactByIdOptions[ΒΆ](#deletecontactbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ------------------------------- | ----- | | **id** | string | The identifier for the contact. | 7.0.0 | #### DeleteGroupByIdOptions[ΒΆ](#deletegroupbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ----------------------------- | ----- | | **id** | string | The identifier for the group. | 7.4.0 | #### DisplayContactByIdOptions[ΒΆ](#displaycontactbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ----------------------------------------- | ----- | | **id** | string | The identifier of the contact to display. | 7.4.0 | #### DisplayCreateContactResult[ΒΆ](#displaycreatecontactresult "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------- | ----- | | **id** | string | The identifier for the created contact. On **Android**, you need the readContacts permission to return the identifier. | 7.4.0 | #### DisplayCreateContactOptions[ΒΆ](#displaycreatecontactoptions "Permanent link") | Prop | Type | Description | Since | | ----------- | ------------------------------- | --------------------------------------------------- | ----- | | **contact** | Omit<[Contact](#contact), 'id'> | The contact to display in the create contact modal. | 7.2.0 | #### DisplayUpdateContactByIdOptions[ΒΆ](#displayupdatecontactbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ---------------------------------------- | ----- | | **id** | string | The identifier of the contact to update. | 7.4.0 | #### GetAccountsResult[ΒΆ](#getaccountsresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------- | --------------------------------------------- | ----- | | **accounts** | Account\[\] | An array of available accounts on the device. | 7.4.0 | #### GetContactByIdResult[ΒΆ](#getcontactbyidresult "Permanent link") | Prop | Type | | ----------- | --------------------------- | | **contact** | [Contact](#contact) \| null | #### GetContactByIdOptions[ΒΆ](#getcontactbyidoptions "Permanent link") | Prop | Type | Description | Default | Since | | ---------- | ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **fields** | (keyof [Contact](#contact))\[\] | The fields to return for the contact. | \['birthday', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'\] | 7.1.0 | | **id** | string | The identifier for the contact. | | 7.0.0 | #### GetContactsResult[ΒΆ](#getcontactsresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------- | ------------------------------------------------------------------------------------------------- | ----- | | **contacts** | Contact\[\] | The list of contacts on the device. **Note**: No photos are returned to avoid performance issues. | 7.0.0 | #### GetContactsOptions[ΒΆ](#getcontactsoptions "Permanent link") | Prop | Type | Description | Default | Since | | ---------- | ------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **fields** | (keyof [Contact](#contact))\[\] | The fields to return for the contact. | \['emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'\] | 7.1.0 | | **limit** | number | Limit the number of contacts returned. | 20 | 7.4.0 | | **offset** | number | Offset the number of contacts returned. | 0 | 7.4.0 | #### GetGroupByIdResult[ΒΆ](#getgroupbyidresult "Permanent link") | Prop | Type | Description | Since | | --------- | ----------------------- | ---------------------------------------- | ----- | | **group** | [Group](#group) \| null | The group with the specified identifier. | 7.4.0 | #### GetGroupByIdOptions[ΒΆ](#getgroupbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ----------------------------- | ----- | | **id** | string | The identifier for the group. | 7.4.0 | #### GetGroupsResult[ΒΆ](#getgroupsresult "Permanent link") | Prop | Type | Description | Since | | ---------- | --------- | --------------------------------- | ----- | | **groups** | Group\[\] | The list of groups on the device. | 7.4.0 | #### IsAvailableResult[ΒΆ](#isavailableresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | --------------------------------------------------- | ----- | | **isAvailable** | boolean | Whether or not contacts is available on the device. | 7.6.0 | #### IsSupportedResult[ΒΆ](#issupportedresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | -------------------------------------------------------------------------------------------- | ----- | | **isSupported** | boolean | Whether the contacts API is available on the device. This is always true on Android and iOS. | 7.0.0 | #### PickContactsResult[ΒΆ](#pickcontactsresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------- | --------------------------------------------------- | ----- | | **contacts** | Contact\[\] | The selected contacts. Empty if none were selected. | 7.0.0 | #### PickContactsOptions[ΒΆ](#pickcontactsoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------ | ------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **fields** | (keyof [Contact](#contact))\[\] | The fields to return for the contact. Only available on Android and iOS. | \['birthday', 'emailAddresses', 'familyName', 'givenName', 'id', 'jobTitle', 'middleName', 'namePrefix', 'nameSuffix', 'organizationName', 'phoneNumbers', 'postalAddresses', 'urlAddresses'\] | 7.4.0 | | **multiple** | boolean | Whether to allow selecting multiple contacts. Only available on Web. | false | 7.0.0 | #### UpdateContactByIdOptions[ΒΆ](#updatecontactbyidoptions "Permanent link") | Prop | Type | Description | Since | | ----------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **contact** | [Nullable](#nullable)> | The updated contact information. Missing properties are ignored and keep their existing values. Properties explicitly set to null (or empty arrays \[\]) will be deleted. | 8.0.0 | | **id** | string | The identifier for the contact. | 8.0.0 | #### PermissionStatus[ΒΆ](#permissionstatus "Permanent link") | Prop | Type | Description | Since | | ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------- | ----- | | **readContacts** | [ContactsPermissionState](#contactspermissionstate) | Permission state for reading contacts. Only available on Android and iOS. | 7.0.0 | | **writeContacts** | [ContactsPermissionState](#contactspermissionstate) | Permission state for writing contacts. Only available on Android and iOS. | 7.0.0 | #### RequestPermissionsOptions[ΒΆ](#requestpermissionsoptions "Permanent link") | Prop | Type | Description | Default | Since | | --------------- | -------------------------- | --------------------------- | ----------------------------------- | ----- | | **permissions** | ContactsPermissionType\[\] | The permissions to request. | \['readContacts', 'writeContacts'\] | 7.0.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### ContactField[ΒΆ](#contactfield "Permanent link") `keyof [Contact](#contact)` #### PickContactOptions[ΒΆ](#pickcontactoptions "Permanent link") `[PickContactsOptions](#pickcontactsoptions)` #### PickContactResult[ΒΆ](#pickcontactresult "Permanent link") `[PickContactsResult](#pickcontactsresult)` #### Nullable[ΒΆ](#nullable "Permanent link") Makes all properties of T nullable. `{ [K in keyof T]: T[K] | null }` #### ContactsPermissionState[ΒΆ](#contactspermissionstate "Permanent link") `[PermissionState](#permissionstate) | 'limited'` #### PermissionState[ΒΆ](#permissionstate "Permanent link") `'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'` #### ContactsPermissionType[ΒΆ](#contactspermissiontype "Permanent link") `'readContacts' | 'writeContacts'` ### Enums[ΒΆ](#enums "Permanent link") #### EmailAddressType[ΒΆ](#emailaddresstype "Permanent link") | Members | Value | Description | Since | | ---------- | -------- | -------------------------- | ----- | | **Custom** | 'CUSTOM' | | 7.0.0 | | **Home** | 'HOME' | | 7.0.0 | | **ICloud** | 'ICLOUD' | Only available on iOS. | 7.0.0 | | **Mobile** | 'MOBILE' | Only available on Android. | 7.0.0 | | **Other** | 'OTHER' | | 7.0.0 | | **School** | 'SCHOOL' | Only available on iOS. | 7.0.0 | | **Work** | 'WORK' | | 7.0.0 | #### PhoneNumberType[ΒΆ](#phonenumbertype "Permanent link") | Members | Value | Description | Since | | --------------- | --------------- | -------------------------- | ----- | | **Assistant** | 'ASSISTANT' | Only available on Android. | 7.0.0 | | **Callback** | 'CALLBACK' | Only available on Android. | 7.0.0 | | **Car** | 'CAR' | Only available on Android. | 7.0.0 | | **CompanyMain** | 'COMPANY\_MAIN' | Only available on Android. | 7.0.0 | | **Custom** | 'CUSTOM' | | 7.0.0 | | **FaxHome** | 'FAX\_HOME' | | 7.0.0 | | **FaxOther** | 'FAX\_OTHER' | | 7.0.0 | | **FaxWork** | 'FAX\_WORK' | | 7.0.0 | | **Home** | 'HOME' | | 7.0.0 | | **IPhone** | 'IPHONE' | Only available on iOS. | 7.0.0 | | **Isdn** | 'ISDN' | Only available on Android. | 7.0.0 | | **Main** | 'MAIN' | | 7.0.0 | | **Mms** | 'MMS' | Only available on Android. | 7.0.0 | | **Mobile** | 'MOBILE' | | 7.0.0 | | **Other** | 'OTHER' | | 7.0.0 | | **Pager** | 'PAGER' | | 7.0.0 | | **Radio** | 'RADIO' | Only available on Android. | 7.0.0 | | **Telex** | 'TELEX' | Only available on Android. | 7.0.0 | | **TtyTdd** | 'TTY\_TDD' | Only available on Android. | 7.0.0 | | **Work** | 'WORK' | | 7.0.0 | | **WorkMobile** | 'WORK\_MOBILE' | Only available on Android. | 7.0.0 | | **WorkPager** | 'WORK\_PAGER' | Only available on Android. | 7.0.0 | #### PostalAddressType[ΒΆ](#postaladdresstype "Permanent link") | Members | Value | Since | | ---------- | -------- | ----- | | **Custom** | 'CUSTOM' | 7.0.0 | | **Home** | 'HOME' | 7.0.0 | | **Other** | 'OTHER' | 7.0.0 | | **Work** | 'WORK' | 7.0.0 | #### UrlAddressType[ΒΆ](#urladdresstype "Permanent link") | Members | Value | Description | Since | | ------------ | ---------- | -------------------------- | ----- | | **Blog** | 'BLOG' | Only available on Android. | 7.5.0 | | **Custom** | 'CUSTOM' | | 7.5.0 | | **Ftp** | 'FTP' | Only available on Android. | 7.5.0 | | **Home** | 'HOME' | | 7.5.0 | | **Homepage** | 'HOMEPAGE' | | 7.5.0 | | **Other** | 'OTHER' | | 7.5.0 | | **Profile** | 'PROFILE' | Only available on Android. | 7.5.0 | | **School** | 'SCHOOL' | Only available on iOS. | 7.5.0 | | **Work** | 'WORK' | | 7.5.0 | ## FAQ[ΒΆ](#faq "Permanent link") ### Do I need any permissions to access contacts?[ΒΆ](#do-i-need-any-permissions-to-access-contacts "Permanent link") Yes. On Android, you need to add the `READ_CONTACTS` and/or `WRITE_CONTACTS` permissions to your `AndroidManifest.xml` file (see [Installation](#installation)). On iOS, you must add the `NSContactsUsageDescription` key to your `Info.plist` file. At runtime, use `checkPermissions()` and `requestPermissions()` to manage the permission state, and `openSettings()` to send the user to the native app settings if the permission was denied. ### How do I update only specific fields of a contact?[ΒΆ](#how-do-i-update-only-specific-fields-of-a-contact "Permanent link") The `updateContactById(...)` method supports partial updates. Properties that are missing from the contact object are preserved, while properties explicitly set to `null` are deleted from the contact. See the [usage example](#update-or-delete-a-contact) above. ### Are contact groups and accounts available on all platforms?[ΒΆ](#are-contact-groups-and-accounts-available-on-all-platforms "Permanent link") No. Contact groups (`createGroup(...)`, `getGroups()`, `getGroupById(...)`, and `deleteGroupById(...)`) are only available on iOS. Accounts (`getAccounts()`) are only available on Android, where you can add contacts to a specific account. ### How do I handle large address books without performance issues?[ΒΆ](#how-do-i-handle-large-address-books-without-performance-issues "Permanent link") Use the `limit` and `offset` options of `getContacts(...)` to paginate through the contacts instead of loading all of them at once. Additionally, only request the contact properties you actually need via the `fields` option, and use `countContacts()` to determine the total number of contacts. ### How is this plugin different from the Capacitor Community Contacts plugin?[ΒΆ](#how-is-this-plugin-different-from-the-capacitor-community-contacts-plugin "Permanent link") This plugin offers advanced features such as partial updates, contact groups on iOS, accounts on Android, pagination, native modals, and contact photos, and comes with priority support from the Capawesome Team. You can find a detailed comparison in the guide [Alternative to the Capacitor Community Contacts plugin](https://capawesome.io/blog/alternative-to-capacitor-community-contacts-plugin/). ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Mail Composer](https://capawesome.io/docs/sdks/capacitor/mail-composer/): Open the native email composer. * [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number. * [SIM](https://capawesome.io/docs/sdks/capacitor/sim/): Read SIM card and carrier information. * [SMS Composer](https://capawesome.io/docs/sdks/capacitor/sms-composer/): Open the native SMS composer prefilled with recipients and a message body. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/contacts/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/contacts/#article", "headline": "Capacitor Contacts Plugin for Android, iOS & Web", "name": "Capacitor Contacts Plugin for Android, iOS & Web", "description": "Capacitor plugin to read, write, or select device contacts with advanced features like filtering and pagination.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/contacts/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/contacts/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/contacts/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/contacts/#software", "name": "Capacitor Contacts Plugin for Android, iOS & Web", "description": "Capacitor plugin to read, write, or select device contacts with advanced features like filtering and pagination.", "url": "https://capawesome.io/docs/sdks/capacitor/contacts/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Do I need any permissions to access contacts?", "acceptedAnswer": {"@type": "Answer", "text": "Yes. On Android, you need to add the READ_CONTACTS and/or WRITE_CONTACTS permissions to your AndroidManifest.xml file (see Installation). On iOS, you must add the NSContactsUsageDescription key to your Info.plist file. At runtime, use checkPermissions() and requestPermissions() to manage the permission state, and openSettings() to send the user to the native app settings if the permission was denied."}}, {"@type": "Question", "name": "How do I update only specific fields of a contact?", "acceptedAnswer": {"@type": "Answer", "text": "The updateContactById(...) method supports partial updates. Properties that are missing from the contact object are preserved, while properties explicitly set to null are deleted from the contact. See the usage example above."}}, {"@type": "Question", "name": "Are contact groups and accounts available on all platforms?", "acceptedAnswer": {"@type": "Answer", "text": "No. Contact groups ( createGroup(...), getGroups(), getGroupById(...), and deleteGroupById(...)) are only available on iOS. Accounts ( getAccounts()) are only available on Android, where you can add contacts to a specific account."}}, {"@type": "Question", "name": "How do I handle large address books without performance issues?", "acceptedAnswer": {"@type": "Answer", "text": "Use the limit and offset options of getContacts(...) to paginate through the contacts instead of loading all of them at once. Additionally, only request the contact properties you actually need via the fields option, and use countContacts() to determine the total number of contacts."}}, {"@type": "Question", "name": "How is this plugin different from the Capacitor Community Contacts plugin?", "acceptedAnswer": {"@type": "Answer", "text": "This plugin offers advanced features such as partial updates, contact groups on iOS, accounts on Android, pagination, native modals, and contact photos, and comes with priority support from the Capawesome Team. You can find a detailed comparison in the guide Alternative to the Capacitor Community Contacts plugin."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/contacts/"} ```