Manage device contacts across iOS, Android, and the Web with a unified Capacitor API.
The most complete doc is available here: https://capgo.app/docs/plugins/contacts/
npm install @capgo/capacitor-contacts
npx cap synccountContacts()createContact(...)createGroup(...)deleteContactById(...)deleteGroupById(...)displayContactById(...)displayCreateContact(...)displayUpdateContactById(...)getAccounts()getContactById(...)getContacts(...)getGroupById(...)getGroups()isAvailable()isSupported()openSettings()pickContact(...)pickContacts(...)updateContactById(...)checkPermissions()requestPermissions(...)getPluginVersion()- Interfaces
- Type Aliases
Capacitor Contacts Plugin interface for managing device contacts.
countContacts() => Promise<CountContactsResult>Count the total number of contacts on the device.
Returns: Promise<CountContactsResult>
Since: 1.0.0
createContact(options: CreateContactOptions) => Promise<CreateContactResult>Create a new contact programmatically.
| Param | Type | Description |
|---|---|---|
options |
CreateContactOptions |
- The contact information to create |
Returns: Promise<CreateContactResult>
Since: 1.0.0
createGroup(options: CreateGroupOptions) => Promise<CreateGroupResult>Create a new contact group.
| Param | Type | Description |
|---|---|---|
options |
CreateGroupOptions |
- The group information to create |
Returns: Promise<CreateGroupResult>
Since: 1.0.0
deleteContactById(options: DeleteContactByIdOptions) => Promise<void>Delete a contact by ID.
| Param | Type | Description |
|---|---|---|
options |
DeleteContactByIdOptions |
- The ID of the contact to delete |
Since: 1.0.0
deleteGroupById(options: DeleteGroupByIdOptions) => Promise<void>Delete a group by ID.
| Param | Type | Description |
|---|---|---|
options |
DeleteGroupByIdOptions |
- The ID of the group to delete |
Since: 1.0.0
displayContactById(options: DisplayContactByIdOptions) => Promise<void>Display a contact using the native contact viewer.
| Param | Type | Description |
|---|---|---|
options |
DisplayContactByIdOptions |
- The ID of the contact to display |
Since: 1.0.0
displayCreateContact(options?: DisplayCreateContactOptions | undefined) => Promise<DisplayCreateContactResult>Display the native create contact UI.
| Param | Type | Description |
|---|---|---|
options |
DisplayCreateContactOptions |
- Optional pre-filled contact information |
Returns: Promise<DisplayCreateContactResult>
Since: 1.0.0
displayUpdateContactById(options: DisplayUpdateContactByIdOptions) => Promise<void>Display the native update contact UI for a specific contact.
| Param | Type | Description |
|---|---|---|
options |
DisplayUpdateContactByIdOptions |
- The ID of the contact to update |
Since: 1.0.0
getAccounts() => Promise<GetAccountsResult>Get all accounts available on the device.
Returns: Promise<GetAccountsResult>
Since: 1.0.0
getContactById(options: GetContactByIdOptions) => Promise<GetContactByIdResult>Get a specific contact by ID.
| Param | Type | Description |
|---|---|---|
options |
GetContactByIdOptions |
- The ID and optional fields to retrieve |
Returns: Promise<GetContactByIdResult>
Since: 1.0.0
getContacts(options?: GetContactsOptions | undefined) => Promise<GetContactsResult>Get all contacts from the device.
| Param | Type | Description |
|---|---|---|
options |
GetContactsOptions |
- Optional filters and pagination options |
Returns: Promise<GetContactsResult>
Since: 1.0.0
getGroupById(options: GetGroupByIdOptions) => Promise<GetGroupByIdResult>Get a specific group by ID.
| Param | Type | Description |
|---|---|---|
options |
GetGroupByIdOptions |
- The ID of the group to retrieve |
Returns: Promise<GetGroupByIdResult>
Since: 1.0.0
getGroups() => Promise<GetGroupsResult>Get all contact groups.
Returns: Promise<GetGroupsResult>
Since: 1.0.0
isAvailable() => Promise<IsAvailableResult>Check if contacts are available on the device.
Returns: Promise<IsAvailableResult>
Since: 1.0.0
isSupported() => Promise<IsSupportedResult>Check if the plugin is supported on the current platform.
Returns: Promise<IsSupportedResult>
Since: 1.0.0
openSettings() => Promise<void>Open the device's contacts settings.
Since: 1.0.0
pickContact(options?: PickContactsOptions | undefined) => Promise<PickContactResult>Pick a single contact using the native contact picker.
| Param | Type | Description |
|---|---|---|
options |
PickContactsOptions |
- Optional fields to retrieve and picker configuration |
Returns: Promise<PickContactsResult>
Since: 1.0.0
pickContacts(options?: PickContactsOptions | undefined) => Promise<PickContactsResult>Pick one or more contacts using the native contact picker.
| Param | Type | Description |
|---|---|---|
options |
PickContactsOptions |
- Optional fields to retrieve and picker configuration |
Returns: Promise<PickContactsResult>
Since: 1.0.0
updateContactById(options: UpdateContactByIdOptions) => Promise<void>Update an existing contact by ID.
| Param | Type | Description |
|---|---|---|
options |
UpdateContactByIdOptions |
- The ID and updated contact information |
Since: 1.0.0
checkPermissions() => Promise<PermissionStatus>Check the current permission status for contacts.
Returns: Promise<PermissionStatus>
Since: 1.0.0
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>Request permissions to access contacts.
| Param | Type | Description |
|---|---|---|
options |
RequestPermissionsOptions |
- Optional specific permissions to request |
Returns: Promise<PermissionStatus>
Since: 1.0.0
getPluginVersion() => Promise<{ version: string; }>Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 1.0.0
Result from counting contacts.
| Prop | Type | Description | Since |
|---|---|---|---|
count |
number |
Total number of contacts. | 1.0.0 |
Result from creating a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the newly created contact. | 1.0.0 |
Options for creating a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
contact |
Omit<Contact, 'id'> |
Contact information to create. The 'id' field will be generated automatically. | 1.0.0 |
Contact information.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Unique identifier for the contact. | 1.0.0 |
account |
Account |
Account information for the contact. | 1.0.0 |
birthday |
Birthday |
Birthday information for the contact. | 1.0.0 |
emailAddresses |
EmailAddress[] |
Email addresses for the contact. | 1.0.0 |
familyName |
string |
Family name (last name) of the contact. | 1.0.0 |
fullName |
string |
Full name of the contact. | 1.0.0 |
givenName |
string |
Given name (first name) of the contact. | 1.0.0 |
groupIds |
string[] |
Group IDs the contact belongs to. | 1.0.0 |
jobTitle |
string |
Job title of the contact. | 1.0.0 |
middleName |
string |
Middle name of the contact. | 1.0.0 |
namePrefix |
string |
Name prefix (e.g., "Dr.", "Mr.", "Ms.") of the contact. | 1.0.0 |
nameSuffix |
string |
Name suffix (e.g., "Jr.", "Sr.", "III") of the contact. | 1.0.0 |
note |
string |
Notes about the contact. | 1.0.0 |
organizationName |
string |
Organization name of the contact. | 1.0.0 |
phoneNumbers |
PhoneNumber[] |
Phone numbers for the contact. | 1.0.0 |
photo |
string |
Base64-encoded photo of the contact. | 1.0.0 |
postalAddresses |
PostalAddress[] |
Postal addresses for the contact. | 1.0.0 |
urlAddresses |
UrlAddress[] |
URL addresses for the contact. | 1.0.0 |
Account information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
name |
string |
The name of the account. | 1.0.0 |
type |
string |
The type of the account. | 1.0.0 |
Birthday information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
day |
number |
The day of the month (1-31). | 1.0.0 |
month |
number |
The month (1-12). | 1.0.0 |
year |
number |
The year. | 1.0.0 |
Email address information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
value |
string |
The email address value. | 1.0.0 |
type |
EmailAddressType |
The type of email address. | 1.0.0 |
label |
string |
Custom label for the email address. | 1.0.0 |
isPrimary |
boolean |
Whether this is the primary email address. | 1.0.0 |
Phone number information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
value |
string |
The phone number value. | 1.0.0 |
type |
PhoneNumberType |
The type of phone number. | 1.0.0 |
label |
string |
Custom label for the phone number. | 1.0.0 |
isPrimary |
boolean |
Whether this is the primary phone number. | 1.0.0 |
Postal address information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
city |
string |
The city name. | 1.0.0 |
country |
string |
The country name. | 1.0.0 |
formatted |
string |
The formatted address string. | 1.0.0 |
isoCountryCode |
string |
The ISO country code. | 1.0.0 |
isPrimary |
boolean |
Whether this is the primary postal address. | 1.0.0 |
label |
string |
Custom label for the postal address. | 1.0.0 |
neighborhood |
string |
The neighborhood name. | 1.0.0 |
postalCode |
string |
The postal code. | 1.0.0 |
state |
string |
The state or province name. | 1.0.0 |
street |
string |
The street address. | 1.0.0 |
type |
PostalAddressType |
The type of postal address. | 1.0.0 |
URL address information for a contact.
| Prop | Type | Description | Since |
|---|---|---|---|
value |
string |
The URL value. | 1.0.0 |
type |
UrlAddressType |
The type of URL. | 1.0.0 |
label |
string |
Custom label for the URL. | 1.0.0 |
Result from creating a group.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the newly created group. | 1.0.0 |
Options for creating a group.
| Prop | Type | Description | Since |
|---|---|---|---|
group |
Omit<Group, 'id'> |
Group information to create. The 'id' field will be generated automatically. | 1.0.0 |
Contact group information.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Unique identifier for the group. | 1.0.0 |
name |
string |
Name of the group. | 1.0.0 |
Options for deleting a contact by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the contact to delete. | 1.0.0 |
Options for deleting a group by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the group to delete. | 1.0.0 |
Options for displaying a contact by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the contact to display. | 1.0.0 |
Result from displaying the native create contact UI.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the created contact, if one was created. Undefined if the user cancelled. | 1.0.0 |
Options for displaying the native create contact UI.
| Prop | Type | Description | Since |
|---|---|---|---|
contact |
Omit<Contact, 'id'> |
Optional pre-filled contact information for the create UI. | 1.0.0 |
Options for displaying the native update contact UI.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the contact to update. | 1.0.0 |
Result from getting accounts.
| Prop | Type | Description | Since |
|---|---|---|---|
accounts |
Account[] |
List of accounts available on the device. | 1.0.0 |
Result from getting a contact by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
contact |
Contact | null |
The contact, or null if not found. | 1.0.0 |
Options for getting a contact by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the contact to retrieve. | 1.0.0 |
fields |
(keyof Contact)[] |
Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 |
Result from getting contacts.
| Prop | Type | Description | Since |
|---|---|---|---|
contacts |
Contact[] |
List of contacts. | 1.0.0 |
Options for getting contacts.
| Prop | Type | Description | Since |
|---|---|---|---|
fields |
(keyof Contact)[] |
Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 |
limit |
number |
Maximum number of contacts to return. | 1.0.0 |
offset |
number |
Number of contacts to skip before starting to return results. | 1.0.0 |
Result from getting a group by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
group |
Group | null |
The group, or null if not found. | 1.0.0 |
Options for getting a group by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the group to retrieve. | 1.0.0 |
Result from getting groups.
| Prop | Type | Description | Since |
|---|---|---|---|
groups |
Group[] |
List of groups. | 1.0.0 |
Result from checking if contacts are available on the device.
| Prop | Type | Description | Since |
|---|---|---|---|
isAvailable |
boolean |
Whether contacts are available on this device. | 1.0.0 |
Result from checking if the plugin is supported on the platform.
| Prop | Type | Description | Since |
|---|---|---|---|
isSupported |
boolean |
Whether the plugin is supported on this platform. | 1.0.0 |
Result from picking contacts.
| Prop | Type | Description | Since |
|---|---|---|---|
contacts |
Contact[] |
List of selected contacts. | 1.0.0 |
Options for picking contacts using the native contact picker.
| Prop | Type | Description | Since |
|---|---|---|---|
fields |
(keyof Contact)[] |
Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 |
multiple |
boolean |
Whether to allow selecting multiple contacts. Default is false. | 1.0.0 |
Options for updating a contact by ID.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The ID of the contact to update. | 1.0.0 |
contact |
Omit<Contact, 'id'> |
Updated contact information. | 1.0.0 |
Status of contacts permissions.
| Prop | Type | Description | Since |
|---|---|---|---|
readContacts |
ContactsPermissionState |
Permission state for reading contacts. | 1.0.0 |
writeContacts |
ContactsPermissionState |
Permission state for writing contacts. | 1.0.0 |
Options for requesting contacts permissions.
| Prop | Type | Description | Since |
|---|---|---|---|
permissions |
ContactsPermissionType[] |
Specific permissions to request. If not provided, all permissions will be requested. | 1.0.0 |
Construct a type with the properties of T except for those in type K.
From T, pick a set of properties whose keys are in the union K
{
[P in K]: T[P];
}
Exclude from T those types that are assignable to U
T extends U ? never : T
Type of email address.
'CUSTOM' | 'HOME' | 'ICLOUD' | 'OTHER' | 'WORK'
Type of phone number.
'ASSISTANT' | 'CALLBACK' | 'CAR' | 'COMPANY_MAIN' | 'CUSTOM' | 'FAX_HOME' | 'FAX_WORK' | 'HOME' | 'HOME_FAX' | 'ISDN' | 'MAIN' | 'MMS' | 'MOBILE' | 'OTHER' | 'OTHER_FAX' | 'PAGER' | 'RADIO' | 'TELEX' | 'TTY_TDD' | 'WORK' | 'WORK_MOBILE' | 'WORK_PAGER'
Type of postal address.
'CUSTOM' | 'HOME' | 'OTHER' | 'WORK'
Type of URL address.
'BLOG' | 'CUSTOM' | 'FTP' | 'HOME' | 'HOMEPAGE' | 'OTHER' | 'PROFILE' | 'SCHOOL' | 'WORK'
Field names available in a Contact object.
keyof Contact
Alias for PickContactsOptions.
Alias for PickContactsResult.
Permission state for contacts access, including the 'limited' state for iOS 18+.
PermissionState | 'limited'
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
Type of contacts permission to request.
'readContacts' | 'writeContacts'
This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader