use-contact-picker

Let the user share contacts with the Contact Picker API.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useContactPicker } from "@vizejs/composable/use-contact-picker";

Try it

Invite people from contacts

Let the reader pick contacts from the device instead of typing addresses.

Open the interactive example

What to observe: On Android Chrome, Pick contacts opens the contact list. Elsewhere the example asks the reader to type addresses.

Request only the properties you need; getProperties() lists those the device supports. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useContactPicker } from "@vizejs/composable/use-contact-picker";
import { useMounted } from "@vizejs/composable/use-mounted";

const mounted = useMounted();
const { supported, select } = useContactPicker();
const invited = ref<string[]>([]);

async function invite() {
  const result = await select(["name", "email"], { multiple: true });
  if (result.status !== "selected") return;
  invited.value = result.contacts.map(
    (contact) => contact.name?.[0] ?? contact.email?.[0] ?? "Unknown",
  );
}
</script>

<template>
  <div class="composable-example">
    <p>Invite people from the device's contacts instead of typing their addresses.</p>
    <button type="button" :disabled="!mounted || !supported" @click="invite">Pick contacts</button>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "The Contact Picker is not available; type the addresses instead."
          : invited.length
            ? `Inviting ${invited.join(", ")}`
            : "Ready to pick contacts."
    }}</output>
  </div>
</template>

Runtime contract

API

useContactPicker

Let the user share contacts with the Contact Picker API. select(["name", "email"]) resolves to contacts typed with exactly those keys (missing values become empty arrays). Dismissing the picker resolves with an empty list. The composable holds no resources, so nothing needs cleanup. Server rendering: nothing is requested, supported and pending are false. Inside a component supported turns true only after mounting, so hydration renders this server state first.

function useContactPicker(options: UseContactPickerOptions = {}): ContactPickerControls

const picker = useContactPicker();
const result = await picker.select(["name", "tel"], { multiple: true });

Types

ContactAddressLike

Postal address returned for the address property.

ContactInfo

Every value the picker can return, keyed by property.

ContactsManagerLike

Minimal navigator.contacts (ContactsManager).

UseContactPickerOptions

Options for useContactPicker.

ContactSelectOptions

Options of ContactPickerControls.select.

ContactPickerControls

Reactive state and actions returned by useContactPicker.