Docs
Comments

Comments

Add comments to text as marks.

💬 Comments

Add comments to your content to provide additional context, insights, or collaborate with others

Features

  • Add text comments as marks.
  • Comments can include explanations, suggestions, questions, notes, or ideas for content improvement.
  • Add a comment by selecting the text and using the comment button or hotkey Cmd+Shift+M.

Installation

npm install @udecode/plate-comments

Usage

import { createCommentsPlugin } from '@udecode/plate-comments';
 
const plugins = [
  // ...otherPlugins,
  createCommentsPlugin(),
];

Keyboard Interactions

KeyDescription
Cmd + Shift + M

Add a comment on the selected text.

API

createCommentsPlugin

Options

Collapse all

    The hotkey used to add a comment.

findCommentNode

Finds the comment node in the editor.

Parameters

Collapse all

    The editor instance.

    Additional options for finding the node.

findCommentNodeById

Finds the comment node in the editor by its ID.

Parameters

Collapse all

    The editor instance.

    The ID of the comment node to find.

getCommentCount

Gets the count of comments in a comment node.

Parameters

Collapse all

    The comment node.

getCommentKey

Generates a comment key based on the provided ID.

Parameters

Collapse all

    The ID of the comment.

getCommentKeyId

Extracts the comment ID from a comment key.

Parameters

Collapse all

    The comment key.

getCommentKeys

Returns an array of comment keys present in the given node.

Parameters

Collapse all

    The node to check for comment keys.

getCommentNodeEntries

Returns an array of node entries for comment nodes in the editor.

Parameters

Collapse all

    The editor instance.

getCommentNodesById

Returns an array of node entries for comment nodes with a specific ID in the editor.

Parameters

Collapse all

    The editor instance.

    The ID of the comment nodes to retrieve.

getCommentPosition

Calculates the position of a comment node relative to the editor.

Parameters

Collapse all

    The editor instance.

    The comment node for which to calculate the position.

getCommentUrl

Generates a URL with a query parameter for a specific comment ID.

Parameters

Collapse all

    The ID of the comment.

getElementAbsolutePosition

Calculates the absolute position of an HTML element relative to the document.

Parameters

Collapse all

    The HTML element for which to calculate the absolute position.

isCommentKey

Checks if a given key is a comment key.

Parameters

Collapse all

    The key to check.

isCommentNodeById

Checks if a given node is a comment with the specified ID.

Parameters

Collapse all

    The node to check.

    The ID of the comment.

isCommentText

Checks if a given node is a comment text node.

Parameters

Collapse all

    The node to check.

Returns

Collapse all

    true if the node is a comment text node.

removeCommentMark

Removes the comment mark from the editor.

Parameters

Collapse all

    The editor instance.

unsetCommentNodesById

Unsets comment nodes with the specified ID from the editor.

Parameters

Collapse all

    The editor instance.

    The ID of the comment nodes to unset.

CommentUser

An interface representing a user who can make comments.

Parameters

Collapse all

    The unique ID of the user.

    The name of the user.

    The URL of the user's avatar.

CommentStoreState

State

Collapse all

    The unique ID of the comment.

    A flag indicating whether the menu associated with this comment is currently open.

    The value currently being edited for this comment. If no editing is in progress, this value is null.

CommentsStoreState

An interface representing the state of the comments store.

State

Collapse all

    The unique ID of the currently logged in or active user.

    An object where each key is a user's unique ID and the corresponding value is an instance of the CommentUser type, representing the user's data.

    An object where each key is a comment's unique ID and the corresponding value is an instance of the TComment type, representing the comment's data.

    The unique ID of the currently active or focused comment.

    The unique ID of the comment that is currently being added.

    The new value to be added to the comments.

    Indicates whether the comment textarea is focused.

    A function that is invoked when a new comment is added. It accepts a partial comment object, which must include the user's ID.

    A function that is invoked when a comment is updated. It accepts a comment object, which must include the comment's ID.

    A function that is invoked when a comment is deleted. It accepts the unique ID of the comment to be deleted.

