Contactos #

Description #

A Flutter plugin to read, create, update and delete the device's contacts and to open the native contact form and picker on Android and iOS.

Features #

Installation #

Add contactos to your pubspec.yaml:

dependencies:
  contactos: ^2.1.0

Permissions #

contactos does not request permissions. Request the contacts permission before calling the plugin, for example with permission_handler. Calls made without the permission fail.

Android #

Add the permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

iOS #

Describe why the app needs contacts in ios/Runner/Info.plist:

<key>NSContactsUsageDescription</key>
<string>This app requires contacts access to function properly.</string>

If you use permission_handler, also enable its contacts permission in ios/Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        ## dart: PermissionGroup.contacts
        'PERMISSION_CONTACTS=1',
      ]
    end
  end
end

Example #

import 'package:contactos/contactos.dart';

final contactos = Contactos.instance;

// All contacts. Thumbnails are loaded by default.
final contacts = await contactos.getContacts();

// Faster: load the list without thumbnails, then load avatars lazily.
final lightweight = await contactos.getContacts(withThumbnails: false);
final avatar = await contactos.getAvatar(lightweight.first);

// Search.
final johns = await contactos.getContacts(query: 'john');
final byPhone = await contactos.getContactsForPhone('+1 555 0100');
final byEmail = await contactos.getContactsForEmail('john@example.com');

// Add a contact. It needs at least a given or a family name.
await contactos.addContact(
  const Contact(
    givenName: 'John',
    familyName: 'Doe',
    phones: [Contact$Field(label: 'mobile', value: '+1 555 0100')],
    emails: [Contact$Field(label: 'work', value: 'john@example.com')],
  ),
);

// Update and delete need a contact with a valid identifier,
// for example one returned by getContacts.
final john = johns.first;
await contactos.updateContact(john.copyWith(jobTitle: 'Engineer'));
await contactos.deleteContact(john);

Native forms and picker #

try {
  // Create a contact in the native form.
  final created = await contactos.openContactForm();

  // Edit an existing contact in the native form.
  final edited = await contactos.openExistingContact(created);

  // Let the user pick a contact. Returns null when nothing is picked.
  final picked = await contactos.openDeviceContactPicker();
} on FormOperationException catch (error) {
  switch (error.errorCode) {
    case FormOperationErrorCode.canceled:
      // The user closed the form.
      break;
    case FormOperationErrorCode.couldNotBeOpen:
    case FormOperationErrorCode.unknown:
    case null:
      // Report the error.
      break;
  }
}

Labels #

Phone, email and address labels are localized by default. Pass iOSLocalizedLabels: false or androidLocalizedLabels: false to get stable English labels such as mobile, home and work instead.

A complete app is available in the example.

Contact model #

Contact is immutable. Use copyWith to change it.

Changelog #

See the CHANGELOG. Contribution and release workflow details are in the CONTRIBUTING guide.

Maintainers #

Anton Ustinoff (ziqq)

License #

MIT

Funding #

If you want to support the development of the library:

• Buy me a coffee
• Subscribe through Boosty