​

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)

When setting data with an existing ID, it updates that data. All subscriptions are automatically managed and cleaned up.

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

// Using Hooks
useSetLiveStateData(liveStateDataId, liveStateData);

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

​

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

subscription?.unsubscribe()

​

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

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