Presence Component List Room

[steep haven]

How can I use the listRoom function when I use the usePresence react hook?

[midnight pewter]

Hi @steep haven. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

The knowledge sources only briefly mention this functionality and don’t show a full example of using listRoom (or similarly named functions) together with the usePresence React hook, so I can’t give you an exact, documented pattern. However, here’s what is clear from the docs:

• The @convex-dev/presence Convex component exposes extra server-side helpers “for querying presence for a given user or room,” and explicitly calls out a listUser function as an example. [Presence component]
• On the client, the most common pattern is to use the usePresence hook, which handles heartbeats and disconnects and gives you a live-updating list of users in a room. [Presence component]

Putting those together:

1. usePresence is for live room presence in React.
   You call it like:

   import { api } from "../convex/_generated/api";
   import usePresence from "@convex-dev/presence/react";
   
   const presenceState = usePresence(api.presence, "my-chat-room", userIdOrName);
   

   This already subscribes you to presence changes for that room and returns the current list of users (plus handles heartbeats). [Presence component]

2. listRoom-style helpers are server-side utilities.
   The docs say the component interface “includes additional functions for maintaining presence state and for querying presence for a given user or room,” and give listUser as an example. [Presence component]
   By analogy, a listRoom function would be called from Convex query functions (or mutations) on the server, not directly from the React usePresence hook.

3. How to combine them conceptually:

   • Use usePresence in React whenever you want a live list of users in a specific room.
   • If you need a server-side query that lists presence for a room (e.g., for admin tools, batch processing, or non-reactive contexts), you’d:
     • Import the Presence helper in a Convex query.
     • Call its listRoom/room-listing helper there.
     • Then, from React, call that query with useQuery if you need that data in the UI. [Presence component]

Because the sources don’t show the exact listRoom signature or a concrete example of wiring it to usePresence, I can’t provide a precise code snippet for that specific function. If you share your generated components.presence types or the exact API surface you see in your project, I could help you map which function to call from a Convex query and how to consume it with useQuery alongside usePresence.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: