Skip to main content
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 "@replyke/react-js";

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

// By Replyke 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
Replyke 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), "new", or "controversial".
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 "@replyke/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="new">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: "top", "new", or "controversial".
setSortBy
(newSortBy: CommentsSortByOptions) => void
Changes the sort order 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).