Skip to main content

Contacts

EOL Notice

Contacts will reach its end-of-life on July 1, 2024, and will no longer receive updates or support. Please see Support Policy for additional information.

The Contacts plugin provides access to read, write, or select device contacts.

Installation

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

npm install @ionic-enterprise/contacts
npx cap sync

Usage

The Contacts plugin ship with a native Angular & es2015+/Typescript wrappers as well as being available on window.

// Angular
import { Contacts } from '@ionic-enterprise/contacts/ngx';
import { Contact, ContactName, ContactField } from '@ionic-enterprise/contacts';

...

constructor(private contacts: Contacts) { }

async createContact() {
let contact = this.contacts.create();
contact.name = new ContactName(null, 'Smith', 'John');
contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
contact.save().then(
() => console.log('Contact saved!', contact),
(error: any) => console.error('Error saving contact.', error)
);
}

...

// ES2015+/TypeScript
import { Contacts, Contact, ContactName, ContactField } from '@ionic-enterprise/contacts';

let contact = Contacts.create();
contact.name = new ContactName(null, 'Smith', 'John');
contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
contact.save().then(
() => console.log('Contact saved!', contact),
(error: any) => console.error('Error saving contact.', error)
);

...

// Vanilla JS
document.addEventListener('deviceready', () => {
let contact = IonicContacts.create();
contact.name = {familyName: 'Smith', givenName: 'John'};
contact.phoneNumbers = {type: 'mobile', value: '6471234567'};
contact.save().then(
() => console.log('Contact saved!', contact),
(error) => console.error('Error saving contact.', error)
);
});

Index

Classes

Type aliases

Type aliases

ContactFieldType

Ƭ ContactFieldType: "" | "addresses" | "birthday" | "categories" | "country" | "department" | "displayName" | "emails" | "name.familyName" | "name.formatted" | "name.givenName" | "name.honorificPrefix" | "name.honorificSuffix" | "id" | "ims" | "locality" | "name.middleName" | "name" | "nickname" | "note" | "organizations" | "phoneNumbers" | "photos" | "postalCode" | "region" | "streetAddress" | "title" | "urls"*

Support for searching varies between platforms. iOS only supports the following types for a text search:

  • 'name'
  • 'emails'
  • 'phoneNumbers'

In addition, the wildcard '*' character is required to return all contacts.

Android supports all defined fields.

Contact

Contains information about a single contact.

Constructors

constructor

+ new Contact(id?: undefined | string, displayName?: undefined | string, name?: ContactName, nickname?: undefined | string, phoneNumbers?: ContactField[], emails?: ContactField[], addresses?: ContactAddress[], ims?: ContactField[], organizations?: ContactOrganization[], birthday?: Date | string | null, note?: undefined | string, photos?: ContactField[], categories?: ContactField[], urls?: ContactField[]): Contact

Parameters:

NameType
id?undefined | string
displayName?undefined | string
name?ContactName
nickname?undefined | string
phoneNumbers?ContactField[]
emails?ContactField[]
addresses?ContactAddress[]
ims?ContactField[]
organizations?ContactOrganization[]
birthday?Date | string | null
note?undefined | string
photos?ContactField[]
categories?ContactField[]
urls?ContactField[]

Returns: Contact

Properties

Optional addresses

addresses? : ContactAddress[] | null

An array of all the contact's addresses.


Optional birthday

birthday? : Date | string | null

The birthday of the contact.


Optional categories

categories? : ContactField[] | null

An array of all the user-defined categories associated with the contact.


Optional displayName

displayName? : string | null

The name of this Contact, suitable for display to end users.


Optional emails

emails? : ContactField[] | null

An array of all the contact's email addresses.


Optional id

id? : string | null

A globally unique identifier.


Optional ims

ims? : ContactField[] | null

An array of all the contact's IM addresses.


Optional name

name? : ContactName | null

An object containing all components of a persons name.


Optional nickname

nickname? : string | null

A casual name by which to address the contact.


Optional note

note? : string | null

A note about the contact on Android.


Optional organizations

organizations? : ContactOrganization[] | null

An array of all the contact's organizations.


Optional phoneNumbers

phoneNumbers? : ContactField[] | null

