Slot layout

The slot layout is the model behind ChatView: its views, the slots in each view, and what each slot holds. This page lists its types, the layout controller, and the hooks that read and change it. Workspace with ChatView explains how it behaves.

Everything on this page imports from stream-chat-react/slot-layout. The navigation interface the SDK's components use, useWorkspaceNavigation(), imports from stream-chat-react: see Workspace navigation API.

The pieces

The layout controller knows which slots exist and what they hold. It doesn't know where they are on screen or how wide they are: the app's CSS places them, and Slot geometry reports what the CSS did.

Binding, not mounting

A slot holds a binding: the kind of thing it shows, a key, and the thing itself. Opening the channel messaging:design binds { kind: "channel", key: "messaging:design", source: channel } to a slot, and the component that renders the slot reads it from there. Where an opened channel or thread lands says which slot.

A binding you pass is a ChatViewEntityBinding: { key?: string; kind; source }. These are the kinds:

• The key is what the layout recognizes the channel or thread by: the channel's cid, or the thread's id. The duplicate check and the navigation's isChannelActive, closeChannel and the others compare it. A binding without a key is never a duplicate.
• A channel binding opens in the channels view, switching to it first. Every other kind opens in the view that's shown.
• A channelList or threadList binding makes its slot a list slot: navigation never picks it on its own, and close and release never empty it.

The layout controller stores bindings in another shape, LayoutSlotBinding: { key?: string; payload: unknown }, with the ChatViewEntityBinding as its payload. useLayoutViewState() returns that shape. Three functions convert:

useChatViewNavigation

useChatViewNavigation() changes what slots hold, following the same rules as the SDK's components. Every member acts on the shown view, and does nothing for a slot the view doesn't have. Outside a ChatView, open returns a rejection and the other members do nothing.

ChatViewOpenOptions:

OpenResult says what happened:

Where an opened channel or thread lands has an example of open with slot, and Layers one of pushLayer.

Layers and history

A slot can hold more than one thing over time: layers stacked on top of what it holds, and a back and forward history of what it held before. Layers and history explains both, and Hiding vs closing compares hide, close and release.

• Layers come from pushLayer, from layer: true, and from an open into a slot in use other than the main panel. While a slot has layers, Slot keeps what it holds and every layer mounted, and shows only the top one. Pushing the first layer and removing the last one mount what the slot holds again, so it loses its scroll position. Layers are never saved.
• History grows when an open replaces what a slot holds: the old binding goes onto the slot's back list. Opening something new clears the slot's forward list, and emptying the slot clears both. The SDK's back button removes a layer; it doesn't use the history.

The layout controller

useChatViewContext().layoutController holds the layout's state. Its methods change the shown view only, and skip the checks useChatViewNavigation() makes: they also act on list slots. Use the controller from an effect that would otherwise depend on the navigation's functions, which change with every layout change.

The methods that take a binding take a LayoutSlotBinding: make one with createChatViewSlotBinding. Back and forward per slot and List slots have examples. The LayoutController class isn't exported, only its type.

Configuring ChatView

ChatView's props are listed on ChatView components. These are the types its layout props take.

Keep these props stable, declared outside the component or memoized. A new layouts, duplicateEntityPolicy or resolveDuplicateEntity starts the layout again, and everything open closes. A new slotRenderers or viewActionSlotResolvers makes every component that reads the layout or the navigation render again.

LayoutDescriptor

layouts takes one LayoutDescriptor per view:

The built-in workspace layout has an example with initialBindings.

slotRenderers

slotRenderers is a ChatViewSlotRenderers: an object with a renderer per kind. A renderer receives ChatViewSlotRendererProps:

A renderer you pass replaces the default for its kind only. It's called as a plain function, not rendered as a component, so it must not call hooks: return an element, and call the hooks in that element's component. A renderer that returns null, undefined or a boolean leaves the slot empty. Slot and slotRenderers has an example.

SlotFallback and slotFallbackComponents take components that receive ChatViewSlotFallbackProps, { slot: string }.

Duplicates

duplicateEntityPolicy and resolveDuplicateEntity decide what happens when a channel or thread is opened into a slot while a slot of the view already holds it:

resolveDuplicateEntity is a ResolveDuplicateEntity: it decides per open, and wins over duplicateEntityPolicy. It receives ResolveDuplicateEntityArgs:

This one moves a channel that's opened again, and lets a thread show in two slots:

import { getChatViewEntityBinding } from "stream-chat-react/slot-layout";
import type { ResolveDuplicateEntity } from "stream-chat-react/slot-layout";

export const resolveDuplicateEntity: ResolveDuplicateEntity = ({ binding }) =>
  getChatViewEntityBinding(binding)?.kind === "channel" ? "move" : "allow";

A channel or thread stacked as a layer isn't checked.

viewActionSlotResolvers

viewActionSlotResolvers takes, per view, a ViewActionSlotResolvers: { openChannel?, openThread? }. Each is a ResolveViewActionTargetSlot, which returns a slot name, or undefined to leave the choice to ChatView. It receives ResolveViewActionTargetSlotArgs:

A resolver isn't asked for an open with additive, and a slot name the view doesn't have is ignored. Changing navigation behaviour has an example.

deriveWorkspaceNavigation

deriveWorkspaceNavigation is a DeriveWorkspaceNavigation. See Overriding navigation.

Reading layout state

These hooks read the layout and re-render when it changes. They throw outside a ChatView. Without view, they read the shown view.

The entity hooks read what a slot holds underneath any layer, except useSlotTopLayerEntity. Pass slot to be precise: without it, they return the first match, which is only right in a layout with one of each.

import { useSlotEntity, useSlotThreads } from "stream-chat-react/slot-layout";

export const WorkspaceStatus = () => {
  const channel = useSlotEntity({ kind: "channel", slot: "channel" });
  const threads = useSlotThreads();

  return (
    <p>
      {channel ? channel.cid : "No channel"}, {threads.length} threads open
    </p>
  );
};

getLayoutViewState(state, view?) reads the same without a hook, for example from layoutController.state.getLatestValue().

ChatViewLayoutViewState

Saving and restoring

• serializeEntityBinding is a SerializeLayoutEntityBinding: (binding: LayoutSlotBinding) => SerializedLayoutSlotBinding | undefined. It turns each binding into something JSON can hold, such as { key, payload: { cid } }. Return undefined to leave a binding out. Without it, bindings are copied as they are, channel and thread objects included, so the snapshot can't be stored as JSON.
• deserializeEntityBinding is a DeserializeLayoutEntityBinding: (saved: SerializedLayoutSlotBinding) => LayoutSlotBinding | undefined. It turns each saved entry back into a binding. Without it, saved entries are used as they are.
• Layers aren't saved.

Saving and restoring a layout has a complete example.