use-contact-picker

Let the user share contacts with the Contact Picker API.


Package	`@vizejs/composable/use-contact-picker`
Own the source	`vize lib pull composable:use-contact-picker`
Runtime exports	`useContactPicker`
Gzip budget	1536 B

Usage

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

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useContactPicker`	capability	experimental	deterministic-fallback	caller-managed	none	web, desktop	`window`	—

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.

Member	Type	Description
`addressLine`?	`readonly string[]`	Street address lines.
`city`?	`string`	City.
`region`?	`string`	Region or state.
`postalCode`?	`string`	Postal code.
`country`?	`string`	ISO 3166 country code.

`ContactInfo`

Every value the picker can return, keyed by property.

Member	Type	Description
`address`	`readonly ContactAddressLike[]`	Postal addresses.
`email`	`readonly string[]`	Email addresses.
`icon`	`readonly Blob[]`	Avatar images.
`name`	`readonly string[]`	Names.
`tel`	`readonly string[]`	Phone numbers.

`ContactsManagerLike`

Minimal navigator.contacts (ContactsManager).

Member	Type	Description
`getProperties`	`() => Promise<readonly string[]>`	Properties this platform supports.
`select`	`(properties: ContactProperty[], options?: { multiple?: boolean }) => Promise<readonly Partial<ContactInfo>[]>`	Open the picker (needs user activation).

`UseContactPickerOptions`

Options for useContactPicker.

Member	Type	Description
`contacts`?	`MaybeRefOrGetter<ContactsManagerLike \| null \| undefined>`	Contacts manager for alternate runtimes and tests.

`ContactSelectOptions`

Options of ContactPickerControls.select.

Member	Type	Description
`multiple`?	`boolean`	Allow picking several contacts.

`ContactPickerControls`

Reactive state and actions returned by useContactPicker.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Contact Picker API is available.
`pending`	`Readonly<Ref<boolean>>`	Whether the picker is open.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared on success.
`getProperties`	`() => Promise<ContactProperty[]>`	Properties the platform supports.
`select`	`<const Property extends ContactProperty>( properties: readonly Property[], options?: ContactSelectOptions, ) => Promise<ContactPickerResult<Property>>`	Open the contact picker.