An array of all the contact's phone numbers.


Optional photos

photos? : ContactField[] | null

An array of the contact's photos.


Optional rawId

rawId? : string | null

A globally unique identifier on Android.


Optional urls

urls? : ContactField[] | null

An array of web pages associated with the contact.

Methods

clone

clone(): Contact

Creates a deep copy of this Contact. With the contact ID set to null.

Returns: Contact

copy of this Contact


display

display(allowEdit?: undefined | false | true): Promise‹any›

iOS only Display a contact in the native Contact Picker UI

Parameters:

NameTypeDescription
allowEdit?undefined | false | truetrue display the contact and allow editing it false (default) display contact without editing

Returns: Promise‹any›


remove

remove(): Promise‹any›

Removes contact from device storage.

Returns: Promise‹any›


save

save(): Promise‹any›

Persists contact to device storage.

Returns: Promise‹any›

Contactaddress

Contact address.

Constructors

constructor

+ new ContactAddress(pref?: undefined | false | true, type?: undefined | string, formatted?: undefined | string, streetAddress?: undefined | string, locality?: undefined | string, region?: undefined | string, postalCode?: undefined | string, country?: undefined | string): ContactAddress

Parameters:

NameType
pref?undefined | false | true
type?undefined | string
formatted?undefined | string
streetAddress?undefined | string
locality?undefined | string
region?undefined | string
postalCode?undefined | string
country?undefined | string

Returns: ContactAddress

Properties

Optional country

country? : string | null

The country name.


Optional formatted

formatted? : string | null

The full address formatted for display.


Optional id

id? : string | null

unique identifier, should only be set by native code


Optional locality

locality? : string | null

The city or locality.


Optional postalCode

postalCode? : string | null

The zip code or postal code.


Optional pref

pref? : undefined | false | true

Set to true if this ContactAddress contains the user's preferred value.


Optional region

region? : string | null

The state or region.


Optional streetAddress

streetAddress? : string | null

The full street address.


Optional type

type? : string | null

A string indicating what type of field this is, home for example.

Contacterror

ContactError. An error code assigned by an implementation when an error has occurred

Constructors

constructor

+ new ContactError(code: number): ContactError

Parameters:

NameType
codenumber

Returns: ContactError

Properties

code

code: number

Error code


Optional message

message? : undefined | string

Error message


Static INVALID_ARGUMENT_ERROR

INVALID_ARGUMENT_ERROR: number = 1


Static IO_ERROR

IO_ERROR: number = 4


Static NOT_SUPPORTED_ERROR

NOT_SUPPORTED_ERROR: number = 5


Static OPERATION_CANCELLED_ERROR

OPERATION_CANCELLED_ERROR: number = 6


Static PENDING_OPERATION_ERROR

PENDING_OPERATION_ERROR: number = 3


Static PERMISSION_DENIED_ERROR

PERMISSION_DENIED_ERROR: number = 20


Static TIMEOUT_ERROR

TIMEOUT_ERROR: number = 2


Static UNKNOWN_ERROR

UNKNOWN_ERROR: number = 0

Error codes

Contactfield

Generic contact field.

Constructors

constructor

+ new ContactField(type?: undefined | string, value?: undefined | string, pref?: undefined | false | true): ContactField

Parameters:

NameType
type?undefined | string
value?undefined | string
pref?undefined | false | true

Returns: ContactField

Properties

Optional id

id? : string | null

unique identifier, should only be set by native code


Optional pref

pref? : undefined | false | true

Set to true if this ContactField contains the user's preferred value.


Optional type

type? : string | null

A string that indicates what type of field this is, home for example.


Optional value

value? : string | null

The value of the field, such as a phone number or email address.

Contactfindoptions

ContactFindOptions. Search options to filter

Constructors

constructor

+ new ContactFindOptions(filter?: undefined | string, multiple?: undefined | false | true, desiredFields?: string[], hasPhoneNumber?: undefined | false | true): ContactFindOptions

Parameters:

NameType
filter?undefined | string
multiple?undefined | false | true
desiredFields?string[]
hasPhoneNumber?undefined | false | true

Returns: ContactFindOptions

Properties

Optional desiredFields

