@stadionhq-v3/comments-react

React SDK for Stadion Comments & Reactions. Provides React hooks and components for easily integrating comments and reactions into your React application.

Installation

npm install @stadionhq-v3/comments-react @stadionhq-v3/comments-core @tanstack/react-query

Import Styles

The SDK includes default styles. Import them in your app:

import '@stadionhq-v3/comments-react/styles';

Or create your own custom styles using the CSS class names provided in the components.

Quick Start

1. Wrap your app with CommentsProvider

import { CommentsProvider } from '@stadionhq-v3/comments-react';

function App() {
  return (
    <CommentsProvider
      config={{
        apiUrl: 'https://api.yourdomain.com',
        userId: 'user-123',
        userName: 'John Doe',
        userEmail: '[email protected]',
        authToken: 'your-jwt-token',
      }}
    >
      <YourApp />
    </CommentsProvider>
  );
}

2. Use the CommentList component

import { CommentList } from '@stadionhq-v3/comments-react';

function Article({ articleId }) {
  return (
    <div>
      <h1>My Article</h1>
      <p>Article content...</p>

      <CommentList
        contentType="article"
        contentId={articleId}
        sort="newest"
        showCommentForm
        showReplies
      />
    </div>
  );
}

Components

CommentList

Displays a complete comment section with form, list, and pagination.

<CommentList
  contentType="article"
  contentId="article-123"
  sort="newest"
  limit={20}
  showCommentForm={true}
  showReplies={true}
  maxDepth={5}
/>

Comment

Displays a single comment with reactions and reply functionality.

<Comment
  comment={commentData}
  onReply={(content) => console.log('Reply:', content)}
  onEdit={(content) => console.log('Edit:', content)}
  onDelete={() => console.log('Delete')}
  onReact={(type) => console.log('React:', type)}
  showReplyButton
  showEditButton
  showDeleteButton
/>

CommentForm

Form for creating or editing comments.

<CommentForm
  onSubmit={(content) => handleSubmit(content)}
  onCancel={() => setEditing(false)}
  placeholder="Write a comment..."
  submitLabel="Post"
  maxLength={5000}
/>

ReactionButton

Button for adding reactions to content or comments.

<ReactionButton
  targetType="content"
  targetId="article-123"
  contentType="article"
  contentId="article-123"
  showLabel
  label="React"
/>

ReactionPicker

Popup picker for selecting reaction emojis.

<ReactionPicker
  onSelect={(type) => handleReaction(type)}
  onClose={() => setShowPicker(false)}
  selectedReaction={currentReaction}
/>

Hooks

useComments

Fetch comments for content.

const { data, isLoading, error } = useComments({
  contentType: 'article',
  contentId: 'article-123',
  page: 1,
  limit: 20,
  sort: 'newest',
});

useComment

Fetch a single comment.

const { data: comment } = useComment('comment-id');

useCreateComment

Create a new comment.

const createComment = useCreateComment();

await createComment.mutateAsync({
  contentType: 'article',
  contentId: 'article-123',
  content: 'Great article!',
  parentId: null,
});

useUpdateComment

Update a comment.

const updateComment = useUpdateComment();

await updateComment.mutateAsync({
  commentId: 'comment-id',
  data: { content: 'Updated content' },
});

useDeleteComment

Delete a comment.

const deleteComment = useDeleteComment();

await deleteComment.mutateAsync('comment-id');

useReplies

Fetch replies for a comment.

const { data: replies } = useReplies('comment-id', {
  page: 1,
  limit: 10,
});

useCommentCount

Get comment count for content.

const { data } = useCommentCount('article', 'article-123');
console.log(data?.count); // Total comments

useToggleContentReaction

Toggle a reaction on content.

const toggleReaction = useToggleContentReaction();

await toggleReaction.mutateAsync({
  contentType: 'article',
  contentId: 'article-123',
  reactionType: '👍',
});

useToggleCommentReaction

Toggle a reaction on a comment.

const toggleReaction = useToggleCommentReaction();

await toggleReaction.mutateAsync({
  commentId: 'comment-id',
  reactionType: '❤️',
});

useContentReactions

Get reaction summary for content.

const { data: reactions } = useContentReactions('article', 'article-123');
console.log(reactions?.total); // Total reactions
console.log(reactions?.byType); // { '👍': 5, '❤️': 3 }

useUserContentReaction

Get current user's reaction for content.

const { data: userReaction } = useUserContentReaction('article', 'article-123');
console.log(userReaction?.type); // '👍' or null

Custom Styling

All components use semantic class names for easy styling:

.comment-list {
}
.comment {
}
.comment-header {
}
.comment-author {
}
.comment-content {
}
.comment-footer {
}
.comment-form {
}
.reaction-picker {
}
.reaction-button {
}

Advanced Usage

Custom Comment Rendering

<CommentList
  contentType="article"
  contentId="article-123"
  renderComment={(comment) => (
    <div className="custom-comment">
      <img src={comment.authorAvatar} />
      <div>{comment.content}</div>
    </div>
  )}
/>

Custom Loading/Empty States

<CommentList
  contentType="article"
  contentId="article-123"
  renderLoading={() => <Spinner />}
  renderEmpty={() => <div>No comments yet!</div>}
  renderError={(error) => <Alert>{error.message}</Alert>}
/>

With Custom QueryClient

import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5000,
    },
  },
});

<CommentsProvider config={config} queryClient={queryClient}>
  <App />
</CommentsProvider>;

License

MIT