ChatView components

ChatView is the SDK's layout. It decides where an opened channel or thread goes, and the components on this page render what it placed. Workspace with ChatView explains how they work together.

Everything on this page imports from stream-chat-react/slot-layout.

ChatView

The root of the layout. It holds the layout's state, provides workspace navigation to the components inside it, and renders the shown view. What it renders depends on its props:

• With views: its children, then the shown view's content.
• With layout="nav-rail-entity-list-workspace" and no views: the built-in workspace layout, the view selector in a rail, then every slot of the shown view rendered through slotRenderers. Its children aren't rendered.
• With neither: its children.

Its root element has the classes str-chat, the theme from Chat, and str-chat__chat-view.

"Keep it stable" means declaring the value outside the component, or memoizing it. Views and slots explains why layouts has to be stable too.

useChatViewContext

useChatViewContext() reads the ChatView around the component. It throws outside a ChatView.

ChatViewContext itself is exported too. useContext(ChatViewContext) returns undefined outside a ChatView instead of throwing, which suits a component that also renders without one.

Switching between the channel list and the thread list has an example of setActiveView. For opening and closing channels and threads, use useWorkspaceNavigation() instead: it works with any layout.

DisposedChannelRelease

DisposedChannelRelease empties every slot of the shown view whose channel stream-chat disposed of: deleted, or the current user removed from it. It takes no props and renders nothing. It's opt-in: render it once inside ChatView, as one of its children. The built-in layout doesn't render ChatView's children, so it can't host it. Disposed channels explains when a channel is disposed of.

WorkspaceLayout

A frame of slots: an optional rail, then a row of slots. The built-in workspace layout is a WorkspaceLayout, and a view's content can use one too.

While no entry has content that renders something (every one is undefined, null or a boolean), WorkspaceLayout shows ChatViewEmptyPlaceholder in place of the slots. So give each slot its content. An entry without content, next to one with content, renders what its slot holds through slotRenderers.

import {
  ChannelHeader,
  ChannelNavigation,
  MessageComposer,
  MessageList,
  ThreadHeader,
  ThreadList,
} from "stream-chat-react";
import {
  ChannelSlot,
  ChatView,
  ChatViewEmptyPlaceholder,
  ThreadSlot,
  WorkspaceLayout,
} from "stream-chat-react/slot-layout";
import type { LayoutDescriptor } from "stream-chat-react/slot-layout";

// "list" isn't one of the views' slots, so nothing opens there.
const layouts: LayoutDescriptor[] = [
  { id: "channels", slots: ["channel", "thread"] },
  { id: "threads", slots: ["thread"] },
];

const threadPanel = {
  content: (
    <ThreadSlot slot="thread">
      <ThreadHeader />
      <MessageList />
      <MessageComposer />
    </ThreadSlot>
  ),
  slot: "thread",
};

const ChannelsView = () => (
  <WorkspaceLayout
    navRail={<ChatView.Selector />}
    slots={[
      { content: <ChannelNavigation />, slot: "list" },
      {
        content: (
          <ChannelSlot fallback={<ChatViewEmptyPlaceholder />} slot="channel">
            <ChannelHeader />
            <MessageList />
            <MessageComposer />
          </ChannelSlot>
        ),
        slot: "channel",
      },
      threadPanel,
    ]}
  />
);

const ThreadsView = () => (
  <WorkspaceLayout
    navRail={<ChatView.Selector />}
    slots={[{ content: <ThreadList />, slot: "list" }, threadPanel]}
  />
);

export const Workspace = () => (
  <ChatView
    layouts={layouts}
    views={{ channels: <ChannelsView />, threads: <ThreadsView /> }}
  />
);

Each view gets its content: the selector can show either view, and a view without content renders nothing, the selector included. The channels view has a thread slot so that a reply thread opens beside the channel. With only a channel slot, the thread would replace the channel there, and ChannelSlot would show its fallback.

ChatViewEmptyPlaceholder

The SDK's empty state for a layout: an icon and "No chat selected", or "No thread selected" in the threads view. It takes no props. WorkspaceLayout shows it while no slot has content, and it works as a fallback or SlotFallback. Outside a ChatView, it uses the channels wording.

Slot

Renders what one slot holds, and the layers on top of it, through slotRenderers.

