flutter_contacts_stack 1.0.1

A powerful and high-performance Flutter plugin to access, modify, and manage device contacts across Android and iOS.

Flutter Contacts

A full-featured, cross-platform Flutter plugin to manage contacts on Android and iOS devices.
Built for speed, reliability, and modern app needs—capable of handling 5000+ contacts seamlessly.

---

✨ Features

• ✅ Light & full fetch (with optional photo, emails, phones, etc.)
• ✅ Pagination / Stream fetch for large datasets
• ✅ Fetch contact by ID
• ✅ Insert / Update / Delete (single & multiple)
• ✅ vCard Export & Import
• ✅ Contact change observer (Android & iOS)
• ✅ Contact search (name, phone, email)
• ✅ Group / Label fetch and assignment
• ✅ Merge contact suggestions
• ✅ Fetch deleted contacts (Android)
• ✅ Filter by SIM / device / social accounts
• ✅ Proper permission handling
• ✅ Type-safe & null-safe Dart APIs

---

🔧 Platform Support

Feature	Android	iOS
Fetch Contacts	✅	✅
Insert/Update/Delete	✅	✅
vCard Export / Import	✅	✅
Contact Observer	✅	✅
Deleted Contacts	✅	🚫
Group/Label support	✅	✅

---

🚀 Installation

dependencies:
  flutter_contacts_stack: ^<latest-version>

Then Run

flutter pub get

🛠️ Permissions

Android: Add to AndroidManifest.xml:

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

iOS: Add to Info.plist:

<key>NSContactsUsageDescription</key>
<string>This app uses contacts to manage your address book.</string>

📦 Usage

import 'package:flutter_contacts_stack/flutter_contacts_stack.dart';

// Check permission
await FlutterContactsStack.requestPermission();

// Fetch all contacts (light)
final contacts = await FlutterContactsStack.fetchContacts();

// Fetch fully with properties
final result = await FlutterContactsStack.fetchContacts(
  const ContactFetchOptions(
    withPhoto: true,
    withProperties: true,
    offset: 0,
    batchSize: 100,
  )
);

// Stream Fetch
FlutterContactsStack.streamContacts(options);

// Insert a contact
final newContact = Contact(
  givenName: 'Titto',
  familyName: 'Stack',
  phones: ['1234567890'],
);
await FlutterContactsStack.insertContact(newContact);

// Export as vCard
final vcard = await FlutterContactsStack.exportToVCard(contactId);

// Import from vCard
final contact = await FlutterContactsStack.importFromVCard(vcard);

📲 Observing Contact Changes

FlutterContactsStack.startListeningToContactChanges((contacts) {
  for (var contact in contacts) {
    if (kDebugMode) {
      print('Updated: ${contact.displayName}');
    }
  }
});

📇 Insert a Contact

final contact = Contact(
displayName: "Titto Stack",
phones: ["1234567890", "9090909090"],
emails: ["[e-mail]", "[e-mail]"],
);
await plugin.insertContact(contact);

📚 vCard Support

exportToVCard(contactId) – Exports a contact to .vcf format

🔍 TODO (Future Updates)

Support for contact favorites

⚫ importFromVCard
⚫ Cross-device sync layer
⚫ Deleted contact recovery (iOS workaround)
⚫ Custom contact field support

💬 Feedback

Pull requests and issues are welcome on GitHub.

👨‍💻 Contributing

Pull requests are welcome. Please ensure any changes maintain cross-platform compatibility and are tested.