Scopes | LiveKit Docs

What is a Scope

Scopes are CompositionLocalProviders that are used to allow child composables to access parent state without the need to pass it via method arguments throughout composition. In return, this means that if a composable depends on some scope you have to make sure that this scope is provided somewhere higher up in the composition.

// ✅ This works!
// rememberRoomInfo depends on the RoomLocal which is provided by RoomScope.
@Composable
fun MyPage() {
  RoomScope {
    val roomInfo = rememberRoomInfo()
  }
}

// ✅ This works!
// The RoomScope does not have to be a immediate parent of the composable needing RoomLocal.
@Composable
fun MyPage() {
    RoomScope {
        MyCustomComposable()
    }
}

@Composable
fun MyCustomComposable() {
    val roomInfo = rememberRoomInfo()
}

// ❌ This will cause an error!
// rememberRoomInfo depends on a parent scope to provide the RoomLocal.
@Composable
fun MyPage() {
  RoomScope {}
  val roomInfo = rememberRoomInfo()
}

The two most important scopes are:

RoomScope

The RoomScope provides the Room object as a composition local.

/* 1️⃣ RoomScope provides the RoomLocal. */
RoomScope(
  url = "server-url",
  token = "user-access-token",
  connect = true,
) {
  /* 2️⃣ rememberRoomInfo uses the RoomLocal to retrieve information about the room. */
  val roomInfo = rememberRoomInfo()
}

ParticipantScope

The ParticipantScope provides a Participant object as a composition local.

/* 1️⃣ ParticipantScope provides the ParticipantLocal. */
ParticipantScope(participant = room.localParticipant) {

  /* 2️⃣ rememberParticipantTrackReferences uses the ParticipantLocal to get the participant's tracks. */
  val participantTracks = rememberParticipantTrackReferences()
}