React to Changes - Flutter SDK

On this page

Register a RealmObject Change Listener
Register RealmList and RealmSet Change Listeners
Pause and Resume a Change Listener
Unsubscribe a Change Listener

Any modern app should be able to react when data changes, regardless of where that change originated. When a user adds a new item to a list, you may want to update the UI, show a notification, or log a message. When someone updates that item, you may want to change its visual state or fire off a network request. Finally, when someone deletes the item, you probably want to remove it from the UI. Realm's notification system allows you to watch for and react to changes in your data, independent of the writes that caused the changes.

You can subscribe to changes on the following events:

Query on collection
Realm object
List and Set in a Realm object

Example

About the Examples on This Page

The examples in this page use two Realm object types, Character and Fellowship:

@RealmModel()
class _Character {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late String species;
  late int age;
}
@RealmModel()
class _Fellowship {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<_Character> members;
}

The examples have this sample data:

final frodo = Character(ObjectId(), 'Frodo', 'Hobbit', 51);
final samwise = Character(ObjectId(), 'Samwise', 'Hobbit', 39);
final gollum = Character(ObjectId(), 'Gollum', 'Hobbit', 589);
final aragorn = Character(ObjectId(), 'Aragorn', 'Human', 87);
final legolas = Character(ObjectId(), 'Legolas', 'Elf', 2931);
final gimli = Character(ObjectId(), 'Gimli', 'Dwarf', 140);
final fellowshipOfTheRing = Fellowship(
    ObjectId(), 'Fellowship of the Ring',
    members: [frodo, samwise, aragorn, legolas, gimli]);
final config = Configuration.local([Fellowship.schema, Character.schema]);
final realm = Realm(config);
realm.write(() {
  realm.add(fellowshipOfTheRing);
  realm.add(gollum); // not in fellowship
});

Register a Query Change Listener

You can register a notification handler on any query within a Realm. The handler receives a RealmResultsChanges object, which includes description of changes since the last notification. RealmResultsChanges contains the following properties:


Property	Type	Description
`inserted`	List<int>	Indexes in the new collection which were added in this version.
`modified`	List<int>	Indexes of the objects in the new collection which were modified in this version.
`deleted`	List<int>	Indexes in the previous version of the collection which have been removed from this one.
`newModified`	List<int>	Indexes of modified objects after deletions and insertions are accounted for.
`moved`	List<int>	Indexes of the objects in the collection which moved.
`results`	RealmResults<T as RealmObject>	Results collection being monitored for changes.
`isCleared`	bool	Deprecated in Realm Flutter SDK v1.1.0. Use `RealmResultsChanges.results.isEmpty` instead. Returns `true` if the results collection is empty in the notification callback.

// Listen for changes on whole collection
final characters = realm.all<Character>();
final subscription = characters.changes.listen((changes) {
  changes.inserted; // indexes of inserted objects
  changes.modified; // indexes of modified objects
  changes.deleted; // indexes of deleted objects
  changes.newModified; // indexes of modified objects
  // after deletions and insertions are accounted for
  changes.moved; // indexes of moved objects
  changes.results; // the full List of objects
});
// Listen for changes on RealmResults
final hobbits = fellowshipOfTheRing.members.query('species == "Hobbit"');
final hobbitsSubscription = hobbits.changes.listen((changes) {
  // ... all the same data as above
});

Register a RealmObject Change Listener

You can register a notification handler on a specific object within a realm. Realm notifies your handler when any of the object's properties change. The handler receives a RealmObjectChanges object, which includes description of changes since the last notification. RealmObjectChanges contains the following properties:


Property	Type	Description
`isDeleted`	bool	`true` if the object was deleted.
`object`	RealmObject	Realm object being monitored for changes.
`properties`	List<String>	Names of the Realm object's properties that have changed.

final frodoSubscription = frodo.changes.listen((changes) {
  changes.isDeleted; // if the object has been deleted
  changes.object; // the RealmObject being listened to, `frodo`
  changes.properties; // the changed properties
});

Register RealmList and RealmSet Change Listeners

You can register a notification handler on a list or set of any of the supported data types within another RealmObject. Realm notifies your handler when any of the items in the set or list change. The handler receives a RealmListChanges object for RealmList and RealmSetChanges object for RealmSet. These objects include description of changes since the last notification.

RealmListChanges contains the following properties:


Property	Type	Description
`inserted`	List<int>	Indexes of items in the new list which were added in this version.
`modified`	List<int>	Indexes of the items in the new list which were modified in this version.
`deleted`	List<int>	Indexes of items in the previous version of the list which have been removed from this one.
`newModified`	List<int>	Indexes of modified items after deletions and insertions are accounted for.
`moved`	List<int>	Indexes of the items in the list which moved.
`list` / `set`	RealmList<T> / RealmSet<T>	`RealmList` being monitored for changes if listening to a `RealmList`. `RealmSet` being monitored for changes if listening to a `RealmSet`.
`isCleared`	boolean	`true` when a collection has been cleared by calling its RealmList.clear() or RealmSet.clear() method.

final fellowshipSubscription =
    fellowshipOfTheRing.members.changes.listen((changes) {
  changes.inserted; // indexes of inserted Realm objects
  changes.modified; // indexes of modified Realm objects
  changes.deleted; // indexes of deleted Realm objects
  changes.newModified; // indexes of modified Realm objects
  // after deletions and insertions are accounted for
  changes.moved; // indexes of moved Realm objects
  changes.list; // the full RealmList of Realm objects
  // `true` after call to fellowshipOfTheRing.members.clear().
  // Otherwise false.
  changes.isCleared;
});

Pause and Resume a Change Listener

Pause your subscription if you temporarily don't want to receive notifications. You can later resume listening.

subscription.pause();
// the changes.listen() method won't fire until the subscription is resumed
subscription.resume();

Unsubscribe a Change Listener

Unsubscribe from your change listener when you no longer want to receive notifications on updates to the data it's watching.

await subscription.cancel();

← Read & Write Data - Flutter SDK Freeze Data - Flutter SDK →