JavaScript Navigator contacts Property

What You’ll Learn

navigator.contacts returns a ContactsManager — the Contact Picker API entry point. Learn feature detection, getProperties(), select(), secure context rules, five examples, and try-it labs.

Introduction

Forms that ask for a friend’s name, email, or phone number are tedious to fill by hand. The Contact Picker API lets the user choose contacts from their device list and share only the fields you request.

Your entry point is navigator.contacts. It is read-only and returns a ContactsManager object. MDN notes that two successive accesses return the same object instance.

Understanding the contacts Property

Think of navigator.contacts as a handle to the Contact Picker for this page. You do not assign to it — you call methods on the ContactsManager it returns.

• getProperties() — Promise of supported field names (name, email, tel, address, icon).
• select(properties, options) — opens the picker; resolves to an array of selected contacts.
• options.multiple — set true to allow selecting more than one contact.
• Call select() from a user gesture (button click) on a secure page.

📝 Syntax

General form of the property:

navigator.contacts

Value

• A ContactsManager object used to open the contact picker and query supported properties.

Common patterns

// MDN-style feature detect:
const supported = "contacts" in navigator && "ContactsManager" in window;

// Supported fields:
const props = await navigator.contacts.getProperties();

// Open picker from a click handler:
const contacts = await navigator.contacts.select(
  ["name", "email", "tel"],
  { multiple: true }
);

Examples Gallery

Examples follow MDN Contact Picker / navigator.contacts patterns. Prefer Try It Yourself on a supporting mobile browser. Use View Output for expected messaging.

const supported = "contacts" in navigator && "ContactsManager" in window;
console.log(supported ? "contacts available" : "contacts missing");

contacts missing
(or "contacts available" on a supporting browser)

const lines = [
  "isSecureContext: " + window.isSecureContext,
  "contacts: " + (("contacts" in navigator) ? "present" : "absent")
];
console.log(lines.join("\n"));

isSecureContext: true
contacts: absent
(on many desktop browsers)

async function listContactProps() {
  if (!("contacts" in navigator)) {
    return "contacts unavailable";
  }
  const props = await navigator.contacts.getProperties();
  return props.join(", ") || "(empty list)";
}

listContactProps().then((msg) => console.log(msg));

contacts unavailable
(or e.g. "name, email, tel, address, icon")

async function pickOneContact() {
  if (!("contacts" in navigator)) {
    return "contacts unavailable";
  }
  try {
    const results = await navigator.contacts.select(
      ["name", "email", "tel"],
      { multiple: false }
    );
    return JSON.stringify(results, null, 2);
  } catch (err) {
    return "select failed: " + err.name;
  }
}

// Call from a button click in Try It

contacts unavailable
(or a JSON array of selected contact fields after Pick)

async function pickContacts() {
  if (!window.isSecureContext) {
    return { ok: false, reason: "insecure-context" };
  }
  if (!("contacts" in navigator)) {
    return { ok: false, reason: "unsupported" };
  }
  try {
    const available = await navigator.contacts.getProperties();
    const want = ["name", "email", "tel"].filter((p) => available.includes(p));
    if (!want.length) {
      return { ok: false, reason: "no-properties" };
    }
    const contacts = await navigator.contacts.select(want, { multiple: true });
    return { ok: true, count: contacts.length, contacts };
  } catch (err) {
    return { ok: false, reason: err.name };
  }
}

// Call from a button click in Try It

{"ok":false,"reason":"unsupported"}
(or ok:true with contacts on a supporting device)

🚀 Common Use Cases

• Invite friends — pick emails or phone numbers for share / invite flows.
• Checkout / shipping — fill a recipient name and address from contacts (where supported).
• Messaging apps — start a chat by selecting a phone number.
• Event RSVPs — add guests without retyping contact details.
• Progressive enhancement — show “Pick contact” only when the API exists.

📝 Notes

• Experimental and not Baseline — support is limited.
• Secure context required (HTTPS / localhost).
• Not Deprecated or Non-standard on MDN — it is a specified Contact Picker API feature with limited adoption.
• select() needs a user gesture; access is on-demand (not a permanent permission dump of the address book).
• Related: cookieEnabled, Window, JavaScript hub.

💡 Best Practices