Comments and collaboration
Add comment threads to the documents in your app. React components handle replies, mentions, emoji reactions, resolving, and links to a specific comment, using the comment data from the Sanity App SDK.
Introduction to the comment components
React components for comment threads on Sanity documents: replies, mentions, reactions, resolve, and deep links, rendering data from the App SDK.
Get started with comments
Install @sanity/collaboration, connect it to the Sanity App SDK, and render a working comments panel on one document.
Use comments in Next.js
Render the comments panel in the Next.js App Router: the client boundary, the stylesheet import, and the styled-components setup.
Use comments in Sanity Studio
Use the comment components in a studio plugin, custom document view, or custom input, with the studio's theme and current user.
Link to a comment
Make a shared link open the comments panel on the comment it names, with wiring for each common router.
Enable mentions
Turn on the mention picker by giving the comments provider a list of users, and query for the mentions that result.
Comment on Portable Text
Add inline comments to a Portable Text editor: highlights under the commented words, linked to the comments panel.
Customize inline comments
Common ways to change what SDKPortableTextComments does once inline comments are wired into your editor.
Show comment counts
Show a comment count next to a field or row with CommentBadge, read the counts efficiently, and open a thread from the badge.
Show a comment preview
Show one comment in a popover from a badge or a highlighted range, and make a comments panel read-only.
Customize comment actions
Add, remove, and reorder the actions on a comment with commentActions and CommentActionBar.
Build a custom comment
Build your own comment card from the primitives the default Comment uses, keeping its behavior and accessibility.
Theme the comment components
Change how the comment components look through the Sanity UI theme, a few typed props, and composition.
Translate the UI text
Replace every string the comment components render with the labels on the provider and on each component.
Threads and comments
How comment threads are shaped: one field of one document, a first comment plus replies, and no separate thread record.
Users and identity
Why comments store user IDs, how names and avatars are looked up at render time, and where the user directory comes from.
Comment components
What each comment component is responsible for, how they nest, and what changes when you compose the primitives yourself.
Comment data flow
How comment data reaches the components as props and leaves through callbacks, and why the wiring lives in your own code.
SDK-wired comment components
What each export of @sanity/collaboration/sdk replaces, and when to use it or drop down to the SDK hooks.
Levels of abstraction in the comment stack
The two ladders of the collaboration stack, what renders and where data comes from, and what each rung trades.
Comment navigation and deep links
How CommentsProvider keeps one active comment address that makes comments addressable, revealable, and linkable.
Inline comments
How an inline comment anchors to a run of Portable Text and keeps its highlight on the same words as the text changes.
Design principles of the comment components
Six promises the comment components make, and what each one means for the code you write.
Comments in the App SDK
Read and write Sanity comments with the App SDK collaboration API: documents, fields, threads and live lists.
Read comments
Read the comments on one document with the App SDK, as a list or as threads, and handle loading and disconnected states.
Query comments
Query comments across documents with useCommentsQuery and a GROQ filter, and learn what the query reaches.
Write comments
Start threads, reply, edit, delete, resolve, and react with useCommentActions, and handle a failed write.
Anchor inline comments
Write an inline comment anchored to Portable Text with the App SDK, and re-anchor it when the text moves.
Use the SDK outside React
Read and write comments from plain TypeScript with @sanity/sdk/collaboration: scripts, servers, tests, or other frameworks.