> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Objects & Collections

> Understand how the social.plus SDKs expose live objects and live collections for cache-backed, real-time data.

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. |

<Info>
  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.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="TypeScript" icon="code" href="./typescript">
    Observe live objects and collections with callbacks, pagination helpers, and topic subscriptions.
  </Card>

  <Card title="iOS" icon="apple" href="./ios">
    Use `AmityObject`, `AmityCollection`, notification tokens, and published snapshots.
  </Card>

  <Card title="Android" icon="smartphone" href="./android">
    Use RxJava `Flowable`, Android Paging 3, and the coroutine `asFlow()` bridge.
  </Card>

  <Card title="Flutter" icon="mobile" href="./flutter">
    Use Dart streams, `LiveCollection`, `LiveResult`, and collection disposal.
  </Card>
</CardGroup>

## Related Topics

<CardGroup cols={2}>
  <Card title="Real-time Events" icon="radio-tower" href="/social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview">
    Learn how real-time events update SDK state.
  </Card>

  <Card title="Presence State" icon="activity" href="/social-plus-sdk/core-concepts/realtime-communication/presence-state/overview">
    Track user, channel, and room presence.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.