TComment

Attributes

Collapse all

    A unique ID for the comment.

    The Slate value of the comment.

    Timestamp when the comment was created.

    • Default: Date.now()

    Id of the author of the comment.

    Id of the parent comment it replies to.

    Whether the comment is resolved.

TCommentText

Attributes

Collapse all

    Indicates whether this is a comment. Multiple comments can be present in a single text node.

API Plugins

useHooksComments

Plugin hook for handling comments functionality in the editor.

Parameters

Collapse all

    The editor instance.

    The comments plugin.

withComments

Enhances the editor with comment-related functionality.

Parameters

Collapse all

    The editor instance.

    The comments plugin.

API Components

CommentDeleteButton

A button component for deleting a comment.

State

Collapse all

    The ID of the active comment.

    The editor instance.

    The ID of the comment.

    A function to call when the comment is deleted.

    A function to remove the comment.

    A function to set the active comment ID.

CommentEditButton

A button component for editing a comment.

State

Collapse all

    A function to set the menu open state.

    The comment object.

    A function to set the editing value.

CommentEditCancelButton

A button component for canceling the editing of a comment.

CommentEditSaveButton

A button component for saving the editing of a comment.

State

Collapse all

    The value of the editing value.

    A function to set the editing value.

    The ID of the comment.

    A function to call when the comment is updated.

    A function to update the comment.

    The value of the comment.

CommentEditTextarea

A textarea component for editing a comment.

State

Collapse all

    A function to set the editing value.

    The textarea ref.

    The value of the textarea.

CommentNewSubmitButton

A button component for submitting a new comment.

State

Collapse all

    The text of the comment being edited.

    A function to reset the new comment value.

    A function to add a comment.

    Whether the comment is a reply.

    The text of the submit button.

    A function to call when the comment is added.

    The ID of the active comment.

    The comment object.

    The value of the edited comment.

CommentNewTextarea

A textarea component for adding a new comment.

State

Collapse all

    The textarea ref.

    The placeholder of the textarea.

    The value of the textarea.

    A function to set the new value.

CommentProvider

A jotai provider for comment data.

Props

Collapse all

    Extends CommentStoreState.

    The scope of the provider.

CommentResolveButton

A button component for resolving/unresolving a comment.

CommentUserName

A div component for displaying the name of a comment user.

CommentsPositioner

A div component for positioning comments in the editor.

State

Collapse all

    The ID for the active comment.

    An object representing the current position of the comment (top and left coordinates).

CommentsProvider

A jotai provider for comments data and users data.

Props

    Extends CommentsStoreState.

useActiveCommentNode

A custom hook that retrieves the active comment node based on the active comment ID.

Returns

    • If there is an active comment ID, it returns the corresponding comment node.

    • If there is no active comment ID or the comment node is not found, it returns null.

useAddCommentMark

A custom hook that adds a comment mark to the selected text in the editor.

Returns

    A function that can be called to add a comment mark to the selected text.

useCommentAddButton

A custom hook that provides functionality for adding a comment mark to the selected text and setting focus to the comment textarea.

Returns

Collapse all

useCommentItemContentState

A state hook for the comment item content component.

Returns

Collapse all

    The comment object.

    A boolean indicating whether the comment is a reply comment.

    The text content of the comment.

    The user associated with the comment.

    The ID of the current user.

    The value of the comment being edited.

    A boolean indicating whether the comment is authored by the current user.

useCommentLeaf

A behavior hook for the comment leaf component.

Parameters

Collapse all

    The function to set the active comment ID.

    The ID of the last comment in the leaf.

Returns

Collapse all

useCommentValue

A custom hook that focuses and selects the text inside a textarea.

Returns

Collapse all

    A ref to the textarea element.

useCommentsResolved

A custom hook that returns an array of resolved comments.

Returns

Collapse all

    An array of resolved comments.

useCommentsShowResolvedButton

A custom hook that returns the props for a button component used to show resolved comments.

Returns

Collapse all

ComboboxDrag & Drop