Suggestions (Beta)

Overview

The Suggestions API adds suggestion mode to any input, editor, or custom component in your app. When it’s on, edits from a human (or an AI agent) aren’t written straight to your data. They’re captured as proposed changes that a reviewer accepts or rejects from the comment dialog, diff-style, like Google Docs suggestions. On accept, your app applies the change. You mark any DOM element as a suggestion target with a single attribute. The SDK captures the before and after values, saves each edit as a Suggestion, and shows accept/reject buttons on the comment dialog.

The accept/reject UI renders on the Velt comment dialog, so your app needs Velt Comments set up. That’s where reviewers act on a suggestion.

How it works

You enable suggestion mode. The SDK starts watching every element tagged with data-velt-suggestion-target="<targetId>", including elements added to the DOM later.
A user focuses a target. The SDK snapshots the target’s current value as the oldValue for that edit session.
A user edits and commits the change (for example, by clicking away from a text field). The SDK reads the new value, compares it to the snapshot, and creates a pending Suggestion only if they differ.
A reviewer accepts or rejects from the comment dialog. The outcome is emitted on the comment element as the suggestionAccepted / suggestionRejected events.
Your app applies the change. Your suggestionAccepted handler reads commentAnnotation.suggestion.newValue and writes it into your own state or backend.

Properties

A suggestion is a regular comment annotation with type: "suggestion" and a populated suggestion field. There is no separate suggestions data store.
Suggestion mode is global for the current user and not persisted. A page reload returns to normal editing until you enable it again.
An edit is committed when the user finishes it, not on every keystroke. Text-like inputs (text, number, date, textarea, contenteditable) commit when the field loses focus (focusout), so each focus session produces at most one suggestion. Dropdowns, checkboxes, and radios commit on change, since picking a value is the whole edit.
Unchanged values never create suggestions. Focusing and blurring without editing is ignored, and commitSuggestion rejects a newValue that’s identical to the old value.
Events come from two elements: accept/reject outcomes are emitted on the comment element, while the rest of the lifecycle (suggestionCreated, suggestionStale, targetEditStart, targetEditCommit) is emitted on the SuggestionElement. See Event Subscription.
The SDK never mutates your data. It captures intent, orchestrates review, and persists the outcome. Applying the change is your code’s job.
Drift detection is best-effort. On accept, if a getter is registered, the live value is compared against oldValue; a mismatch sets driftDetected: true on the suggestion. v1 records the flag; a future release will surface a confirmation prompt.
Stale wins over drift. If the target DOM node can’t be resolved at accept time, the suggestion transitions to stale immediately and drift detection is skipped.

APIs

Frontend APIs

Follow these steps to add suggestions to your app. Steps 1 and 2 are the minimum to capture suggestions; step 3 controls how edits become suggestions, step 4 applies them once accepted, and step 5 lets you query suggestions for your own UI. All Suggestions methods live on a single SuggestionElement instance. Get it once and reuse it. In React, the hooks shown below wrap it for you, so you rarely need the element directly:

React / Next.js
Other Frameworks

import { useSuggestionUtils } from '@veltdev/react';

const suggestionElement = useSuggestionUtils();

const suggestionElement = Velt.getSuggestionElement();

1. Define Suggestion Targets

Add the data-velt-suggestion-target="<targetId>" attribute to any element you want to track. The targetId is an ID you own and should stay stable, like the ID of the record the input edits. Don’t generate a random ID on each render: if the targetId changes, the SDK can’t match suggestions back to the element.

React / Next.js
Other Frameworks

<input data-velt-suggestion-target="row.123.qty" type="number" defaultValue="5" />

<input data-velt-suggestion-target="row.123.qty" type="number" value="5">

Do you need registerTarget? Usually not. For a single input, the SDK reads the value on its own: it checks for a registered getter first, then the form value (.value / .checked), then textContent. So a plain <input> needs no registerTarget call. You only need it when one target covers several inputs at once, like a table row with a qty field and a price field. There’s no single .value to read in that case, so you provide a getter function that returns the whole object:

React / Next.js
Other Frameworks

import { useRegisterTarget, useUnregisterTarget } from '@veltdev/react';
import { useEffect } from 'react';

function EditableRow() {
  const { registerTarget } = useRegisterTarget();
  const { unregisterTarget } = useUnregisterTarget();

  useEffect(() => {
    registerTarget({
      targetId: 'row.123',
      getter: () => ({
        qty: Number(document.getElementById('qty-input').value),
        price: Number(document.getElementById('price-input').value),
      }),
    });
    return () => unregisterTarget('row.123');
  }, []);

  return (
    <div data-velt-suggestion-target="row.123">
      <input id="qty-input" type="number" defaultValue="5" />
      <input id="price-input" type="number" defaultValue="99" />
    </div>
  );
}