It renders a section with the class str-chat__chat-view__slot and data-slot set to the slot name. A hidden slot also gets str-chat__chat-view__slot--hidden and aria-hidden, and stays mounted. While the slot has layers, what it holds and each layer stay mounted: only the top one shows, and the ones beneath get the hidden attribute. Pushing the first layer and removing the last one mount what the slot holds again, so it loses its scroll position.

Slot declares its slot as the panel its content renders in, so useWorkspacePanel() inside returns the slot name. Panels explains what the panel is for.

Entity adapters

Three components render a slot's channel, thread or thread list with the matching SDK component, around their children. Rendering a slot compares them with Slot.

Always pass slot. Without it, ChannelSlot and ThreadSlot render the first channel or thread in the view, which is only right in a layout with one of each. An adapter only displays: it never moves a channel or thread from another slot.

ChannelSlot

Renders a Channel for the channel in its slot. It shows what the slot holds underneath any layer, never the layer.

It also takes every prop of Channel except channel, and passes them on.

ThreadSlot

Renders a Thread for the thread in its slot. Like ChannelSlot, it shows what the slot holds underneath any layer.

It also takes every prop of Thread except thread. ThreadSlot doesn't mark the thread as on screen: call useActiveThread inside it.

ThreadListSlot

Puts a thread list in a slot of the shown view, and renders that slot as a Slot. The slot it uses is the first of: slot, when the view has it; the slot that already holds a thread list; the first empty slot; the view's first slot. When slot is passed and another slot holds the list, it empties that one.

Without children or fallback, the slot renders slotRenderers.threadList, which is ThreadList by default.

View selector

ChatView.Selector renders the buttons that switch views, in a role="navigation" element labelled "Chat view controls".

Each entry is { Component, type }: Component receives iconOnly, and type is the entry's unique key. The default set is the channels button and the threads button. A button of your own doesn't have to switch views: there are only the two, channels and threads. This set adds a button that opens a support channel:

import { useMemo } from "react";
import { useChatContext, useWorkspaceNavigation } from "stream-chat-react";
import {
  ChatView,
  ChatViewSelectorButton,
  defaultChatViewSelectorItemSet,
} from "stream-chat-react/slot-layout";
import type {
  ChatViewSelectorEntry,
  ChatViewSelectorItemProps,
} from "stream-chat-react/slot-layout";

const SupportIcon = () => (
  <svg aria-hidden="true" viewBox="0 0 20 20">
    <circle cx="10" cy="10" fill="currentColor" r="8" />
  </svg>
);

const SupportSelectorButton = ({ iconOnly }: ChatViewSelectorItemProps) => {
  const { client } = useChatContext();
  const { isChannelActive, openChannel } = useWorkspaceNavigation();
  const channel = useMemo(
    () => client.channel("messaging", "support"),
    [client],
  );

  return (
    <ChatViewSelectorButton
      Icon={SupportIcon}
      iconOnly={iconOnly}
      isActive={isChannelActive(channel.cid)}
      onClick={(event) => {
        // openChannel places the channel; watching loads it.
        channel.watch().catch((error) => console.error(error));
        openChannel(channel, { event });
      }}
      text="Support"
    />
  );
};

const itemSet: ChatViewSelectorEntry[] = [
  ...defaultChatViewSelectorItemSet,
  { Component: SupportSelectorButton, type: "support" },
];

export const Selector = () => <ChatView.Selector itemSet={itemSet} />;

The individual buttons

Render them directly when a rail of your own needs its own arrangement.

ChatViewSelectorButton takes every prop of a button, plus:

useActiveThread

useActiveThread({ activeThread }) marks a thread as on screen while the window is visible and focused, and unmarks it when the window is hidden or loses focus, when the component unmounts, and when activeThread changes. It returns nothing.

While a thread is on screen, its new replies are marked read, and a thread that went out of date, after a lost connection for example, reloads. ThreadSlot doesn't call it, so call it from a component inside the slot:

const ActiveThread = () => {
  const thread = useThreadContext();
  useActiveThread({ activeThread: thread });
  return null;
};

It doesn't need ChatView: Providing your own navigation calls it without one.

See also

• Workspace with ChatView: views, slots, where things land, and rendering a slot.
• Slot layout: the bindings, the layout controller and the hooks that read the layout.
• Workspace navigation API: the navigation ChatView provides.