Presence React component for Tailwind CSS v4
v1.0.0Added in 1.0.0
React presence indicators for collaboration: an avatar stack with status rings and a who-is-here list, typing, live cursors and last seen.
People joining pop into the stack on a quick spring and the others slide over; people leaving shrink away, and a status change only recolors the ring, so nobody jumps places. Hover or focus an avatar for the name and what they are doing (a long press on touch). Tap any avatar or the +N chip to open the full list, grouped as here now, away or busy, and offline with the time last seen: a popover on desktop, a bottom sheet on phones. Tab lands on the stack once; Left and Right (Home and End) move between avatars, Enter or Space opens the list, Escape closes it and focus returns to the avatar you pressed. The typing line fades in with the names, lingers 400ms after the last keystroke so it never flickers, and is announced politely. Cursors glide to each new position on a spring (they jump with reduced motion) and their name chip fades to the bare arrow after a few idle seconds. In the playground, Daniel can join and leave and Ryan can come back, while two scripted cursors move over the invoice.
Presence is a Pro React component in the React data display components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add presence, together with Avatar, Tooltip, Popover, Relative time, useLocale and 5 more and the npm package motion.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add presencePresence is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans
Usage
Import Presence from @/components/ui/presence.
import { Presence, PresenceCursors, TypingIndicator, type PresenceUser } from "@/components/ui/presence"
const users: PresenceUser[] = [
{ id: "ana", name: "Emma Carter", avatar: "/demo/ana-pop.jpg", status: "online" },
{ id: "mihai", name: "Michael Reed", status: "online", activity: "editing the lines" },
{ id: "radu", name: "Ryan Mitchell", status: "away" },
{ id: "vlad", name: "Lucas Grant", status: "offline", lastSeen: Date.now() - 40 * 60_000 },
]
export function InvoiceHeader() {
return (
<div className="relative rounded-3xl bg-surface p-5 shadow-raised">
<div className="flex items-center justify-between gap-3">
<h2 className="text-lg font-semibold">Invoice #2026-0412</h2>
<Presence users={users} currentUserId="ana" surfaceColor="var(--surface)" labels={{ group: "Viewing now" }} />
</div>
<TypingIndicator users={users.filter((user) => user.typing)} labels={{ typing: (names) => `${names[0]} is writing…` }} />
<PresenceCursors users={users} cursors={[{ userId: "mihai", x: 0.4, y: 0.6 }]} relative />
</div>
)
}Props
users*PresenceUser[]The people, in display order (put the current user first or last). { id, name, avatar?, color?, status?, lastSeen?, activity?, typing? }; status defaults to online. Duplicate ids: the last one wins, with a warning in development.
maxdefault4numberAvatars shown before the +N chip. When only one would hide, it shows instead of a +1. Fine up to a few hundred people: only max avatars render, the list renders every row (no virtualization).
sizedefault"sm""xs" | "sm" | "md" | "lg"Avatar size, 24 / 32 / 40 / 48px. Every size keeps a 44px hit area on touch screens.
indicatordefault"ring""ring" | "dot" | "none"ring: a 2px ring in the person's color, dashed amber while away, red while busy, none while offline. dot: the avatar's status dot. none: plain avatars. The status is also in every avatar's spoken label.
overlapdefault"md""sm" | "md" | "lg"How much neighbors overlap: 16 / 26 / 36% of the size (a little less with rings).
surfaceColordefault""stringThe surface behind the stack, used for the rings that separate the avatars. Empty means var(--background); pass var(--surface) or var(--card) on a panel. Sets --presence-surface.
showOfflinedefaultfalsebooleanKeeps offline people in the stack, dimmed and grayscale. Off, they only appear in the list.
summarydefaultfalsebooleanA line after the stack from labels.summary: "Emma, Michael and 3 others are here". Counts everyone who is not offline; wraps to two lines at most on narrow screens.
currentUserIddefault""stringMarks you with labels.you ("You") in the list and the spoken label, and is what hideSelf leaves out. The playground picks a teammate id.
hideSelfdefaultfalsebooleanLeaves the current user out of the stack. The list still shows you.
showListdefaulttruebooleanThe +N chip, and any avatar when there is no onUserClick, opens the full list: a popover on desktop, a bottom sheet below 768px. Off, +N is a plain count.
tooltipsdefaulttruebooleanThe name, status and activity on hover and keyboard focus (a long press on touch).
responsivedefaulttruebooleanThe list becomes a bottom sheet below 768px.
aligndefault"end""start" | "center" | "end"Which edge of the stack the list popover lines up with on desktop. end suits a stack in the top-right of a header; it shifts to stay on screen either way.
defaultOpendefaultfalsebooleanStarts with the list open (uncontrolled).
openbooleanControls the list; pair it with onOpenChange.
onOpenChange(open: boolean) => voidFires when the list opens or closes.
onUserClick(user: PresenceUser) => voidClicking an avatar (or a list row) calls this instead of opening the list, e.g. to jump to that person's cursor. +N still opens the list.
nowDate | numberThe reference time for last seen. Defaults to the live clock (useNow, once a minute); until it is known after hydration, times print as dates.
localedefault""stringLocale for last seen times. Empty uses UIProvider's locale, then the page's.
labelsPartial<PresenceLabels>Every string: group "People here", more(n) "+n", morePeople(n) "n more people", summary(names, rest), you, unknown, online, away, busy, offline, here "Here now", idle "Away or busy", lastSeen(text) "Seen {text}", at, typing(names). DEFAULT_PRESENCE_LABELS has the English set.
classNamesPartial<Record<"avatar" | "ring" | "overflow" | "summary" | "popover" | "list" | "group" | "row" | "self", string>>Extra classes for the inner parts.
classNamestringExtra classes for the root, merged last.
Parts
PresenceList
componentThe list the popover shows, exported for side panels: rows with the avatar and its status dot, the name (and a You chip), the activity, and the status word or last seen. Grouped here now, away or busy, offline. Props: { users; currentUserId?; grouped? = true; onUserClick?; now?; locale?; labels?; classNames? }.
TypingIndicator
componentPass only the people typing. text: three rising dots and "Julia is typing…" (two names, then "Several people are typing…"); dots: the dots alone; bubble: the dots in a chat bubble. role="status", polite; lingers 400ms after the list empties. Reads UIProvider defaults as "typing-indicator". Props: { users; variant?: "dots" | "text" | "bubble" = "text"; showAvatars? = true; size?: "sm" | "md" | "lg" = "md"; surfaceColor?; labels?; classNames? }.
PresenceCursor
componentOne live cursor: an arrow in the person's color with a white (dark mode: black) outline and a name chip with black or white text by contrast. New x / y feed a spring (no re-render per frame); it fades out when hidden or outside its container, and the chip fades to the arrow after idleAfter ms (0 never). Reads UIProvider defaults as "presence-cursor". Props: { user; x; y; label?; mode?: "spring" | "instant" = "spring"; idleAfter? = 5000; hidden?; color?; showName? = true }.
PresenceCursors
componentA pointer-events-none layer (absolute inset-0) over a relative container, one PresenceCursor per { userId, x, y, label? }. relative: x and y are 0 to 1 of the container. Decorative (aria-hidden); the list says who is here. Props: { cursors: CursorPosition[]; users: PresenceUser[]; relative?; mode?; idleAfter?; showNames? = true; classNames? }.
LastSeen
componentA <time> with "Seen 5 min ago", "Seen yesterday at 6:20 PM", then the date; the full date and time in its title. The wording comes from labels.lastSeen. Props: { value; now?; locale?; labels?; prefix? = true }.
presenceColor
functionThe user's color, else the stable avatarColor(name): the ring, the cursor and the chip use it. Signature: (user: { name; color? }) => string.
DEFAULT_PRESENCE_LABELS
constantThe English labels, to spread under your own. Type: PresenceLabels.
Examples
Sizes and indicators
xs to lg, and ring (dashed amber away, red busy), the avatar's status dot, or nothing.
Summary text
A custom labels.summary after the stack: who is looking at the quote right now.
Typing indicator
text, dots and bubble with one, two and four people; the names come from labels.typing.
Live cursors
Move over the board: your pointer comes back as Michael's cursor 250ms later, gliding on a spring.
Who is here, as a list
PresenceList in a side panel: online first, then away or busy, then offline with the last time seen.
Offline people in the stack
showOffline keeps offline people in the stack, dimmed and without a ring.
Dependencies
Files
- components/ui/presence.tsx
FAQ
Is the React Presence component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install Presence?
Run npx wingo-ui@latest add presence. It also adds the Wingo UI items it builds on (Avatar, Tooltip, Popover, Relative time, useLocale and 5 more) and the npm package motion. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/presence.
How does Presence behave on phones?
The list becomes a bottom sheet below 768px. The responsive prop controls this and is on by default.