@capacitor/contacts

Access, search, pick, create, update and remove device contacts.

Install

To use npm

npm install @capacitor/contacts

To use yarn

yarn add @capacitor/contacts

Sync native files

npx cap sync

iOS

Add the NSContactsUsageDescription key to your app's Info.plist and describe why the app accesses the user's contacts; iOS crashes on first contacts access without it:

<key>NSContactsUsageDescription</key>
<string>We need access to contacts to search, save and remove them.</string>

Notes:

The plugin uses the modern Contacts framework (CNContactStore, never the deprecated AddressBook APIs), so it fully supports iOS 18+ Limited Access: find, save and remove operate on the subset the user shared with the app, and pickContact presents the system picker (which needs no permission and always shows the full contact list).
The note field is not supported on iOS: reading or writing it requires Apple's restricted com.apple.developer.contacts.notes entitlement. The field is omitted on read and ignored on save.
Contact ids are opaque CNContact identifiers; ids persisted by the legacy AddressBook-based Cordova plugin do not resolve after migration.

Android

The plugin declares READ_CONTACTS and WRITE_CONTACTS in its own manifest; Gradle manifest merging adds them to your app automatically. Each method requests the runtime permission it needs the first time it runs; read for find/pickContact, read + write for save/remove.

Permission model

This plugin intentionally exposes no checkPermissions() / requestPermissions() methods: permissions are requested implicitly by each method, matching the legacy cordova-plugin-contacts behavior. A call rejects with OS-PLUG-CONT-0020 when the user denies access.

Errors

Every rejection carries a structured code + message:

Code	Meaning
`OS-PLUG-CONT-0000`	Unknown error
`OS-PLUG-CONT-0001`	Invalid argument (e.g. unknown id)
`OS-PLUG-CONT-0002`	Timeout (reserved, currently unused)
`OS-PLUG-CONT-0003`	Pending operation (e.g. picker already open)
`OS-PLUG-CONT-0004`	I/O error
`OS-PLUG-CONT-0005`	Not supported
`OS-PLUG-CONT-0006`	Operation cancelled (picker closed)
`OS-PLUG-CONT-0020`	Permission denied

Usage

import { Contacts } from '@capacitor/contacts';

// Search every field for "ada" and return all matches with a phone number
const { contacts } = await Contacts.find({
  fields: ['*'],
  filter: 'ada',
  multiple: true,
  hasPhoneNumber: true,
});

// Create a contact
const saved = await Contacts.save({
  contact: {
    name: { givenName: 'Ada', familyName: 'Lovelace' },
    phoneNumbers: [{ type: 'mobile', value: '+351910000000' }],
    emails: [{ type: 'home', value: 'ada@example.com' }],
  },
});

// Update it (id present -> update)
await Contacts.save({ contact: { ...saved, nickname: 'Countess' } });

// Pick a contact with the native picker
const picked = await Contacts.pickContact();

// Remove it by id
await Contacts.remove({ id: saved.id! });

find(...)

find(options: ContactFindOptions) => Promise<ContactFindResult>

Queries the device contacts database and returns the matching contacts.

Requests the READ_CONTACTS (Android) / Contacts (iOS) permission internally the first time it runs; there is no separate permission method.

iOS 18+: under Limited Access the search runs against (and returns only) the subset of contacts the user shared with the app.

Param	Type
`options`	`ContactFindOptions`

Returns: Promise<ContactFindResult>

Since: 1.0.0

save(...)

save(options: ContactSaveOptions) => Promise<Contact>

Persists a new contact or updates an existing one (matched by contact.id). Resolves with the full saved contact.

Requests the READ/WRITE_CONTACTS (Android) / Contacts (iOS) permission internally.

iOS 18+: works under Limited Access: new contacts are added to the app's accessible set; updating requires the target contact to be in that set (otherwise the call rejects with OS-PLUG-CONT-0001).

Param	Type
`options`	`ContactSaveOptions`

Returns: Promise<Contact>

Since: 1.0.0

remove(...)

remove(options: ContactRemoveOptions) => Promise<void>

