Cord LogoDocs
Sign inStart now

Composer

Components /
Ask the Community

Create new conversations or reply to existing ones

When to use #

The Composer component renders a message composer to create new threads and to reply to existing ones.

This component pairs well with:

How to use #

React:
import { Composer } from "@cord-sdk/react";
  
  export const Example = () => {
    return (
      <Composer
        threadId={"<any string that is unique across your entire application>"}
        groupId="my-group"
        location={{ page: "index" }}
        onFocus={({ threadId }) =>
          console.log('Focussed <Composer /> threadId =', threadId)
        }
        onBlur={({ threadId }) =>
          console.log('Blurred <Composer /> threadId =', threadId)
        }
        onClose={({ threadId }) =>
          console.log('Closed <Composer /> threadId =', threadId)
        }
        onSend={({ threadId, messageId }) =>
        console.log('Sent a message from <Composer /> threadId =', threadId, 'messageId=', messageId)
      }
        style={{
          width: "300px" // Recommended so that the composer doesn't stretch horizontally based on its content
        }}
      />
    );
  };
Vanilla JavaScript:
<cord-composer
    thread-id="<id of thread>"
    group-id="my-group"
    location='{ page: "index" }'
    // Setting a width is recommended so that the composer doesn't stretch horizontally based on its content
    style="width: 300px;"
  ></cord-composer>
  
  <script>
    document
      .getElementById("composer")
      .addEventListener("cord-composer:close", (event) => {
        console.log("composer close button clicked, threadId=", event.detail[0].threadId);
      });
  </script>
  
import { Composer } from "@cord-sdk/react";
  
  export const Example = () => {
    return (
      <Composer
        threadId={"<any string that is unique across your entire application>"}
        groupId="my-group"
        location={{ page: "index" }}
        onFocus={({ threadId }) =>
          console.log('Focussed <Composer /> threadId =', threadId)
        }
        onBlur={({ threadId }) =>
          console.log('Blurred <Composer /> threadId =', threadId)
        }
        onClose={({ threadId }) =>
          console.log('Closed <Composer /> threadId =', threadId)
        }
        onSend={({ threadId, messageId }) =>
        console.log('Sent a message from <Composer /> threadId =', threadId, 'messageId=', messageId)
      }
        style={{
          width: "300px" // Recommended so that the composer doesn't stretch horizontally based on its content
        }}
      />
    );
  };
Copy

Want to customize the features in the composer?

The buttons shown at the bottom of the composer may vary depending on which Cord features are enabled. Check out initialization to learn more about configuring these features at load time. →

Properties #

threadId #

optional
string
An arbitrary string that uniquely identifies a thread. Messages sent will go to the provided thread ID. If the thread ID doesn't exist yet, it will be created. If no ID is passed, each message sent will create a new thread.

Warning! An important restriction of working with thread identifiers is that they must be unique across your entire application. You can't use the same thread identifier in two separate groups. This is an intentional limitation imposed by Cord.

groupId #

optional
string
The group ID which this thread should belong to. This controls which users will be able to see the thread.
Required when creating a new thread. If loading a composer for an existing thread ID, specifying a group ID which does not match the group the thread belongs to will result in an error.

location #

optional
string
The location value set for the newly created threads.
If unset, this will default to the location provided to the useCordLocation hook if that was used. Otherwise, will default to the current URL for the page.

threadName #

optional
string
Sets the name of the thread. The thread name is used in a small number of places where a short name or header is useful to distinguish the thread; the default value is nearly always fine. A newly-created thread will have its title set to this value, and an existing thread will have its title updated to this value.
The default setting is the current page's title.

autofocus #

optional
boolean
If true, the composer input field will render with the autofocus HTML attribute set.
The default value is false.

showExpanded #

optional
boolean
If true, the composer will always appear expanded. This means that it will always show the button list (such as the mention button and emoji button) right below the editor.
If false, the composer will start from a single-line state, but will expand when a user clicks in the editor or starts typing. It will return to a single-line state when it loses focus and there is no input in the editor.
The default value is false.

