Comments API Reference

The Contextual Comments component embeds a fully customizable commenting experience into your web application, allowing users to interact and collaborate seamlessly within the context of specific elements on the page.

How to use

To initialize the <Comments> component, you can follow our quickstart guide.

Usage

<canvas> context

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

  const canvasId = "canvas-container";

  const { pin } = useCanvasPin({ canvasId });

  return (
    <>
      // this implements pins on a canvas.
      <canvas id={canvasId} />

      // assign the pin to the components
      <Comments pin={pin} />
    </>
  );

<div> context

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

  const containerId = "html-pin-participant";

  const { pin } = useHTMLPin({ containerId });

  return (
    <>
      <div id={containerId}>
        <p data-superviz-id="23">Paragraph that can have a comment</p>
        <p data-superviz-id="42">Another paragraph that can have a comment</p>
        <p data-superviz-id="16">One more paragraph to have a comment</p>
      </div>
      <Comments pin={pin} />
    </>
  );

Matterport context

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

  const [mpSdkInstance, setMpSdkInstance] = useState(null);
  const showcase = document.getElementById("showcase");
  const showcaseWindow = showcase.contentWindow;

  const { pin } = useMatterportPin({
      matterportInstance: mpSdkInstance,
      showcaseWindow: showcase,
  });

  return (
    <>
      <Comments pin={pin} />
      <iframe id="showcase" />
    </>
  );

Autodesk context

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

  const { pin } = useAutodeskPin({ autodeskInstance: viewer });

  return (
    <>
      <Comments pin={pin} />
      <div id="forge-viewer"></div>
    </>
  );

Three.js context

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

  const { pin } = useAutodeskPin({ autodeskInstance: viewer });

  // add types
  const { pin } = useThreeJsPin({
    camera: cameraRef.current,
    scene: sceneRef.current,
    player: playerRef.current,
    renderer: rendererRef.current,
  });

  return (
    <>
      <Comments pin={pin} />
       <canvas id="threejs-canvas" />
    </>
  );

Properties

Name	Type	Description
pin	pin	Required Specifies the context where the pins will be located.
position	string	Optional 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
buttonLocation	string	Optional 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
styles	string	Optional CSS String that allows you to customize all elements individually.

Hooks

useComments

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.

useCanvasPin

Exported

pin

Type: CanvasPin | null

A CanvasPin object

function Room() {
  const { pin } = useCanvasPin({ canvasId: "mycanvas" });

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

destroy

Type: function

Destroy Pin object

function Room() {
  const { pin, destroy } = useCanvasPin({ canvasId: "mycanvas" });

  function destroyPin() {
    destroy();
  }

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

Parameters

canvasId

Type: Required string

Specifies the ID of the canvas HTML element where comments can be added.

function Room() {
  const { pin } = useCanvasPin({ canvasId: "mycanvas" });

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

onGoToPin

Optional (position: { x: number; y: number }) => void

An optional handler function for when a pin is clicked

function Room() {
  const { pin } = useCanvasPin({
    canvasId: "mycanvas",
    onGoToPin: (position) => {
      // Do something
    },
   });

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


<div className="space"></div>

### useMatterport

#### `follow`

**Type:** `function` `(participantId?: string) => void`

When called with a participant ID as an argument, this function enables other participants to follow the specified participant in the Matterport 3D space. If no ID is provided, the follow feature is disabled.

```jsx
function Room() {
  const { follow } = useMatterport();

  function followUser() {
    follow("participant-id");
  }

  function unFollow() {
    follow();
  }

  return (
    <>
      <button onClick={followUser}>Follow user</button>
      <button onClick={unFollow}>Unfollow</button>
    </>
  );
}

goto

Type: function (participantId: string) => void

When invoked with a participant ID as an argument, this function allows other participants to instantly navigate to the specified participant's position in the 3D space, enabling easy and quick location of participants.

function Room() {
  const { goTo } = useMatterport();

  function goToUser() {
    goTo("participant-id");
  }

  return <button onClick={goToUser}>Go to user</button>;
}

useHTMLPin

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

useMatterportPin

Exported

pin

Type: MatterportPin | null

A Matterport Pin object

function Room() {
  const { pin } = useMatterportPin({
    matterportInstance: mpSdkInstance,
    showcaseWindow: iframe.current,
  });

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

destroy

function

Destroy Pin object

function Room() {
  const { pin, destroy } = useMatterportPin({
    matterportInstance: mpSdkInstance,
    showcaseWindow: iframe.current,
  });

  function destroyPin() {
    destroy();
  }

  return <button onclick={destroyPin}>Destroy</button>;
}

Parameters

matterportInstance

Type: string

Specifies the Matterport SDK instance where comments can be added.

function Room() {
  const { pin } = useMatterportPin({
    matterportInstance: mpSdkInstance,
  });
}

useAutodeskPin

Exported

pin

Type: AutodeskPin | null

An AutodeskPin object

function Room() {
  const { pin } = useAutodeskPin({
    autodeskInstance: viewer,
  });
  return (
    <Comments pin={pin} />
    <div id="forge-viewer"></div>
  );
}

destroy

Type: function

Destroy Pin object

function Room() {
  const { pin, destroy } = useAutodeskPin({
    autodeskInstance: viewer,
  });

  function destroyPin() {
    destroy();
  }

  return (
    <>
      <Comments pin={pin} />
      <div id="forge-viewer"></div>
      <button onclick={destroyPin}>Destroy</button>
    </>
  );
}

Parameters

autodeskInstance

Type: string

Specifies the Autodesk viewer instance where comments can be added.

function Room() {
  const { pin } = useAutodeskPin({
    autodeskInstance: viewer,
  });

  return (
    <Comments pin={pin} />
    <div id="forge-viewer"></div>
  );
}