Nutrient Setup

The Nutrient integration renders each Velt comment as a view-only overlay positioned over the commented PDF text with Nutrient CustomOverlayItems. It does not modify your PDF. Comment anchors are stored as a durable { text, pageNumber, occurrence } object and re-resolved against the page text whenever comments render.

Setup

Step 1: Add Comment components

Add the Velt Comments component to the root of your app. This component is required to create and render comments in your app.
Authenticate the user with authProvider and set the Velt document before users add comments.
Set the textMode prop to false to hide the default Velt text comment tool. Nutrient selections are handled by @veltdev/nutrient-velt-comments.
Add VeltCommentsSidebar if you want a Google Docs-style comment sidebar.

React / Next.js

import { VeltComments, VeltCommentsSidebar, VeltProvider, useSetDocument } from '@veltdev/react';

const user = {
  userId: 'user-1',
  organizationId: 'org-1',
  name: 'User One',
  email: 'user@example.com',
};

function VeltSetup() {
  useSetDocument('document-id', { documentName: 'Document name' });
  return null;
}

function App() {
  return (
    <VeltProvider apiKey="API_KEY" authProvider={{ user }}>
      <VeltSetup />
      <VeltComments textMode={false} />
      <VeltCommentsSidebar />
      {/* Your app content */}
    </VeltProvider>
  );
}

Step 2: Install the Velt Nutrient extension

npm i @veltdev/nutrient-velt-comments @nutrient-sdk/viewer@1.15.1

@nutrient-sdk/viewer is a peer dependency used for types. Use the same Nutrient version that you load from the CDN script. Load the Nutrient Web SDK at runtime so your app does not bundle the browser-only PDF viewer and WebAssembly assets.

React / Next.js

import Script from 'next/script';

const NUTRIENT_CDN_SCRIPT =
  'https://cdn.cloud.nutrient.io/pspdfkit-web@1.15.1/nutrient-viewer.js';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Script src={NUTRIENT_CDN_SCRIPT} strategy="afterInteractive" />
        {children}
      </body>
    </html>
  );
}

If you self-host Nutrient assets, copy node_modules/@nutrient-sdk/viewer/dist/ into your static folder and load the SDK script from that path. The Velt Nutrient package expects the runtime SDK namespace on window.NutrientViewer.

Step 3: Configure the Nutrient viewer with the Velt Comments extension

Load the Nutrient viewer, then attach NutrientVeltComments to the viewer instance after NutrientViewer.load(...) resolves. The same instance is used by addComment, captureSelection, and renderComments.

React / Next.js

import { useEffect, useRef, useState } from 'react';
import { useCommentAnnotations } from '@veltdev/react';
import {
  NutrientVeltComments,
  renderComments,
  type AttachedExtension,
  type NutrientInstance,
} from '@veltdev/nutrient-velt-comments';

type NutrientViewerApi = (typeof import('@nutrient-sdk/viewer'))['default'];

declare global {
  interface Window {
    NutrientViewer?: NutrientViewerApi;
  }
}

const EDITOR_ID = 'my-pdf';

function waitForNutrientViewer(timeoutMs = 30000): Promise<NutrientViewerApi> {
  return new Promise((resolve, reject) => {
    const start = Date.now();

    const tick = () => {
      if (window.NutrientViewer) {
        resolve(window.NutrientViewer);
        return;
      }

      if (Date.now() - start > timeoutMs) {
        reject(new Error('Nutrient SDK did not load.'));
        return;
      }

      window.setTimeout(tick, 50);
    };

    tick();
  });
}

function NutrientViewerComponent() {
  const viewerRef = useRef<HTMLDivElement | null>(null);
  const instanceRef = useRef<NutrientInstance | null>(null);
  const extensionRef = useRef<AttachedExtension | null>(null);
  const [instance, setInstance] = useState<NutrientInstance | null>(null);
  const annotations = useCommentAnnotations();

  useEffect(() => {
    if (!viewerRef.current || instanceRef.current) return;

    let cancelled = false;
    const container = viewerRef.current;

    waitForNutrientViewer().then((Nutrient) => {
      if (cancelled || instanceRef.current) return;

      Nutrient.unload(container);

      Nutrient.load({
        container,
        document: '/your-document.pdf',
        licenseKey: 'YOUR_NUTRIENT_LICENSE_KEY',
      }).then((nutrientInstance) => {
        if (cancelled) {
          Nutrient.unload(container);
          return;
        }

        instanceRef.current = nutrientInstance;
        extensionRef.current = NutrientVeltComments
          .configure({ editorId: EDITOR_ID })
          .attach(nutrientInstance);
        setInstance(nutrientInstance);
      });
    });

    return () => {
      cancelled = true;
      extensionRef.current?.detach();
      extensionRef.current = null;
      window.NutrientViewer?.unload(container);
      instanceRef.current = null;
      setInstance(null);
    };
  }, []);

  useEffect(() => {
    if (!instance) return;

    renderComments({
      instance,
      commentAnnotations: annotations ?? [],
    });
  }, [instance, annotations]);

  return <div ref={viewerRef} style={{ width: '100%', height: '100vh' }} />;
}

Step 4: Add a comment button to your Nutrient viewer

Add a button that users can click after selecting text in the PDF. Call captureSelection(instance) before addComment({ instance }) so the Velt Nutrient package records the current Nutrient selection before focus moves to your host UI.

React / Next.js

import { addComment, captureSelection } from '@veltdev/nutrient-velt-comments';

const handleAddComment = async () => {
  if (!instance) return;

  await captureSelection(instance);
  const result = await addComment({ instance });

  if (!result) {
    console.warn('Select text in the PDF before adding a comment.');
  }
};

<button
  onMouseDown={(event) => event.preventDefault()}
  onClick={handleAddComment}
