Actions

Every menu of actions in the SDK is built from an action set: a list of items, each naming an action and the component that renders it. Use this page to know which action sets there are, how the SDK filters them for each user, and how to add, remove or replace actions.

Each set has a default you can start from, and a base filter that removes the actions the user can't take. Each section names them.

The last three are channel details actions, exported from stream-chat-react/channel-detail. Everything else is exported from stream-chat-react.

How an action set works

An action set is a list of items. Every item has:

• a type, the action's name, which the base filter uses to recognize it. The menu button item, described in Placements, has none;
• a component that renders the action;
• in the message, channel list item and channel members header sets, a placement that decides where the action renders.

Placements

What happens when a menu renders

The same three steps apply to every set:

1. The base filter drops the actions the user can't take. It reads the user's capabilities, the channel's settings, and what the action applies to: the message, the channel or the member. A type the filter doesn't know passes it, so your own actions always show, and checking whether the user may use them is up to your component.
2. The placement, in the sets that have one, decides where an action goes, as in Placements.
3. The list's order is the order in the menu.

When the filter leaves no action, the message actions, the attachment selector, the channel list item actions and the channel members header actions render nothing.

Message actions

The menu of someone else's message. Edit and Delete show on the user's own messages, and Remind me and Save for later when reminders are on.

<MessageActions/> renders one message's actions from a message action set. By default, that's defaultMessageActionSet.

The message action set

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

For each message, <MessageActions/> drops the items the base filter or their own isVisible rules out, then renders the rest by placement, in the set's order.

The default set starts like this:

[
  { Component: QuickDropdownToggle, placement: "quick-dropdown-toggle" },
  { Component: QuickReply, placement: "quick", type: "reply" },
  { Component: QuickReact, placement: "quick", type: "react" },
  { Component: AddReaction, placement: "dropdown", type: "react" },
  { Component: ThreadReply, placement: "dropdown", type: "reply" },
  // quote, download, pin, copy, resend, edit, mark unread, remind me,
  // save for later, flag, mute, delete, block user
];

An item's placement decides where it renders, and what its component must do:

Next to the message, the menu button always comes first, then the quick items in list order. The SDK's stylesheet lays them out from right to left.

To use your own set, register a component under the MessageActions key that renders <MessageActions messageActionSet={yourSet} />. Here is a ChannelWithCustomMessageActions component, a channel whose messages have no "Block user" action and a "Copy link" one:

import {
  Channel,
  ContextMenuButton,
  defaultMessageActionSet,
  MessageActions,
  MessageComposer,
  MessageList,
  useComponentContextIcons,
  useContextMenuContext,
  useMessageContext,
  WithComponents,
} from "stream-chat-react";
import type { MessageActionSetItem } from "stream-chat-react";
import type { Channel as StreamChannel } from "stream-chat";

const CopyLinkAction = () => {
  const { IconLink } = useComponentContextIcons();
  const { closeMenu } = useContextMenuContext();
  const { message } = useMessageContext();

  return (
    <ContextMenuButton
      Icon={IconLink}
      onClick={() => {
        void navigator.clipboard.writeText(
          `${window.location.origin}/messages/${message.id}`,
        );
        closeMenu();
      }}
    >
      Copy link
    </ContextMenuButton>
  );
};

// Declared once: the base filter recomputes whenever it gets a new list.
const messageActionSet: MessageActionSetItem[] = [
  ...defaultMessageActionSet.filter(
    (item) =>
      item.placement === "quick-dropdown-toggle" || item.type !== "blockUser",
  ),
  { Component: CopyLinkAction, placement: "dropdown", type: "copyLink" },
];

const CustomMessageActions = () => (
  <MessageActions messageActionSet={messageActionSet} />
);

const messageOverrides = { MessageActions: CustomMessageActions };

// The messages in this channel get the custom actions.
export const ChannelWithCustomMessageActions = ({
  channel,
}: {
  channel: StreamChannel;
}) => (
  <WithComponents overrides={messageOverrides}>
    <Channel channel={channel}>
      <MessageList />
      <MessageComposer />
    </Channel>
  </WithComponents>
);

The base filter gives some messages no actions, or only a few, such as a message still sending or one that failed to send; Message actions lists them. On a reply in a thread it drops pin, reply and markUnread. On any other message it keeps each action that passes the base filter's check in Checks per action, and never resendMessage.

