Getting Started

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/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:

bun add @capgo/capacitor-contacts
bunx cap sync

Import

import { CapacitorContacts } from '@capgo/capacitor-contacts';

API Overview

countContacts

Count the total number of contacts on the device.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.countContacts();
console.log(result);

createContact

Create a new contact programmatically.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.createContact({ contact: {} });
console.log(result);

createGroup

Create a new contact group.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.createGroup({ group: { name: 'example' } });
console.log(result);

deleteContactById

Delete a contact by ID.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.deleteContactById({ id: 'id-123' });

deleteGroupById

Delete a group by ID.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.deleteGroupById({ id: 'id-123' });

displayContactById

Display a contact using the native contact viewer.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.displayContactById({ id: 'id-123' });

displayCreateContact

Display the native create contact UI.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.displayCreateContact();
console.log(result);

displayUpdateContactById

Display the native update contact UI for a specific contact.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.displayUpdateContactById({ id: 'id-123' });

getAccounts

Get all accounts available on the device.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getAccounts();
console.log(result);

getContactById

Get a specific contact by ID.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getContactById({ id: 'id-123' });
// The result holds sensitive values: use it without logging it.

getContacts

Get all contacts from the device.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getContacts();
// The result holds sensitive values: use it without logging it.

getGroupById

Get a specific group by ID.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getGroupById({ id: 'id-123' });
console.log(result);

getGroups

Get all contact groups.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getGroups();
console.log(result);

isAvailable

Check if contacts are available on the device.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.isAvailable();
console.log(result);

isSupported

Check if the plugin is supported on the current platform.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.isSupported();
console.log(result);

openSettings

Open the device’s contacts settings.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.openSettings();

pickContact

Pick a single contact using the native contact picker.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.pickContact();
// The result holds sensitive values: use it without logging it.

pickContacts

Pick one or more contacts using the native contact picker.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.pickContacts();
// The result holds sensitive values: use it without logging it.

updateContactById

Update an existing contact by ID.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.updateContactById({
  id: 'id-123',
  contact: {},
});

checkPermissions

Check the current permission status for contacts.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.checkPermissions();
console.log(result);

requestPermissions

Request permissions to access contacts.

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.requestPermissions();
console.log(result);

Type Reference

CountContactsResult

Result from counting contacts.

export interface CountContactsResult {
  /**
   * Total number of contacts.
   *
   * @since 1.0.0
   */
  count: number;
}

CreateContactOptions

Options for creating a contact.

export interface CreateContactOptions {
  /**
   * Contact information to create. The 'id' field will be generated automatically.
   *
   * @since 1.0.0
   */
  contact: Omit<Contact, 'id'>;
}

CreateContactResult

Result from creating a contact.

export interface CreateContactResult {
  /**
   * The ID of the newly created contact.
   *
   * @since 1.0.0
   */
  id: string;
}

CreateGroupOptions

Options for creating a group.

export interface CreateGroupOptions {
  /**
   * Group information to create. The 'id' field will be generated automatically.
   *
   * @since 1.0.0
   */
  group: Omit<Group, 'id'>;
}

CreateGroupResult

Result from creating a group.

export interface CreateGroupResult {
  /**
   * The ID of the newly created group.
   *
   * @since 1.0.0
   */
  id: string;
}

DeleteContactByIdOptions

Options for deleting a contact by ID.

export interface DeleteContactByIdOptions {
  /**
   * The ID of the contact to delete.
   *
   * @since 1.0.0
   */
  id: string;
}

DeleteGroupByIdOptions

Options for deleting a group by ID.

export interface DeleteGroupByIdOptions {
  /**
   * The ID of the group to delete.
   *
   * @since 1.0.0
   */
  id: string;
}

DisplayContactByIdOptions

Options for displaying a contact by ID.

export interface DisplayContactByIdOptions {
  /**
   * The ID of the contact to display.
   *
   * @since 1.0.0
   */
  id: string;
}

DisplayCreateContactOptions

Options for displaying the native create contact UI.

export interface DisplayCreateContactOptions {
  /**
   * Optional pre-filled contact information for the create UI.
   *
   * @since 1.0.0
   */
  contact?: Omit<Contact, 'id'>;
}

DisplayCreateContactResult

Result from displaying the native create contact UI.

export interface DisplayCreateContactResult {
  /**
   * The ID of the created contact, if one was created. Undefined if the user cancelled.
   *
   * @since 1.0.0
   */
  id?: string;
}

DisplayUpdateContactByIdOptions

Options for displaying the native update contact UI.

export interface DisplayUpdateContactByIdOptions {
  /**
   * The ID of the contact to update.
   *
   * @since 1.0.0
   */
  id: string;
}

GetAccountsResult

Result from getting accounts.

export interface GetAccountsResult {
  /**
   * List of accounts available on the device.
   *
   * @since 1.0.0
   */
  accounts: Account[];
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-contacts for the native capability in Using @capgo/capacitor-contacts, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.