Live Objects & Collections

Live objects and live collections are SDK patterns for reading data that can change after your first request. They let your app subscribe to SDK-managed state instead of treating every query as a one-time network response. Use a live object when the screen is centered on one entity, such as a post, message, channel, community, user, room, stream, poll, or story. Use a live collection when the screen renders a list, such as posts, comments, messages, members, followers, reactions, rooms, or streams.

Platform Surface

Platform	Live object	Live collection	Pagination	Cleanup
TypeScript	`Amity.LiveObject<T>` delivered to repository callbacks such as `PostRepository.getPost()`	`Amity.LiveCollection<T>` delivered to query callbacks such as `PostRepository.getPosts()`	`onNextPage`, `hasNextPage`, `onPrevPage`, `hasPrevPage` when supported by that query	Call the returned `Amity.Unsubscriber`; also unsubscribe from any real-time topics you subscribed to
iOS	`AmityObject<T>`	`AmityCollection<T>`	`nextPage()`, `previousPage()`, `hasNext`, `hasPrevious`, `resetPage()`	Retain the returned `AmityNotificationToken`; call `invalidate()` or release the token
Android	`Flowable<T>` from repository methods such as `getPost(postId)`	`Flowable<PagingData<T>>` or `Flowable<List<T>>`, depending on the query	Android Paging 3 through `PagingData` for paged collections	Dispose the RxJava subscription or cancel the coroutine collector
Flutter	`Stream<T>` from live-object builders such as `live.getPost(postId)`	`LiveCollection<T>` / `LiveCollectionStream<T>`	`loadNext()`, `loadPrevious()`, `hasNextPage()`, `hasPreviousPage()`, `reset()`	Cancel stream subscriptions and call `dispose()` on live collections

Data Sources

Live results can be updated by more than one source:

Source	What it means
Local cache	The SDK may emit cached data first so the UI can render quickly.
Server fetch	The SDK fetches newer data and updates the same live object or live collection.
Local mutation	Actions from the current device update the local SDK store and notify observers.
Real-time event	Events from subscribed topics update the SDK store and notify observers.

Live objects and collections observe SDK state. They do not remove the need to subscribe to the right real-time topics where a platform exposes explicit topic subscriptions.

Live Object

A live object tracks one entity. The SDK can emit:

State	TypeScript	iOS	Android	Flutter
Current data	`snapshot.data`	`liveObject.snapshot`	emitted `T` value	emitted `T` value
Loading	`snapshot.loading`	`loadingStatus`	stream lifecycle / app state	stream lifecycle / app state
Error	`snapshot.error`	`error` or observer `error` parameter	`onError`	stream `onError`
Freshness/origin	`origin`	`dataStatus`	not exposed as a shared public enum	not exposed as a shared public enum

Typical screens: post detail, message detail, channel profile, community header, user profile, room detail, or stream detail.

Live Collection

A live collection tracks a list. The SDK can append, refresh, or re-emit the list when local cache, server fetches, or real-time events change the underlying data.

Capability	TypeScript	iOS	Android	Flutter
Current list	`collection.data`	`collection.snapshots`	`PagingData<T>` or `List<T>` emission	`LiveResult<T>.data`
Loading	`collection.loading`	`loadingStatus`	paging load state / Rx lifecycle	`LiveResult<T>.isFetching` and `observeLoadingState()`
Next page	`collection.onNextPage?.()`	`collection.nextPage()`	collect more through Paging 3	`collection.loadNext()`
Reset	Recreate the query or collection	`collection.resetPage()`	invalidate/recreate the paging source or query	`collection.reset()`

Typical screens: post feeds, comment threads, chat messages, channel lists, member lists, reaction lists, follower lists, rooms, streams, and notifications.

Usage Notes

Keep the live subscription for as long as the UI needs updates.
Clean up subscriptions when the screen, component, view model, or widget is disposed.
Treat the first emission as potentially local or loading unless the platform exposes freshness status and it says otherwise.
Do not assume all platforms expose identical states. Use each platform’s native live primitive.
For TypeScript, subscribe to the relevant topic when you need cross-device real-time updates, then dispose both the repository observer and the topic subscription.

Platform Guides

TypeScript

Observe live objects and collections with callbacks, pagination helpers, and topic subscriptions.

iOS

Use AmityObject, AmityCollection, notification tokens, and published snapshots.

Android

Use RxJava Flowable, Android Paging 3, and the coroutine asFlow() bridge.

Flutter

Use Dart streams, LiveCollection, LiveResult, and collection disposal.

Real-time Events

Learn how real-time events update SDK state.

Presence State

Track user, channel, and room presence.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Live Objects & Collections

Platform Surface

Data Sources

Live Object

Live Collection

Usage Notes

Platform Guides

TypeScript

iOS

Android

Flutter

Real-time Events

Presence State

​Platform Surface

​Data Sources

​Live Object

​Live Collection

​Usage Notes

​Platform Guides

TypeScript

iOS

Android

Flutter

​Related Topics

Real-time Events

Presence State

Platform Surface

Data Sources

Live Object

Live Collection

Usage Notes

Platform Guides

Related Topics