suggestionElement.registerTarget({
  targetId: 'row.123',
  getter: () => ({
    qty: Number(document.getElementById('qty-input').value),
    price: Number(document.getElementById('price-input').value),
  }),
});

// Later, to remove the getter:
suggestionElement.unregisterTarget('row.123');

Your getter must return what the user currently sees, not what’s saved. The SDK calls it twice: on focus to capture oldValue, and on commit to capture newValue. If it reads from app state that only updates after the user saves (common when suggestion mode is on), both calls return the same value and no suggestion is ever created. Read from the DOM (input.value), or for controlled inputs that update state on every keystroke, from that state.

registerTarget() doesn’t return an unsubscribe function. To remove a registration, call unregisterTarget(targetId).

2. Enable Suggestion Mode

Nothing is captured until you turn suggestion mode on, typically from a “Suggest changes” toggle in your toolbar. It applies to the whole page for the current user and resets on page reload, so enable it again after a refresh. Pass an optional EnableSuggestionModeConfig to control how edits become suggestions (see step 3).

React / Next.js
Other Frameworks

import { useEnableSuggestionMode, useDisableSuggestionMode } from '@veltdev/react';

function Toolbar() {
  const { enableSuggestionMode } = useEnableSuggestionMode();
  const { disableSuggestionMode } = useDisableSuggestionMode();

  return (
    <button onClick={() => enableSuggestionMode()}>Suggest changes</button>
  );
}

suggestionElement.enableSuggestionMode();

// Later, return targets to normal editing:
suggestionElement.disableSuggestionMode();

To show the current mode in your UI (for example, to highlight the “Suggesting” toggle), subscribe to it instead of reading it once:

React / Next.js
Other Frameworks

import { useSuggestionModeState } from '@veltdev/react';

const isSuggesting = useSuggestionModeState(); // boolean, updates reactively

// Synchronous read
const isSuggesting = suggestionElement.isSuggestionModeEnabled();

// Reactive stream
suggestionElement.isSuggestionModeEnabled$().subscribe((isEnabled) => {
  console.log('Suggestion mode:', isEnabled);
});

3. Capture Edits as Suggestions

When a user finishes an edit, you decide how it becomes a suggestion. There are three ways, from simplest to most control. Use one per target; only one of them handles any given edit. Option 1: Auto-commit with onTargetEditCommit (simplest) Pass onTargetEditCommit when you enable suggestion mode. The SDK calls it with the old and new values every time a user finishes an edit. Return an object and the SDK creates the suggestion right away, using your summary and metadata. This is the path most apps want. (onTargetEditStart fires when editing begins; it’s informational in v1 and its return value is reserved for future use.)

React / Next.js
Other Frameworks

const { enableSuggestionMode } = useEnableSuggestionMode();

enableSuggestionMode({
  onTargetEditStart: ({ targetId, oldValue }) => {
    // Informational: a user just started editing `targetId` (oldValue snapshotted).
  },
  onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
    // Returning a result auto-creates the suggestion.
    return {
      summary: `${targetId}: ${oldValue} → ${newValue}`,
      metadata: { source: 'inline-edit' },
    };
  },
});

suggestionElement.enableSuggestionMode({
  onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
    return {
      summary: `${targetId}: ${oldValue} → ${newValue}`,
      metadata: { source: 'inline-edit' },
    };
  },
});

Don’t want every edit to become a suggestion automatically? Return null (or leave out onTargetEditCommit) and handle the edit yourself with the targetEditCommit event below, for example to validate the value or ask the user to confirm first.

Option 2: Decide per edit with the targetEditCommit event If you skip onTargetEditCommit, subscribe to the targetEditCommit event instead. The event gives you the edit details plus a commitSuggestion function that’s already tied to that edit. Call it to create the suggestion (you can override summary / metadata), or don’t call it to discard the edit. Nothing is created until you call it.

React / Next.js
Other Frameworks

import { useSuggestionEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

function CommitGate() {
  const commitEvent = useSuggestionEventCallback('targetEditCommit');

  useEffect(() => {
    if (!commitEvent) return;
    const { details, commitSuggestion } = commitEvent;
    if (isValid(details.newValue)) {
      commitSuggestion({ summary: `Update ${details.targetId}` });
    }
  }, [commitEvent]);

  return null;
}

suggestionElement.on('targetEditCommit').subscribe(({ details, commitSuggestion }) => {
  // `commitSuggestion` is a pre-bound builder. Call it to finalize the suggestion,
  // or skip it to discard this edit.
  if (isValid(details.newValue)) {
    commitSuggestion({ summary: `Update ${details.targetId}` });
  }
});

Option 3: Create suggestions manually with startSuggestion / commitSuggestion When there’s no input for the SDK to watch (a custom widget, a canvas element, or an “AI proposes a change” button), create the suggestion yourself. Call startSuggestion(targetId) to capture the current value as oldValue, then commitSuggestion(config) with the newValue to create it.

React / Next.js
Other Frameworks

import { useStartSuggestion, useCommitSuggestion } from '@veltdev/react';

function ProposeButton() {
  const { startSuggestion } = useStartSuggestion();
  const { commitSuggestion } = useCommitSuggestion();

  const propose = async () => {
    startSuggestion('row.123'); // snapshot oldValue now
    const { id } = await commitSuggestion({
      targetId: 'row.123',
      newValue: { qty: 7, price: 99 },
      summary: 'Bump qty + price',
      metadata: { source: 'manual' },
    });
    console.log('Created suggestion', id);
  };

  return <button onClick={propose}>Propose change</button>;
}

suggestionElement.startSuggestion('row.123');

const { id } = await suggestionElement.commitSuggestion({
  targetId: 'row.123',
  newValue: { qty: 7, price: 99 },
  summary: 'Bump qty + price',
  metadata: { source: 'manual' },
});

commitSuggestion only works while suggestion mode is on and the targetId is known to the SDK (tagged in the DOM or registered via registerTarget). It also creates nothing when newValue is identical to the captured oldValue.

4. Apply Accepted Suggestions

This is the step you can’t skip. When a reviewer clicks Accept or Reject on the comment dialog, the SDK updates the suggestion’s status but does not change your data. Listen for the suggestionAccepted event on the comment element (not the SuggestionElement), read commentAnnotation.suggestion.newValue, and write it to your state or backend yourself.

React / Next.js
Other Frameworks

import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

function ApplyAcceptedSuggestions() {
  const accepted = useCommentEventCallback('suggestionAccepted');
  const rejected = useCommentEventCallback('suggestionRejected');

  useEffect(() => {
    const suggestion = accepted?.commentAnnotation?.suggestion;
    if (!suggestion) return;
    applyToYourState(suggestion.targetId, suggestion.newValue); // your code writes the change
  }, [accepted]);

  useEffect(() => {
    if (rejected?.commentAnnotation) {
      console.log('Rejected:', rejected.rejectReason);
    }
  }, [rejected]);

  return null;
}

const commentElement = Velt.getCommentElement();

commentElement.on('suggestionAccepted').subscribe(({ commentAnnotation }) => {
  const suggestion = commentAnnotation?.suggestion; // suggestion.status === 'accepted'
  applyToYourState(suggestion.targetId, suggestion.newValue);
});

commentElement.on('suggestionRejected').subscribe(({ commentAnnotation, rejectReason }) => {
  console.log('Rejected:', rejectReason);
});

If the target element is no longer on the page when a reviewer accepts, the suggestion is marked stale instead of accepted. Listen for that on the SuggestionElement with useSuggestionEventCallback('suggestionStale') (React) or suggestionElement.on('suggestionStale') (other frameworks).

Your accept handler can run more than once (after reconnects, in multiple tabs, and on every client viewing the document), so applying newValue must be safe to repeat. Set the field to newValue rather than incrementing it. If your handler throws while applying, the SDK marks the suggestion apply_failed.

5. Get Suggestions

Beyond the built-in accept/reject buttons, you’ll often want to render your own indicators: a “1 pending change” badge on a row, a custom review panel, or a count in a toolbar. Query suggestions reactively with an optional SuggestionGetSuggestionsFilter, or fetch the single pending suggestion for a target.

React / Next.js
Other Frameworks

import { useSuggestions, usePendingSuggestion } from '@veltdev/react';

// All suggestions, or filter by target / status
const all = useSuggestions();
const pendingForRow = useSuggestions({ targetId: 'row.123', status: 'pending' });

// The newest pending suggestion for one target (or null)
const pending = usePendingSuggestion('row.123');

// Synchronous snapshot
const pending = suggestionElement.getSuggestions({ status: 'pending' });

// Reactive stream
suggestionElement.getSuggestions$({ targetId: 'row.123' }).subscribe((list) => {
  console.log('Suggestions for row.123:', list);
});

// Newest pending suggestion for a single target
suggestionElement.getPendingSuggestion$('row.123').subscribe((s) => {
  console.log('Pending:', s);
});

Backend APIs

Suggestions are stored as comment annotations, so you manage them from your backend with the same Comment Annotations REST APIs.

Add Suggestions

Add agent-generated suggestions using the Add Comment Annotations REST API with type: "suggestion" and an agent block on the root comment. Learn more
See the Agent Comments guide for the full walkthrough of agent findings.

Get Suggestions

Get suggestion annotations using the Get Comment Annotations REST API. Use the agentSuggestions filter to return only fresh (unaccepted) agent suggestions. Learn more

Update and Delete Suggestions

Update annotation-level fields using the Update Comment Annotations REST API. Learn more
Delete suggestion threads using the Delete Comment Annotations REST API. Learn more

Event Subscription

on

Subscribe to Suggestion Events. Events come from two elements: review outcomes are emitted on the comment element, and the rest of the lifecycle is emitted on the SuggestionElement. Here is the list of events you can subscribe to and the event objects you will receive.

Category	Event Type	Description	Event Object
Review Outcomes (Comment Element)	`suggestionAccepted`	Triggered when a reviewer accepts a suggestion from the comment dialog	SuggestionAcceptEvent
Review Outcomes (Comment Element)	`suggestionRejected`	Triggered when a reviewer rejects a suggestion from the comment dialog	SuggestionRejectEvent
Lifecycle (SuggestionElement)	`suggestionCreated`	Triggered when a pending suggestion is created	SuggestionCreatedEvent
Lifecycle (SuggestionElement)	`suggestionStale`	Triggered when a suggestion goes stale at accept time	SuggestionStaleEvent
Editing (SuggestionElement)	`targetEditStart`	Triggered when a user focuses a target and editing begins	TargetEditStartEvent
Editing (SuggestionElement)	`targetEditCommit`	Triggered when an edit is committed. Carries the `commitSuggestion` builder.	TargetEditCommitEvent

React / Next.js
Other Frameworks

// Hook: SuggestionElement events
const suggestionEventCallbackData = useSuggestionEventCallback('suggestionCreated');
useEffect(() => {
  if (suggestionEventCallbackData) {
    // Handle suggestion event response
  }
}, [suggestionEventCallbackData]);

// Hook: comment element events (accept / reject outcomes)
const commentEventCallbackData = useCommentEventCallback('suggestionAccepted');
useEffect(() => {
  if (commentEventCallbackData) {
    // Handle accept event response
  }
}, [commentEventCallbackData]);

// API Method
const suggestionElement = client.getSuggestionElement();
suggestionElement.on('suggestionCreated').subscribe((event) => {
  // Handle the event response
});

const commentElement = client.getCommentElement();
commentElement.on('suggestionAccepted').subscribe((event) => {
  // Handle the event response
});

const suggestionElement = Velt.getSuggestionElement();
suggestionElement.on('suggestionCreated').subscribe((event) => {
  // Handle the event response
});

const commentElement = Velt.getCommentElement();
commentElement.on('suggestionAccepted').subscribe((event) => {
  // Handle the event response
});

Lifecycle

A suggestion moves forward through these states (see SuggestionStatus):

Status	Meaning
`pending`	Created and awaiting review.
`accepted`	A reviewer accepted it; your `suggestionAccepted` handler applies `newValue`.
`rejected`	A reviewer rejected it (optional `rejectReason`). Nothing is applied.
`stale`	The target DOM node couldn’t be resolved at accept time, so the change can’t be applied.
`apply_failed`	Your accept handler threw while applying. Surfaced as a status only; there’s no separate event in v1.

Data model

Suggestions are stored as CommentAnnotation objects with type === 'suggestion' and a populated suggestion field. The full type hierarchy lives in the Suggestions section of the Data Models reference.

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Suggestions (Beta)

Overview

How it works

Properties

APIs

Frontend APIs

1. Define Suggestion Targets

2. Enable Suggestion Mode

3. Capture Edits as Suggestions

4. Apply Accepted Suggestions

5. Get Suggestions

Backend APIs

Add Suggestions

Get Suggestions

Update and Delete Suggestions

Event Subscription

on

Lifecycle

Data model

​Overview

​How it works

​Properties

​APIs

​Frontend APIs

​1. Define Suggestion Targets

​2. Enable Suggestion Mode

​3. Capture Edits as Suggestions

​4. Apply Accepted Suggestions

​5. Get Suggestions

​Backend APIs

​Add Suggestions

​Get Suggestions

​Update and Delete Suggestions

​Event Subscription

​on

​Lifecycle

​Data model

Overview

How it works

Properties

APIs

Frontend APIs

1. Define Suggestion Targets

2. Enable Suggestion Mode

3. Capture Edits as Suggestions

4. Apply Accepted Suggestions

5. Get Suggestions

Backend APIs

Add Suggestions

Get Suggestions

Update and Delete Suggestions

Event Subscription

on

Lifecycle

Data model