Message composer UI

The message composer UI is where a user writes, edits and sends a message. The message composition is held by a MessageComposer controller from stream-chat, in its state stores: the text, attachments, quoted message, poll and location. The UI components subscribe to that state and call the controller's API to carry out what the user does. Use this page to know which MessageComposer controller the UI uses (the channel's, the thread's, or one you supply), what each part of the UI shows, and how to add or replace parts. The props are in the MessageComposer reference, and the controller is explained on Message composer.

This composer is replying to Cara, with an image attached and a link in its text. Its parts, from top to bottom:

Which composer it drives

<MessageComposer/>, its parts and your own components get the composer from useMessageComposerController(). It returns a composer supplied with MessageComposerControllerProvider, or else the thread's or the channel's:

graph LR
    H["useMessageComposerController()"] --> P{"Supplied by a provider?"}
    P -- no --> T{"In a Thread?"}
    P -- yes --> S["supplied composer"]
    T -- yes --> TC["thread.messageComposer"]
    T -- no --> CC["channel.messageComposer"]

Supply a composer of your own for a separate composition, such as editing a message inline, so its state doesn't leak into the channel's or thread's composer already rendered in the UI. This InlineEditor component edits a message in a composer of its own:

import { useState } from "react";
import { MessageComposer as MessageComposerController } from "stream-chat";
import type { LocalMessage } from "stream-chat";
import {
  MessageComposer,
  MessageComposerControllerProvider,
  useChatContext,
} from "stream-chat-react";

export const InlineEditor = ({ message }: { message: LocalMessage }) => {
  const { client } = useChatContext();
  const [composer] = useState(
    () =>
      new MessageComposerController({
        client,
        composition: message,
        compositionContext: message,
      }),
  );

  return (
    <MessageComposerControllerProvider messageComposerController={composer}>
      <MessageComposer />
    </MessageComposerControllerProvider>
  );
};

Inline message editing builds the full editor.

The default "Edit" action edits in the channel's or thread's composer itself:

When <MessageComposer/> unmounts:

Previews

Above the input, the composer shows what the message will carry: the message being replied to, the files, a link card and so on. <MessageComposerPreviews/> renders these previews from a preview set.

The preview set

A preview set is an array, and each item in it describes one preview:

<MessageComposerPreviews/> goes through the set in order and renders the Component of every item whose isVisible returns true. When none does, it renders nothing, not even its wrapper. When any does, the wrapper renders, even if that item's Component then renders nothing, so an item that often has nothing to show should hide itself through isVisible.

The default set, defaultMessageComposerPreviewSet, has these items, in this order:

type	Shows	Visible while	Looks like
editedMessage	The message being edited, with ✕ to cancel the edit	a message is being edited
quotedMessage	The message being replied to, with ✕ to remove it	a message is quoted and none is being edited
voiceRecording	A recording waiting to be sent	the composer holds a voice recording
attachments	Files, images and videos, with their upload progress	the composer holds an attachment other than a voice recording
linkPreviews	The first link's card. The displayLinkCount prop of <LinkPreviewList/> shows more.	a link preview is loading or loaded
location	A location to share, as <GeolocationPreview/>. It can't be removed while editing.	the composer holds a location

No item shows a poll: the default poll creation dialog sends the poll at once, so the composer doesn't keep one. Poll with text and attachments keeps the poll in the composer and adds an item that shows it.

Custom previews

To hide, reorder or add previews, build your own set from the default one, render <MessageComposerPreviews/> with it, and register that component under the MessageComposerPreviews key. The state isVisible gets is what useMessageComposerPreviewState returns.

Here is a ComposerPreviews component that hides the link cards and adds a hint while the user replies:

import type { ReactNode } from "react";
import {
  defaultMessageComposerPreviewSet,
  MessageComposerPreviews,
  type MessageComposerPreviewSetItem,
  WithComponents,
} from "stream-chat-react";

// Your own preview: static text, so it reads no composer state.
const ReplyHint = () => (
  <div className="reply-hint">Everyone in the channel sees your reply.</div>
);

// The default previews without the link cards, then the hint while a message is quoted.
const previewSet: MessageComposerPreviewSetItem[] = [
  ...defaultMessageComposerPreviewSet.filter(
    ({ type }) => type !== "linkPreviews",
  ),
  {
    Component: ReplyHint,
    isVisible: ({ editedMessage, quotedMessage }) =>
      !editedMessage && !!quotedMessage,
    type: "replyHint",
  },
];

const CustomPreviews = () => (
  <MessageComposerPreviews messageComposerPreviewSet={previewSet} />
);

const overrides = { MessageComposerPreviews: CustomPreviews };

export const ComposerPreviews = ({ children }: { children: ReactNode }) => (
  <WithComponents overrides={overrides}>{children}</WithComponents>
);

Hiding an item hides only its preview. The message still carries what the composer holds: here, the link previews still go out with it.

