Contacts

Search, pick, create, and edit address book contacts

One.Contacts reads and writes the system address book: search by name, let the user pick one contact, or create, update, and delete entries. The picker exposes only the chosen contact and needs no address book permission, so prefer it for one-shot flows like inviting a friend; use search and writes when your app manages contacts itself.

On iOS it uses CNContactStore from the Contacts framework and CNContactPickerViewController from ContactsUI. On Android it queries ContactsContract through the content resolver. On web the address book stays closed, but browsers with the Contact Picker API can still pick one contact from a user gesture.

Usage

import { One } from 'one'

const permission = await One.Contacts.requestPermission()
if (permission === 'authorized' || permission === 'limited') {
  const matches = await One.Contacts.search('Ada', 20)
  console.log(matches.map((contact) => `${contact.givenName} ${contact.familyName}`))
}

Search needs address book permission; the grant can be full or, on iOS, limited to the contacts the user shared. Results carry names, phone numbers, emails, and postal addresses.

How it works

Set native.app.contacts.usage before prebuild. It becomes NSContactsUsageDescription on iOS and stamps READ_CONTACTS plus WRITE_CONTACTS into the Android manifest. Without it, permission and read calls reject with E_CONTACTS_MANIFEST. The status is not determined, restricted, denied, authorized, or limited; Android has no limited tier. Search and writes run off the UI thread: a background queue on iOS, a single worker thread on Android.

search takes a nonempty name and a whole-number limit from 1 to 100 (default 100) and returns matches with an identifier, given and family names, phone and email string arrays, and structured postal addresses. create saves a new contact and returns its identifier. update edits any combination of fields and returns the updated contact; omitted fields keep their values, while supplied phone, email, and address arrays replace their whole field, so an empty array clears one. Blank phone and email entries are rejected, and a contact must keep at least one given or family name when either name changes. delete removes a contact the app may change. Ask the user before changing their contacts. Contact notes need an Apple-granted entitlement and are not exposed.

pickContact presents the system picker from the visible screen and resolves with the chosen contact in the search shape, or undefined on cancel. It never asks for address book permission. Only one picker runs at a time; a second call, or a missing presentation surface, rejects with E_CONTACTS_PICKER. On web the browser picker returns the display name as givenName with an empty family name and identifier, since the browser exposes neither separate name fields nor a stable id, and phone, email, and address fields are requested only when supported. Browsers without the picker API keep the native-build rejection, and search, create, update, and delete keep their unavailable contracts everywhere off native: denied status, empty searches, and rejections for calls that return a contact, while deletion silently resolves.

API reference

Platform differences

Limits and gotchas

• Supplied arrays replace the whole field. Update merges nothing: pass the full phone, email, or address list you want, or an empty array to clear one.
• A contact must keep a name. Changing the names to leave both blank rejects. Clear other fields instead of anonymizing the entry.
• Addresses need one nonblank part. An input with every part blank rejects with E_CONTACTS_INPUT.
• The picker resolves undefined on cancel. Treat a missing contact as a closed picker, not an error.
• One picker at a time. A second pickContact while one is open rejects with E_CONTACTS_PICKER.
• Limited access hides the rest of the book. On iOS a limited grant returns only shared contacts from search; writes still apply to what the app may change.

Examples

import { useState } from 'react'
import { Button, Text } from 'react-native'
import { One } from 'one'

function InviteButton({ invite }: { invite: (phone: string) => void }) {
  const [name, setName] = useState('')

  async function pick() {
    const contact = await One.Contacts.pickContact()
    const phone = contact?.phoneNumbers[0]
    if (!contact || !phone) return
    setName(`${contact.givenName} ${contact.familyName}`.trim())
    invite(phone)
  }

  return (
    <>
      <Button title="Invite a contact" onPress={pick} />
      {name ? <Text>Inviting {name}</Text> : null}
    </>
  )
}

The picker needs no permission prompt, so inviting stays a one-tap flow. A cancel or a contact without a number returns quietly to the idle state.

import { One } from 'one'

async function fixSpelling(query: string, givenName: string) {
  const permission = await One.Contacts.requestPermission()
  if (permission !== 'authorized' && permission !== 'limited') return
  const [match] = await One.Contacts.search(query, 5)
  if (!match) return
  const updated = await One.Contacts.update(match.identifier, { givenName })
  console.log('Renamed to', updated.givenName, updated.familyName)
}

Only the changed field is passed; every omitted field keeps its value. The returned contact confirms the new state without a second search.

import { One } from 'one'

async function saveFriend() {
  const identifier = await One.Contacts.create({
    givenName: 'Ada',
    familyName: 'Lovelace',
    phoneNumbers: ['+1 555-0100'],
    emailAddresses: [],
    postalAddresses: [
      {
        label: 'home',
        street: '12 Analytical Way',
        city: 'London',
        postalCode: 'E1 6AN',
        country: 'United Kingdom',
        isoCountryCode: 'GB',
      },
    ],
  })
  console.log('Saved contact', identifier)
}

Phone and email arrays are required even when empty; addresses stay optional. The resolved identifier is the handle for later updates.