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)

const liveStateSyncElement = useLiveStateSyncUtils();

// Basic usage
liveStateSyncElement.enableSingleEditorMode();

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

const liveStateSyncElement = useLiveStateSyncUtils();

// Basic usage
liveStateSyncElement.enableSingleEditorMode();

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

// Get LiveStateSyncElement from Velt Client
const liveStateSyncElement = Velt.getLiveStateSyncElement();

// Basic usage
liveStateSyncElement.enableSingleEditorMode();

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

disableSingleEditorMode

Disables single editor mode and returns to normal editing.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

// 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>
);

// 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>
);

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

<!-- Exclude elements from sync access -->
<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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.disableEditorAccessTransferOnTimeOut();

getEditorAccessTimer

Track the state of editor access request timeout.

Returns

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

// 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);
});

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

const liveStateSyncElement = useLiveStateSyncUtils();

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

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

const liveStateSyncElement = useLiveStateSyncUtils();

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

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

<script>
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.enableAutoSyncState();
</script>

<body>
    <!-- Enable auto-sync on text elements -->
    <textarea id="uniqueId" data-velt-sync-state="true"></textarea>
</body>

Editor

setUserAsEditor

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

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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

// 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()

// 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()

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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

// 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()

// 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()

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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

// 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()

// 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()

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.acceptEditorAccessRequest();

rejectEditorAccessRequest

Reject editor access requests.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.rejectEditorAccessRequest();

editCurrentTab

Make current tab editable when editor has multiple tabs open.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.editCurrentTab();

Viewer

requestEditorAccess

Request editor access from the current editor.

Returns

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

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()

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()

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.cancelEditorAccessRequest();

resetUserAccess

Reset editor access for all users.

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();
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.

const liveStateSyncElement = useLiveStateSyncUtils();

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

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

const liveStateSyncElement = useLiveStateSyncUtils();

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

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

const liveStateSyncElement = Velt.getLiveStateSyncElement();

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

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

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

<velt-single-editor-mode-panel shadow-dom="false" dark-mode="true" variant="custom-ui"></velt-single-editor-mode-panel>

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

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);
});

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);
});

const liveStateSyncElement = Velt.getLiveStateSyncElement();
// 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

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Email Notifications

Webhooks

Security

Miscellaneous

Setup

Core Configurations

enableSingleEditorMode

disableSingleEditorMode

Define Single Editor Mode Elements

Restrict to specific containers

Fine tune elements control

Timeout Configuration

setEditorAccessTimeout

enableEditorAccessTransferOnTimeOut

disableEditorAccessTransferOnTimeOut

getEditorAccessTimer

Auto-Sync Text Elements

Editor

setUserAsEditor

isUserEditor

getEditor

isEditorAccessRequested

acceptEditorAccessRequest

rejectEditorAccessRequest

editCurrentTab

Viewer

requestEditorAccess

cancelEditorAccessRequest

resetUserAccess

UI

enableDefaultSingleEditorUI

Embed Single Editor Mode Panel

Event Subscription

on

Best Practices

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Email Notifications

Webhooks

Security

Miscellaneous

​Core Configurations

​enableSingleEditorMode

​disableSingleEditorMode

​Define Single Editor Mode Elements

​Restrict to specific containers

​Fine tune elements control

​Timeout Configuration

​setEditorAccessTimeout

​enableEditorAccessTransferOnTimeOut

​disableEditorAccessTransferOnTimeOut

​getEditorAccessTimer

​Auto-Sync Text Elements

​Editor

​setUserAsEditor

​isUserEditor

​getEditor

​isEditorAccessRequested

​acceptEditorAccessRequest

​rejectEditorAccessRequest

​editCurrentTab

​Viewer

​requestEditorAccess

​cancelEditorAccessRequest

​resetUserAccess

​UI

​enableDefaultSingleEditorUI

​Embed Single Editor Mode Panel

​Event Subscription

​on

​Best Practices

Core Configurations

enableSingleEditorMode

disableSingleEditorMode

Define Single Editor Mode Elements

Restrict to specific containers

Fine tune elements control

Timeout Configuration

setEditorAccessTimeout

enableEditorAccessTransferOnTimeOut

disableEditorAccessTransferOnTimeOut

getEditorAccessTimer

Auto-Sync Text Elements

Editor

setUserAsEditor

isUserEditor

getEditor

isEditorAccessRequested

acceptEditorAccessRequest

rejectEditorAccessRequest

editCurrentTab

Viewer

requestEditorAccess

cancelEditorAccessRequest

resetUserAccess

UI

enableDefaultSingleEditorUI

Embed Single Editor Mode Panel

Event Subscription

on

Best Practices