Checks per action

Rules on the items

An item can carry its own rule as isVisible(params). It gets MessageActionVisibilityFilterParams: isMyMessage, isThreadReply and the message. The action shows only while isVisible returns true.

An item's rule can only hide an action: one the base filter drops stays hidden. The rule also applies to a message that failed to send, and with disableBaseMessageActionSetFilter.

An item without isVisible shows wherever the base filter allows it. So a set that writes its own edit, copyMessageText or download item by hand loses the default rule: without it, edit shows on a poll message the user may update. Spread the default item, or copy its isVisible. To change a rule, replace the item's isVisible:

import { defaultMessageActionSet } from "stream-chat-react";
import type { MessageActionSetItem } from "stream-chat-react";

// Lets users edit the text and attachments sent with a poll; a giphy still can't be edited.
const messageActionSet: MessageActionSetItem[] = defaultMessageActionSet.map(
  (item) =>
    item.placement !== "quick-dropdown-toggle" && item.type === "edit"
      ? { ...item, isVisible: ({ message }) => message.command !== "giphy" }
      : item,
);

<MessageActions/> takes disableBaseMessageActionSetFilter to skip the base filter's checks. Pass it only when your components check the base filter's conditions in Checks per action themselves. To build your own actions component, run useBaseMessageActionSetFilter(set) on your list, as <MessageActions/> does.

What each default action does, and the actions that come with flagging, muting and reminders, are on Message actions.

Channel list item actions

<ChannelListItemActionButtons/> renders each channel list item's actions. To customize them, replace it with your own component, as in Replacing the actions. It renders defaultChannelActionSet, filtered by useBaseChannelActionSetFilter.

The default set, in this order:

The placements work as in Message actions: quick on the channel list item, dropdown in the menu.

Replacing the actions

The set has no prop, and neither it nor its filter is exported, so your component starts from scratch:

1. Write a component that renders the actions you want. It renders inside the channel list item, so useChannelListItemContext() gives it the item's channel.
2. Register it under the ChannelListItemActionButtons key with <WithComponents/>, around the channel list.

Here is a ChannelListWithMarkAsRead component, a channel list whose items show a "Mark as read" button, MarkAsReadAction, instead of their actions:

import type { ChannelPaginator, OwnCapabilitiesState } from "stream-chat";
import {
  Button,
  ChannelList,
  useChannelListItemContext,
  useComponentContextIcons,
  useStateStore,
  WithComponents,
} from "stream-chat-react";

const capabilitiesSelector = ({ ownCapabilities }: OwnCapabilitiesState) => ({
  ownCapabilities,
});

const MarkAsReadAction = () => {
  const { channel } = useChannelListItemContext();
  const { IconChecks } = useComponentContextIcons();
  const { ownCapabilities } = useStateStore(
    channel.state,
    capabilitiesSelector,
  );

  if (!ownCapabilities.includes("read-events")) return null;

  return (
    <div className="str-chat__channel-list-item__action-buttons">
      <Button
        appearance="ghost"
        aria-label="Mark as read"
        circular
        onClick={() => void channel.markRead()}
        size="sm"
        variant="secondary"
      >
        <IconChecks />
      </Button>
    </div>
  );
};

const channelListItemOverrides = {
  ChannelListItemActionButtons: MarkAsReadAction,
};

// Every item of this channel list gets the "Mark as read" button instead of its actions.
export const ChannelListWithMarkAsRead = ({
  paginator,
}: {
  paginator: ChannelPaginator;
}) => (
  <WithComponents overrides={channelListItemOverrides}>
    <ChannelList paginator={paginator} />
  </WithComponents>
);

Your component replaces the default buttons, menu included, and does its own capability checks, here through channel.state. The actions themselves are on Channel lists.

Attachment selector actions

The menu in a channel with polls disabled. Attachment Selector lists when Poll and the other actions show.

<AttachmentSelector/>, the button beside the composer's input, renders a menu of defaultAttachmentSelectorActionSet, filtered by a filter built into it. The filter isn't exported, and it always runs. An item of this set has a type and an ActionButton, its entry in the menu, but no placement.

To change the set, see Custom action sets, which lists the fields of an item. To give an action of your own a button that replaces the menu, see Standalone buttons.

