Skip to main content

HTMLPin

Contextual Comments embeds a customizable commenting experience into your application, enabling people to collaborate in real-time and asynchronously on html elements.

Before we start

Before utilizing the <Comments> element, it is essential to initialize a room with a defined name and ID for the participant.

How to use it

Comments

To add contextual comments to a <html> element, you need to add the <Comments> component, configure position and styling, and then point it to the 'useHTMLPin' hook.

useHTMLPin

When using the useHTMLPin hook, you need to pass, as a parameter in the constructor, the HTML element ID that wrappers the elements where comments can be added, and, optionally, options about the adapter behavior. With that, participants will be able to place a Comment Pin on any element that has the data-superviz-id attribute. The value of this attribute will be used to identify the element and its position on the page, meaning that it should be unique and persist on the page.

After initializing, you can add the adapter to the Contextual Comments passing it as a parameter in its constructor, enabling the Contextual Comments for HTML. Here is how to do it:

import { Comments, useHTMLPin } from "@superviz/react-sdk";

function Room({ participantId }) {
const { pin } = useHTMLPin({ containerId: "myContainer" });
return (
<Comments pin={pin} buttonLocation="top-right" position="left" />
);
}

export default Room;

Properties

NameTypeDescription
pinpinRequired. Specifies the element or plugin that can receive comments. For <htmls> elements always use the useHTMLPin hook.
positionstringOptional. Represents the position where the element with the list of comments will be placed on the page. Values are left and right

Default value: left
buttonLocationstringOptional. Represents the position where the button to activate or deactivate the comments functionality will be placed. Values are top-left, top-right, bottom-left, bottom-right, or an HTML element id.

Default value: top-left
stylesstringOptional. CSS String that allows you to customize all elements individually.

useComments Hook

openThreads

Type: () => void

Opens the superviz-comments section, where you can see the list of comments and reply to them.


function Room() {
const { openThreads } = useComments();

function open() {
openThreads();
}

return <button onClick={open}>Open Threads</button>
}

closeThreads

Type: () => void

Closes the superviz-comments section, where you can see the list of comments and reply to them.


function Room() {
const { closeThreads } = useComments();

function close() {
closeThreads();
}

return <button onClick={close}>Close Threads</button>
}

useHTMLPin Hook

Exported

pin

Type: HTMLPin | null

An HTMLPin object


function Room() {
const { pin } = useHTMLPin({ elementId: "myContainer" });

return (
<Comments pin={pin} />
);
}

destroy

Type: function

Destroy Pin object


function Room() {
const { pin, destroy } = useHTMLPin({ elementId: "myContainer" });

function destroyPin() {
destroy();
}

return (
<>
<Comments pin={pin} />
<button onclick={destroyPin}>Destroy</button>
</>
);
}

Parameters

elementId

Required. string

Specifies the parent of the HTML elements where comments can be added.


function Room({ participantId }) {
const { pin } = useHTMLPin({ containerId: "myContainer" });

return (
<Comments pin={pin} />
);
}

dataAttributeName

Optional. string

Use this property to change the data attribute used to locate the elements that can receive a comment pin. The value of this attribute should be unique and persist on the page.

Default: data-superviz-id


function Room({ participantId }) {
const { pin } = useHTMLPin({
containerId: "myContainer",
dataAttributeName: "data-comment-id",
});

return (
<Comments pin={pin} />
);
}

dataAttributeValueFilters

Optional. RegExp[]

This Regex array is used to filter what elements should not be able to receive a comment pin.


function Room({ participantId }) {
const { pin } = useHTMLPin({
containerId: "myContainer",
dataAttributeValueFilters: [/.*-null-(target|target)$/] ,
});

return (
<Comments pin={pin} />
);
}