Getter and Setter Methods

Set Live Data

The Live State Sync feature allows you to set and update shared data that syncs in real-time across all connected clients. Params

liveStateDataId (string, required): A unique string ID to identify the data
liveStateData (any serializable type, required): The data to sync (objects, arrays, strings, numbers)
setLiveStateDataConfig (object, optional): Configuration object
- merge (boolean): Whether to merge the data with existing data (default: false)

Live State data persists indefinitely until manually removed - there is no automatic cleanup.

React / Next.js
Other Frameworks

const liveStateDataId = 'uniqueId'; // A unique string identifier for the data
const liveStateData = { 'key': 'value' }; // The data to be synced (can be any serializable type)
const config = { merge: true };

// Using Hooks
useSetLiveStateData(liveStateDataId, liveStateData, config);

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setLiveStateData(liveStateDataId, liveStateData, config);

const liveStateDataId = 'uniqueId';
const liveStateData = { 'key': 'value' }; // any type of data
const config = { merge: true };

const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.setLiveStateData(liveStateDataId, liveStateData, config);

Get Live Data

Get live state data by providing the unique ID used when setting the data. Params

liveStateDataId (string, required) - A unique string ID to identify the data to retrieve
liveStateDataConfig (object, optional) - Configuration object for controlling data retrieval behavior
- listenToNewChangesOnly (boolean, optional) - Whether to only receive new changes from when the client subscribed (default: false)

React / Next.js
Other Frameworks

const liveStateDataConfig = {
	listenToNewChangesOnly: true // default is false
};
const liveStateDataId = 'uniqueId';

// Using Hooks
const liveStateData = useLiveStateData(liveStateDataId, liveStateDataConfig);

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getLiveStateData(liveStateDataId, liveStateDataConfig).subscribe((data) => {
		// your logic here...
});

If using API, you can unsubscribe from the subscription after you are done:

subscription?.unsubscribe()

const liveStateDataConfig = {
	listenToNewChangesOnly: true // default is false
};
const liveStateDataId = 'uniqueId';

const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.getLiveStateData(liveStateDataId, liveStateDataConfig).subscribe((data) => {
		// your logic here...
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

Fetch Live Data

Fetch live state data as a Promise when you need to retrieve the current state once, rather than subscribing to ongoing changes. This is useful for initialization, conditional logic, or one-time data retrieval. When to use fetchLiveStateData() vs getLiveStateData():

Use fetchLiveStateData() (Promise): When you need the current value once
Use getLiveStateData() (Observable): When you want to reactively update to changes

Params

request (FetchLiveStateDataRequest, optional): Configuration object
- liveStateDataId (string, optional): Unique identifier for specific data. If not provided, returns all live state data.

Returns

Promise<T>: Promise resolving to the live state data. Supports generic type for type safety.

Common Use Cases:

Initializing state on component mount
Checking current state before performing an action
Loading data for server-side rendering
One-time data retrieval without needing updates

React / Next.js
Other Frameworks

// Using Hooks
const liveStateSyncElement = useLiveStateSyncUtils();

/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();

/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
    liveStateDataId: "LIVE_STATE_DATA_ID"
});

// Using API methods
const liveStateSyncElement = client.getLiveStateSyncElement();

/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();

/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
    liveStateDataId: "LIVE_STATE_DATA_ID"
});

const liveStateSyncElement = Velt.getLiveStateSyncElement();

// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();

// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
    liveStateDataId: "LIVE_STATE_DATA_ID"
});

Alternative: useLiveState()

The useLiveState() hook provides a familiar React’s useState() like API while automatically syncing state changes across all connected clients in real-time. The hook accepts the following parameters:

id (string, required): Unique identifier for syncing this state across clients
initialValue (any, required): Initial state value
options (object, optional): Configuration object with the following properties:
- syncDuration (number, optional): Debounce delay in milliseconds before syncing. Defaults to 50ms.
- resetLiveState (boolean, optional): Whether to reset server state when the hook initializes. Defaults to false.
- listenToNewChangesOnly (boolean, optional): When true, only receives changes that occur after subscribing and discards historical changes. Defaults to false.

Returns

[value, setValue, connectionState]
- value: Current value of the data you set
- setValue: Function to update the data
- connectionState: Current server connection status

React / Next.js

import { useLiveState } from "@veltdev/react";

export function MyReactComponent() {
  const [counter, setCounter, serverConnectionStateInLiveState] = useLiveState<number> ("counter", 0, {
    syncDuration: 100,
    resetLiveState: true,
    listenToNewChangesOnly: true // receive only new changes from when the client subscribed
  });

  useEffect(() => {
    console.log('serverConnectionStateInLiveState:', serverConnectionStateInLiveState);
  }, [serverConnectionStateInLiveState]);

  return (
    <div>
      <button onClick={() => setCounter((counter || 0) - 1)}>-</button>
      <span>Counter: {counter}</span>
      <button onClick={() => setCounter((counter || 0) + 1)}>+</button>
    </div>
  );
}

Server Connection State

The server connection state indicates the current status of the connection to Velt’s servers. The possible states are:

enum ServerConnectionState {
  ONLINE = 'online', // Connected to Velt's servers
  OFFLINE = 'offline', // Not connected to Velt's servers
  PENDING_INIT = 'pendingInit', // Pending SDK Initialization
  PENDING_DATA = 'pendingData', // Pending receiving data from server
}

React / Next.js
Other Frameworks

// Using Hooks
const serverConnectionState = useServerConnectionStateChangeHandler();

useEffect(() => {
  console.log('serverConnectionState', serverConnectionState);
}, [serverConnectionState]);

// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.onServerConnectionStateChange().subscribe((data) => {
  console.log('server connection state change: ', data);
});

If using API, you can unsubscribe from the subscription after you are done:

subscription?.unsubscribe()

const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.onServerConnectionStateChange().subscribe((data) => {
  console.log('server connection state change: ', data);
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

Best Practices

Keep your state data structures simple and flat when possible
Use meaningful IDs that reflect the purpose of the data
If using APIs, clean up subscriptions when components unmount
Consider network latency when setting syncDuration
Sync only what you need, not the entire state
Use listenToNewChangesOnly when appropriate

​Getter and Setter Methods

​Set Live Data

​Get Live Data

​Fetch Live Data

​Alternative: useLiveState()

​Server Connection State

​Best Practices

Getter and Setter Methods

Set Live Data

Get Live Data

Fetch Live Data

Alternative: useLiveState()

Server Connection State

Best Practices