Comment Section

CommentSectionProvider setup and the useCommentSection hook reference

CommentSectionProvider loads and manages all comment state for a given entity. Descendant components access this state through useCommentSection.

Setting Up CommentSectionProvider

Identify the target entity with one of four mutually exclusive props:

import { CommentSectionProvider } from "@sublay/react-js";

// By foreign ID (most common — links to your own content)
<CommentSectionProvider foreignId="your-article-id" createIfNotFound>
  <CommentList />
</CommentSectionProvider>

// By Sublay entity ID
<CommentSectionProvider entityId="ent_abc123">
  <CommentList />
</CommentSectionProvider>

// By short ID
<CommentSectionProvider shortId="x7k2m">
  <CommentList />
</CommentSectionProvider>

// By passing the entity object directly (no fetch needed)
<CommentSectionProvider entity={myEntity}>
  <CommentList />
</CommentSectionProvider>

Provider Props Reference

entityId · string

Sublay entity ID. Mutually exclusive with foreignId, shortId, and entity.

foreignId · string

Your system’s ID for the entity.

shortId · string

Auto-generated short ID.

entity · Entity

A pre-fetched entity object. Skips the entity fetch.

createIfNotFound · boolean

Only valid with foreignId. Auto-creates the entity if it doesn’t exist yet.

limit · number

Comments per page. Default: 15.

defaultSortBy · string

Initial sort order: "top" (default), "createdAt", or "controversial". "new"/"old" are deprecated aliases for "createdAt" (removed in v8).

defaultSortDir · "asc" | "desc"

Initial sort direction for sortBy: "createdAt". Default: "desc" (newest first).

highlightedCommentId · string

If provided, fetches this comment and its parent and injects it into the tree. Useful for deep-linking to a specific comment.

callbacks · Record<string, function>

Optional callback functions for handling UI interactions:

• loginRequiredCallback() — called when a non-authenticated user tries to comment
• usernameRequiredCallback() — called when the user has no username set
• commentTooShortCallback() — called when the submitted comment is too short

mentionTriggers · { user?: string; space?: string }

Override the trigger characters for mentions. Defaults: { user: "@", space: "#" }.

Accessing State with useCommentSection

import { useCommentSection } from "@sublay/react-js";

function CommentList() {
  const {
    comments,
    newComments,
    loading,
    hasMore,
    loadMore,
    sortBy,
    setSortBy,
    createComment,
  } = useCommentSection();

  return (
    <>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="top">Top</option>
        <option value="createdAt">New</option>
      </select>
      {loading && <p>Loading...</p>}
      {[...newComments, ...comments].map((c) => (
        <CommentItem key={c.id} comment={c} />
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}

useCommentSection Return Values

entity · Entity | null | undefined

The entity these comments belong to.

comments · Comment[]

Paginated root-level comments (not newly submitted ones).

newComments · Comment[]

Comments submitted in this session. Displayed separately from paginated results, sorted newest-first.

entityCommentsTree · EntityCommentsTree

The full comment tree as a flat map keyed by comment ID. Used for building threaded reply UIs.

highlightedComment · { comment: Comment; parentComment: Comment | null } | null

The highlighted comment (and its parent, if any) when highlightedCommentId is set.

loading · boolean

true while the initial comment load is in progress.

hasMore · boolean

true when more pages are available.

submittingComment · boolean

true while a createComment call is in flight.

loadMore · () => void

Loads the next page of comments.

sortBy · CommentsSortByOptions | null

Current sort: "createdAt", "top", or "controversial". ("new"/"old" are deprecated aliases for "createdAt".)

setSortBy · (newSortBy: CommentsSortByOptions) => void

Changes the sort order and resets to page 1.

sortDir · "asc" | "desc"

Current sort direction for sortBy: "createdAt".

setSortDir · (newSortDir: "asc" | "desc") => void

Changes the sort direction and resets to page 1.

createComment · (props) => Promise<Comment | undefined>

Submits a new comment. Applies an optimistic placeholder immediately. Accepts:

• parentId — reply to a specific comment ID
• content — text content
• gif — GIF data object
• mentions — array of Mention objects
• autoReaction — automatically react with this reaction type after creating (e.g. "upvote")

updateComment · (props: { commentId: string; content: string }) => Promise<void>

Updates a comment’s text content.

deleteComment · (props: { commentId: string }) => Promise<void>

Marks a comment as deleted (Reddit-style placeholder). The comment remains in the tree with its content hidden.

selectedComment · Comment | null

Currently selected/focused comment. Managed via setSelectedComment.

setSelectedComment · (comment: Comment | null) => void

Set or clear the selected comment.

repliedToComment · Partial<Comment> | null

The comment currently being replied to.

setRepliedToComment · (comment: Comment | null) => void

Set the comment to reply to.

showReplyBanner · boolean

Whether to show a reply indicator UI banner.

setShowReplyBanner · ({ newState }: { newState: boolean }) => void

Show or hide the reply banner.

pushMention · User | null

A user to auto-insert as a mention in the next comment. Set by handleShallowReply.

handleDeepReply · (comment: Comment) => void

Sets the reply target for a deep reply (reply appears nested under the parent comment).

handleShallowReply · (comment: Comment) => void

Sets the reply target for a shallow reply (reply appears at root level with an @mention).