@capgo/capacitor-contacts 8.0.18 → 8.1.0

package/README.md

@@ -45,6 +45,48 @@ npm install @capgo/capacitor-contacts
 npx cap sync
 ```
 
+## Android
+
+Google Play's Contacts Permissions policy (effective 27 January 2027) allows `READ_CONTACTS` only when the Android Contact Picker cannot cover your core feature, for apps that target Android 17 (API 37) or later.
+
+This plugin does **not** declare `READ_CONTACTS` or `WRITE_CONTACTS`. Add them in your app manifest only if you need them.
+
+**Pick a phone, email, or address without `READ_CONTACTS`:**
+
+```typescript
+import { CapacitorContacts, ContactProperty } from '@capgo/capacitor-contacts';
+
+const { contacts } = await CapacitorContacts.pickContacts({
+  property: ContactProperty.PhoneNumber,
+});
+
+const number = contacts[0]?.phoneNumbers?.[0]?.value;
+```
+
+`property` works on every Android version. The picker returns a data-row URI the plugin can read without a permission. The result contains `id`, `displayName`, and the selected property only.
+
+Use `ContactProperty.EmailAddress` or `ContactProperty.PostalAddress` the same way.
+
+**When you still need `READ_CONTACTS`:**
+
+- `getContacts()`, `getContactById()`, `countContacts()`, `getGroups()`, `getAccounts()`
+- Picking a full contact without `property` on Android 16 and below
+- Syncing, backing up, or matching the whole address book
+
+If those are core features, add the permission and file the Play Console declaration before pre-review checks start on 27 October 2026:
+
+```xml
+<uses-permission android:name="android.permission.READ_CONTACTS" />
+```
+
+`WRITE_CONTACTS` is unchanged by this policy. Add it only if you create or update contacts in code.
+
+On Android 17 and later, picking a full contact without `property` also works without `READ_CONTACTS` because the system picker returns a session URI. Keep using `property` if you still support older Android versions and want the permission out of the manifest entirely.
+
+## iOS
+
+`pickContact()` / `pickContacts()` never require a contacts permission. Add `NSContactsUsageDescription` only if you call methods that read or write the address book (`getContacts`, `createContact`, and similar).
+
 ## API
 
 <docgen-index>
@@ -73,6 +115,7 @@ npx cap sync
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
+* [Enums](#enums)
 
 </docgen-index>
 
@@ -359,6 +402,9 @@ pickContact(options?: PickContactsOptions | undefined) => Promise<PickContactRes
 
 <a href="#pick">Pick</a> a single contact using the native contact picker.
 
+Same options as {@link pickContacts}. Pass `property` to select one phone
+number, email address, or postal address without `READ_CONTACTS` on Android.
+
 | Param         | Type                                                                | Description                                            |
 | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
 | **`options`** | <code><a href="#pickcontactsoptions">PickContactsOptions</a></code> | - Optional fields to retrieve and picker configuration |
@@ -378,6 +424,18 @@ pickContacts(options?: PickContactsOptions | undefined) => Promise<PickContactsR
 
 <a href="#pick">Pick</a> one or more contacts using the native contact picker.
 
+On iOS this never requires a contacts permission.
+
+On Android, pass `property` to select a single phone number, email address,
+or postal address with no `READ_CONTACTS` permission. That works on every
+Android version and is the way to ship without declaring the permission
+when targeting Android 17 (API 37) or later.
+
+Picking a full contact without `property` still needs `READ_CONTACTS` below
+Android 17, because the picker URI exposes no phone, email, or structured
+name. On Android 17 and later the system contact picker returns a session
+URI the plugin reads without that permission.
+
 | Param         | Type                                                                | Description                                            |
 | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
 | **`options`** | <code><a href="#pickcontactsoptions">PickContactsOptions</a></code> | - Optional fields to retrieve and picker configuration |
@@ -489,26 +547,27 @@ Options for creating a contact.
 
 <a href="#contact">Contact</a> information.
 
-| Prop                   | Type                                          | Description                                                   | Since |
-| ---------------------- | --------------------------------------------- | ------------------------------------------------------------- | ----- |
-| **`id`**               | <code>string</code>                           | Unique identifier for the contact.                            | 1.0.0 |
-| **`account`**          | <code><a href="#account">Account</a></code>   | <a href="#account">Account</a> information for the contact.   | 1.0.0 |
-| **`birthday`**         | <code><a href="#birthday">Birthday</a></code> | <a href="#birthday">Birthday</a> information for the contact. | 1.0.0 |
-| **`emailAddresses`**   | <code>EmailAddress[]</code>                   | Email addresses for the contact.                              | 1.0.0 |
-| **`familyName`**       | <code>string</code>                           | Family name (last name) of the contact.                       | 1.0.0 |
-| **`fullName`**         | <code>string</code>                           | Full name of the contact.                                     | 1.0.0 |
-| **`givenName`**        | <code>string</code>                           | Given name (first name) of the contact.                       | 1.0.0 |
-| **`groupIds`**         | <code>string[]</code>                         | <a href="#group">Group</a> IDs the contact belongs to.        | 1.0.0 |
-| **`jobTitle`**         | <code>string</code>                           | Job title of the contact.                                     | 1.0.0 |
-| **`middleName`**       | <code>string</code>                           | Middle name of the contact.                                   | 1.0.0 |
-| **`namePrefix`**       | <code>string</code>                           | Name prefix (e.g., "Dr.", "Mr.", "Ms.") of the contact.       | 1.0.0 |
-| **`nameSuffix`**       | <code>string</code>                           | Name suffix (e.g., "Jr.", "Sr.", "III") of the contact.       | 1.0.0 |
-| **`note`**             | <code>string</code>                           | Notes about the contact.                                      | 1.0.0 |
-| **`organizationName`** | <code>string</code>                           | Organization name of the contact.                             | 1.0.0 |
-| **`phoneNumbers`**     | <code>PhoneNumber[]</code>                    | Phone numbers for the contact.                                | 1.0.0 |
-| **`photo`**            | <code>string</code>                           | Base64-encoded photo of the contact.                          | 1.0.0 |
-| **`postalAddresses`**  | <code>PostalAddress[]</code>                  | Postal addresses for the contact.                             | 1.0.0 |
-| **`urlAddresses`**     | <code>UrlAddress[]</code>                     | URL addresses for the contact.                                | 1.0.0 |
+| Prop                   | Type                                          | Description                                                                                                                                                                                                                                               | Since |
+| ---------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`id`**               | <code>string</code>                           | Unique identifier for the contact.                                                                                                                                                                                                                        | 1.0.0 |
+| **`displayName`**      | <code>string</code>                           | Formatted name shown by the device for this contact. Derived from `CNContactFormatter` on iOS and `DISPLAY_NAME` on Android. Read-only: setting this when creating or updating a contact has no effect. Use `givenName` and `familyName` to write a name. | 8.1.0 |
+| **`account`**          | <code><a href="#account">Account</a></code>   | <a href="#account">Account</a> information for the contact.                                                                                                                                                                                               | 1.0.0 |
+| **`birthday`**         | <code><a href="#birthday">Birthday</a></code> | <a href="#birthday">Birthday</a> information for the contact.                                                                                                                                                                                             | 1.0.0 |
+| **`emailAddresses`**   | <code>EmailAddress[]</code>                   | Email addresses for the contact.                                                                                                                                                                                                                          | 1.0.0 |
+| **`familyName`**       | <code>string</code>                           | Family name (last name) of the contact.                                                                                                                                                                                                                   | 1.0.0 |
+| **`fullName`**         | <code>string</code>                           | Full name of the contact.                                                                                                                                                                                                                                 | 1.0.0 |
+| **`givenName`**        | <code>string</code>                           | Given name (first name) of the contact.                                                                                                                                                                                                                   | 1.0.0 |
+| **`groupIds`**         | <code>string[]</code>                         | <a href="#group">Group</a> IDs the contact belongs to.                                                                                                                                                                                                    | 1.0.0 |
+| **`jobTitle`**         | <code>string</code>                           | Job title of the contact.                                                                                                                                                                                                                                 | 1.0.0 |
+| **`middleName`**       | <code>string</code>                           | Middle name of the contact.                                                                                                                                                                                                                               | 1.0.0 |
+| **`namePrefix`**       | <code>string</code>                           | Name prefix (e.g., "Dr.", "Mr.", "Ms.") of the contact.                                                                                                                                                                                                   | 1.0.0 |
+| **`nameSuffix`**       | <code>string</code>                           | Name suffix (e.g., "Jr.", "Sr.", "III") of the contact.                                                                                                                                                                                                   | 1.0.0 |
+| **`note`**             | <code>string</code>                           | Notes about the contact.                                                                                                                                                                                                                                  | 1.0.0 |
+| **`organizationName`** | <code>string</code>                           | Organization name of the contact.                                                                                                                                                                                                                         | 1.0.0 |
+| **`phoneNumbers`**     | <code>PhoneNumber[]</code>                    | Phone numbers for the contact.                                                                                                                                                                                                                            | 1.0.0 |
+| **`photo`**            | <code>string</code>                           | Base64-encoded photo of the contact.                                                                                                                                                                                                                      | 1.0.0 |
+| **`postalAddresses`**  | <code>PostalAddress[]</code>                  | Postal addresses for the contact.                                                                                                                                                                                                                         | 1.0.0 |
+| **`urlAddresses`**     | <code>UrlAddress[]</code>                     | URL addresses for the contact.                                                                                                                                                                                                                            | 1.0.0 |
 
 
 #### Account
@@ -774,10 +833,11 @@ Result from picking contacts.
 
 Options for picking contacts using the native contact picker.
 
-| Prop           | Type                                                  | Description                                                                              | Since |
-| -------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- |
-| **`fields`**   | <code>(keyof <a href="#contact">Contact</a>)[]</code> | Optional list of specific fields to retrieve. If not specified, all fields are returned. | 1.0.0 |
-| **`multiple`** | <code>boolean</code>                                  | Whether to allow selecting multiple contacts. Default is false.                          | 1.0.0 |
+| Prop           | Type                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Since |
+| -------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`fields`**   | <code>(keyof <a href="#contact">Contact</a>)[]</code>       | Optional list of specific fields to retrieve. If not specified, all fields are returned. Ignored when {@link <a href="#pickcontactsoptions">PickContactsOptions.property</a>} is set. The result then contains only `id`, `displayName`, and the selected property.                                                                                                                                                                                                                                                                   | 1.0.0 |
+| **`multiple`** | <code>boolean</code>                                        | Whether to allow selecting multiple contacts. Default is false. Ignored when {@link <a href="#pickcontactsoptions">PickContactsOptions.property</a>} is set. Property picking always returns a single value.                                                                                                                                                                                                                                                                                                                          | 1.0.0 |
+| **`property`** | <code><a href="#contactproperty">ContactProperty</a></code> | Restrict the picker to a single contact property. On Android this launches the picker against the phone, email, or postal address table and reads the granted data row. That requires no `READ_CONTACTS` permission on any Android version, which is required for apps that only pick a contact detail and target Android 17 (API 37) or later under the Google Play Contacts Permissions policy. On iOS the picker lets the user choose one phone number, email address, or postal address. It never requires a contacts permission. | 8.1.0 |
 
 
 #### UpdateContactByIdOptions
@@ -900,6 +960,18 @@ Type of contacts permission to request.
 
 <code>'readContacts' | 'writeContacts'</code>
 
+
+### Enums
+
+
+#### ContactProperty
+
+| Members             | Value                        | Description              | Since |
+| ------------------- | ---------------------------- | ------------------------ | ----- |
+| **`PhoneNumber`**   | <code>'phoneNumber'</code>   | A single phone number.   | 8.1.0 |
+| **`EmailAddress`**  | <code>'emailAddress'</code>  | A single email address.  | 8.1.0 |
+| **`PostalAddress`** | <code>'postalAddress'</code> | A single postal address. | 8.1.0 |
+
 </docgen-api>
 
 ### Credit

package/android/src/main/java/app/capgo/contacts/CapacitorContactsPlugin.java

@@ -40,7 +40,7 @@ import java.util.Set;
 )
 public class CapacitorContactsPlugin extends Plugin {
 
-    private final String pluginVersion = "8.0.18";
+    private final String pluginVersion = "8.1.0";
     private static final int BATCH_SIZE = 50;
 
     // MARK: - Implemented API surface
@@ -467,19 +467,87 @@ public class CapacitorContactsPlugin extends Plugin {
     private static final int EDIT_CONTACT_REQUEST = 7004;
 
     private PluginCall currentPickerCall;
+    private String currentPickerProperty;
+
+    // Android 17 (API 37) system contact picker. Constants are inlined so the
+    // plugin still compiles against compileSdk 36.
+    private static final int ANDROID_API_17 = 37;
+    private static final String ACTION_PICK_CONTACTS = "android.provider.action.PICK_CONTACTS";
+    private static final String EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS = "android.provider.extra.PICK_CONTACTS_REQUESTED_DATA_FIELDS";
+    private static final String EXTRA_PICK_CONTACTS_SELECTION_LIMIT = "android.provider.extra.PICK_CONTACTS_SELECTION_LIMIT";
 
     @PluginMethod
     public void pickContact(PluginCall call) {
-        currentPickerCall = call;
-        Intent intent = new Intent(Intent.ACTION_PICK, ContactsContract.Contacts.CONTENT_URI);
-        startActivityForResult(call, intent, PICK_CONTACT_REQUEST);
+        launchContactPicker(call);
     }
 
     @PluginMethod
     public void pickContacts(PluginCall call) {
-        // Android doesn't have a native multi-select contact picker
-        // Fall back to single selection
-        pickContact(call);
+        launchContactPicker(call);
+    }
+
+    private void launchContactPicker(PluginCall call) {
+        String property = call.getString("property");
+        if (property != null && contentUriForProperty(property) == null) {
+            call.reject("Invalid property. Use phoneNumber, emailAddress, or postalAddress.");
+            return;
+        }
+
+        currentPickerCall = call;
+        currentPickerProperty = property;
+        startActivityForResult(call, createPickIntent(call, property), PICK_CONTACT_REQUEST);
+    }
+
+    private Intent createPickIntent(PluginCall call, String property) {
+        if (property != null) {
+            return new Intent(Intent.ACTION_PICK, contentUriForProperty(property));
+        }
+
+        if (android.os.Build.VERSION.SDK_INT >= ANDROID_API_17) {
+            Intent intent = new Intent(ACTION_PICK_CONTACTS);
+            intent.putStringArrayListExtra(EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS, requestedMimeTypes(call));
+            boolean multiple = Boolean.TRUE.equals(call.getBoolean("multiple", false));
+            if (!multiple) {
+                intent.putExtra(EXTRA_PICK_CONTACTS_SELECTION_LIMIT, 1);
+            } else {
+                intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true);
+            }
+            if (intent.resolveActivity(getContext().getPackageManager()) != null) {
+                return intent;
+            }
+        }
+
+        return new Intent(Intent.ACTION_PICK, ContactsContract.Contacts.CONTENT_URI);
+    }
+
+    private Uri contentUriForProperty(String property) {
+        if ("phoneNumber".equals(property)) {
+            return ContactsContract.CommonDataKinds.Phone.CONTENT_URI;
+        }
+        if ("emailAddress".equals(property)) {
+            return ContactsContract.CommonDataKinds.Email.CONTENT_URI;
+        }
+        if ("postalAddress".equals(property)) {
+            return ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_URI;
+        }
+        return null;
+    }
+
+    private ArrayList<String> requestedMimeTypes(PluginCall call) {
+        Set<String> fields = parseFieldsArray(call);
+        if (fields != null) {
+            return new ArrayList<>(getMimeTypesForFields(fields));
+        }
+        ArrayList<String> mimeTypes = new ArrayList<>();
+        mimeTypes.add(ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Organization.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Note.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Event.CONTENT_ITEM_TYPE);
+        mimeTypes.add(ContactsContract.CommonDataKinds.Website.CONTENT_ITEM_TYPE);
+        return mimeTypes;
     }
 
     @PluginMethod
@@ -546,6 +614,7 @@ public class CapacitorContactsPlugin extends Plugin {
         currentPickerCall = null;
 
         if (resultCode != android.app.Activity.RESULT_OK) {
+            currentPickerProperty = null;
             if (requestCode == PICK_CONTACT_REQUEST) {
                 call.resolve(new JSObject().put("contacts", new JSArray()));
             } else if (requestCode == CREATE_CONTACT_REQUEST) {
@@ -557,20 +626,9 @@ public class CapacitorContactsPlugin extends Plugin {
         try {
             if (requestCode == PICK_CONTACT_REQUEST) {
                 if (data != null && data.getData() != null) {
-                    String contactId = getContactIdFromUri(data.getData());
-                    if (contactId != null) {
-                        ContactBuilder builder = fetchContact(contactId, null);
-                        if (builder != null) {
-                            JSArray contacts = new JSArray();
-                            contacts.put(builder.toJSObject(null));
-                            call.resolve(new JSObject().put("contacts", contacts));
-                        } else {
-                            call.resolve(new JSObject().put("contacts", new JSArray()));
-                        }
-                    } else {
-                        call.resolve(new JSObject().put("contacts", new JSArray()));
-                    }
+                    resolvePickedUri(call, data.getData());
                 } else {
+                    currentPickerProperty = null;
                     call.resolve(new JSObject().put("contacts", new JSArray()));
                 }
             } else if (requestCode == CREATE_CONTACT_REQUEST) {
@@ -590,6 +648,168 @@ public class CapacitorContactsPlugin extends Plugin {
         }
     }
 
+    private void resolvePickedUri(PluginCall call, Uri uri) {
+        String property = currentPickerProperty;
+        currentPickerProperty = null;
+
+        if (isSessionUri(uri)) {
+            call.resolve(new JSObject().put("contacts", contactsFromSessionUri(uri, fieldsForPickedContact(call))));
+            return;
+        }
+
+        if (property != null || isDataRowUri(uri)) {
+            JSObject contact = contactFromDataRowUri(uri, property);
+            JSArray contacts = new JSArray();
+            if (contact != null) {
+                contacts.put(contact);
+            }
+            call.resolve(new JSObject().put("contacts", contacts));
+            return;
+        }
+
+        call.resolve(new JSObject().put("contacts", contactsFromContactUri(uri, fieldsForPickedContact(call))));
+    }
+
+    private Set<String> fieldsForPickedContact(PluginCall call) {
+        Set<String> fields = parseFieldsArray(call);
+        if (fields == null) {
+            return null;
+        }
+        Set<String> withIdentity = new HashSet<>(fields);
+        withIdentity.add("id");
+        withIdentity.add("displayName");
+        return withIdentity;
+    }
+
+    private boolean isSessionUri(Uri uri) {
+        String authority = uri.getAuthority();
+        return authority != null && authority.contains("picker");
+    }
+
+    private boolean isDataRowUri(Uri uri) {
+        List<String> segments = uri.getPathSegments();
+        return segments != null && !segments.isEmpty() && "data".equals(segments.get(0));
+    }
+
+    private JSArray contactsFromSessionUri(Uri sessionUri, Set<String> fields) {
+        JSArray contacts = new JSArray();
+        Map<String, ContactBuilder> builders = new java.util.LinkedHashMap<>();
+        ContentResolver resolver = getContext().getContentResolver();
+
+        try (Cursor cursor = resolver.query(sessionUri, null, null, null, null)) {
+            if (cursor == null) {
+                return contacts;
+            }
+            while (cursor.moveToNext()) {
+                String contactId = getStringColumn(cursor, ContactsContract.Data.CONTACT_ID);
+                if (contactId == null) {
+                    continue;
+                }
+                ContactBuilder builder = builders.get(contactId);
+                if (builder == null) {
+                    builder = new ContactBuilder(contactId);
+                    String displayName = getStringColumn(cursor, ContactsContract.Data.DISPLAY_NAME);
+                    builder.displayName = displayName;
+                    builder.fullName = displayName;
+                    builders.put(contactId, builder);
+                }
+                processDataRow(builder, cursor);
+            }
+        }
+
+        for (ContactBuilder builder : builders.values()) {
+            contacts.put(builder.toJSObject(fields));
+        }
+        return contacts;
+    }
+
+    private JSObject contactFromDataRowUri(Uri uri, String property) {
+        ContentResolver resolver = getContext().getContentResolver();
+        try (Cursor cursor = resolver.query(uri, null, null, null, null)) {
+            if (cursor == null || !cursor.moveToFirst()) {
+                return null;
+            }
+
+            String contactId = getStringColumn(cursor, ContactsContract.Data.CONTACT_ID);
+            ContactBuilder builder = new ContactBuilder(contactId != null ? contactId : uri.getLastPathSegment());
+            String displayName = getStringColumn(cursor, ContactsContract.Data.DISPLAY_NAME);
+            builder.displayName = displayName;
+            builder.fullName = displayName;
+            processDataRow(builder, cursor);
+
+            Set<String> fields = new HashSet<>();
+            fields.add("id");
+            fields.add("displayName");
+            if ("emailAddress".equals(property)) {
+                fields.add("emailAddresses");
+            } else if ("postalAddress".equals(property)) {
+                fields.add("postalAddresses");
+            } else {
+                fields.add("phoneNumbers");
+            }
+            return builder.toJSObject(fields);
+        } catch (Exception ex) {
+            android.util.Log.w("CapacitorContacts", "Failed to read picked contact data row", ex);
+            return null;
+        }
+    }
+
+    private JSArray contactsFromContactUri(Uri contactUri, Set<String> fields) {
+        JSArray contacts = new JSArray();
+        String contactId = getContactIdFromUri(contactUri);
+        if (contactId == null) {
+            return contacts;
+        }
+
+        if (hasReadPermission()) {
+            try {
+                ContactBuilder builder = fetchContact(contactId, fields);
+                if (builder != null) {
+                    if (builder.displayName == null) {
+                        builder.displayName = builder.fullName;
+                    }
+                    contacts.put(builder.toJSObject(fields));
+                }
+                return contacts;
+            } catch (Exception ex) {
+                android.util.Log.w("CapacitorContacts", "Failed to fetch picked contact", ex);
+            }
+        }
+
+        ContactBuilder builder = new ContactBuilder(contactId);
+        String displayName = resolveDisplayNameFromUri(contactUri);
+        builder.displayName = displayName;
+        builder.fullName = displayName;
+        Set<String> thinFields = new HashSet<>();
+        thinFields.add("id");
+        thinFields.add("displayName");
+        thinFields.add("fullName");
+        contacts.put(builder.toJSObject(thinFields));
+        return contacts;
+    }
+
+    private String resolveDisplayNameFromUri(Uri contactUri) {
+        ContentResolver resolver = getContext().getContentResolver();
+        try (
+            Cursor cursor = resolver.query(contactUri, new String[] { ContactsContract.Contacts.DISPLAY_NAME_PRIMARY }, null, null, null)
+        ) {
+            if (cursor != null && cursor.moveToFirst()) {
+                return cursor.getString(cursor.getColumnIndexOrThrow(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY));
+            }
+        } catch (Exception ex) {
+            // The picker URI grant may only expose a subset of columns.
+        }
+        return null;
+    }
+
+    private static String getStringColumn(Cursor cursor, String column) {
+        int index = cursor.getColumnIndex(column);
+        if (index < 0) {
+            return null;
+        }
+        return cursor.getString(index);
+    }
+
     private String getContactIdFromUri(Uri contactUri) {
         ContentResolver resolver = getContext().getContentResolver();
         try (Cursor cursor = resolver.query(contactUri, new String[] { ContactsContract.Contacts._ID }, null, null, null)) {
@@ -1110,6 +1330,7 @@ public class CapacitorContactsPlugin extends Plugin {
                 String id = cursor.getString(cursor.getColumnIndexOrThrow(ContactsContract.Contacts._ID));
                 String displayName = cursor.getString(cursor.getColumnIndexOrThrow(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY));
                 ContactBuilder builder = new ContactBuilder(id);
+                builder.displayName = displayName;
                 builder.fullName = displayName;
                 builderMap.put(id, builder);
             }
@@ -1292,6 +1513,9 @@ public class CapacitorContactsPlugin extends Plugin {
         if (builder.fullName == null) {
             builder.fullName = resolveDisplayName(contactId);
         }
+        if (builder.displayName == null) {
+            builder.displayName = builder.fullName;
+        }
 
         return builder;
     }
@@ -1480,6 +1704,7 @@ public class CapacitorContactsPlugin extends Plugin {
         String jobTitle;
         String note;
         String fullName;
+        String displayName;
         String photoBase64;
         String accountName;
         String accountType;
@@ -1612,6 +1837,7 @@ public class CapacitorContactsPlugin extends Plugin {
             if (includeAll || fields.contains("jobTitle")) contact.put("jobTitle", jobTitle);
             if (includeAll || fields.contains("note")) contact.put("note", note);
             if (includeAll || fields.contains("fullName")) contact.put("fullName", fullName);
+            if (includeAll || fields.contains("displayName")) contact.put("displayName", displayName != null ? displayName : fullName);
             if (includeAll || fields.contains("photo")) contact.put("photo", photoBase64);
             if (includeAll || fields.contains("groupIds")) contact.put("groupIds", groupIds);
             if (includeAll || fields.contains("emailAddresses")) contact.put("emailAddresses", emailAddresses);

package/dist/docs.json

@@ -475,7 +475,7 @@
             "text": "1.0.0"
           }
         ],
-        "docs": "Pick a single contact using the native contact picker.",
+        "docs": "Pick a single contact using the native contact picker.\n\nSame options as {@link pickContacts}. Pass `property` to select one phone\nnumber, email address, or postal address without `READ_CONTACTS` on Android.",
         "complexTypes": [
           "PickContactsResult",
           "PickContactOptions",
@@ -508,7 +508,7 @@
             "text": "1.0.0"
           }
         ],
-        "docs": "Pick one or more contacts using the native contact picker.",
+        "docs": "Pick one or more contacts using the native contact picker.\n\nOn iOS this never requires a contacts permission.\n\nOn Android, pass `property` to select a single phone number, email address,\nor postal address with no `READ_CONTACTS` permission. That works on every\nAndroid version and is the way to ship without declaring the permission\nwhen targeting Android 17 (API 37) or later.\n\nPicking a full contact without `property` still needs `READ_CONTACTS` below\nAndroid 17, because the picker URI exposes no phone, email, or structured\nname. On Android 17 and later the system contact picker returns a session\nURI the plugin reads without that permission.",
         "complexTypes": [
           "PickContactsResult",
           "PickContactsOptions"
@@ -727,6 +727,18 @@
           "complexTypes": [],
           "type": "string | undefined"
         },
+        {
+          "name": "displayName",
+          "tags": [
+            {
+              "text": "8.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Formatted name shown by the device for this contact.\n\nDerived from `CNContactFormatter` on iOS and `DISPLAY_NAME` on Android.\nRead-only: setting this when creating or updating a contact has no effect.\nUse `givenName` and `familyName` to write a name.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
         {
           "name": "account",
           "tags": [
@@ -1971,7 +1983,7 @@
               "name": "since"
             }
           ],
-          "docs": "Optional list of specific fields to retrieve. If not specified, all fields are returned.",
+          "docs": "Optional list of specific fields to retrieve. If not specified, all fields are returned.\n\nIgnored when {@link PickContactsOptions.property} is set. The result then\ncontains only `id`, `displayName`, and the selected property.",
           "complexTypes": [
             "ContactField"
           ],
@@ -1985,9 +1997,23 @@
               "name": "since"
             }
           ],
-          "docs": "Whether to allow selecting multiple contacts. Default is false.",
+          "docs": "Whether to allow selecting multiple contacts. Default is false.\n\nIgnored when {@link PickContactsOptions.property} is set. Property picking\nalways returns a single value.",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "property",
+          "tags": [
+            {
+              "text": "8.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Restrict the picker to a single contact property.\n\nOn Android this launches the picker against the phone, email, or postal\naddress table and reads the granted data row. That requires no\n`READ_CONTACTS` permission on any Android version, which is required for\napps that only pick a contact detail and target Android 17 (API 37) or\nlater under the Google Play Contacts Permissions policy.\n\nOn iOS the picker lets the user choose one phone number, email address,\nor postal address. It never requires a contacts permission.",
+          "complexTypes": [
+            "ContactProperty"
+          ],
+          "type": "ContactProperty"
         }
       ]
     },
@@ -2103,7 +2129,47 @@
       ]
     }
   ],
-  "enums": [],
+  "enums": [
+    {
+      "name": "ContactProperty",
+      "slug": "contactproperty",
+      "members": [
+        {
+          "name": "PhoneNumber",
+          "value": "'phoneNumber'",
+          "tags": [
+            {
+              "text": "8.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "A single phone number."
+        },
+        {
+          "name": "EmailAddress",
+          "value": "'emailAddress'",
+          "tags": [
+            {
+              "text": "8.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "A single email address."
+        },
+        {
+          "name": "PostalAddress",
+          "value": "'postalAddress'",
+          "tags": [
+            {
+              "text": "8.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "A single postal address."
+        }
+      ]
+    }
+  ],
   "typeAliases": [
     {
       "name": "Omit",