# Presence

> React presence indicators for collaboration: an avatar stack with status rings and a who-is-here list, typing, live cursors and last seen.

- Type: React component (Data Display)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add presence`
- Docs: https://wingo-ui.com/components/presence

## Interaction

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.

## Installation

```bash
npx wingo-ui@latest add presence
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/presence` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/presence.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [useLocale](https://wingo-ui.com/components/use-locale) ([Markdown](https://wingo-ui.com/components/use-locale.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |
| `max?` | `number` | `4` | Avatars 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). |
| `size?` | `"xs" \| "sm" \| "md" \| "lg"` | `"sm"` | Avatar size, 24 / 32 / 40 / 48px. Every size keeps a 44px hit area on touch screens. |
| `indicator?` | `"ring" \| "dot" \| "none"` | `"ring"` | 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. |
| `overlap?` | `"sm" \| "md" \| "lg"` | `"md"` | How much neighbors overlap: 16 / 26 / 36% of the size (a little less with rings). |
| `surfaceColor?` | `string` | `""` | The 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. |
| `showOffline?` | `boolean` | `false` | Keeps offline people in the stack, dimmed and grayscale. Off, they only appear in the list. |
| `summary?` | `boolean` | `false` | A 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. |
| `currentUserId?` | `string` | `""` | Marks you with labels.you ("You") in the list and the spoken label, and is what hideSelf leaves out. The playground picks a teammate id. |
| `hideSelf?` | `boolean` | `false` | Leaves the current user out of the stack. The list still shows you. |
| `showList?` | `boolean` | `true` | The +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. |
| `tooltips?` | `boolean` | `true` | The name, status and activity on hover and keyboard focus (a long press on touch). |
| `responsive?` | `boolean` | `true` | The list becomes a bottom sheet below 768px. |
| `align?` | `"start" \| "center" \| "end"` | `"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. |
| `defaultOpen?` | `boolean` | `false` | Starts with the list open (uncontrolled). |
| `open?` | `boolean` |  | Controls the list; pair it with onOpenChange. |
| `onOpenChange?` | `(open: boolean) => void` |  | Fires when the list opens or closes. |
| `onUserClick?` | `(user: PresenceUser) => void` |  | Clicking 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. |
| `now?` | `Date \| number` |  | The reference time for last seen. Defaults to the live clock (useNow, once a minute); until it is known after hydration, times print as dates. |
| `locale?` | `string` | `""` | Locale for last seen times. Empty uses UIProvider's locale, then the page's. |
| `labels?` | `Partial<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. |
| `classNames?` | `Partial<Record<"avatar" \| "ring" \| "overflow" \| "summary" \| "popover" \| "list" \| "group" \| "row" \| "self", string>>` |  | Extra classes for the inner parts. |
| `className?` | `string` |  | Extra classes for the root, merged last. |

## Parts

### PresenceList (component)

The 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 (component)

Pass 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 (component)

One 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 (component)

A 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 (component)

A <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 (function)

The 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 (constant)

The 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.

## See also

- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Chat Thread](https://wingo-ui.com/components/chat-thread) ([Markdown](https://wingo-ui.com/components/chat-thread.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))

---

Canonical: https://wingo-ui.com/components/presence
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt