Api Reference

Shared Connections

ℹ️

Built for multiple widgets

Framework adapters already share connections by default. Use the core manager only when you need control over grouping or dynamic membership.

A page with several presence cards does not need one network connection per component. PresenceKit provides a shared connection manager that groups compatible subscriptions and reuses the same underlying browser-tab streams.

When to use it

A portfolio showing a profile card and a Spotify widget for the same Discord ID.
A team dashboard with overlapping groups of members.
A UI where the member list can change while the page remains open.
A diagnostic display showing aggregate connection health.

React, Vue, and Svelte adapters use the shared manager automatically. Use the core API below when you need explicit control.

Watch a dynamic roster

example.tstypescript

import { getSharedPresenceClient } from "@iconical/presence";

const manager = getSharedPresenceClient();
const roster = manager.watchPresences(
  ["123456789012345678"],
  {
    onUpdate(batch) {
      console.log(Object.keys(batch.presences));
    },
    onError(error) {
      console.error(error.message);
    },
  },
);

// Later, add a second approved user without losing cleanup control.
roster.setUserIds(["123456789012345678", "222222222222222222"]);

// When the view is destroyed:
roster.unsubscribe();

setUserIds() updates SDK-managed membership; it may reconnect an affected SSE batch. It does not send an in-band WebSocket command.

Shared browser connections

graph TD
  A[Profile widget] --> C[Shared manager]
  B[Spotify widget] --> C
  D[Team widget] --> C
  C --> E[Consent-filtered API batches]

Shared versus independent clients

API	Recommended use
`getSharedPresenceClient()`	Most browser applications with multiple widgets
`createPresenceConnectionManager()`	Custom lifecycle boundaries or isolated managers
`createPresenceClient()`	A single low-level request or independent subscription

The shared manager can track up to 250 distinct IDs in a group, but its underlying public API connections remain 25 IDs per batch. Connections are grouped by compatible transport and polling interval options. Sharing is local to the current JavaScript runtime or browser tab, not cross-tab.

Observe connection diagnostics

example.tstypescript

const stopObserving = manager.observeDiagnostics((state) => {
  console.log(state.mode);              // connecting | sse | poll | stopped
  console.log(state.activeConnections); // Number of active stream/poll groups
  console.log(state.subscribers);       // Number of interested subscribers
  console.log(state.lastError);         // Most recent error, if any
});

stopObserving();

Other fields include users and lastUpdateAt. Diagnostics are aggregate connection state, not a guarantee of availability for any individual user, and do not reveal user IDs or presence payloads.

Framework integration

React: usePresence, usePresences, useConnectionDiagnostics from @iconical/presence/react.
Vue: corresponding usePresence, usePresences, useConnectionDiagnostics composables from @iconical/presence/vue.
Svelte: createPresenceStore, createPresencesStore, createConnectionDiagnosticsStore from @iconical/presence/svelte.

These adapters clean up subscriptions when components unmount or stores lose subscribers. An isolated manager is useful for custom lifecycle needs but is not necessary for ordinary framework usage.

Privacy behavior

Even if a website requests an ID, the hosted API only returns users with valid active approval. When access is revoked, the manager clears stale data. See Privacy and consent and Multi-user.

Was this page helpful?

Multi User Features