useContactPicker

browser

Installation

npx usehooks-cli@latest add use-contact-picker

Description

A hook for accessing the Contact Picker API to select contacts with user permission. Allows web applications to access contact information from the user's device with explicit consent.

Return Type

UseContactPickerReturn

Property	Type	Description
contacts	Contact[]	Array of selected contacts
isLoading	boolean	Whether contact selection is in progress
error	string \| null	Error message if contact selection failed
isSupported	boolean	Whether the Contact Picker API is supported
availableProperties	ContactProperty[]	Array of available contact properties that can be requested
selectContacts	(properties: ContactProperty[], options?: UseContactPickerOptions) => Promise<Contact[]>	Select contacts with specified properties
getAvailableProperties	() => Promise<ContactProperty[]>	Get available contact properties that can be requested
clearContacts	() => void	Clear the selected contacts

Examples

Basic Contact Selection

Select contacts with name and email properties

import { useContactPicker } from '@usehooks/use-contact-picker';

function ContactSelector() {
  const {
    contacts,
    isLoading,
    error,
    isSupported,
    selectContacts,
    clearContacts
  } = useContactPicker();

  const handleSelectContacts = async () => {
    try {
      await selectContacts(['name', 'email']);
    } catch (err) {
      console.error('Failed to select contacts:', err);
    }
  };

  if (!isSupported) {
    return <div>Contact Picker API not supported</div>;
  }

  return (
    <div>
      <button onClick={handleSelectContacts} disabled={isLoading}>
        {isLoading ? 'Selecting...' : 'Select Contacts'}
      </button>
      
      <button onClick={clearContacts}>Clear</button>
      
      {error && <p>Error: {error}</p>}
      
      {contacts.length > 0 && (
        <div>
          <h3>Selected Contacts:</h3>
          {contacts.map((contact, index) => (
            <div key={index}>
              <p>Name: {contact.name?.[0] || 'N/A'}</p>
              <p>Email: {contact.email?.[0] || 'N/A'}</p>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Multiple Contact Selection

Select multiple contacts with various properties

import { useContactPicker } from '@usehooks/use-contact-picker';

function MultiContactSelector() {
  const {
    contacts,
    isLoading,
    selectContacts,
    getAvailableProperties,
    availableProperties
  } = useContactPicker();

  const handleSelectMultiple = async () => {
    await selectContacts(['name', 'email', 'tel'], { multiple: true });
  };

  const handleGetProperties = async () => {
    await getAvailableProperties();
  };

  return (
    <div>
      <button onClick={handleGetProperties}>
        Get Available Properties
      </button>
      
      <button onClick={handleSelectMultiple} disabled={isLoading}>
        Select Multiple Contacts
      </button>
      
      {availableProperties.length > 0 && (
        <div>
          <h3>Available Properties:</h3>
          <ul>
            {availableProperties.map(prop => (
              <li key={prop}>{prop}</li>
            ))}
          </ul>
        </div>
      )}
      
      {contacts.length > 0 && (
        <div>
          <h3>Selected Contacts ({contacts.length}):</h3>
          {contacts.map((contact, index) => (
            <div key={index} style={{ border: '1px solid #ccc', padding: '10px', margin: '5px' }}>
              <p><strong>Name:</strong> {contact.name?.join(', ') || 'N/A'}</p>
              <p><strong>Email:</strong> {contact.email?.join(', ') || 'N/A'}</p>
              <p><strong>Phone:</strong> {contact.tel?.join(', ') || 'N/A'}</p>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Contact with Address

Select contacts including address information

import { useContactPicker } from '@usehooks/use-contact-picker';

function AddressContactSelector() {
  const { contacts, selectContacts, isLoading } = useContactPicker();

  const handleSelectWithAddress = async () => {
    await selectContacts(['name', 'email', 'tel', 'address']);
  };

  return (
    <div>
      <button onClick={handleSelectWithAddress} disabled={isLoading}>
        Select Contact with Address
      </button>
      
      {contacts.map((contact, index) => (
        <div key={index} style={{ border: '1px solid #ddd', padding: '15px', margin: '10px' }}>
          <h4>{contact.name?.[0] || 'Unknown Contact'}</h4>
          
          {contact.email && (
            <p><strong>Email:</strong> {contact.email.join(', ')}</p>
          )}
          
          {contact.tel && (
            <p><strong>Phone:</strong> {contact.tel.join(', ')}</p>
          )}
          
          {contact.address && contact.address.length > 0 && (
            <div>
              <strong>Address:</strong>
              {contact.address.map((addr, addrIndex) => (
                <div key={addrIndex} style={{ marginLeft: '10px' }}>
                  {addr.addressLine && <p>{addr.addressLine.join(', ')}</p>}
                  {addr.city && <p>{addr.city}, {addr.region} {addr.postalCode}</p>}
                  {addr.country && <p>{addr.country}</p>}
                </div>
              ))}
            </div>
          )}
        </div>
      ))}
    </div>
  );
}

Dependencies

react

Notes

•Only available in browsers that support the Contact Picker API (Chrome 80+, Edge 80+)
•Requires user gesture to initiate contact selection
•Requires HTTPS in production environments
•Available properties vary by platform and browser
•User has full control over which contacts and properties to share
•Contact data is not persisted and must be requested each time

Implementation

'use client';

import { useState, useCallback } from "react";

type ContactProperty = "name" | "email" | "tel" | "address" | "icon";

interface ContactAddress {
  country?: string;
  addressLine?: string[];
  region?: string;
  city?: string;
  dependentLocality?: string;
  postalCode?: string;
  sortingCode?: string;
}

interface Contact {
  name?: string[];
  email?: string[];
  tel?: string[];
  address?: ContactAddress[];
  icon?: Blob[];
}

interface UseContactPickerOptions {
  multiple?: boolean;
}

interface UseContactPickerReturn {
  contacts: Contact[];
  isLoading: boolean;
  error: string | null;
  isSupported: boolean;
  availableProperties: ContactProperty[];
  selectContacts: (
    properties: ContactProperty[],
    options?: UseContactPickerOptions
  ) => Promise<Contact[]>;
  getAvailableProperties: () => Promise<ContactProperty[]>;
  clearContacts: () => void;
}

// Extend Navigator interface for TypeScript
declare global {
  interface Navigator {
    contacts?: {
      select: (
        properties: ContactProperty[],
        options?: { multiple?: boolean }
      ) => Promise<Contact[]>;
      getProperties: () => Promise<ContactProperty[]>;
    };
  }
}

export const useContactPicker = (): UseContactPickerReturn => {
  const [contacts, setContacts] = useState<Contact[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [availableProperties, setAvailableProperties] = useState<
    ContactProperty[]
  >([]);

  // Check if Contact Picker API is supported
  const isSupported =
    typeof navigator !== "undefined" &&
    "contacts" in navigator &&
    typeof navigator.contacts?.select === "function";

  // Get available contact properties
  const getAvailableProperties = useCallback(async (): Promise<
    ContactProperty[]
  > => {
    if (!isSupported || !navigator.contacts?.getProperties) {
      setError("Contact Picker API is not supported");
      return [];
    }

    try {
      setError(null);
      const properties = await navigator.contacts.getProperties();
      setAvailableProperties(properties);
      return properties;
    } catch (err) {
      const errorMessage =
        err instanceof Error
          ? err.message
          : "Failed to get available properties";
      setError(errorMessage);
      return [];
    }
  }, [isSupported]);

  // Select contacts with specified properties
  const selectContacts = useCallback(
    async (
      properties: ContactProperty[],
      options: UseContactPickerOptions = {}
    ): Promise<Contact[]> => {
      if (!isSupported || !navigator.contacts?.select) {
        setError("Contact Picker API is not supported");
        return [];
      }

      if (properties.length === 0) {
        setError("At least one contact property must be specified");
        return [];
      }

      try {
        setIsLoading(true);
        setError(null);

        const selectedContacts = await navigator.contacts.select(properties, {
          multiple: options.multiple || false,
        });

        setContacts(selectedContacts);
        return selectedContacts;
      } catch (err) {
        let errorMessage = "Failed to select contacts";

        if (err instanceof Error) {
          // Handle specific error cases
          if (err.name === "InvalidStateError") {
            errorMessage = "Contact picker is already open";
          } else if (err.name === "SecurityError") {
            errorMessage =
              "Contact picker requires user gesture and secure context";
          } else if (err.name === "NotSupportedError") {
            errorMessage = "One or more requested properties are not supported";
          } else {
            errorMessage = err.message;
          }
        }

        setError(errorMessage);
        return [];
      } finally {
        setIsLoading(false);
      }
    },
    [isSupported]
  );

  // Clear selected contacts
  const clearContacts = useCallback(() => {
    setContacts([]);
    setError(null);
  }, []);

  return {
    contacts,
    isLoading,
    error,
    isSupported,
    availableProperties,
    selectContacts,
    getAvailableProperties,
    clearContacts,
  };
};

useClipboard

CLI Docs All Hooks

useStorage