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} />
  );
}