Activity Feed

Install

pnpm exec vegastack-design verify activity-feed

pnpm dlx shadcn@4.21.0 add @vegastack/activity-feed

Usage

import {
  ActivityFeed,
  ActivityFeedItem,
  ActivityFeedList,
} from "@/components/ui/activity-feed";

<ActivityFeed>
  <ActivityFeedList>
    <ActivityFeedItem>{event}</ActivityFeedItem>
  </ActivityFeedList>
</ActivityFeed>;

Scope

• Owns the activity list, event presentation, filtering and order controls, and keyboard navigation.
• The host owns data fetching, merging, paging, filter/order state, and read acknowledgements.
• Compose with CommentThread, CommentComposer, and CommentDayDivider from comments.

Anatomy

Examples

Comments and events

import {
  ActivityEvent,
  ActivityFeed,
  ActivityFeedItem,
  ActivityFeedList,
  ActivityJumpToLatest,
  ActivityKindIcon,
  ActivityUnreadDivider,
  ActivityValue,
  useActivityFeedKeyboard,
} from "@/components/ui/activity-feed";
import { CommentComposer, CommentThread } from "@/components/ui/comments";

const feedRef = useActivityFeedKeyboard();

<ActivityFeed
  ref={feedRef}
  count={threads.length}
  filter={filter}
  onFilterChange={setFilter}
  order={order}
  onOrderChange={setOrder}
>
  <ActivityFeedList>
    {items.map((item) =>
      item.type === "event" ? (
        <ActivityFeedItem key={item.id}>
          <ActivityEvent
            actor={item.actor}
            icon={<ActivityKindIcon kind={item.kind} />}
            date={item.at}
          >
            changed status to <ActivityValue>{item.to}</ActivityValue>
          </ActivityEvent>
        </ActivityFeedItem>
      ) : (
        <ActivityFeedItem key={item.id} kind="thread">
          <CommentThread thread={item.thread} viewer={me} onReply={reply} />
        </ActivityFeedItem>
      ),
    )}
  </ActivityFeedList>
  <CommentComposer onSubmit={post} />
  <ActivityJumpToLatest target={latestBoundary} />
</ActivityFeed>;

The parts are presentational and data-agnostic: the host merges its comment threads and its change events into one list, applies the filter and the order, and pages them. Events sit 4px apart; a thread card or a divider keeps 12px around it. Each event leads with a 20px node in the same column as the comments' avatars — an ActivityKindIcon, the new value's StatusIcon or PriorityIcon, or the actor's avatar (icon="avatar") — then the actor, whose name opens their person hover card, the sentence with its ActivityValues, and the relative time.

Put CommentDayDivider (from comments) between items on different days, and one ActivityUnreadDivider before the first item the viewer hasn't seen; its onVisible fires once, when the line is half on screen. The host chooses whether observing that line acknowledges anything. ActivityJumpToLatest takes the host's latest-content boundary. It observes that element in its scrolling container, points toward it, and transfers focus after reaching it. It floats only while that boundary is off screen and the reader is scrolling, and fades about 1.5 seconds after they settle; hovering or focusing it holds it in place. forceVisible keeps a catch-up action available for content already on screen, and turning it on surfaces the control until the reader settles; capture a batch in onJump and acknowledge it in onReached. Replacing the target or interrupting with a gesture cancels an in-progress completion and calls onCancel, allowing the host to release its jump state. The control contains no read-state or data logic. The latest items are last in oldest-first order and first in newest-first order. The arrow points toward that boundary. Set direction="up" for newest-first or direction="down" for oldest-first when an on-screen batch keeps the action visible. An agent event says "Agent" after the actor's name.

Event kinds

ActivityKindIcon draws a 14px muted icon for twenty-eight common kinds; approved, rejected, requested and the agent-run kinds keep their status colour.

Status and priority values

A status or priority change leads with the new value's own icon. Pass label="" — the sentence already names the value.

Event groups

Pass pre-grouped events to ActivityEventGroup for one compact entry: the actor and latest timestamp appear once, every change stays visible in chronological order, and the sentence wraps under its text column. The host bounds a burst (two minutes, say), keeps actor, comment/reply, calendar-day and unread boundaries, and groups before reversing the entry order. Server comment-boundary markers let hidden replies separate edits too. Supply each event's stable id so its position survives joining a group across cursor pages.