To build a preview area of your own, use the two hooks <MessageComposerPreviews/> is built on. useMessageComposerPreviewSetFilter returns the visible items of a set. useMessageComposerPreviewState returns the state that isVisible gets.

The input

<TextareaComposer/> is the text input. It reads and writes messageComposer.textComposer state: the text, the cursor position, the mentions and the active command.

Typing a trigger opens the suggestion list, <SuggestionList/>: @ suggests people and groups to mention, / suggests commands, and : suggests emoji once you add the emoji middleware from stream-chat-react/emojis to the text composer. Each item is a <SuggestionListItem/>. The suggestions come from the text composer's middleware; Suggestions explains them.

Picking a command, such as /giphy, shows it as a chip before the input, <CommandChip/>. The chip's ✕ clears the command.

Actions

The composer has three action areas around the input:

The send area shows the first of these that applies:

In threads

In a thread, the composer shows a checkbox, <SendToChannelCheckbox/>, that also posts the reply to the channel. It reads "Also send in channel", or "Also send as a direct message" in a channel with two members. It toggles showReplyInChannel in the composer's state, and is hidden while editing.

Drag and drop

Files dropped on the composer are uploaded into it. The composer UI wraps itself in <WithDragAndDropUpload/>, which shows "Drag your files here" while files are dragged over it, and refuses the files that messageComposer.attachments.acceptedFiles in client.config doesn't accept.

To accept drops on a larger area, such as the whole channel, wrap that area in <WithDragAndDropUpload/>. Files dropped anywhere in it go to the composers inside. Here is a ChannelWithDropZone component that accepts drops on the whole channel:

import {
  Channel,
  ChannelHeader,
  MessageComposer,
  MessageList,
  WithDragAndDropUpload,
} from "stream-chat-react";
import type { Channel as StreamChannel } from "stream-chat";

export const ChannelWithDropZone = ({
  channel,
}: {
  channel: StreamChannel;
}) => (
  <Channel channel={channel}>
    <WithDragAndDropUpload className="channel-drop-zone" component="section">
      <ChannelHeader />
      <MessageList />
      <MessageComposer />
    </WithDragAndDropUpload>
  </Channel>
);

A thread works the same way: wrap its list and composer inside <Thread/>. The thread renders beside the channel, not inside it, so each wrapper uploads only to its own composer. A wrapper uploads a dropped file to every composer inside it, so wrap the channel and the thread separately. When wrappers are nested, only the outermost one handles drops. It gets the class str-chat__dropzone-root, which makes the overlay cover it; add your own layout with className if necessary.

The composer's own drop zone turns off during a cooldown and when the user can't upload files. A wrapper around it takes over and stays on, but the composer still refuses those uploads. The props are in the WithDragAndDropUpload reference.

The composer state each UI part reads

Each part of the composer UI subscribes to the state of the MessageComposer member it shows, and calls that member's API when the user acts:

A UI part of your own reads the same way: get the composer with useMessageComposerController() and subscribe to a store with useStateStore. Here is a ComposerWithCount component that shows the number of characters typed, beside the emoji picker:

import type { TextComposerState } from "stream-chat";
import {
  AdditionalMessageComposerActions,
  MessageComposer,
  useMessageComposerController,
  useStateStore,
  WithComponents,
} from "stream-chat-react";

const textSelector = ({ text }: TextComposerState) => ({ text });

const CharacterCount = () => {
  const { textComposer } = useMessageComposerController();
  const { text } = useStateStore(textComposer.state, textSelector);

  return <span className="character-count">{text.length}</span>;
};

// Renders the default part too, so the emoji picker stays.
const ActionsWithCount = () => (
  <>
    <CharacterCount />
    <AdditionalMessageComposerActions />
  </>
);

const overrides = { AdditionalMessageComposerActions: ActionsWithCount };

export const ComposerWithCount = () => (
  <WithComponents overrides={overrides}>
    <MessageComposer />
  </WithComponents>
);

The same part works in a channel, in a thread and while editing, because the hook returns the composer of the place it is rendered in.

Replacing parts

Register replacements with <WithComponents/>. Overriding components explains how overrides apply.

A replacement for EditedMessagePreview, QuotedMessagePreview, VoiceRecordingPreviewSlot, AttachmentPreviewList or LinkPreviewList shows only while its item in the preview set is visible. Say your AttachmentPreviewList also draws the location. It still shows only while the composer holds attachments, so a location on its own wouldn't appear. Build your own preview set from defaultMessageComposerPreviewSet, as Custom previews shows, and in it:

• make the attachments item's isVisible also return true while the composer holds a location;
• leave out the location item, so the location isn't drawn twice.

The defaults of SendToChannelCheckbox and StopAIGenerationButton aren't exported, so a replacement for one of them can't render the default inside it.

The Custom composer recipe builds a composer UI of its own.

Used in

• Sending, editing and deleting
• Drafts
• Attachments and uploads
• Polls
• Location sharing
• Link previews
• Commands and Giphy
• Emoji
• Custom composer, Attachment previews, Attachment actions and Custom suggestions