MessageComposer API

This page lists the API of MessageComposer in stream-chat and of the parts it's built from: the text composer, the attachment manager, the link previews manager, the location composer, the poll composer and the custom data manager.

What a composer does, and how sending, uploads, drafts and editing work, is explained on Message composer. Its middleware chains are on Composer middleware, and its settings on Configuration tree.

Best practices

• Subscribe to a part's state to follow it. Getters such as textComposer.text or composer.quotedMessage return the value at the moment you read them, and don't tell you when it changes.
• Change state through the methods below. Writing to a store directly skips the checks and side effects the methods run, such as cancelling uploads or applying a command.
• Check what MessageComposer.send() and MessageComposer.update() return. They never throw: they resolve to 'sent', 'nothing-to-send' or 'failed'.
• Configure every composer through client.config. Settings made on one composer with MessageComposer.updateConfig() or a setter stay on that composer, and uploads always use the channel composer's upload settings.
• Change behaviour with middleware. Adding, replacing or removing a step of a chain is the supported way to change how text, uploads and messages are processed.
• Inside a thread, use the thread's composer, thread.messageComposer, not the channel's.

const unsubscribe = composer.textComposer.state.subscribeWithSelector(
  ({ text }) => ({ text }),
  ({ text }) => console.log(`${text.length} characters`),
);

MessageComposer class architecture

A MessageComposer coordinates its parts. Each part keeps its data in a store of its own:

graph TD
    MC[MessageComposer] --> TC[textComposer]
    MC --> AM[attachmentManager]
    MC --> LPM[linkPreviewsManager]
    MC --> LC[locationComposer]
    MC --> PC[pollComposer]
    MC --> CDM[customDataManager]

Getting a composer

The channel and thread composers are created with their channel or thread. Build a composer yourself only to edit a message outside them:

import { MessageComposer } from "stream-chat";

const editComposer = new MessageComposer({
  client,
  compositionContext: message,
  composition: message,
});

The constructor takes MessageComposerOptions:

A composer starts with an empty state, with a draft, or with a message to edit:

• Empty. The composer has a new id, which becomes the id of the message it sends.
• A draft. The content is loaded, and draftId is the draft's id. The message gets a new id.
• A message to edit. The content is loaded, editedMessage is the message, and id is the message's id. Drafts aren't saved and commands can't be used while editing.

Composer state

Getters

The getters of MessageComposer return the value at the moment you read them, and don't tell you when it changes.

Methods

Sending

MessageComposerSubmitResult is 'sent', 'nothing-to-send' or 'failed'. Message composer explains each one.

const result = await composer.send();

if (result === "failed") {
  // The message is in the list as failed, and the composer is already empty.
}

State

Drafts. MessageComposer.createDraft(), MessageComposer.deleteDraft() and MessageComposer.getDraft() do nothing while drafts.enabled is off or a message is being edited. The first two also do nothing for a channel that has no id yet.

Polls

Commands

Configuration

Effects and snapshots. The command chips use these, and Effect handlers explains them.

Subscriptions

Static members

Events

While its subscriptions run, a composer reacts to these:

The composer also rebuilds its settings when client.config or its setup function changes and when the channel's server settings arrive. When the content becomes empty, it deletes the draft. When the text changes, it looks for links to preview.

Text composition with suggestions

composer.textComposer is a TextComposer. Its state holds:

A MentionEntity has an id and a mentionType: 'user' (with the user's fields), 'channel', 'here', 'role' or 'user_group'. Suggestions explains how mentions and commands are found.

Getters and setters

text, selection, mentions, mentionedUsers, command, suggestions and typing read the state. textIsEmpty says whether the text is empty or only Markdown markers. config is composer.config.text, channel the composer's channel, and middlewareExecutor the text chain.

These read the composer's text settings and write them with MessageComposer.updateConfig(), for this composer only:

Methods

TextComposer.upsertMentionedUser(user), TextComposer.getMentionedUser(userId) and TextComposer.removeMentionedUser(userId) are deprecated. Use the mention-entity methods with mentionType: 'user'.

Pass a selection to TextComposer.insertText() and TextComposer.wrapSelection(), or keep the cursor current with TextComposer.setSelection(): without one they use textComposer.selection.

textIsEmpty(text), exported from stream-chat, is the check textIsEmpty uses.

Attachment management

composer.attachmentManager is an AttachmentManager. Its state has one field, attachments, a LocalAttachment[].

Every local attachment has a localMetadata object, which is removed before the message is sent:

An attachment loaded from a draft or an edited message has only an id and, for an uploaded file, uploadState: 'finished'.

Getters

acceptedFiles, maxNumberOfFilesPerMessage and the deprecated fileUploadFilter are getters and setters for the settings of those names, on this composer only. preUploadMiddlewareExecutor and postUploadMiddlewareExecutor are the upload chains.

Methods

AttachmentManager.toLocalUploadAttachment(file) is a static method that turns a File, Blob or FileReference into a pending local attachment with an id and a preview URL. AttachmentManager.fileToLocalUploadAttachment() and AttachmentManager.uploadAttachment() are deprecated: use AttachmentManager.toLocalUploadAttachment() and AttachmentManager.uploadFile().

Custom uploads

Uploads to your own storage are set up with attachments.doUploadRequest and attachments.customCdn, as Message composer shows. To choose which files are taken, add a pre-upload middleware that calls discard() for the ones to leave out.

The pre-upload chain also checks each file against the app's upload settings in Stream, even with customCdn on. Storage of your own may accept files Stream wouldn't. To skip that check, remove its middleware in the composer setup function. A key has one setup function, so put this in the same one as the rest of your composer setup:

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  composer.attachmentManager.preUploadMiddlewareExecutor.remove(
    "stream-io/attachment-manager-middleware/file-upload-config-check",
  );
});