The children-based form remains available for explicitly folded rows (visible and defaultOpen).

Runs

groupActivityRuns(items, { actorKey, date, isBreak, breakBefore, runWindowMs }) splits a chronological list into runs: one actor's consecutive events within runWindowMs (10 minutes by default) of the run's first, ended by any isBreak item (a comment) or the host's own breakBefore (a new day, the unread line). Render each run with ActivityEventGroup. Give events a change — { field, verb?, from?, to } — and a run that changes one field reads as one chain: "moved it Todo → In progress → In review". Set summarizeAt={3} and a run of three or more different changes reads "made 3 changes" (or summarizeRun's words), a disclosure that lists them under the line. Agents' bursts read as one line this way.

const runs = groupActivityRuns(items, {
  actorKey: (item) => item.actorId,
  date: (item) => item.createdAt,
  isBreak: (item) => item.type === "comment",
});

{
  runs.map((run) => (
    <ActivityFeedItem key={run[0].id}>
      <ActivityEventGroup events={run.map(toEventProps)} summarizeAt={3} />
    </ActivityFeedItem>
  ));
}

Cursor pagination

Pass loadMore={{ hasMore, onLoadMore, loading, error }} and a paginationKey containing the filter, list generation and next cursor to ActivityFeed. The history edge loads automatically when it enters view: above the list oldest first, below it newest first. Loading older items preserves the current visible change in both orders, including when you scroll during the request or the page joins an existing group. While a page loads, skeleton event rows hold its place. Set loadMore.error after a failed read; automatic retries stop and a Retry button appears. loadingMoreLabel and retryMoreLabel override the pagination copy. Keep an unread divider within the same timeline rather than paginating unread items separately.

Agents and the system

An actor (or comment author) with kind: "agent" and via — "Claude Code" working for Priya — is drawn as the purple bot and named "Claude Code via Priya" with the "Agent" label; a comment gets a violet bar. (The agent boolean on an event or a comment is the deprecated spelling of the same and goes away next release.) An event with actor={null} is the system's. An actor's badge (a string such as "Inactive", for someone deactivated or whose invite is pending) follows their name as a small muted outline badge, as everywhere a person is named.

Agent runs

delegated and undelegated mark a member handing a record to their agent and taking it back; agent-queued, agent-working, agent-needs-you, agent-done and agent-failed are the agent's run in its status tones (working is a static play mark — a history line never spins); agent-step is one server-written step of the run.

Comments only

The filter's Comments option: the host shows the threads alone.

Activity only

The filter's Activity option: the events alone.

Loading

ActivityFeedSkeleton holds the feed's shape — event rows, a thread card and the composer — while it loads. Set pending on ActivityFeed instead while a new filter or order loads: the old items stay, dimmed.

Empty

A record with no history yet shows the header and the composer.

API Reference

ActivityFeedItem

ActivityEvent

ActivityEventGroup

ActivityJumpToLatest

Accessibility

• The feed is a section labelled by its heading; the items are an ordered list named "Activity".
• The filter is a select named "Show"; the order toggle is a button whose label names the order shown.
• An event is one sentence: the event's icon is decorative, the actor's name is a button that opens their hover card, and the relative time shows the exact time on hover or focus.
• Combined event groups keep every change visible and announce the actor and time once. A chain's arrows read as "to". A folded run ("made 3 changes") and the children-based disclosure are buttons with aria-expanded; the folded run's button names the list it controls.
• The heading's count says what it counts through countLabel ("Activity 2 comments").
• The unread line is a separator named "New".
• "Jump to latest" is hidden from assistive technology and out of the tab order while it is not shown; activating it moves focus to the "Latest activity" spot it scrolled to.
• J and K never fire while focus is in a field, a menu, a listbox or a dialog, with a modifier held, or when something else already handled the key. With several feeds on a page, the one holding focus answers (else the one mounted last); X ignores an item that has left the list.
• Scrolling (J/K, Jump to latest) is instant when the viewer prefers reduced motion.

Do / Don't