Contact Picker API

What Is the Contact Picker API?

The Contact Picker API is a web platform feature that allows users to selectively share contact information from their device's address book with websites. Unlike native applications that often request broad access to contacts, this API follows a privacy-by-design approach where users see a familiar contact picker interface, choose which specific contacts to share, and control exactly which data fields are included in the response.

Core Design Principles

The API was designed around three fundamental principles that guide its implementation across all browsers. First, user control means the API can only be invoked through an explicit user gesture (such as clicking a button) in a secure context, preventing websites from displaying the picker arbitrarily or accessing contacts without user awareness. Second, transparency ensures the picker always displays which data fields the website is requesting, and users can deselect specific fields even if the website requests them. Third, data minimization means the API only returns information for selected contacts--websites never receive data about contacts the user chose not to share.

These principles make the Contact Picker API a trusted choice for web applications that need contact access while respecting user privacy. The design reflects modern expectations for privacy-first web development.

Supported Contact Properties

The Contact Picker API currently supports five contact properties that websites can request. The name property returns the contact's full name as stored in the device's address book. The email property provides email addresses associated with the contact. The tel property returns telephone numbers. The address property, available in newer browser versions, provides physical postal addresses. Finally, the icon property returns the contact's photo or avatar if one exists.

Not all properties are available in all browser versions--Chrome 84 or later introduced the address and icon properties, while name, email, and tel have broader support across all compatible browsers.

Implementation Guide

Feature Detection

Before using the Contact Picker API, applications should verify that the feature is available in the current browser. The API is only available in secure contexts (HTTPS) and requires the browser to support the feature. Feature detection is straightforward and should be performed before any API calls to ensure graceful fallbacks for unsupported browsers.

// Check if the Contact Picker API is supported
const supported = "contacts" in navigator && "ContactsManager" in window;

if (supported) {
 // Contact Picker API is available
 console.log("Contact Picker API is supported");
} else {
 // Fallback to alternative approaches
 console.log("Contact Picker API is not available");
}

This detection pattern is essential because browser support varies significantly across platforms. Implementing proper feature detection is a fundamental practice in modern JavaScript development.

Detecting Available Properties

Not all browsers and devices support every contact property. The getProperties() method returns an array of supported properties, allowing applications to dynamically adjust their requests based on actual capabilities. This helps avoid requesting properties that aren't available, improving the user experience by preventing unnecessary prompts and potential errors.

async function getAvailableProperties() {
 const supportedProperties = await navigator.contacts.getProperties();

 console.log("Supported properties:", supportedProperties);
 // Example output: ['name', 'email', 'tel', 'address', 'icon']

 return supportedProperties;
}

Opening the Contact Picker

The primary entry point is the select() method, which displays the contact picker and returns selected contact information. The method accepts an array of desired properties and optional configuration options. This method can only be called in response to a user gesture (like a button click), which prevents websites from accessing contacts without explicit user action.

async function selectContacts() {
 // Define which contact properties you need
 const properties = ["name", "email", "tel", "address", "icon"];

 // Configure selection options
 const options = { multiple: true }; // Allow selecting multiple contacts

 try {
 // Display the contact picker
 const contacts = await navigator.contacts.select(properties, options);

 // Process the selected contacts
 console.log("Selected contacts:", contacts);
 handleContactSelection(contacts);

 } catch (error) {
 // Handle errors (user cancelled, security restrictions, etc.)
 console.error("Contact selection failed:", error);
 }
}

function handleContactSelection(contacts) {
 contacts.forEach(contact => {
 console.log("Contact name:", contact.name);
 console.log("Email addresses:", contact.email);
 console.log("Phone numbers:", contact.tel);
 console.log("Addresses:", contact.address);
 console.log("Photo:", contact.icon);
 });
}

Understanding the Response Format

The API returns an array of contact objects, each containing the requested properties as arrays. If a contact doesn't have data for a requested property, that property's array will be empty. Note that each property value is an array because contacts can have multiple values of the same type (multiple phone numbers, multiple email addresses, etc.).

// Example response when requesting name, email, and tel for one contact
[
 {
 name: ["John Doe"],
 email: ["[email protected]"],
 tel: ["+1-555-123-4567", "+1-555-987-6543"],
 address: [],
 icon: ["/path/to/photo.jpg"]
 }
]

Your application should handle empty arrays gracefully without displaying errors to users, as users might select contacts that don't have data for all requested properties or deselect certain data types. When building web APIs that interact with user data, handling these edge cases gracefully is essential for creating robust, user-friendly applications.

Security and Privacy

Privacy-First Design Philosophy

The Contact Picker API was designed from the ground up with privacy as a core principle, not an afterthought. Unlike native applications that often request blanket access to the entire address book, this API provides granular, on-demand access that puts users firmly in control of what information is shared. The fundamental privacy protections include several key mechanisms that make this API a trusted solution for modern web applications.

The fundamental privacy protections include several key mechanisms. First, access requires a secure context (HTTPS), ensuring the API cannot be used on insecure websites. Second, the picker can only be triggered by an explicit user gesture, preventing automated or hidden access to contact information. Third, users see exactly what data fields the website is requesting before making their selection. Fourth, users can deselect individual data types even if the website requests them. Fifth, websites only receive data for contacts the user explicitly selects.

User Control Model

The contact picker interface provides users with complete control over the sharing process. Users see the website's requested properties at the top of the picker and can toggle each property on or off independently. This means even if a website requests email addresses, users can deselect that field and prevent the email from being shared.

Additionally, users select individual contacts manually--there is no "select all" option. This prevents accidental bulk sharing and encourages users to consider each contact individually. The picker also shows which contacts will share their information, with each contact displaying the data that will be included.

Transparency Features

Every interaction with the Contact Picker API maintains transparency about what data is being shared. The picker displays the website's name and icon, the specific data fields being requested, and the actual contact information that will be shared for each selected contact. Users can review all this information before confirming the selection. After selection, the website receives only the approved data for chosen contacts--no additional information about unselected contacts or the user's address book structure is revealed.

Security Restrictions

Several security restrictions govern the Contact Picker API. The API is only available in secure contexts (HTTPS), preventing use on insecure websites. It requires a user gesture to activate, so websites cannot display the picker programmatically or on page load. The API does not persist permissions--users must explicitly select contacts each time. Finally, no access to contacts is available in Web Workers or background contexts.

These restrictions align with our approach to security-first web development practices, ensuring that contact access is always explicit, transparent, and controlled by the user. Understanding these principles is essential for building secure, privacy-conscious applications that users can trust.

Browser Compatibility

Current Support Status

The Contact Picker API has limited but growing browser support. As of 2025, the API is available primarily in Chromium-based browsers on Android devices, including Chrome, Edge, and Opera for Android. Support on desktop browsers and other platforms remains limited. The API requires Android M (6.0) or later on mobile devices, and the browser must support the feature.

iOS Safari and Firefox do not currently support the Contact Picker API, though this may change as the specification matures. When building applications that rely on this API, always implement graceful fallbacks for browsers that don't support it.

Feature Support Variations

Not all properties are available in all browser versions. The name, email, and tel properties have the broadest support across all compatible browsers, while address and icon properties require Chrome 84 or later. Applications should use getProperties() to determine which properties are available before requesting data, ensuring a smooth experience across different browser versions.

Fallback Strategies

For browsers that don't support the Contact Picker API, applications should implement graceful fallbacks. Common approaches include manual contact entry forms, integrating with platform-specific contact APIs through native wrappers, or guiding users to native applications for contact selection.

async function getContactsWithFallback() {
 // Check for API support
 if ("contacts" in navigator) {
 try {
 const contacts = await navigator.contacts.select(
 ["name", "email", "tel"],
 { multiple: true }
 );
 return contacts;
 } catch (error) {
 console.log("Contact picker cancelled or failed");
 return null;
 }
 }

 // Fallback: Use manual entry form
 return await showManualContactEntry();
}

Implementing proper fallback strategies is essential for delivering a consistent user experience regardless of browser capabilities. This approach aligns with our commitment to progressive enhancement in modern web development. When working with browser APIs that have varying support, always plan for graceful degradation as part of your cross-browser testing strategy.

Best Practices

Request Only Necessary Properties

Only request the contact properties your application actually needs. Requesting unnecessary properties reduces user trust and increases the likelihood that users will deny access to certain fields. For example, if your application only needs phone numbers, don't request email addresses or physical addresses. This principle of data minimization is fundamental to maintaining user confidence.

Handle Empty Responses Gracefully

Users might select contacts that don't have data for all requested properties, or they might deselect certain data types. Your application should handle empty arrays for properties gracefully without displaying errors to users. The response format means that each property returns an array, which may be empty for contacts without that type of data.

Provide Clear User Guidance

Before triggering the contact picker, explain to users why you're requesting contact access and what you'll do with the information. This transparency increases user trust and improves the likelihood of successful contact selection. A simple explanation like "We need to access your contacts to help you select recipients for your message" can make a significant difference in user acceptance.

Implement Proper Error Handling

The select() method can throw errors in several scenarios: user cancellation, secure context violations, unsupported properties, or browser restrictions. Wrap API calls in try-catch blocks and provide helpful feedback to users when operations fail. Common error messages should guide users on next steps rather than displaying technical details.

Consider Performance Implications

Contact data can be substantial, especially when including photos (icons). Consider implementing lazy loading for contact images, caching selected contacts to avoid repeated picker invocations, and processing contact data asynchronously to prevent blocking the main thread. These performance optimizations become particularly important when dealing with contacts that include profile images.

Respect User Privacy

Never store contact information without user consent, don't share contact data with third parties, provide clear privacy policies explaining how contact data is used, and allow users to delete previously shared contact information. Respecting user privacy builds trust and encourages continued use of your contact-related features. This commitment to privacy is a cornerstone of ethical web development. When implementing features that access user data, following established data protection guidelines ensures your applications remain trustworthy and compliant.

Conclusion

The Contact Picker API represents a significant advancement in bringing native-like functionality to web applications while maintaining strong privacy protections. By enabling users to selectively share contact information with granular control, the API creates opportunities for innovative contact-related features without compromising user privacy. This balance of functionality and privacy makes it an essential tool for modern web applications that need contact access.

As browser support continues to expand, the Contact Picker API will become increasingly valuable for web applications that need contact access. The W3C-standardized approach ensures interoperability across browsers that implement the API, while the privacy-first design philosophy aligns with growing user expectations for data control and transparency.

Developers should implement the API following best practices--requesting only necessary properties, providing clear user guidance, and respecting user privacy--to build trust and create positive user experiences. The key to successful implementation lies in understanding the privacy-first design philosophy and aligning your application's contact features with user expectations for control and transparency.

When implementing contact-related features in your web applications, consider partnering with experienced developers who understand both the technical implementation and the privacy implications. Our web development team specializes in building modern web applications that leverage cutting-edge APIs while maintaining the highest standards of user privacy and security. From JavaScript API integration to comprehensive security implementation, we can help you build robust, privacy-conscious applications that users trust.

Sources

1. MDN Web Docs: Contact Picker API - Comprehensive API documentation covering interfaces, methods, and browser compatibility
2. Chrome for Developers: Contact Picker - Official Google Chrome documentation with implementation guidance and security considerations
3. W3C Contact Picker Specification - The authoritative technical specification defining the standard