Channel details actions

Channel details come from stream-chat-react/channel-detail. An app usually opens them from the channel header, by passing AvatarWithChannelDetail as its Avatar. They have three action sets, each rendered by one view. Using your own sets changes two of them in one example.

Channel management

The actions of a group channel.

<ChannelManagementView/>, the Channel info section, renders them at its bottom: defaultChannelManagementActionSet, filtered by useBaseChannelManagementActionSetFilter. The filter always runs.

The channel management action set

An item has no placement, and these fields:

The view renders the items the base filter keeps, in the set's order.

The default set, in this order:

Channel member

<ChannelMemberDetail/>, a member's detail view opened from the Members section, renders the member's actions: defaultChannelMemberActionSet, filtered by useBaseChannelMemberActionSetFilter. The filter always runs.

The channel member action set

An item has these fields:

The view renders the items the base filter keeps, in the set's order.

The default set, in this order:

<ChannelMembersView/> opens this view from the members list without passing a set, so the Members section always shows the default member actions. Only a <ChannelMemberDetail/> you render yourself uses your set.

Channel members header

<ChannelMembersView/>, the Members section, renders these actions in its header, in browse mode: defaultChannelMembersHeaderActionSet, filtered by useBaseChannelMembersHeaderActionSetFilter.

The channel members header action set

An item has the same fields as a message action item:

The default header actions drop the items that the base filter or their own isVisible rules out, then render the rest by placement, in the set's order.

The default set:

Placements says where each placement renders. Two of them ask more of your component here:

• A dropdown component closes the menu when its action is done: it calls closeMenu() from useContextMenuContext().
• The quick-dropdown-toggle component is a forwardRef button. It gets a ref, aria-expanded and onClick, and spreads them onto its button. One that ignores them never opens the menu.

The default set already holds a menu button. Keep it when you build your set from the default one, and add one when you write a set from scratch, or the dropdown items can't be opened.

The filter runs in the default header actions only. <ChannelMembersView/> takes a HeaderActions component that replaces them, and it receives your headerActionSet unfiltered. To match the default, run useBaseChannelMembersHeaderActionSetFilter(set) in your component and render the dropdown items in a <ContextMenu/> anchored to the menu button, since useContextMenuContext() throws outside one. DefaultHeaderActions in ChannelMembersHeaderActions.defaults.tsx of the SDK shows the wiring.

Using your own sets

Each view takes its set as a prop, and you reach the view through the sections of <ChannelDetail/>. Using your own sets takes six steps:

1. Write the components of your own actions.
2. Build your sets from the defaults.
3. Give each set to its view, and use that view as its section's content.
4. Give the sections to <ChannelDetail/>.
5. Open that <ChannelDetail/> from the channel header's avatar.
6. Render that header in a channel.

Here is a ChannelWithCustomDetails component that follows them. It removes "Delete chat", adds "Export chat" to the channel management actions, and adds "Copy invite link" to the members header. The comments mark the steps:

import {
  Channel,
  ChannelHeader,
  ContextMenuButton,
  ListItemLayout,
  MessageComposer,
  MessageList,
  useContextMenuContext,
} from "stream-chat-react";
import type { Channel as StreamChannel } from "stream-chat";
import {
  AvatarWithChannelDetail,
  ChannelDetail,
  ChannelManagementView,
  ChannelMembersView,
  defaultChannelDetailSections,
  defaultChannelManagementActionSet,
  defaultChannelMembersHeaderActionSet,
  useChannelDetailContext,
} from "stream-chat-react/channel-detail";
import type {
  AvatarWithChannelDetailProps,
  ChannelDetailProps,
  ChannelManagementActionItem,
  ChannelMembersHeaderActionItem,
  SectionNavigatorSection,
  SectionNavigatorSectionContentProps,
} from "stream-chat-react/channel-detail";

// 1. Write the components of your own actions.
const ExportChatAction = () => {
  const { channel } = useChannelDetailContext();

  return (
    <ListItemLayout
      RootElement="button"
      rootProps={{
        onClick: () => window.open(`/exports/${channel.id}`),
        type: "button",
      }}
      title="Export chat"
    />
  );
};

