Setup

Core Configurations

enableSingleEditorMode

Enables single editor mode, allowing only one user to edit the document at a time while others remain in read-only mode.

Params

• config: (object, optional). Configuration object for controlling single editor mode behavior
  • customMode: (boolean, optional). When true, SDK won’t automatically make HTML elements read-only for viewers. You need to handle this manually with the help of other APIs listed here. (default: false)
  • singleTabEditor: (boolean, optional). When enabled, restricts the editor to edit in only one browser tab at a time, preventing them from making changes across multiple tabs simultaneously (default: true)

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();

// Basic usage
liveStateSyncElement.enableSingleEditorMode();

// With configuration
liveStateSyncElement.enableSingleEditorMode({ 
    customMode: true,
    singleTabEditor: false 
});

disableSingleEditorMode

Disables single editor mode and returns to normal editing.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.disableSingleEditorMode();

Define Single Editor Mode Elements

Restrict to specific containers

• Restrict Single Editor Mode to specific containers.
• By default Single Editor Mode is enabled at the entire DOM level. You can restrict this feature to only certain HTML containers & their children by using this.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.singleEditorModeContainerIds(["rightPanel", "editor"]);

Fine tune elements control

Control which elements are controlled by Single Editor Mode.

You must add the data-velt-sync-access-* attributes to native HTML elements (e.g. button, input). It will not work directly on React components.

React / Next.js

// Enable sync access on custom elements
return (
    <div data-velt-sync-access="true">
        Controlled by Single Editor Mode
    </div>
);

// Exclude elements from sync access
return (
    <button data-velt-sync-access-disabled="true">
        Not controlled by Single Editor Mode
    </button>
);

Timeout Configuration

setEditorAccessTimeout

• Configure automatic editor access timeout.
• Default: 5 seconds.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setEditorAccessTimeout(15); // in seconds

enableEditorAccessTransferOnTimeOut

• When editor access timeout is reached, automatically transfer editor access to the next user in the queue.
• Enabled by default.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.enableEditorAccessTransferOnTimeOut();

disableEditorAccessTransferOnTimeOut

• When editor access timeout is reached, do not automatically transfer editor access to the next user in the queue.
• Enabled by default.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.disableEditorAccessTransferOnTimeOut();

getEditorAccessTimer

Track the state of editor access request timeout.

Returns

• EditorAccessTimer object:
  • state ('idle' | 'inProgress' | 'completed')
  • durationLeft (number)

React / Next.js

// Using Hooks
const editorAccessTimer = useEditorAccessTimer();

useEffect(() => {
    if (editorAccessTimer?.state === 'completed') {
        // Handle timeout completion
        if (isEditor) {
            acceptEditorAccessRequest();
        } else if (isRequester) {
            setUserAsEditor();
        }
    }
}, [editorAccessTimer]);

return (
    <div>
        Status: {editorAccessTimer?.state}
        Time Left: {editorAccessTimer?.durationLeft}s
    </div>
);


// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getEditorAccessTimer().subscribe((editorAccessTimer) => {
    console.log('Editor Access Timer:', editorAccessTimer);
});

Auto-Sync Text Elements

• Enable automatic syncing of text element contents across all users.
• Supported elements:
  • <input>
  • <textarea>
  • ContentEditable <div>
• First enable the feature and then define which elements should sync realtime.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();

// Enable auto-sync state
liveStateSyncElement.enableAutoSyncState();

// In your JSX
return (
    <textarea id="uniqueId" data-velt-sync-state="true"></textarea>
);

Editor

setUserAsEditor

Sets the current user as the editor, making all other users read-only.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setUserAsEditor();

isUserEditor

• Get the current user’s editor status.

Returns

• null: When the state is not available yet.
• undefined: When there are no current editors available in single editor mode.
• UserEditorAccess: When there is at least one editor available in single editor mode.
  • isEditor (boolean) - Whether the user is the editor
  • isEditorOnCurrentTab (boolean) - Whether the user is editor on current tab

React / Next.js

