Navigation

React to Changes - iOS SDK

You can register a notification handler on an entire realm. Realm Database calls the notification handler whenever any write transaction involving that Realm is committed. The handler receives no information about the change.

You can register a notification handler on a collection within a realm.

Realm Database notifies your handler:

  • After first retrieving the collection.
  • Whenever a write transaction adds, changes, or removes objects in the collection.

Notifications describe the changes since the prior notification with three lists of indices: the indices of the objects that were deleted, inserted, and modified.

Important
Order Matters

In collection notification handlers, always apply changes in the following order: deletions, insertions, then modifications. Handling insertions before deletions may result in unexpected behavior.

You can register a notification handler on a specific object within a Realm. Realm Database notifies your handler:

  • When the object is deleted.
  • When any of the object's properties change.

The handler receives information about what fields changed and whether the object was deleted.

You can write to a realm without sending a notification to a specific observer by passing the observer's notification token in an array to realm.write(withoutNotifying:_:):

Tip

Observation stops when the token returned by an observe call becomes invalid. You can explicitly invalidate a token by calling its invalidate() method.

Important
Retain Tokens as Long as You Want to Observe

Notifications stop if the token is in a local variable that goes out of scope.

Realm Database objects are key-value observing (KVO) compliant for most properties:

  • Almost all managed (non-ignored) properties on Object subclasses
  • The invalidated property on Object and List

You cannot observe LinkingObjects properties via Key-value observation.

Important

You cannot add an object to a realm (with realm.add(obj) or similar methods) while it has any registered observers.

Observing the properties of unmanaged instances of Object subclasses works like any other dynamic property.

Observing the properties of managed objects works differently. With realm-managed objects, the value of a property may change when:

  • You assign to it
  • The realm is refreshed, either manually with realm.refresh() or automatically on a runloop thread
  • You begin a write transaction after changes on another thread

Realm applies changes made in the write transaction(s) on other threads at once. Observers see Key-value observation notifications at once. Intermediate steps do not trigger KVO notifications.

Example

Say your app performs a write transaction that increments a property from 1 to 10. On the main thread, you get a single notification of a change directly from 1 to 10. You won't get notifications for every incremental change between 1 and 10.

Avoid modifying managed Realm objects from within observeValueForKeyPath(_:ofObject:change:context:). Property values can change when not in a write transaction, or as part of beginning a write transaction.

Observing changes made to Realm List properties is simpler than NSMutableArray properties:

  • You don't have to mark List properties as dynamic to observe them.
  • You can call modification methods on List directly. Anyone observing the property that stores it gets a notification.

You don't need to use mutableArrayValueForKey(_:), although realm does support this for code compatibility.

Tip
See also:

Examples of using Realm with ReactiveCocoa from Objective‑C , and ReactKit from Swift.

Give Feedback

On this page