Getting Started
Quick Start
Quick start
ℹ️
Before you begin
The Discord user you display must join the official community and run /confirm. Otherwise PresenceKit will not return their presence.
recipes
Each example assumes bun add @iconical/presencekit and an opted-in Discord user ID.
Read status, games, and Spotify
basic-usage.tstypescript
import {
createPresenceClient,
getPlayingActivities,
getCustomStatus,
getSpotifyNowPlaying,
} from "@iconical/presencekit";
const client = createPresenceClient();
const result = await client.getPresence("123456789012345678");
if (result.presence) {
console.log("Status:", result.presence.status);
console.log("Games:", getPlayingActivities(result.presence));
console.log("Custom status:", getCustomStatus(result.presence)?.state);
console.log("Spotify:", result.spotify ?? getSpotifyNowPlaying(result.presence));
} else {
console.log("Status not available yet:", result.availability);
}Add a live React card
MyStatus.tsxtsx
"use client";
import { LivePresenceCard } from "@iconical/presencekit/react-ui";
export function MyStatus() {
return (
<LivePresenceCard
userId="123456789012345678"
transport="auto"
theme={{ accent: "#ac1c23" }}
loadingFallback={<p>Connecting…</p>}
errorFallback={<p>Presence unavailable.</p>}
/>
);
}Show every activity, not just the first one
CustomStatus.tsxtsx
"use client";
import { usePresence } from "@iconical/presencekit/react";
import { ActivityArtwork } from "@iconical/presencekit/react-ui";
export function Activities({ userId }: { userId: string }) {
const { data, loading, error } = usePresence({ userId });
if (loading) return <p>Loading…</p>;
if (error || !data?.presence) return <p>No current activities.</p>;
return (
<ul>
{data.presence.activities.map((activity, index) => (
<li key={activity.id ?? `${activity.name}-${index}`}>
<ActivityArtwork activity={activity} preferred="icon" size={40} />
{activity.name} — {activity.details ?? activity.state ?? "Active"}
</li>
))}
</ul>
);
}Fetch a roster in a single request
multi-user.tstypescript
const ids = ["123456789012345678", "234567890123456789"];
const result = await createPresenceClient().getPresences(ids);
for (const [id, person] of Object.entries(result.presences)) {
console.log(id, person.profile.displayName, person.presence?.status);
}Only authorized IDs are returned; some requested IDs may be missing. For live rosters use batch subscriptions or LiveTeamCards.
Was this page helpful?