const CopyInviteLinkAction = () => {
  const { channel } = useChannelDetailContext();
  const { closeMenu } = useContextMenuContext();

  return (
    <ContextMenuButton
      onClick={() => {
        void navigator.clipboard.writeText(
          `${window.location.origin}/join/${channel.id}`,
        );
        closeMenu();
      }}
    >
      Copy invite link
    </ContextMenuButton>
  );
};

// 2. Build your sets from the defaults.
const channelManagementActionSet: ChannelManagementActionItem[] = [
  ...defaultChannelManagementActionSet.filter(
    ({ type }) => type !== "deleteChat",
  ),
  { Component: ExportChatAction, type: "exportChat" },
];

const headerActionSet: ChannelMembersHeaderActionItem[] = [
  ...defaultChannelMembersHeaderActionSet,
  {
    Component: CopyInviteLinkAction,
    // An app's own action carries its own permission check.
    isVisible: ({ channel }) =>
      channel.data?.own_capabilities?.includes("update-channel-members") ??
      false,
    placement: "dropdown",
    type: "copyInviteLink",
  },
];

// 3. Give each set to its view, and use that view as its section's content.
const ManagementSection = (props: SectionNavigatorSectionContentProps) => (
  <ChannelManagementView
    {...props}
    channelManagementActionSet={channelManagementActionSet}
  />
);

const MembersSection = (props: SectionNavigatorSectionContentProps) => (
  <ChannelMembersView {...props} headerActionSet={headerActionSet} />
);

// 4. Give the sections to ChannelDetail.
const sections: SectionNavigatorSection[] = defaultChannelDetailSections.map(
  (section) => {
    if (section.id === "channel-info")
      return { ...section, SectionContent: ManagementSection };
    if (section.id === "channel-members")
      return { ...section, SectionContent: MembersSection };
    return section;
  },
);

const CustomChannelDetail = (props: ChannelDetailProps) => (
  <ChannelDetail {...props} sections={sections} />
);

// 5. Open that ChannelDetail from the channel header's avatar.
const HeaderAvatar = (props: AvatarWithChannelDetailProps) => (
  <AvatarWithChannelDetail {...props} ChannelDetail={CustomChannelDetail} />
);

const CustomChannelHeader = () => <ChannelHeader Avatar={HeaderAvatar} />;

// 6. Render the custom header in a channel.
export const ChannelWithCustomDetails = ({
  channel,
}: {
  channel: StreamChannel;
}) => (
  <Channel channel={channel}>
    <CustomChannelHeader />
    <MessageList />
    <MessageComposer />
  </Channel>
);

The views and their other props are on Channel Detail Views, and the feature on Channel details and members.

Adding, removing and replacing actions

Start from the default set and change it, rather than writing a list from scratch:

Here is a PinWithConfirmation component that replaces the pin action, and a message action set that also adds CopyLinkAction from Message actions before "flag":

// Asks before pinning or unpinning.
const PinWithConfirmation = () => {
  const { closeMenu } = useContextMenuContext();
  const { handlePin, message } = useMessageContext();

  return (
    <ContextMenuButton
      onClick={(event) => {
        if (
          window.confirm(
            message.pinned ? "Unpin this message?" : "Pin this message?",
          )
        ) {
          void handlePin(event);
        }
        closeMenu();
      }}
    >
      {message.pinned ? "Unpin" : "Pin"}
    </ContextMenuButton>
  );
};

// Replace the pin action's component, and add CopyLinkAction (from the Message actions example) before "flag".
const messageActionSet: MessageActionSetItem[] =
  defaultMessageActionSet.flatMap((item): MessageActionSetItem[] => {
    if (item.placement === "dropdown" && item.type === "pin") {
      return [{ ...item, Component: PinWithConfirmation }];
    }
    if (item.placement === "dropdown" && item.type === "flag") {
      return [
        { Component: CopyLinkAction, placement: "dropdown", type: "copyLink" },
        item,
      ];
    }
    return [item];
  });

A replaced action keeps its type, so the base filter still treats it as that action: PinWithConfirmation still shows only to users with the pin-message capability, and not on thread replies. An added action has a type the filter doesn't know: it always passes, so its component checks whether the user may use it and returns null when not. Keep the base filter on, so the default actions keep following the user's capabilities.

The Custom message actions and Product card recipes walk through complete examples.

Used in

• Message actions
• Flagging, muting, blocking and bans
• Channel lists
• Channel details and members