Attachment identity functions

stream-chat exports type guards for attachments. An attachment is local when its localMetadata has an id.

import { isLocalImageAttachment } from "stream-chat";

const firstImage = attachmentManager.attachments.find(isLocalImageAttachment);
console.log(firstImage?.original_width);

Link preview management

composer.linkPreviewsManager is a LinkPreviewsManager. Its state has one field, previews, a Map from URL to LinkPreview. A LinkPreview is the preview's Open Graph data with a status, a LinkPreviewStatus:

Getters

previews reads the map. loadingPreviews, loadedPreviews, failedPreviews, dismissedPreviews and pendingPreviews return the previews in each status, as arrays. config is composer.config.linkPreviews.

enabled, debounceURLEnrichmentMs, findURLFn and onLinkPreviewDismissed are getters and setters for the settings of those names, on this composer only.

Methods

The static methods LinkPreviewsManager.previewIsLoading(), LinkPreviewsManager.previewIsLoaded(), LinkPreviewsManager.previewIsFailed(), LinkPreviewsManager.previewIsDismissed() and LinkPreviewsManager.previewIsPending() check a preview's status. LinkPreviewsManager.getPreviewData(preview) returns the preview without its status, as it's sent.

Location composition

composer.locationComposer is a LocationComposer. Its state has one field, location: the location to share, or null. It holds latitude, longitude, created_by_device_id and message_id, and either durationMs for a live location being composed or end_at for one loaded from a message.

A latitude or longitude of exactly 0 counts as missing: LocationComposer.setData() ignores it, and validLocation is null.

To send a location on its own, call MessageComposer.sendLocation(). A location set in locationComposer also goes out with the next MessageComposer.send().

Poll composition

composer.pollComposer is a PollComposer. Its state holds the poll form and its errors:

The getters id, name, description, options, max_votes_allowed, enforce_unique_vote, allow_answers, allow_user_suggested_options and voting_visibility read the fields of data. stateMiddlewareExecutor and compositionMiddlewareExecutor are the poll's chains, described on Composer middleware.

To create the poll, call MessageComposer.createPoll(), then MessageComposer.send() to send the message that carries it.

Custom data management

composer.customDataManager is a CustomDataManager. Its state holds two objects:

Type both by augmenting the CustomMessageData and CustomMessageComposerData interfaces of stream-chat, as Data conventions explains.

CustomDataManager.setMessageData() writes to the top level of the message, not to message.custom. To send message.custom, add a composition middleware, as Composer middleware shows.

isMessageDataEqual is a property, so a setup function can replace it on each composer. This one compares the top-level values one by one, so the order of the keys doesn't matter, as it does for the default JSON comparison:

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  composer.customDataManager.isMessageDataEqual = (next, previous) => {
    const nextData: Record<string, unknown> = { ...next.message };
    const previousData: Record<string, unknown> = { ...previous?.message };
    const keys = new Set([
      ...Object.keys(nextData),
      ...Object.keys(previousData),
    ]);
    return [...keys].every((key) => nextData[key] === previousData[key]);
  };
});

Additional low-level exports

stream-chat exports more of the composer than the classes above. These are useful for custom uploads, suggestions and middleware:

CustomTextComposerSuggestion is an interface: augment it in stream-chat to type the fields of your own suggestion items, for example interface CustomTextComposerSuggestion { label?: string } inside declare module "stream-chat". Declare the fields optional, because every suggestion type in the app shares the interface.