Realtime Store - React Native

The Realtime Store allows you to store, update, retrieve, and observe custom key-value data within a room — in real time. Every participant in the room sees the same values.

This is particularly useful for collaborative or stateful room experiences such as:

• Pinned messages and flags
• Moderation data (e.g., blocked users)
• Collaborative notes or polls

note

This page uses the following asynchronous methods. Refer to their API reference for the errors each Promise may reject with, and handle these rejections appropriately based on your use case.

• setValue()
• getValue()

useRealtimeStore

To utilize Realtime Store in a room, VideoSDK provides a hook called useRealtimeStore. This hook enables you to subscribe to any key and publish to any key, facilitating the exchange of realtime key-value data during the room.

---

setValue()

The setValue() method is used to store or update data in the RealtimeStore. If a key already exists, it will be overwritten with the new value. Passing null as the value deletes the key. Since this method throws errors directly, it should be enclosed in a try...catch block to handle exceptions gracefully.

Key Notes

• Supports string values only.
• Each key can store up to 1 KB of data.
• A maximum of 100 keys are allowed per session.
• Deletion is performed by setting the value to null.
• Throws an error if:
  • The room is not joined or is reconnecting (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED, ERROR_ROOM_RECONNECTING).
  • The value is larger than 1 KB (ERROR_PAYLOAD_TOO_LARGE).
  • The request fails or the session exceeds the 100-key limit (FAILED_TO_SET_VALUE).
  • The request times out (ERROR_OPERATION_TIMED_OUT).

Example

import { useRealtimeStore } from "@videosdk.live/react-native-sdk";
import { TouchableOpacity, Text } from "react-native";

const RoomView = () => {
  //Getting the setValue method from hook
  const { setValue } = useRealtimeStore("Blocked_Students");

  const handleSetValue = async () => {
    try {
      await setValue("[abcd,efgh]");
      console.log("Data set successfully!");
    } catch (error) {
      console.error("Failed to set data:", error);
    }
  };

  return (
    <TouchableOpacity
      onPress={() => {
        handleSetValue();
      }}
    >
      <Text> Set Value </Text>
    </TouchableOpacity>
  );
};

---

getValue()

The getValue() method retrieves the current value associated with a given key. It rejects on failure, so call it inside a try...catch block.

Key Notes

• Resolves the current string value for the given key, or null when the server answers with no value.
• Useful for fetching shared state when joining a room or reloading a view.
• Rejects if:
  • The key is not set or was cleared (4046 FAILED_TO_GET_VALUE). Treat this as "no value yet".
  • The room is not joined or is reconnecting (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED, ERROR_ROOM_RECONNECTING).
  • The server otherwise refuses the request (FAILED_TO_GET_VALUE).
  • The request times out (ERROR_OPERATION_TIMED_OUT).

Example

import { useRealtimeStore } from "@videosdk.live/react-native-sdk";
import { TouchableOpacity, Text } from "react-native";

const RoomView = () => {
  //Getting the getValue method from hook
  const { getValue } = useRealtimeStore("Blocked_Students");

  const handleGetValue = async () => {
    try {
      const value = await getValue();
    } catch (error) {
      console.error("Failed to get data:", error);
    }
  };

  return (
    <TouchableOpacity
      onPress={() => {
        handleGetValue();
      }}
    >
      <Text> Get Value </Text>
    </TouchableOpacity>
  );
};

---

onValueChanged()

The onValueChanged event is emitted whenever a value is changed for the given key in the realtime store. It receives two arguments: the new value and updatedBy, the participant who made the change. updatedBy is null once that participant has left.

Example

import { useRealtimeStore } from "@videosdk.live/react-native-sdk";

const RoomView = () => {
  //Event to receive the data
  function onValueChanged(value, updatedBy) {
    console.log("onValueChanged", value, updatedBy?.id);
  }

  //Passing the onValueChanged callback to the hook
  const {} = useRealtimeStore("Blocked_Students", {
    onValueChanged,
  });

};

---

⚠️ Error Handling & Constraints

Property	Description
Error Handling	All RealtimeStore methods throw directly; wrap them in try...catch.
Payload Size	Maximum 1 KB per key.
Supported Type	Only string values are supported. Use null to delete key.
Concurrency	The latest write overwrites previous values (last write wins)
Key Limit	A maximum of 100 keys are allowed in a single session.

API Reference

The API references for all the methods utilized in this guide are provided below:

• useRealtimeStore()