// Using Hooks
const { isEditor, isEditorOnCurrentTab } = useUserEditorState();

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.isUserEditor().subscribe((userEditorAccess) => {
    console.log('Is Editor:', userEditorAccess.isEditor);
    console.log('Is Editor on Current Tab:', userEditorAccess.isEditorOnCurrentTab);
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

getEditor

Get information about the current editor.

Returns

• User object:
  • email (string) - Editor’s email
  • name (string) - Editor’s name
  • photoUrl (string) - Editor’s photo URL
  • userId (string) - Editor’s unique ID

React / Next.js

// Using Hooks
const editor = useEditor();

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getEditor().subscribe((user) => {
    console.log('Editor:', user);
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

isEditorAccessRequested

Check if any viewer has requested editor access.

Returns

• null - User is not editor or request was canceled
• EditorRequest object:
  • requestStatus (string) - ‘requested’ for active requests
  • requestedBy (User) - User object of the requester

React / Next.js

// Using Hooks
const editorAccessRequested = useEditorAccessRequestHandler();

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.isEditorAccessRequested().subscribe((data) => {
    if (data === null) {
        console.log('No active requests or user is not editor');
    } else {
        console.log('Request from:', data.requestedBy.name);
    }
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

acceptEditorAccessRequest

Accept editor access requests.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.acceptEditorAccessRequest();

rejectEditorAccessRequest

Reject editor access requests.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.rejectEditorAccessRequest();

editCurrentTab

Make current tab editable when editor has multiple tabs open.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.editCurrentTab();

Viewer

requestEditorAccess

Request editor access from the current editor.

Returns

• null - Request is pending
• true - Request accepted
• false - Request rejected

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.requestEditorAccess().subscribe((status) => {
    if (status === null) console.log('Request pending');
    else if (status === true) console.log('Request accepted');
    else console.log('Request rejected');
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

cancelEditorAccessRequest

Cancel the editor access request.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.cancelEditorAccessRequest();

resetUserAccess

Reset editor access for all users.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.resetUserAccess();

UI

enableDefaultSingleEditorUI

• Control the visibility of the default Single Editor Mode System UI.
• The default UI shows:
  • Current user’s editor/viewer status
  • Editor access requests
  • Request timeout countdown
  • Request rejection options
• If you disable the default UI, you’ll need to implement your own UI for these features.

React / Next.js

const liveStateSyncElement = useLiveStateSyncUtils();

// Enable default UI (enabled by default)
liveStateSyncElement.enableDefaultSingleEditorUI();

// Disable default UI for custom implementation
liveStateSyncElement.disableDefaultSingleEditorUI();

Embed Single Editor Mode Panel

• Embed the Single Editor Mode Panel into your UI.

React / Next.js

<VeltSingleEditorModePanel shadowDom={false} darkMode={true} variant="custom-ui" />

Event Subscription

on

Subscribe to Single Editor Mode Events. Here is the list of events you can subscribe to and the event objects you will receive.

Category	Event Type	Description	Event Object
Editor	accessRequested	When a user requests editor access. Editor will get this event.	AccessRequestEvent
Editor	accessRequestCanceled	When a user cancels their request for editor access. Editor will get this event.	AccessRequestEvent
Viewer	accessAccepted	When a user’s request for editor access is accepted. Requesting Viewer will get this event.	AccessRequestEvent
Viewer	accessRejected	When a user’s request for editor access is rejected. Requesting Viewer will get this event.	AccessRequestEvent
Access Assignment	editorAssigned	When a user is assigned as the editor.	SEMEvent
Access Assignment	viewerAssigned	When a user is assigned as a viewer.	SEMEvent
Editor	editorOnDifferentTabDetected	When the editor opens the same document in a different browser tab. Editor will get this event.	SEMEvent

React / Next.js

Using Hooks:

// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
const eventData = useLiveStateSyncEventCallback("EVENT_TYPE"); 

useEffect(() => {
  if (eventData) { 
    console.log("EVENT_TYPE data: ", eventData);
  }
}, [eventData]);

Using API:

const liveStateSyncElement = useLiveStateSyncUtils();
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
liveStateSyncElement.on("EVENT_TYPE").subscribe((eventData) => {
  console.log("EVENT_TYPE data: ", eventData);
});

Best Practices

• Use singleTabEditor to prevent confusion when users have multiple tabs open
• Add IDs to HTML elements with sync attributes for more robust syncing
• Only apply sync attributes to native HTML elements, not framework components