This is exactly the kind of post I needed today. Saving for the weekend read.
Comment Thread
alphav0.6.0Recursive comment thread with composer, optimistic add, like, and delete, inline expansion past max depth, and realtime subscription hooks.
Context
Fifth ship in the social-posts-system arc. Since 0.4.0 the thread closes under the consumer contract: `comments` is read once at mount unless `onCommentsChange` is passed, which makes it controlled (pending operations show as an overlay over the prop; accepted changes are reported, not applied). Realtime via Subscribe<CommentDelta> is idempotent (id first, then `clientId`). Moderation (inline edit, tombstones, pin marker) is the opt-in feature item `comment-thread-moderation`, wired through the `moderation` prop; the base never imports it. Per-row engagement-bar is controlled by the thread state. No framer-motion, no textarea-autosize dep, no date-fns dep. Migration origin: kasder kas-social-front-v0 PostEngagementPanel.tsx.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/comment-threadAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/comment-thread-fixturespnpm dlx shadcn@latest add @ilinxa/comment-thread-moderationInline edit, tombstones that keep replies, and a pinned marker, wired in through the moderation prop.
CLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview
MS @miraTZ @theozHot take: most of what's framed as a system-design problem is actually a state-management problem dressed up. The boundaries we draw between services are usually load-bearing for our state model, not the other way around. Curious what others think about this — particularly in the context of the analytics-pipeline rewrite we shipped last quarter.
IP @inesBookmarked. Thanks for sharing — fixed a typo here, the original phrasing was misleading.
(edited)SA @sina(my own comment — kebab shows Delete)
LO @levFollowing.
HS @hanaI think I disagree with point 3 — but it depends on what you mean by 'eventual consistency' here. Are you describing the storage layer or the read model?
Demo source
"use client"; import { useMemo, useRef, useState } from "react";import { Card } from "@/components/ui/card";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { CommentThread } from "./comment-thread";import { CommentThreadRoot } from "./parts/comment-thread-root";import { CommentThreadList } from "./parts/comment-thread-list";import { CommentThreadLoadMore } from "./parts/comment-thread-load-more";import { CommentThreadComposer } from "./parts/comment-thread-composer";import { CommentThreadScrollArea } from "./parts/comment-thread-scroll-area";import { commentModeration } from "./features/moderation";import { commentDeleteConfirm } from "./features/confirm-delete";import type { Comment, CommentThreadHandle, CommentThreadSize } from "./types";import { DUMMY_CURSOR_FIRST_PAGE, DUMMY_FLAT_COMMENTS, DUMMY_LARGE_THREAD, DUMMY_MODERATION_COMMENTS, DUMMY_NESTED_DEPTH_2, DUMMY_NESTED_DEPTH_3, DUMMY_RTL_COMMENTS, DUMMY_RTL_VIEWER, DUMMY_VIEWER, createDummySubscribe, generateOlderPage, loadCursorPage, loadReplyPage,} from "./dummy-data"; const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)); function ConsoleSink({ tag, payload }: { tag: string; payload: unknown }) { // Demo-only no-op log helper. if (typeof console !== "undefined") { console.log(`[demo:${tag}]`, payload); }} function FlatTab() { return ( <CommentThread comments={DUMMY_FLAT_COMMENTS} currentUser={DUMMY_VIEWER} onAddComment={async (content) => { ConsoleSink({ tag: "add", payload: content }); }} onLikeComment={(id, liked) => ConsoleSink({ tag: "like", payload: { id, liked } }) } onDeleteComment={(id) => ConsoleSink({ tag: "delete", payload: id }) } onReportComment={(id) => ConsoleSink({ tag: "report", payload: id }) } /> );} function NestedDepth2Tab() { return ( <CommentThread comments={DUMMY_NESTED_DEPTH_2} currentUser={DUMMY_VIEWER} maxDepth={2} onAddComment={async (content, parentId) => { ConsoleSink({ tag: "reply", payload: { content, parentId } }); }} onLikeComment={(id, liked) => ConsoleSink({ tag: "like", payload: { id, liked } }) } /> );} function NestedDepth3Tab() { return ( <CommentThread comments={DUMMY_NESTED_DEPTH_3} currentUser={DUMMY_VIEWER} maxDepth={2} onAddComment={async (content, parentId) => { ConsoleSink({ tag: "reply", payload: { content, parentId } }); }} /> );} function PaginatedTab() { return ( <CommentThread comments={DUMMY_LARGE_THREAD} currentUser={DUMMY_VIEWER} pageSize={10} onAddComment={async (content) => { ConsoleSink({ tag: "add", payload: content }); }} onLoadMore={async (page) => { await wait(500); return generateOlderPage(page); }} /> );} /** * 0.6.0 compound: a height-capped panel (the in-place comments panel under a feed card). The list * scrolls in a focusable region and loads the next page as you near its end; the composer sits * below the scroll, always visible; Delete asks first (the confirm-delete add-on). */function PanelTab() { const [size, setSize] = useState<CommentThreadSize>("default"); return ( <div className="flex flex-col gap-3"> <div className="flex items-center gap-2"> <Button variant="outline" size="sm" aria-pressed={size === "touch"} onClick={() => setSize((s) => (s === "touch" ? "default" : "touch"))} > Touch size (44 px) </Button> </div> <Card className="max-w-xl gap-0 p-0"> <CommentThreadRoot comments={DUMMY_LARGE_THREAD} currentUser={DUMMY_VIEWER} pageSize={10} size={size} confirmDelete={commentDeleteConfirm} // The server's comment (a real id): your own comments can then be deleted (with a confirmation). onAddComment={async (content, _parentId, options) => { ConsoleSink({ tag: "add", payload: content }); await wait(300); return { id: `server-${options?.clientId ?? content}`, author: DUMMY_VIEWER, content, createdAt: new Date(), likes: 0, } satisfies Comment; }} onDeleteComment={async (id) => { ConsoleSink({ tag: "delete", payload: id }); }} onLoadMore={async (page) => { await wait(600); return generateOlderPage(page); }} className="gap-0" > <CommentThreadScrollArea className="max-h-96 px-4 pt-4"> <CommentThreadList /> <CommentThreadLoadMore mode="auto" className="py-3" /> </CommentThreadScrollArea> <CommentThreadComposer className="border-t border-border p-3" /> </CommentThreadRoot> </Card> </div> );} function RealtimeTab() { const subscribe = useMemo(() => createDummySubscribe(), []); return ( <CommentThread comments={DUMMY_FLAT_COMMENTS} currentUser={DUMMY_VIEWER} subscribe={subscribe} onSubscribeDelta={(d) => ConsoleSink({ tag: "delta", payload: d })} onAddComment={async (content) => { ConsoleSink({ tag: "add", payload: content }); }} onLikeComment={(id, liked) => ConsoleSink({ tag: "like", payload: { id, liked } }) } /> );} function DisabledComposerTab() { return ( <CommentThread comments={DUMMY_FLAT_COMMENTS} currentUser={undefined} composerEmptyState={ <Card className="flex items-center justify-between rounded-md p-3"> <span className="text-sm text-muted-foreground"> Sign in to join the conversation. </span> <Button size="sm" variant="default"> Sign in </Button> </Card> } /> );} function CompactVariantTab() { return ( <CommentThread variant="compact" comments={DUMMY_NESTED_DEPTH_2} currentUser={DUMMY_VIEWER} maxDepth={1} indentPx={16} /> );} /** Controlled thread: cursor paging, lazy replies, and a post that fails once so Retry shows. */function ControlledTab() { const [comments, setComments] = useState<Comment[]>(DUMMY_CURSOR_FIRST_PAGE); const [failNext, setFailNext] = useState(true); return ( <div className="flex flex-col gap-3"> <label className="flex items-center gap-2 text-sm text-muted-foreground"> <input type="checkbox" checked={failNext} onChange={(e) => setFailNext(e.target.checked)} /> Make the next post fail (the composer keeps your text; send again to retry) </label> <CommentThread comments={comments} onCommentsChange={(next) => setComments(next)} currentUser={DUMMY_VIEWER} pageSize={3} onLoadMoreCursor={loadCursorPage} onLoadReplies={loadReplyPage} onAddComment={async (content, _parentId, options) => { await wait(700); if (failNext) { setFailNext(false); throw new Error("The demo server said no"); } return { id: `server-${options?.clientId ?? content}`, author: DUMMY_VIEWER, content, createdAt: new Date(), likes: 0, } satisfies Comment; }} onLikeComment={async () => { await wait(300); }} onDeleteComment={async () => { await wait(300); }} onError={(error, context) => ConsoleSink({ tag: "error", payload: { error, context } })} /> </div> );} const REACTIONS = [ { key: "love", icon: <span aria-hidden="true">❤️</span>, label: "Love" }, { key: "laugh", icon: <span aria-hidden="true">😂</span>, label: "Laugh" }, { key: "wow", icon: <span aria-hidden="true">😮</span>, label: "Wow" },]; function ReactionsTab() { const comments = useMemo<Comment[]>( () => [ { ...DUMMY_FLAT_COMMENTS[0]!, id: "rx1", reactions: { viewerReaction: "love", counts: { love: 9, laugh: 2, wow: 1 }, totalCount: 12 }, }, { ...DUMMY_FLAT_COMMENTS[1]!, id: "rx2", reactions: { viewerReaction: null, counts: { love: 3, laugh: 8, wow: 0 }, totalCount: 11 }, }, { ...DUMMY_FLAT_COMMENTS[4]!, id: "rx3", likes: null, reactions: { viewerReaction: null } }, ], [], ); return ( <CommentThread comments={comments} currentUser={DUMMY_VIEWER} reactionKinds={REACTIONS} onReactComment={async (id, reaction) => { await wait(300); ConsoleSink({ tag: "react", payload: { id, reaction } }); }} /> );} /** The `comment-thread-moderation` add-on: edit, tombstones with replies, pin marker. */function ModerationTab() { const ref = useRef<CommentThreadHandle>(null); return ( <CommentThread ref={ref} comments={DUMMY_MODERATION_COMMENTS} currentUser={DUMMY_VIEWER} moderation={commentModeration} removedMode="tombstone" onEditComment={async (id, content) => { await wait(400); ConsoleSink({ tag: "edit", payload: { id, content } }); }} onDeleteComment={async () => { await wait(300); }} extraActions={(comment, { isOwn }) => isOwn ? [] : [ { label: "Hide (moderator)", separatorBefore: true, onClick: () => ref.current?.dispatch({ kind: "subscribe-delta", delta: { kind: "state", commentId: comment.id, state: "hidden" }, }), }, ] } /> );} // 0.5.0 — renderContent: turn @mentions and URLs into links without injecting HTML.function linkify(text: string) { return text.split(/(@\w+|https?:\/\/\S+)/g).map((part, i) => { if (part.startsWith("@")) { return ( <a key={i} href={`#/u/${part.slice(1)}`} className="font-medium text-foreground underline decoration-primary underline-offset-2"> {part} </a> ); } if (/^https?:\/\//.test(part)) { return ( <a key={i} href={part} className="underline underline-offset-2" target="_blank" rel="noreferrer"> {part} </a> ); } return part; });} const RICH_COMMENTS: Comment[] = DUMMY_FLAT_COMMENTS.map((c, i) => i === 0 ? { ...c, content: `${c.content} cc @marta, notes at https://ui.ilinxa.com/components/comment-thread` } : i === 1 ? { ...c, content: `@leo agreed. ${c.content}` } : c,); function RichLinksTab() { const [closed, setClosed] = useState(false); return ( <div className="flex flex-col gap-3"> <Button type="button" size="sm" variant="outline" className="self-start" aria-pressed={closed} onClick={() => setClosed((c) => !c)} > {closed ? "Reopen comments" : "Close comments"} </Button> <CommentThread comments={RICH_COMMENTS} currentUser={DUMMY_VIEWER} closed={closed} renderContent={(c) => <p className="whitespace-pre-wrap">{linkify(c.content)}</p>} getAuthorHref={(author) => (author.username ? `#/u/${author.username}` : undefined)} onAddComment={async (content) => { ConsoleSink({ tag: "add", payload: content }); }} onLikeComment={(id, liked) => ConsoleSink({ tag: "like", payload: { id, liked } })} /> </div> );} function TurkishTab() { return ( <CommentThread locale="tr" comments={DUMMY_NESTED_DEPTH_2} currentUser={DUMMY_VIEWER} labels={{ composerPlaceholder: "Yorum yaz…", composerSend: "Gönder", composerCancel: "İptal", like: "Beğen", unlike: "Beğenmekten vazgeç", reply: "Yanıtla", delete: "Sil", report: "Şikayet et", viewReplies: (count) => `${count} yanıtı gör`, loadMore: "Daha eski yorumlar", kebabAriaLabel: (name) => `${name} yorumu için işlemler`, replyTo: (name) => `${name} kişisine yanıt`, sending: "Gönderiliyor…", postFailed: "Yorumunuz gönderilemedi. Tekrar deneyin.", editedSuffix: "(düzenlendi)", showMore: "Devamını gör", showLess: "Daha az göster", closed: "Yorumlar kapatıldı.", engagement: { comment: "Yorum", share: "Paylaş", react: "Tepki ver" }, }} onReportComment={() => {}} /> );} function RtlTab() { return ( <div dir="rtl" lang="ar"> <CommentThread dir="rtl" locale="ar" comments={DUMMY_RTL_COMMENTS} currentUser={DUMMY_RTL_VIEWER} labels={{ composerPlaceholder: "اكتب تعليقاً…", composerSend: "إرسال", composerCancel: "إلغاء", like: "أعجبني", unlike: "إلغاء الإعجاب", reply: "رد", delete: "حذف", report: "إبلاغ", viewReplies: (count) => `عرض ${count} ردود`, sending: "جارٍ الإرسال…", postFailed: "تعذّر إرسال تعليقك. حاول مرة أخرى.", }} onAddComment={async () => { await wait(400); }} /> </div> );} export default function CommentThreadDemo() { const [tab, setTab] = useState("flat"); return ( <Tabs value={tab} onValueChange={setTab} className="w-full"> <SwipeTabsList> <TabsTrigger value="flat">Flat</TabsTrigger> <TabsTrigger value="depth2">Nested d2</TabsTrigger> <TabsTrigger value="depth3">Nested d3</TabsTrigger> <TabsTrigger value="paginated">Paginated</TabsTrigger> <TabsTrigger value="panel">Panel (parts)</TabsTrigger> <TabsTrigger value="controlled">Controlled</TabsTrigger> <TabsTrigger value="moderation">Moderation</TabsTrigger> <TabsTrigger value="rich">Rich & links</TabsTrigger> <TabsTrigger value="reactions">Reactions</TabsTrigger> <TabsTrigger value="realtime">Realtime</TabsTrigger> <TabsTrigger value="disabled">No user</TabsTrigger> <TabsTrigger value="compact">Compact</TabsTrigger> <TabsTrigger value="tr">Türkçe</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> </SwipeTabsList> <TabsContent value="flat" className="mt-4"> <FlatTab /> </TabsContent> <TabsContent value="depth2" className="mt-4"> <NestedDepth2Tab /> </TabsContent> <TabsContent value="depth3" className="mt-4"> <NestedDepth3Tab /> </TabsContent> <TabsContent value="paginated" className="mt-4"> <PaginatedTab /> </TabsContent> <TabsContent value="panel" className="mt-4"> <PanelTab /> </TabsContent> <TabsContent value="controlled" className="mt-4"> <ControlledTab /> </TabsContent> <TabsContent value="moderation" className="mt-4"> <ModerationTab /> </TabsContent> <TabsContent value="rich" className="mt-4"> <RichLinksTab /> </TabsContent> <TabsContent value="reactions" className="mt-4"> <ReactionsTab /> </TabsContent> <TabsContent value="realtime" className="mt-4"> <RealtimeTab /> </TabsContent> <TabsContent value="disabled" className="mt-4"> <DisabledComposerTab /> </TabsContent> <TabsContent value="compact" className="mt-4"> <CompactVariantTab /> </TabsContent> <TabsContent value="tr" className="mt-4"> <TurkishTab /> </TabsContent> <TabsContent value="rtl" className="mt-4"> <RtlTab /> </TabsContent> </Tabs> );} Usage
When to use
Reach for CommentThread when you need a recursive comment panel under any content surface — posts, news articles, events, product reviews, document annotations. It composes expandable-text for long bodies and engagement-bar variant="compact" for the per-row like or reaction action.
Basic example
import { CommentThread } from "@/components/comment-thread";
export function Example() {
return (
<CommentThread
comments={post.comments}
currentUser={{ id: viewer.id, name: viewer.name, avatar: viewer.avatarUrl }}
onAddComment={async (content, parentId, options) => {
const created = await api.addComment(post.id, { content, parentId, clientId: options?.clientId });
return created; // swaps the pending comment for the real one
}}
onLikeComment={(id, nextLiked) => api.likeComment(id, nextLiked)}
onDeleteComment={(id) => api.deleteComment(id)}
onReportComment={(id) => openReportDialog(id)}
/>
);
}Controlled or read-once
Pass onCommentsChange and comments is controlled: it wins on every render, and accepted changes are reported as (next, change) — never applied locally. A change is accepted after its promise resolves (at once for a handler that returns nothing, and for realtime deltas, loaded pages and handle calls); until then it shows as an overlay, and a rejection drops the overlay and reports nothing. Without onCommentsChangethe tree is read once at mount (use the handle's reset(next) to push updates); changing comments then logs one development warning.
const [comments, setComments] = useState(initial);
<CommentThread
comments={comments}
onCommentsChange={(next, change) => setComments(next)}
currentUser={viewer}
onLikeComment={(id, liked) => api.like(id, liked)} // may return a promise
/>Posting, pending comments and failures
onAddComment(content, parentId, { clientId })— send theclientIdto your server and echo it in the realtimeaddedbroadcast: the echo then replaces your pending comment instead of duplicating it. Matching uses the comment id first, then theclientId.- A pending comment shows
labels.sendinginstead of a time. The built-in actions (like, reaction, reply, delete, report) are disabled and Edit is not offered while it is pending, so your handlers never receive its temporary id from them. Your own actions (extraActions,commentActions,engagementActions,renderNode) gethelpers.isPendingand must check it. Without anonAddCommenthandler a posted comment is a normal, local comment. - A rejected
onAddCommentremoves the pending comment, callsonError, keeps the text in the composer and showslabels.postFailed(role="alert"). Returning nothing keeps the pending comment until a delta orresetbrings the real one (controlled: it is removed when the call returns). onLikeComment,onReactComment,onDeleteCommentandonEditCommentmay return a promise; a rejection rolls the change back (a deleted subtree returns to its old position). Only the latest request per comment decides.optimistic={false}— no pending comment; likes and deletes wait for their promise.onError(error, { kind, commentId?, parentId? })— every failure above, plusload-moreandload-replies.
Paging and replies
<CommentThread
comments={page1.items}
nextCursor={page1.nextCursor} // first cursor; wins on every render
hasMore={page1.hasMore} // optional; wins over every heuristic
onLoadMoreCursor={(cursor) => api.comments(post.id, cursor)} // { items, nextCursor, hasMore? }
onLoadReplies={(commentId, cursor) => api.replies(commentId, cursor)}
/>onLoadMoreCursorwins over the page-numberonLoadMore(page). For the page-number loader, Load more shows while the thread holds at leastpageSizetop-level comments and the last page was full.- A comment with
replyCountlarger than its loadedrepliesshows "View N replies" whenonLoadRepliesis wired. Its first cursor iscomment.repliesCursor; "View more replies" follows while more exist. - A failed load shows an alert and a Retry button; a loading button is
aria-busyand keeps focus. Pages are de-duplicated.
Permissions and the kebab
Each comment's permissions beat the defaults: canDelete / canEdit = you wrote it, canReply = signed in, canReact = true, canReport = you did not write it (Report no longer shows on your own comments), canPin / canHide = false (they reach your slots through the helpers).
<CommentThread
comments={comments}
currentUser={viewer}
// appended after the defaults:
extraActions={(comment, { permissions }) => [
{ label: "Hide", hidden: !permissions.canHide, separatorBefore: true,
onClick: () => api.hide(comment.id) },
]}
// or take the whole menu over:
// commentActions={(comment, { isOwn, permissions, isPending }) => [...]}
/>CommentMenuItem.hidden leaves an item out (a menu with nothing left renders no kebab) and separatorBefore draws a divider.
Reactions per row
<CommentThread
comments={comments} // comment.reactions = { viewerReaction, counts, totalCount }
reactionKinds={[{ key: "love", icon: <Heart />, label: "Love" }]}
onReactComment={(id, reaction) => api.react(id, reaction)} // string | null (clear)
// engagementActions={(comment, { defaultActions }) => [...defaultActions, myAction]}
/>Without reactionKinds + onReactComment each row keeps the like. Comment.likes may be null: the count is withheld (no number, none in the accessible name).
Moderation add-on
Inline edit, tombstones and the pinned marker ship separately: pnpm dlx shadcn@latest add @ilinxa/comment-thread-moderation. The thread never imports it — pass it in.
import { commentModeration } from "@/components/comment-thread/features/moderation";
<CommentThread
comments={comments}
moderation={commentModeration}
onEditComment={(id, content) => api.edit(id, content)} // promise rolls back on reject
removedMode="tombstone" // a removed delta keeps the comment as a tombstone, replies below
/>- Edit appears for comments with
permissions.canEdit(your own by default) onceonEditCommentis wired. Save is optimistic (content,edited: true); a failure rolls back and the editor showslabels.editFailed. - A comment whose
stateis not"visible"renders as a tombstone and keeps its replies. Without the add-on such comments are left out with their replies (one development warning),onEditCommentshows no Edit item, andisPinnedis ignored.
Labels, locale and time
- Every string is in
labels(an omitted orundefinedkey keeps the English default, exported asdefaultCommentThreadLabels); strings that carry a value are functions:kebabAriaLabel(name),replyTo(name),viewReplies(count),tombstone(state). locale(default"en") drives relative times and counts: English keeps "5m"; other locales useIntl.RelativeTimeFormatand a long date past five weeks (timeZonefixes the zone).formatRelativeTime/formatCountoverride them;createRelativeTimeFormatter(locale, timeZone)is exported.- Relative text needs "now": pass
now, or the thread reads the clock after mount and every minute — the server render and the first client render print no relative text, so hydration matches. - Layout is RTL-safe (indent uses the inline-start edge). Wrap the thread in
dir="rtl"and passdirfor the reaction pickers' arrow keys.
Realtime via subscribe
const subscribe = useCallback<Subscribe<CommentDelta>>(
(handler) => channel.on("comment", handler),
[channel],
);
<CommentThread
comments={post.initialComments}
currentUser={viewer}
subscribe={subscribe}
onSubscribeDelta={(d) => analytics.track("comment-delta", d)}
/>Hosts must memoize subscribe via useCallback — identity changes trigger a clean teardown + re-call. Deltas are idempotent (a repeated added changes nothing) and also include state and reacted. An added delta whose parentId is unknown is dropped with one development warning.
Standalone composer
CommentComposer ships standalone for hosts that want the composer without the thread. A rejected onSubmit keeps the text and shows labels.postFailed (style it with errorClassName, observe it with onError):
import { CommentComposer } from "@/components/comment-thread";
<CommentComposer
currentUser={viewer}
placeholder="Share your thoughts…"
onSubmit={async (content) => api.addArticleComment(article.id, content)}
/>Notes
maxDepthdefaults to 2; past it, "view N replies" inline-expands. Override the link viarenderViewRepliesfor navigate-to-detail mode.currentUserabsent → bottom composer hidden. Render a sign-in CTA viacomposerEmptyState.renderNode,renderViewReplies, andrenderComposerare full-takeover slots. The composer slot'ssubmitnever rejects; a failure shows asstate.hasError.Comment.editedrenders an(edited)suffix; the realtime{ kind: "edited" }delta sets it.
Features
- v0.6.0 — compound parts: `CommentThreadRoot` (all state, the handle) with `CommentThreadList`, `CommentThreadLoadMore`, `CommentThreadComposer`, `CommentThreadScrollArea` and `useCommentThread()`; `CommentThread` is now Root + List + LoadMore + Composer with the same layout. Hand-assemble a height-capped panel with the composer below the scroll, or a list with no composer (which leaves the composer code out)
- v0.6.0 — `CommentThreadLoadMore mode="auto"`: the next page loads as the button nears the visible edge of the enclosing scroll area (or `scrollRoot`, or the viewport), one request at a time, no automatic retry after a failure, a polite status, the button kept for keyboard users
- v0.6.0 — `CommentThreadScrollArea`: a focusable, named scroll region (`labels.commentsRegion`), usable around any thread
- v0.6.0 — `confirmDelete`: ask before a delete from the row's menu, with the `comment-thread-confirm-delete` add-on's dialog (`labels.deleteTitle` / `deleteBody(hasReplies)` / `deleteConfirm` / `deleteCancel`) or your own function; Cancel returns focus to the row's menu trigger, a confirmed delete to the neighbouring row; `helpers.onDelete` in every helper bag and `handle.deleteComment(id)` (no confirmation) delete through the built-in path
- v0.6.0 — `size="touch"`: every control (row engagement bars, Reply, the actions menu trigger, the author-name link, Show more, View replies, Load more, the composers' buttons) has a hit area of at least 44 × 44 px; `CommentComposer` takes `size` too
- v0.6.0 — fixes: when the last page arrives and "Load older comments" goes away, focus moves to the first new comment also when a controlled host applies the page late; the "(edited)" suffix meets 4.5:1 contrast in light mode
- v0.5.0 — `renderContent(comment, { depth })`: your own links / mentions / hashtags inside the row's clamped body (Show more still works); the edit composer still edits the raw `content`
- v0.5.0 — labels reach every row: `labels.showMore` / `showLess`, and `labels.engagement` (all engagement-bar labels: comment, share, bookmark, view count, reaction picker); the thread's `like` / `unlike` win over `engagement.like` / `unlike`; avatar initials follow `locale`
- v0.5.0 — author links: `getAuthorHref(author, comment)` + `linkComponent`; the avatar link is hidden from assistive technology and the tab order, the name link is the one announced; name in `<bdi>`, `@handle` `dir="ltr"`
- v0.5.0 — `closed` + `labels.closed`: no composer (a notice instead; `renderComposer` is not called), no Reply, open reply composers close, `handle.openReply` / `focusComposer` do nothing (one development warning); likes and menus unchanged
- v0.5.0 — fix: the "View replies" link reports its real `aria-expanded` and sets `aria-controls` only while the list it controls is in the DOM
- v0.4.0 — controlled `comments` + `onCommentsChange(next, change)`: the prop wins on every render, pending operations show over it, accepted changes are reported once accepted
- v0.4.0 — idempotent realtime: an `added` delta for an id already shown never duplicates, and `clientId` (sent through `onAddComment(content, parentId, { clientId })`) reconciles your own echo with the pending comment
- v0.4.0 — rollback: a failed post removes the pending comment and keeps the text (`labels.postFailed`); like, reaction, delete and edit roll back when their promise rejects; latest request wins; `optimistic`, `onError`; no unhandled rejections
- v0.4.0 — pending comments cannot be liked, replied to or deleted, so a temporary id never reaches your server
- v0.4.0 — cursor paging (`onLoadMoreCursor`, `hasMore`, `nextCursor`) beside `onLoadMore(page)`; Retry on failure; replies loaded on demand (`onLoadReplies`, `replyCount`, `repliesCursor`)
- v0.4.0 — per-comment `permissions`, `extraActions` appended to the defaults, `hidden` / `separatorBefore` menu items; Report no longer shows on your own comments
- v0.4.0 — reactions per row (`reactionKinds` + `onReactComment`, `Comment.reactions`) or your own row actions (`engagementActions`); `likes: null` withholds a count
- v0.4.0 — every string is a label (`kebabAriaLabel(name)`, `replyTo(name)`, …); `locale`, `timeZone`, `now`, `formatRelativeTime`, `formatCount`; relative time renders only after mount, so the server and the first client render agree; indentation mirrors in RTL
- v0.4.0 — moderation add-on `comment-thread-moderation` (inline edit, tombstones that keep replies, pinned marker) through the `moderation` prop; `removedMode="tombstone"`
- v0.3.1 — the `renderComposer` slot now receives real helpers: `setValue` / `submit` / `cancel` were empty-bodied stubs, so a custom composer could not set a value, send, or clear
- Recursive Comment[] with optional `replies?` per node — depth-aware indentation
- maxDepth default 2; past it, inline-expand 'view N replies' (slot-overridable)
- Autosize composer (roll-our-own ~25-LOC hook; no react-textarea-autosize)
- Keyboard ergonomics — Enter submits, Shift+Enter newline, Escape cancels
- Optimistic add (head insertion top-level; tail insertion replies)
- Optimistic like flip via thread reducer (per-row engagement-bar always-controlled)
- Optimistic delete; a rejected promise restores the comment at its position
- Realtime via Subscribe<CommentDelta> — added / edited / removed / liked / state / reacted
- onSubscribeDelta callback fires for every delta regardless of mode
- v0.2.0 — `Comment.edited` first-paint flag + `(edited)` suffix render after timestamp; realtime `{ kind: "edited" }` delta also flips `edited:true` so first-paint and post-edit UI behave identically
- v0.2.0 — `CommentMenuItem.separatorBefore` opt-in divider above any kebab item (used by post-card's moderator section; reusable for host-grouped kebabs)
- v0.2.1 — F-cross-13 + F-S1 cleanup: `<CommentKebab>` drops `<Button asChild>` wrapper (shadcn CLI rewrites `asChild` to `render={…}` at install-time which breaks consumers on Radix); render trigger directly as `<button>` via `buttonVariants(…)`. Cross-procomp imports in `comment-node.tsx` converted to relative + specific-file paths. Zero public-API change.
- Pagination — onLoadMore(page) appends; pageSize default 10
- Inline reply composer per row (kasder UX); single composer in DOM at a time
- Default kebab from per-comment permissions — Delete (own), Report (others', when wired), Edit (with the moderation add-on); `extraActions` appends, `commentActions` takes over
- renderNode / renderViewReplies / renderComposer full-takeover slots
- composerEmptyState slot for sign-in CTA when currentUser absent
- Imperative handle — focusComposer / openReply / getCurrentComments / reset / dispatch
- commentReducer + useCommentState publicly exported (external state coordination)
- useAutosizeTextarea publicly exported (composer behaviour without the thread)
- CommentComposer publicly exported standalone (article-page hero CTAs)
- i18n via a typed labels object with English defaults (`defaultCommentThreadLabels`)
- a11y — role=article + aria-labelledby; aria-pressed on like; useId() per node
- Touch-friendly kebab via pointer-coarse:opacity-100 (Tailwind v4)