advanced_native_contact_picker 0.0.3

A Flutter plugin for picking contacts using native system UIs on Android and iOS without requiring explicit permissions.

advanced_native_contact_picker

A Flutter plugin for picking contacts using native system UIs on Android and iOS. This plugin avoids requiring explicit READ_CONTACTS permissions on Android or contacts permissions on iOS by relying on modern native system pickers that grant zero-permission / temporary read access to the selected contacts.

Features

• Zero Permissions Required: Operates using native system picker flows (CNContactPickerViewController on iOS, zero-permission ACTION_PICK / API 37+ Contact Picker on Android).
• Single & Multi Selection: Pick a single contact or enable multi-selection mode (allowMultiple: true).
• Native Selection Action Sheet (iOS): When a single contact has multiple numbers/emails, iOS automatically presents a native action sheet bottom sheet after contact selection so the user can choose the exact entry.
• Configurable Fields: Easily choose whether to fetch phone numbers only (default) or include email addresses (includeEmail: true).
• Clean Models: Returns strongly-typed NativeContact models with lookupKey, name, phones, and emails.

Demo / Visuals

Android 17 Picker	Android 16 Picker

Important Note for Android 16 and Below

• No Permissions Required: On Android 16 or lower, the contact picker still works perfectly without requiring explicit READ_CONTACTS permissions.
• Duplicate Contacts Display: In Android 16 or lower, if a single contact has multiple phone numbers saved (e.g., Contact A has 5 different numbers), the system picker will display 5 separate entries with the same name instead of grouping them together under one contact entry.

Getting Started

Add advanced_native_contact_picker to your pubspec.yaml:

dependencies:
  advanced_native_contact_picker: ^0.0.3

Usage

Import the package in your Dart code:

import 'package:advanced_native_contact_picker/advanced_native_contact_picker.dart';

Pick a Single Contact (Phone Only)

By default, calling pickContact() opens the picker and retrieves phone numbers only:

final List<NativeContact> contacts = await NativeContactPicker.pickContact();

if (contacts.isNotEmpty) {
  final contact = contacts.first;
  print('Name: ${contact.name}');
  for (final phone in contact.phones) {
    print('Phone (${phone.label}): ${phone.value}');
  }
}

Pick a Contact with Emails Included

To include email addresses alongside phone numbers, set includeEmail: true:

final List<NativeContact> contacts = await NativeContactPicker.pickContact(
  includeEmail: true,
);

Pick Multiple Contacts

To enable selecting multiple contacts at once:

final List<NativeContact> contacts = await NativeContactPicker.pickContact(
  allowMultiple: true,
  selectionLimit: 5, // Supported on Android API 37+
  includeEmail: true,
);

for (final contact in contacts) {
  print('${contact.name}: ${contact.phones.map((p) => p.value).join(", ")}');
}

Parameters

Parameter	Type	Default	Description
allowMultiple	bool	false	Enables multi-contact selection mode.
includeEmail	bool	false	When true, fetches email addresses in addition to phone numbers. Defaults to phone-only.
selectionLimit	int?	null	Optional limit on the number of contacts that can be selected in multi-select mode (Android API 37+).

Data Structure

NativeContact

Property	Type	Description
lookupKey	String	Unique platform identifier for the contact.
name	String	Full display name of the contact.
phones	List<LabeledValue>	List of phone numbers associated with the contact (or the specifically selected phone number).
emails	List<LabeledValue>	List of email addresses associated with the contact.

LabeledValue

Property	Type	Description
label	String	The label associated with the entry (e.g., "mobile", "work", "home").
value	String	The actual phone number or email address string.

Example App

Check the example/ directory for a complete sample Flutter application.