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.

​
1. Getting the SuggestionElement

To access the Suggestions API, get the SuggestionElement singleton from the client. 
import { useSuggestionUtils } from '@veltdev/react';

const suggestionElement = useSuggestionUtils();

​
2. Enable/Disable Suggestion Mode

Enable suggestion mode with an optional EnableSuggestionModeConfig. 
import { useEnableSuggestionMode, useDisableSuggestionMode } from '@veltdev/react';

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

// Enable with optional callbacks
enableSuggestionMode({
  onTargetEditStart: ({ targetId, oldValue, newValue, element }) => {
    // Informational. Reserved for future overrides.
  },
  onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
    return {
      summary: `${targetId}: ${oldValue} → ${newValue}`,
      metadata: { source: 'inline-edit' },
    };
  },
});

// Disable
disableSuggestionMode();
API Method:
suggestionElement.enableSuggestionMode({
  onTargetEditStart: ({ targetId, oldValue, newValue, element }) => {},
  onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
    return { summary: 'change description' };
  },
});
suggestionElement.disableSuggestionMode();

​
3. Check Suggestion Mode State

Synchronously check or reactively observe whether suggestion mode is active. 
import { useSuggestionModeState } from '@veltdev/react';

const isSuggestionModeEnabled = useSuggestionModeState();
API Method:
// Synchronous
const isEnabled = suggestionElement.isSuggestionModeEnabled();

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

​
4. Register a Suggestion Target

Register a target using registerTarget() with a RegisterTargetConfig. The config takes a targetId and a getter function. Returns an unsubscribe function; call it to remove the registration. 
import { useRegisterTarget, useUnregisterTarget } from '@veltdev/react';
import { useEffect } from 'react';

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

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

  return (
    <input id="qty-input" data-velt-suggestion-target="row.123" type="number" defaultValue="5" />
  );
}
API Method:
const unsubscribe = suggestionElement.registerTarget({
  targetId: 'row.123',
  getter: () => ({
    qty: parseInt(document.getElementById('qty-input').value, 10),
    price: parseInt(document.getElementById('price-input').value, 10),
  }),
});

// Later, to remove:
unsubscribe();
// Or:
suggestionElement.unregisterTarget('row.123');

​
5. Query Suggestions

Retrieve all suggestions or filter by targetId or status using a SuggestionGetSuggestionsFilter. 
import { useSuggestions, usePendingSuggestion } from '@veltdev/react';

// All suggestions
const suggestions = useSuggestions();

// Filtered by target
const targetSuggestions = useSuggestions({ targetId: 'row.123' });

// Filtered by status
const pendingSuggestions = useSuggestions({ status: 'pending' });

// Pending suggestion for a specific target
const pending = usePendingSuggestion('row.123');
API Method:
// Synchronous
const suggestions = suggestionElement.getSuggestions({ targetId: 'row.123' });

// Reactive
suggestionElement.getSuggestions$({ status: 'pending' }).subscribe((list) => {
  console.log('Pending suggestions:', list);
});

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

​
6. Suggestion Lifecycle Events

Subscribe to suggestion lifecycle events. All event types are defined in SuggestionEventType.
EventDescriptionPayload Type
suggestionCreatedA new pending suggestion was createdSuggestionCreatedEvent
suggestionApprovedA suggestion was acceptedSuggestionApprovedEvent
suggestionRejectedA suggestion was rejectedSuggestionRejectedEvent
suggestionStaleA suggestion became staleSuggestionStaleEvent
targetEditStartA target edit session beganTargetEditStartEvent
targetEditCommitA target edit session was committedTargetEditCommitEvent
import { useSuggestionEventCallback } from '@veltdev/react';
import { useEffect } from 'react';

function SuggestionHandler() {
  const approved = useSuggestionEventCallback('suggestionApproved');
  const rejected = useSuggestionEventCallback('suggestionRejected');
  const stale = useSuggestionEventCallback('suggestionStale');

  useEffect(() => {
    if (approved?.suggestion) {
      // Apply approved.suggestion.newValue to your app state.
    }
  }, [approved]);

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

  useEffect(() => {
    if (stale?.suggestion) {
      console.log('Stale:', stale.suggestion);
    }
  }, [stale]);

  return null;
}
API Method:
suggestionElement.on('suggestionApproved').subscribe(({ suggestion }) => {
  // Apply suggestion.newValue to your app state here.
});

suggestionElement.on('suggestionRejected').subscribe(({ suggestion }) => {
  console.log('Rejected:', suggestion);
});

​
7. Lower-Level Edit-Detect Events

Subscribe to targetEditStart and targetEditCommit for fine-grained control over the edit capture flow.
API Method:
suggestionElement.on('targetEditStart').subscribe(({ details }) => {
  console.log('Edit started on:', details.targetId, 'oldValue:', details.oldValue);
});

suggestionElement.on('targetEditCommit').subscribe(({ details, commitSuggestion }) => {
  // commitSuggestion is a pre-bound TargetEditCommitBuilder.
  // Calling it commits with SDK defaults, or pass { summary, metadata } to override.
  commitSuggestion({ summary: 'auto: ' + details.targetId });
});

​
8. Manually Start or Commit a Suggestion

You can programmatically start or commit a suggestion without relying on user interaction. 
import { useStartSuggestion, useCommitSuggestion } from '@veltdev/react';

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

  const handleManualCommit = async () => {
    // Manually capture a snapshot (alternative to focus auto-snapshot)
    startSuggestion('row.123');

    // Commit a suggestion explicitly
    const { id } = await commitSuggestion({
      targetId: 'row.123',
      newValue: { qty: 7, price: 99 },
      summary: 'Bump qty + price',
      metadata: { source: 'manual-commit' },
    });
    console.log('Created suggestion:', id);
  };

  return <button onClick={handleManualCommit}>Submit Suggestion</button>;
}
API Method:
suggestionElement.startSuggestion('row.123');

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