desiredFields? : string[]

Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields.


Optional filter

filter? : undefined | string

The search string used to find navigator.contacts.


Optional hasPhoneNumber

hasPhoneNumber? : undefined | false | true

(Android only): Filters the search to only return contacts with a phone number informed.


Optional multiple

multiple? : undefined | false | true

Determines if the find operation returns multiple navigator.contacts. Defaults to false.

Contactname

Contact name.

Constructors

constructor

+ new ContactName(formatted?: undefined | string, familyName?: undefined | string, givenName?: undefined | string, middleName?: undefined | string, honorificPrefix?: undefined | string, honorificSuffix?: undefined | string): ContactName

Parameters:

NameType
formatted?undefined | string
familyName?undefined | string
givenName?undefined | string
middleName?undefined | string
honorificPrefix?undefined | string
honorificSuffix?undefined | string

Returns: ContactName

Properties

Optional familyName

familyName? : string | null

The contact's family name.


Optional formatted

formatted? : string | null

The complete name of the contact.


Optional givenName

givenName? : string | null

The contact's given name.


Optional honorificPrefix

honorificPrefix? : string | null

The contact's prefix (example Mr. or Dr.)


Optional honorificSuffix

honorificSuffix? : string | null

The contact's suffix (example Esq.).


Optional middleName

middleName? : string | null

The contact's middle name.

Contactorganization

Contact organization.

Constructors

constructor

+ new ContactOrganization(type?: undefined | string, name?: undefined | string, department?: undefined | string, title?: undefined | string, pref?: undefined | false | true): ContactOrganization

Parameters:

NameType
type?undefined | string
name?undefined | string
department?undefined | string
title?undefined | string
pref?undefined | false | true

Returns: ContactOrganization

Properties

Optional department

department? : string | null

The department the contract works for.


Optional id

id? : string | null

unique identifier, should only be set by native code


Optional name

name? : string | null

The name of the organization.


Optional pref

pref? : undefined | false | true

Set to true if this ContactOrganization contains the user's preferred value.


Optional title

title? : string | null

The contact's title at the organization.


Optional type

type? : string | null

A string that indicates what type of field this is, home for example.

Contacts

Access and manage Contacts on the device.

Methods

create

create(properties?: any): Contact

This function creates a new contact, but it does not persist the contact to device storage. To persist the contact to device storage, invoke contact.save().

Parameters:

NameTypeDescription
properties?anyan object whose properties will be examined to create a new Contact

Returns: Contact

new Contact object


find

find(fields: ContactFieldType[], options?: ContactFindOptions): Promise‹Contact[]›

Returns an array of Contacts matching the search criteria.

Parameters:

NameTypeDescription
fieldsContactFieldType[]that should be searched (see platform specific notes)
options?ContactFindOptionsthat can be applied to contact searching

Returns: Promise‹Contact[]›

a promise that resolves with the array of Contacts matching search criteria


newContactUI

newContactUI(): Promise‹string›

iOS only Create a contact using the iOS Contact Picker UI

returns: a promise that resolves with the id of the created contact as param to successCallback

Returns: Promise‹string›


pickContact

pickContact(): Promise‹Contact

This function picks contact from phone using contact picker UI

Returns: Promise‹Contact

a promise that resolves with the selected Contact object

Changelog

[1.1.2] (2020-06-10)

Bug Fixes

  • ios: Adding additional search predicates on iOS

[1.1.1] (2020-05-28)

Bug Fixes

  • ios: make wildcard return all contacts

[1.1.0] (2020-04-24)

Features

  • ios: enable wildcard fetch-all contacts

[1.0.6] (2020-02-07)

Bug Fixes

  • ios: make save work on existing contacts

[1.0.5] (2019-11-22)

Bug Fixes

  • prevent devideready block when package is not installed as plugin

[1.0.4] (2019-11-08)

Bug Fixes

  • ios: make pickContact prompt for permission if not granted

[1.0.3] (2019-11-04)

Bug Fixes

  • make plugin don't break web context

[1.0.2] (2019-10-02)

Bug Fixes

  • ios: remove contact notes code to work on iOS 13

1.0.1 (2019-09-20)

Bug Fixes

  • plugin files not included on published package