Docs Menu

Docs HomeDevelop ApplicationsAtlas Device SDK

React to Changes - Flutter SDK

On this page

  • Register a Query Change Listener
  • Register a RealmObject Change Listener
  • Register Collection Change Listeners
  • Register a User Instance Change Listener
  • Pause and Resume a Change Listener
  • Unsubscribe a Change Listener
  • Change Notification Limits

All Realm objects are live objects, which means they automatically update whenever they're modified. Realm emits a notification event whenever any property changes.

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:

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
});

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
});

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
});

Changed in version 1.7.0: Added support for RealmMap change listeners.

You can register a notification handler on a collection of any of the supported data types within another RealmObject. Realm notifies your handler when any of the items in the collection change. The handler receives one of the following objects that include a description of changes since the last notification:

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;
});

New in version 1.9.0.

In Flutter SDK version 1.9.0 and later, you can register a notification handler on a specific User instance within a realm. Realm notifies your handler when any of the user's properties change (for example, the user acces token is updated or the user state changes). The handler receives a UserChanges object, which includes description of changes since the last notification. UserChanges contains the following property:

Property
Type
Description
user
User
The user instance that has changed.
final userSubscription = user.changes.listen((changes) {
changes.user; // the User being listened to
});

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 from your change listener when you no longer want to receive notifications on updates to the data it's watching.

await subscription.cancel();

Changes in nested documents deeper than four levels down do not trigger change notifications.

If you have a data structure where you need to listen for changes five levels down or deeper, workarounds include:

  • Refactor the schema to reduce nesting.

  • Add something like "push-to-refresh" to enable users to manually refresh data.

←  CRUD - Delete - Flutter SDKFreeze Data - Flutter SDK →