Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velt.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

​
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
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
}

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

​
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