# Occupancy Occupancy enables you to view the number of users currently online in a room. This feature can be used to display user counts to highlight popular, or trending chat rooms. ## Subscribe to room occupancy Subscribe to a room's occupancy by registering a listener. Occupancy events are emitted whenever the number of online users within a room changes. Use the [`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#subscribe)[`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/subscribe%28%29-3loon)[`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/subscribe.html) method in a room to receive updates: Use the [`collectAsOccupancy()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-occupancy.html) extension function to observe occupancy changes reactively in Jetpack Compose: Subscribe to a room's occupancy with the [`useOccupancy`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useOccupancy.html) hook. ```javascript const {unsubscribe} = room.occupancy.subscribe((event) => { console.log(event); }); ``` ```react import { useOccupancy } from '@ably/chat/react'; const MyComponent = () => { const { connections, presenceMembers } = useOccupancy({ listener: (occupancyEvent) => { console.log('Number of users connected is: ', occupancyEvent.occupancy.connections); console.log('Number of members present is: ', occupancyEvent.occupancy.presenceMembers); }, }); return (

Number of users connected is: {connections}

Number of members present is: {presenceMembers}

); }; ``` ```swift let occupancySubscription = room.occupancy.subscribe() for await event in occupancySubscription { occupancyInfo = "Connections: \(event.occupancy.presenceMembers) (\(event.occupancy.connections))" } ``` ```kotlin val subscription = room.occupancy.subscribe { event: OccupancyEvent -> println("Number of users connected is: ${event.occupancy.connections}") println("Number of members present is: ${event.occupancy.presenceMembers}") } ``` ```jetpack import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room import com.ably.chat.extensions.compose.collectAsOccupancy @Composable fun OccupancyComponent(room: Room) { val occupancy by room.collectAsOccupancy() Text("Number of users connected: ${occupancy.connections}") Text("Number of members present: ${occupancy.presenceMembers}") } ```
### Occupancy event structure The following is the structure of an occupancy event: ```json { "type": "occupancy.updated", "occupancy": { "connections": 103, "presenceMembers": 95 } } ``` ```json { "connections": 103, "presenceMembers": 95 } ``` The following are the properties of an occupancy event: | Property | Description | Type | | -------- | ----------- | ---- | | type | The type of the occupancy event. | String | | occupancy | The occupancy data for the room. | OccupancyData | | | `connections`: The number of connections in the room. | Number | | | `presenceMembers`: The number of users entered into the [presence set](https://ably.com/docs/chat/rooms/presence) of the room. | Number | | Property | Description | Type | | -------- | ----------- | ---- | | connections | The number of connections in the room. | Number | | presenceMembers | The number of users entered into the [presence set](https://ably.com/docs/chat/rooms/presence) of the room. | Number | ### Unsubscribe from room occupancy Use the `unsubscribe()` function returned in the `subscribe()` response to remove a room occupancy listener: Jetpack Compose automatically handles lifecycle and cleanup when using `collectAsOccupancy()`. You don't need to handle removing listeners, as this is done automatically by the SDK. When you unmount the component that is using the `useOccupancy` hook, it will automatically handle unsubscribing any associated listeners registered for room occupancy. ```javascript // Initial subscription const { unsubscribe } = room.occupancy.subscribe((event) => { console.log(event); }); // To remove the listener unsubscribe(); ``` ```kotlin // Initial subscription val (unsubscribe) = room.occupancy.subscribe { event -> println(event) } // To remove the listener unsubscribe() ``` ## Current room occupancy The latest occupancy received in realtime (the same mechanism that powers occupancy subscriptions) can be retrieved in a one-off call. Use the [`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/current.html) property to retrieve the most recently received room occupancy: ```javascript const occupancy = room.occupancy.current; ``` ```swift let occupancy = room.occupancy.current ``` ```kotlin val occupancy = room.occupancy.current ``` ```jetpack val occupancy = room.occupancy.current ``` Use the [`connections`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#connections) and [`presenceMembers`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#presenceMembers) properties available from the response of the `useOccupancy` hook to view the occupancy of a room. The following is the structure of the occupancy data: ```json { "connections": 103, "presenceMembers": 95, } ``` The following are the properties of the occupancy data: | Property | Description | Type | | -------- | ----------- | ---- | | connections | The number of connections in the room. | Number | | presenceMembers | The number of users entered into the [presence set](https://ably.com/docs/chat/rooms/presence) of the room. | Number | ## Retrieve room occupancy The occupancy of a room can be retrieved in one-off calls instead of subscribing to updates. Use the [`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#get)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/get%28%29)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/get.html) method to retrieve the occupancy of a room: ```javascript const occupancy = await room.occupancy.get(); ``` ```swift let occupancy = try await room.occupancy.get() ``` ```kotlin val occupancy = room.occupancy.get() ``` ```jetpack val occupancy = room.occupancy.get() ``` Use the [`connections`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#connections) and [`presenceMembers`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseOccupancyResponse.html#presenceMembers) properties available from the response of the `useOccupancy` hook to view the occupancy of a room. The following is the structure the occupancy data: ```json { "connections": 103, "presenceMembers": 95, } ``` The following are the properties of an occupancy data: | Property | Description | Type | | -------- | ----------- | ---- | | connections | The number of connections in the room. | Number | | presenceMembers | The number of users entered into the [presence set](https://ably.com/docs/chat/rooms/presence) of the room. | Number |