LiveViewSocket API - Context

The "context" of a LiveView is the current state of the LiveView. One way to think of a LiveView is as a set of methods that handle events, read and write the context, and render a view based on the data in the context. Obviously, properties and methods that manipulate the context are very important to a LiveView.

Context Properties and Methods on the LiveViewSocket

Three parts of the LiveViewSocket are used to manipulate the context:

Name	Description
context (property, read-only)	The current context (i.e., state) of the LiveView
assign(context:Partial<TContext>):void;	Update the context (i.e., state) of the LiveView
tempAssign(context:Partial<TContext>):void;	Marks any set properties as temporary and will be reset to the given value after the next render cycle. Typically used to ensure large but infrequently updated values are not kept in memory.

Details

socket.assign and socket.context are the work-horse methods for manipulating and reading the state of the LiveView. The assign method is used to update the state of the LiveView and the context property is used to read the state of the LiveView.

// Update the context (i.e.,  current state) of the `LiveView`
socket.assign({ foo: "bar" });

// Read the context (i.e.,  current state) of the `LiveView`
if (socket.context.foo === "baz") {
  // do something
}
// or destructure data from the context
const { foo } = socket.context;

Context Type Annotations

When creating a LiveView, developers can provide a type annotation for TContext which describes the "shape" of the context for that LiveView. This is useful for providing type safety and autocomplete for the context (in Typescript).

// You can define the "shape" of the TContext by annotating the createLiveView function
const myLiveView = createLiveView<{foo: string}>(
  mount: (socket) => {
    socket.assign({ foo: "bar" });
    ...
    socket.assign({ baz: "qux" }); // type error no "baz" property in context
  }
  ...
)

You can type the Context inline as above or you can define the context type first and then use it as a type annotation:

// Define the MyContext interface
interface MyContext { foo: string };
// Annotate the createLiveView function with the MyContext interface
const myLiveView = createLiveView<MyContext>(...)

Context Persisted for the Life of the LiveView

The context of a LiveView is persisted on the server (in memory by default) which means any data added to the context (via assign) will be stored until that LiveView instance is cleaned up.

Temporary Data for Context

Sometimes you want to add data to a context that is temporary — that is, only added to the context for one "render cycle". There is a method called socket.tempAssign that allows a developer to tell LiveViewJS to set a context property to a given value after the render cycle. Typically this is used for large objects or collections that don't change often and therefore probably don't need to be stored in memory (e.g., collection of users or messages, etc).

// first assign a large object to the context
socket.assign({ photos: [
  ...// 10s, 100s, 1000s, of photos
]});
// use tempAssign to tell LiveViewJS to clear the photos array after this render cycle
socket.tempAssign({ photos: [] });