QuisApp/flutter_contacts

To access contact notes on iOS, add the com.apple.developer.contacts.notes entitlement and set FlutterContacts.config.enableIosNotes = true. See Apple's documentation.

On Android, multiple "raw contacts" from different accounts are automatically merged into unified contacts. On iOS, the same merging happens behind the scenes. The plugin provides a single, consistent API across both platforms.

Accounts (containers on iOS) organize contacts by source - Google, iCloud, local device. Groups (labels on Android) organize contacts within an account. When creating a contact, you can specify which account to use; otherwise, it uses the default.

bool has = await FlutterContacts.permissions.has(PermissionType.read);
PermissionStatus status = await FlutterContacts.permissions.check(PermissionType.read);
PermissionStatus result = await FlutterContacts.permissions.request(PermissionType.readWrite);
await FlutterContacts.permissions.openSettings();

Types: PermissionType.read, .write, .readWrite (on iOS, all are equivalent).

List<Account> accounts = await FlutterContacts.accounts.getAll();
Account? defaultAccount = await FlutterContacts.accounts.getDefault();
await FlutterContacts.accounts.showDefaultPicker(); // Android only

Group? group = await FlutterContacts.groups.get(groupId, withContactCount: true);
List<Group> groups = await FlutterContacts.groups.getAll(accounts: [account]);
Group created = await FlutterContacts.groups.create('Family', account: account);
await FlutterContacts.groups.update(group);
await FlutterContacts.groups.delete(groupId);
await FlutterContacts.groups.addContacts(groupId: groupId, contactIds: [id1, id2]);
await FlutterContacts.groups.removeContacts(groupId: groupId, contactIds: [id1]);
List<Group> contactGroups = await FlutterContacts.groups.getOf(contactId);

String vCard = FlutterContacts.vCard.export(contact, version: VCardVersion.v3);
String vCards = FlutterContacts.vCard.exportAll([contact1, contact2]);
List<Contact> contacts = FlutterContacts.vCard.import(vCardString);

Supports vCard 2.1, 3.0, and 4.0.

System UI for picking, viewing, editing, and creating contacts.

Contact? picked = await FlutterContacts.native.showPicker(
  properties: {ContactProperty.phone},
);
await FlutterContacts.native.showViewer(contactId);
String? editedId = await FlutterContacts.native.showEditor(contactId);
String? createdId = await FlutterContacts.native.showCreator(contact: prefill);

Permissions:

• showPicker() and showCreator() need no contacts permission on either platform.
• showPicker(properties: …) is permissionless on iOS. On Android it requires READ_CONTACTS and throws PlatformException if missing.
• showViewer() and showEditor() are permissionless on Android. On iOS they require NSContactsUsageDescription in Info.plist and a granted read permission.

FlutterContacts.onDatabaseChange.listen((_) => refreshUI());

FlutterContacts.onContactChange.listen((changes) {
  for (final change in changes) {
    print('${change.type}: ${change.contactId}');
  }
});

List<Contact> simContacts = await FlutterContacts.sim.get();

SIM contacts are read-only and typically contain only name and phone.

Contact? me = await FlutterContacts.profile.get(properties: ContactProperties.all);

Returns the device owner's profile (Android) or "Me" card (macOS). Not available on iOS.

Requires app to be default phone app. See example manifest.

if (await FlutterContacts.blockedNumbers.isAvailable()) {
  bool isBlocked = await FlutterContacts.blockedNumbers.isBlocked('+1234567890');
  List<Phone> blocked = await FlutterContacts.blockedNumbers.getAll();
  await FlutterContacts.blockedNumbers.block('+1234567890');
  await FlutterContacts.blockedNumbers.blockAll([number1, number2]);
  await FlutterContacts.blockedNumbers.unblock('+1234567890');
  await FlutterContacts.blockedNumbers.unblockAll([number1, number2]);
  await FlutterContacts.blockedNumbers.openDefaultAppSettings();
}