showCloseButton #

optional
boolean
If true the composer will show a close button next to the send button that will trigger the onClose callback when clicked.
The default value is false.

disabled #

optional
boolean
If true the composer will render in a disabled state, preventing writing or sending a message. This can be used, for example, to visually suggest the user can not or should not send a message to a thread. However, it is not a permission control, since it does not prevent the user from sending to the thread directly (such as via the JS API). Only Cord's groups should be used for permissions.
The default value is false.

size #

optional
"small" | "medium" | "large"
This customizes the size of the composer. You can set it to one of the three following values:
  1. small: The composer will start in a single-line state and expand to show the button list without a separator when a user clicks in the editor or starts typing. It will return to a single-line state when it loses focus and there is no input in the editor.
  2. medium: The composer will start in a single-line state and expand to show the button list with a separator when a user clicks in the editor or starts typing. It will return to a single-line state when it loses focus and there is no input in the editor.
  3. large: The composer will start with a size similar to the expanded state but without the button list and expand minimally to show the button list when a user clicks in the editor or starts typing. It will return to the state without the button list when it loses focus and there is no input in the editor.
    The default setting is medium.

threadUrl #

optional
string
The URL of a thread is used to direct users to the correct place when clicking on a notification. The threadUrl defaults to window.location.href. Setting this property would override that default.
Note: The URL specified only applies to new threads and will not change the url of existing threads.
The default value is fine for almost all use cases.

messageMetadata #

optional
object
A JSON object that can be used to store metadata about a message on creation. Keys are strings, and values can be strings, numbers or booleans.

threadMetadata #

optional
object
A JSON object that can be used to store extra data about a thread. Keys are strings, and values can be strings, numbers or booleans. This only affects newly-created threads and does not change the metadata on existing threads.
This property will only have an effect if the specific composer component is used to create a new thread.

onFocus #

optional
function
Callback invoked when a user focuses the composer. The callback is passed an object of type { threadId: string; thread: ThreadSummary | null } containing the ID and summary of the thread linked to the composer.

onBlur #

optional
function
Callback invoked when the composer loses focus. The callback is passed an object of type { threadId: string; thread: ThreadSummary | null } containing the ID and summary of the thread linked to the composer.

onClose #

optional
function
Callback invoked when a user clicks on the close button in the composer. The callback is passed an object of type { threadId: string; thread: ThreadSummary | null } containing the ID and summary of the thread linked to the composer.

onSend #

optional
function
Callback invoked when a user sends a message from the composer. The callback is passed an object containing the messageId of the sent message, threadId and thread which is the summary of the thread linked to the composer.

onThreadReopen #

optional
function
If a threadId is specified in the composer component, it is possible that this thread is resolved. In which case, the composer will not be available to use and will contain a button labeled: "Reopen to reply". This callback will be invoked when a user clicks on this button.
The callback is passed an object of type { threadId: string; thread: ThreadSummary | null } containing the ID and summary of the thread linked to the composer.

CSS customization #

If you want to customize this component, you can target the classes below in your app's CSS. These are guaranteed to be stable.

There are more classes that are best understood in context. We suggest inspecting the component with your browser's developer tools to view everything. You can target any classes starting with cord-.

Class nameDescription
.cord-composer
Applied to the container div. This class is always present.
.cord-expanded
Applied to the container div when the composer is expanded, usually on focus, or when some text is already there.
.cord-editor-container
Applied to the div containing the editor.
.cord-composer-menu
Applied to the div containing the primary and secondary buttons.
.cord-placeholder
Applied to the typing placeholder.
.cord-attachments
Applied to the div containing the attachments (files and images).
.cord-composer-error-message
Applied to the div containing the error message that appears when a message fails to send

Not finding the answer you need? Ask our Developer Community

Ask Cordy