>
  Add Comment
</button>

Step 5: Call `addComment` to add a comment

Call this method to add a comment to selected text in the Nutrient viewer.
Params: AddCommentArgs. It has the following properties:
- instance: Nutrient viewer instance returned by NutrientViewer.load(...).
Returns: Promise<AddCommentResult | null>. It returns null if no text is selected or Velt is not loaded.

React / Next.js

import { addComment, captureSelection } from '@veltdev/nutrient-velt-comments';

await captureSelection(instance);
const result = await addComment({ instance });

To scope comments to a specific viewer on pages with multiple Nutrient instances, pass an editor id when attaching the extension:

NutrientVeltComments.configure({ editorId: 'EDITOR_ID' }).attach(instance);

Step 6: Render comments in Nutrient viewer

Get comment data from the Velt SDK and render it in the Nutrient viewer.
Params: RenderCommentsArgs. It has the following properties:
- instance: Nutrient viewer instance.
- commentAnnotations: Array of Comment Annotation objects.

React / Next.js

import { useEffect } from 'react';
import { useCommentAnnotations } from '@veltdev/react';
import { renderComments } from '@veltdev/nutrient-velt-comments';

const commentAnnotations = useCommentAnnotations();

useEffect(() => {
  if (!instance) return;

  renderComments({
    instance,
    commentAnnotations: commentAnnotations ?? [],
  });
}, [instance, commentAnnotations]);

Highlights are view-only. The library re-derives each highlight from its TextEditorConfig anchor and Nutrient repositions the overlays across scroll, zoom, and page changes. Re-run renderComments when Velt’s annotation list changes or when you unload and reload the document.

Step 7: Clean up the Velt Nutrient extension

NutrientVeltComments.configure(...).attach(instance) returns an AttachedExtension. Call detach() in your effect cleanup to remove listeners, clear per-instance state, and remove overlay elements before unloading the viewer.

return () => {
  extensionRef.current?.detach();
  extensionRef.current = null;
  window.NutrientViewer?.unload(container);
};

Step 8: Style the commented text

Each highlight is a div.velt-nutrient-highlight inside a velt-comment-text overlay.
Override the default inline highlight styles with !important.

velt-comment-text .velt-nutrient-highlight {
  background-color: rgba(255, 212, 0, 0.4) !important;
  border-bottom: 2px solid rgba(255, 170, 0, 0.95) !important;
}

velt-comment-text:hover .velt-nutrient-highlight,
velt-comment-text[comment-selected="true"] .velt-nutrient-highlight,
velt-comment-text.velt-comment-selected .velt-nutrient-highlight {
  background-color: rgba(255, 212, 0, 0.7) !important;
}

Complete Example

APIs

NutrientVeltComments

Creates the Velt Comments extension for a Nutrient viewer. Use NutrientVeltComments.configure(...).attach(instance) to attach it to a viewer instance.

Config: NutrientVeltCommentsConfig
Returns: NutrientVeltComments

React / Next.js

import { NutrientVeltComments } from '@veltdev/nutrient-velt-comments';

const attached = NutrientVeltComments
  .configure({ editorId: 'my-pdf' })
  .attach(instance);

attached.detach();

captureSelection()

Records the current Nutrient text selection for the next addComment call.

Signature: (instance: NutrientInstance) => Promise<void>
Params: instance: NutrientInstance
Returns: Promise<void>

React / Next.js

import { captureSelection } from '@veltdev/nutrient-velt-comments';

await captureSelection(instance);

addComment()

Creates a comment annotation for the currently captured Nutrient text selection.

Signature: async (args: AddCommentArgs) => Promise<AddCommentResult | null>
Params: args: AddCommentArgs
Returns: Promise<AddCommentResult | null>; see AddCommentResult.

React / Next.js

import { addComment } from '@veltdev/nutrient-velt-comments';

const result = await addComment({ instance });

renderComments()

Renders and updates Velt comment highlights in the Nutrient viewer.

Signature: (args: RenderCommentsArgs) => void
Params: args: RenderCommentsArgs
Returns: void

React / Next.js

import { renderComments } from '@veltdev/nutrient-velt-comments';

renderComments({
  instance,
  commentAnnotations: annotations ?? [],
});

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Nutrient Setup

Setup

Step 1: Add Comment components

Step 2: Install the Velt Nutrient extension

Step 3: Configure the Nutrient viewer with the Velt Comments extension

Step 4: Add a comment button to your Nutrient viewer

Step 5: Call `addComment` to add a comment

Step 6: Render comments in Nutrient viewer

Step 7: Clean up the Velt Nutrient extension

Step 8: Style the commented text

Complete Example

APIs

NutrientVeltComments

captureSelection()

addComment()

renderComments()

​Setup

​Step 1: Add Comment components

​Step 2: Install the Velt Nutrient extension

​Step 3: Configure the Nutrient viewer with the Velt Comments extension

​Step 4: Add a comment button to your Nutrient viewer

​Step 5: Call addComment to add a comment

​Step 6: Render comments in Nutrient viewer

​Step 7: Clean up the Velt Nutrient extension

​Step 8: Style the commented text

​Complete Example

​APIs

​NutrientVeltComments

​captureSelection()

​addComment()

​renderComments()

Setup

Step 1: Add Comment components

Step 2: Install the Velt Nutrient extension

Step 3: Configure the Nutrient viewer with the Velt Comments extension

Step 4: Add a comment button to your Nutrient viewer

Step 5: Call `addComment` to add a comment

Step 6: Render comments in Nutrient viewer

Step 7: Clean up the Velt Nutrient extension

Step 8: Style the commented text

Complete Example

APIs

NutrientVeltComments

captureSelection()

addComment()

renderComments()