String? uri = await FlutterContacts.ringtones.pick(type: RingtoneType.ringtone);
Ringtone? ringtone = await FlutterContacts.ringtones.get(uri, withMetadata: true);
List<Ringtone> all = await FlutterContacts.ringtones.getAll(type: RingtoneType.ringtone);
String? defaultUri = await FlutterContacts.ringtones.getDefaultUri(RingtoneType.ringtone);
await FlutterContacts.ringtones.setDefaultUri(RingtoneType.ringtone, uri);
await FlutterContacts.ringtones.play(uri);
await FlutterContacts.ringtones.stop();

FlutterContacts.config.enableIosNotes = true; // Requires iOS entitlement

class Contact {
  final String? id;                         // Stable identifier
  final String? displayName;                // Read-only, auto-generated
  final Photo? photo;
  final Name? name;
  final List<Phone> phones;
  final List<Email> emails;
  final List<Address> addresses;
  final List<Organization> organizations;
  final List<Website> websites;
  final List<SocialMedia> socialMedias;
  final List<Event> events;                 // Birthdays, anniversaries
  final List<Relation> relations;
  final List<Note> notes;

  // Android-specific fields: isFavorite, customRingtone,
  // sendToVoicemail, timestamp, identifiers
  final AndroidData? android;
}

// Name
Name(
  first: 'John',
  last: 'Smith',
  middle: 'Q',
  prefix: 'Dr.',
  suffix: 'Jr.',
)

// Phone, Email, Address
Phone('555-1234')
Phone('555-1234', label: Label(PhoneLabel.mobile))
Email('john@example.com', label: Label(EmailLabel.work))
Address(
  street: '123 Main St',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  label: Label(AddressLabel.home),
)

// Organization
Organization(
  organizationName: 'FlutterCorp',
  jobTitle: 'Software Engineer',
  departmentName: 'Engineering',
)

// Photo
Photo(fullSize: imageBytes)

Address Usage: Prefer component fields (street, city, state, etc.) when creating/editing. The formatted field is available when reading and is guaranteed to be present.

Photo Usage: When creating/updating, set Photo(fullSize: imageBytes) - the system automatically generates the thumbnail. When reading, fetch ContactProperty.photoThumbnail (fast) for contact lists, ContactProperty.photoFullRes (slower) for detail views.

Note: The examples above show common fields. See lib/models/ for the complete list of all available fields and properties.

Most properties support labels (home, work, mobile, etc.) and custom labels:

// Standard label
Phone('555-1234', label: Label(PhoneLabel.mobile))

// Custom label
Phone('555-1234', label: Label(PhoneLabel.custom, customLabel: 'Emergency'))

Platform Support: Some labels are platform-specific (e.g., PhoneLabel.appleWatch is iOS-only, PhoneLabel.workMobile is Android-only). Unsupported labels are automatically converted to custom labels with the original name preserved.

Not Available:

• APIs: ringtones, blockedNumbers, sim, profile (iOS), native (macOS)
• Properties: favorite, ringtone, sendToVoicemail, timestamp, identifiers, debugData (all nested in android field)
• Fields: Phone.isPrimary, Phone.normalizedNumber, Email.isPrimary, Address.poBox, Address.neighborhood, Organization.jobDescription, Organization.symbol, Organization.officeLocation
• Some Android-specific labels (auto-converted to custom)

Limits: One organization, one note, one birthday per contact.

Filtering: Phone and email filters only support full match (not partial).

iOS Notes: Requires the com.apple.developer.contacts.notes entitlement and FlutterContacts.config.enableIosNotes = true. See Apple's documentation.

Not Available:

• Fields: Name.previousFamilyName, Address.isoCountryCode, Address.subAdministrativeArea, Address.subLocality
• Some iOS-specific labels (auto-converted to custom)

Special Features:

• SIM Contacts: Read-only, typically name + phone only
• Blocked Numbers: Requires app to be default phone app