Skip to main content

Documentation Index

Fetch the complete documentation index at: https://velt-v5-0-2-beta-23.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Suggestions API lets you wire any DOM element as a suggestion target. When suggestion mode is active, the SDK captures before/after values, persists them as typed Suggestion annotations, and surfaces accept/reject actions on the comment dialog. Approving fires a suggestionApproved event your app handles to apply the change.

​
Key Concepts

  • Suggestion target: Any DOM element tagged with data-velt-suggestion-target="<targetId>".
  • Suggestion mode: When enabled, the SDK listens for edits on registered targets and wraps them as pending suggestions rather than committing them immediately.
  • Suggestion lifecycle: pending → approved / rejected / stale / apply_failed.
  • SuggestionElement: The singleton object returned by client.getSuggestionElement() (HTML/Vanilla) or the useSuggestionUtils() hook (React). All Suggestions API methods live on this object.

​
How It Works

  1. Register one or more DOM elements as suggestion targets using registerTarget().
  2. Enable suggestion mode via enableSuggestionMode().
  3. The SDK intercepts edits, captures before/after values, and creates a pending Suggestion backed by a CommentAnnotation with type === 'suggestion'.
  4. The accept/reject actions appear in the comment dialog. Accepting fires suggestionApproved; your handler applies the change to your data.

​
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.

​
Behavior Notes

  • Stale wins over drift: If the target DOM node cannot be resolved at approve time, the suggestion transitions to stale immediately and drift detection is skipped.
  • Drift detection is best-effort: On approve, 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.
  • One suggestion per edit session: For text-like inputs, one suggestion is captured per focus session (focusout). For atomic inputs (e.g., <select>), one suggestion is captured per change event.
  • Mode is not persisted: Suggestion mode is per-user-per-session. A page reload returns suggestion mode to disabled.