FlutterContacts class

Complete contact management with ultra-fast get, create, update, and delete supporting all fields (phone, email, organization, photo, etc.). Includes groups, accounts, vCard import/export, native dialogs, change listeners, SIM support, and number blocking across Android, iOS, and macOS.

class FlutterContacts {
  // Core CRUD operations
  static Future<Contact?> get(String id, {Set<ContactProperty>? properties, Account? account});
  static Future<List<Contact>> getAll({Set<ContactProperty>? properties, ContactFilter? filter, Account? account, int? limit});
  static Future<String> create(Contact contact, {Account? account});
  static Future<List<String>> createAll(List<Contact> contacts, {Account? account});
  static Future<void> update(Contact contact);
  static Future<void> updateAll(List<Contact> contacts);
  static Future<void> delete(String id);
  static Future<void> deleteAll(List<String> ids);

  // Sub-APIs for related functionality
  static final config = ConfigApi();
  static final accounts = AccountsApi();
  static final groups = GroupsApi();
  static final permissions = PermissionsApi();
  static final vCard = VCardApi();
  static final native = NativeApi(); // Android & iOS only
  static final sim = SimApi(); // Android only
  static final profile = ProfileApi(); // Android & macOS only
  static final blockedNumbers = BlockedNumbersApi(); // Android only
  static final ringtones = RingtonesApi(); // Android only

  // Streams
  static Stream<void> get onDatabaseChange;
  static Stream<List<ContactChange>> get onContactChange;
}

// Configuration
class ConfigApi {
  bool enableIosNotes; // Requires iOS entitlement
}

// Account management
class AccountsApi {
  Future<List<Account>> getAll();
  Future<Account?> getDefault();
  Future<void> showDefaultPicker(); // Android only
}

// Group operations
class GroupsApi {
  Future<Group?> get(String groupId, {bool withContactCount = false});
  Future<List<Group>> getAll({List<Account>? accounts, bool withContactCount = false});
  Future<Group> create(String name, {Account? account});
  Future<void> update(Group group);
  Future<void> delete(String groupId);
  Future<void> addContacts({required String groupId, required List<String> contactIds});
  Future<void> removeContacts({required String groupId, required List<String> contactIds});
  Future<List<Group>> getOf(String contactId);
}

// Permissions
class PermissionsApi {
  Future<bool> has(PermissionType type);
  Future<PermissionStatus> check(PermissionType type);
  Future<PermissionStatus> request(PermissionType type);
  Future<void> openSettings();
}

// vCard import/export
class VCardApi {
  String export(Contact contact, {VCardVersion version = VCardVersion.v3});
  String exportAll(List<Contact> contacts, {VCardVersion version = VCardVersion.v3});
  List<Contact> import(String vCard);
}

// Native dialogs (Android & iOS only)
class NativeApi {
  Future<void> showViewer(String contactId);
  Future<String?> showPicker();
  Future<String?> showEditor(String contactId);
  Future<String?> showCreator({Contact? contact});
}

// SIM card storage (Android only)
class SimApi {
  Future<List<Contact>> get();
}

// User Profile / "Me" Card (Android & macOS only)
class ProfileApi {
  Future<Contact?> get({Set<ContactProperty>? properties});
}

// Android number blocking
class BlockedNumbersApi {
  Future<bool> isAvailable();
  Future<bool> isBlocked(String number);
  Future<List<Phone>> getAll();
  Future<void> block(String number);
  Future<void> blockAll(List<String> numbers);
  Future<void> unblock(String number);
  Future<void> unblockAll(List<String> numbers);
  Future<void> openDefaultAppSettings();
}

// Android ringtones
class RingtonesApi {
  Future<Ringtone?> get(String ringtoneUri, {bool withMetadata = true});
  Future<List<Ringtone>> getAll({RingtoneType? type, bool withMetadata = false});
  Future<String?> pick(RingtoneType type, {String? existingUri});
  Future<String?> getDefaultUri(RingtoneType type);
  Future<void> setDefaultUri(RingtoneType type, String? ringtoneUri);
  Future<void> play(String ringtoneUri);
  Future<void> stop();
}

Constructors

FlutterContacts()

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

config → ConfigApi: final
onContactChange → Stream<List<ContactChange>>: Stream that provides detailed diffs of changes (Added, Updated, Removed).
no setter
onDatabaseChange → Stream<void>: Stream that triggers whenever the contact database changes.
no setter

Static Methods

create(Contact contact, {Account? account}) → Future<String>: Creates a new contact.
createAll(List<Contact> contacts, {Account? account}) → Future<List<String>>: Creates multiple contacts in a single batch operation.
delete(String id) → Future<void>: Deletes a contact.
deleteAll(List<String> ids) → Future<void>: Deletes multiple contacts in a single batch operation.
get(String id, {Set<ContactProperty>? properties, Account? account, bool androidLookup = false}) → Future<Contact?>: Gets a single contact by ID.
getAll({Set<ContactProperty>? properties, ContactFilter? filter, Account? account, int? limit}) → Future<List<Contact>>: Gets all contacts matching the criteria.
openExternalEdit(String contactId) → Future<String?>: Opens the native contact editor dialog.
openExternalInsert([Contact? contact]) → Future<String?>: Opens the native contact creator dialog.
openExternalPick() → Future<String?>: Opens the native contact picker dialog.
openExternalView(String contactId) → Future<void>: Opens the native contact viewer dialog.
update(Contact contact) → Future<void>: Updates a contact.
updateAll(List<Contact> contacts) → Future<void>: Updates multiple contacts in a single batch operation.

Constants

accounts → const AccountsApi
blockedNumbers → const BlockedNumbersApi
groups → const GroupsApi
native → const NativeApi
permissions → const PermissionsApi
profile → const ProfileApi
ringtones → const RingtonesApi
sim → const SimApi
vCard → const VCardApi