Removes the contact with the given id from the device contacts database. Rejects with OS-PLUG-CONT-0001 when no contact has that id (on iOS 18+ Limited Access, also when the contact is outside the accessible set).

Requests the READ/WRITE_CONTACTS (Android) / Contacts (iOS) permission internally.

Param	Type
`options`	`ContactRemoveOptions`

Since: 1.0.0

pickContact()

pickContact() => Promise<Contact>

Launches the native contact picker UI and resolves with the contact the user selects. Rejects with OS-PLUG-CONT-0006 if the user cancels.

On iOS the system picker requires no permission and always shows the full contact list, even under iOS 18+ Limited Access (the picked contact is returned without joining the app's accessible set). On Android the READ_CONTACTS permission is requested internally to read the picked contact's details.

Returns: Promise<Contact>

Since: 1.0.0

Interfaces

ContactFindResult

Result of a {@link ContactsPlugin.find} call.

Prop	Type	Description	Since
`contacts`	`Contact[]`	The contacts matching the search criteria.	1.0.0

Contact

A single device contact.

Prop	Type	Description	Since
`id`	`string`	Globally unique, platform-assigned identifier. Absent for contacts not yet saved to the device.	1.0.0
`rawId`	`string`	Android raw-contact id backing this aggregated contact. iOS leaves this unset.	1.0.0
`displayName`	`string`	Name suitable for display to end users.	1.0.0
`name`	`ContactName`	The structured name components.	1.0.0
`nickname`	`string`	A casual name by which to address the contact.	1.0.0
`phoneNumbers`	`ContactField[]`	The contact's phone numbers.	1.0.0
`emails`	`ContactField[]`	The contact's email addresses.	1.0.0
`addresses`	`ContactAddress[]`	The contact's postal addresses.	1.0.0
`ims`	`ContactField[]`	The contact's instant-messaging handles.	1.0.0
`organizations`	`ContactOrganization[]`	The contact's organizations.	1.0.0
`birthday`	`number`	The contact's birthday as epoch milliseconds.	1.0.0
`note`	`string`	A free-form note about the contact. iOS: not supported by default: reading/writing a contact's note requires Apple's restricted `com.apple.developer.contacts.notes` entitlement. Without it the field is omitted on read and ignored on save. Android has no such restriction.	1.0.0
`photos`	`ContactField[]`	The contact's photos. Reads return `type: 'url'` with the `value` holding a reference to the image, never image bytes: on Android the contact's `content://` photo URI, on iOS the path of a copy written to the app's temporary directory (cleared by the system). On save, the first entry is applied: pass `type: 'base64'` with base64 data, or `type: 'url'` with a local `file://`/`content://` URI to import.	1.0.0
`categories`	`ContactField[]`	User-defined categories associated with the contact. Read-only: populated from the contact's group memberships on Android, never returned on iOS (the Contacts framework has no equivalent), and ignored on save.	1.0.0
`urls`	`ContactField[]`	Web pages associated with the contact.	1.0.0

ContactName

Structured name of a {@link Contact}.

Prop	Type	Description	Since
`formatted`	`string`	The complete formatted name.	1.0.0
`familyName`	`string`	Family (last) name.	1.0.0
`givenName`	`string`	Given (first) name.	1.0.0
`middleName`	`string`	Middle name.	1.0.0
`honorificPrefix`	`string`	Honorific prefix (e.g. `Mr.`, `Dr.`).	1.0.0
`honorificSuffix`	`string`	Honorific suffix (e.g. `Esq.`).	1.0.0

ContactField

A generic, repeatable contact field (phone number, email, IM, photo, URL, category).

Prop	Type	Description	Since
`type`	`string`	The kind of field, e.g. `home`, `work`, `mobile`. For photos, `url` or `base64`.	1.0.0
`value`	`string`	The field value (phone number, email address, URI, etc.).	1.0.0
`pref`	`boolean`	`true` if this is the contact's preferred value for the field.	1.0.0
`id`	`string`	Platform-assigned id of this individual field entry.	1.0.0

ContactAddress

A postal address of a {@link Contact}.

Prop	Type	Description	Since
`id`	`string`	Platform-assigned id of this address entry.	1.0.0
`pref`	`boolean`	`true` if this is the contact's preferred address.	1.0.0
`type`	`string`	The kind of address, e.g. `home`, `work`.	1.0.0
`formatted`	`string`	The full address formatted for display.	1.0.0
`streetAddress`	`string`	The street address.	1.0.0
`locality`	`string`	The city or locality.	1.0.0
`region`	`string`	The state or region.	1.0.0
`postalCode`	`string`	The ZIP or postal code.	1.0.0
`country`	`string`	The country name.	1.0.0

ContactOrganization

An organization a {@link Contact} belongs to.

Prop	Type	Description	Since
`id`	`string`	Platform-assigned id of this organization entry. Android only; iOS models the organization as flat contact properties without an id.	1.0.0
`pref`	`boolean`	`true` if this is the contact's preferred organization.	1.0.0
`type`	`string`	The kind of organization, e.g. `work`.	1.0.0
`name`	`string`	The organization name.	1.0.0
`department`	`string`	The department within the organization.	1.0.0
`title`	`string`	The contact's title at the organization.	1.0.0

ContactFindOptions

Search options accepted by {@link ContactsPlugin.find}.

Prop	Type	Description	Since
`fields`	`ContactFieldType[]`	Fields to search against. Pass `['*']` to match every field. An empty array is invalid and rejects with `OS-PLUG-CONT-0001`. The `id` field matches by exact identifier; all other fields match case-insensitive substrings. `photos` and `categories` are not searchable.	1.0.0
`filter`	`string`	Search string matched (case-insensitively) against the selected `fields`. An empty/omitted filter returns every contact.	1.0.0
`multiple`	`boolean`	When `true`, returns every match; when `false` (default), returns at most one contact.	1.0.0
`desiredFields`	`ContactFieldType[]`	If set, each returned {@link Contact} only includes these fields (plus the always-present `id`).	1.0.0
`hasPhoneNumber`	`boolean`	OutSystems extension: when `true`, only contacts that have at least one phone number are returned. Defaults to `false`.	1.0.0

ContactSaveOptions

Options accepted by {@link ContactsPlugin.save}.

Prop	Type	Description	Since
`contact`	`Contact`	The contact to create (no `id`) or update (existing `id`). Update semantics: every field present on the contact replaces the stored value entirely (e.g. `name` replaces the whole structured name, `phoneNumbers` replaces all phone numbers); omitted fields are left unchanged.	1.0.0

ContactRemoveOptions

Options accepted by {@link ContactsPlugin.remove}.

Prop	Type	Description	Since
`id`	`string`	The native id of the contact to remove.	1.0.0

Type Aliases

ContactFieldType

The set of contact fields a {@link ContactsPlugin.find} call can search against or request back. Mirrors the legacy Cordova ContactFieldType string values exactly.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
android		android
example-app		example-app
ios		ios
scripts		scripts
src		src
.eslintignore		.eslintignore
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
CONTRIBUTING.md		CONTRIBUTING.md
CapacitorContacts.podspec		CapacitorContacts.podspec
LICENSE		LICENSE
NOTICE		NOTICE
Package.swift		Package.swift
README.md		README.md
package.json		package.json
release.config.cjs		release.config.cjs
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@capacitor/contacts

Install

iOS

Android

Permission model

Errors

Usage

API

find(...)

save(...)

remove(...)

pickContact()

Interfaces

ContactFindResult

Contact

ContactName

ContactField

ContactAddress

ContactOrganization

ContactFindOptions

ContactSaveOptions

ContactRemoveOptions

Type Aliases

ContactFieldType

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@capacitor/contacts

Install

iOS

Android

Permission model

Errors

Usage

API

find(...)

save(...)

remove(...)

pickContact()

Interfaces

ContactFindResult

Contact

ContactName

ContactField

ContactAddress

ContactOrganization

ContactFindOptions

ContactSaveOptions

ContactRemoveOptions

Type Aliases

ContactFieldType

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages