Expand description

RoomListService API.

The RoomListService is a UI API dedicated to present a list of Matrix rooms to the user. The syncing is handled by SlidingSync. The idea is to expose a simple API to handle most of the client app use cases, like: Showing and updating a list of rooms, filtering a list of rooms, handling particular updates of a range of rooms (the ones the client app is showing to the view, i.e. the rooms present in the viewport) etc.

As such, the RoomListService works as an opinionated state machine. The states are defined by State. Actions are attached to the each state transition. Apart from that, one can apply Inputs on the state machine, like notifying that the client app viewport of the room list has changed (if the user of the client app has scrolled in the room list for example) etc.

The API is purposely small. Sliding Sync is versatile. RoomListService is one specific usage of Sliding Sync.

§Basic principle

RoomListService works with 2 Sliding Sync List:

  • all_rooms (referred by the constant ALL_ROOMS_LIST_NAME) is the main list. Its goal is to load all the user’ rooms. It starts with a SlidingSyncMode::Selective sync-mode with a small range (i.e. a small set of rooms) to load the first rooms quickly, and then updates to a SlidingSyncMode::Growing sync-mode to load the remaining rooms “in the background”: it will sync the existing rooms and will fetch new rooms, by a certain batch size.
  • visible_rooms (referred by the constant VISIBLE_ROOMS_LIST_NAME) is the “reactive” list. Its goal is to react to the client app user actions. If the user scrolls in the room list, the visible_rooms will be configured to sync for the particular range of rooms the user is actually seeing (the rooms in the current viewport). visible_rooms has a different configuration than all_rooms as it loads more timeline events: it means that the room will already have a “history”, a timeline, ready to be presented when the user enters the room.

This behavior has proven to be empirically satisfying to provide a fast and fluid user experience for a Matrix client.

RoomListService::all_rooms provides a way to get a RoomList for all the rooms. From that, calling RoomList::entries provides a way to get a stream of room list entry. This stream can be filtered, and the filter can be changed over time.

RoomListService::state provides a way to get a stream of the state machine’s state, which can be pretty helpful for the client app.


  • A collection of room filters.




Type Aliases§