---
id: reactions
sidebar_position: 4
title: Reactions
---

import GHComponentLink from '../../_docusaurus-components/GHComponentLink';

:::caution
If you're moving from older versions to `11.0.0` then make sure to read ["Introducing new reactions"](../../release-guides/upgrade-to-v11.mdx#introducing-new-reactions) release guide to help you transition to the new implementation.
:::

The Stream Chat API provides built-in support for adding reactions to messages. The component library provides three default components to enable reaction selection and display:

- [`ReactionSelector`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Reactions/ReactionSelector.tsx) - allows the connected user to select a reaction on a message
- [`ReactionsList`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Reactions/ReactionsList.tsx) - displays the reactions added to a message
- [`SimpleReactionsList`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Reactions/SimpleReactionsList.tsx) - displays a minimal list of the reactions added to a message

## Basic Usage

By default, the `ReactionSelector` and `ReactionsList` components are included within `MessageSimple`. To render reaction UI within a custom [Message UI](./message-ui.mdx) component, import both components (or `SimpleReactionsList` for a lightweight view) and render conditionally.

```jsx
const CustomMessage = () => {
  // consume `MessageContext`
  const { message, showDetailedReactions } = useMessageContext();

  return (
    <div>
      {showDetailedReactions && <ReactionSelector />}
      // render remaining custom Message UI
      {message.latest_reactions && <ReactionsList reactions={message.latest_reactions} />}
    </div>
  );
};

<Chat client={client}>
  <Channel channel={channel} Message={CustomMessage}>
    <MessageList />
    <MessageInput />
  </Channel>
</Chat>;
```

## UI Customization

Be default, the `ReactionSelector` component provides the following reaction options and corresponding emojis:

- `like`
- `love`
- `haha`
- `wow`
- `sad`
- `angry` - removed in `11.0.0`

The `defaultMinimalEmojis` data set that populates the default reaction options can be found in the <GHComponentLink as="code" text='emojiData' branch="v10.17.0" path='/Channel/emojiData.ts'/> file in the component library.

To override the default selection set, provide your own array of `MinimalEmoji` type objects and pass into the `reactionOptions` prop on the `ReactionSelector` component. You can also override the default [`handleReaction`](../contexts/message-context.mdx#handlereaction) function by adding the `handleReaction` prop.

:::caution
If custom `reactionOptions` are supplied to the `ReactionSelector` component, then the same data set needs to be delivered to the `ReactionsList` component so the display for processed reactions has the same emoji objects.
:::

```jsx
const customReactions = [
  // add array of custom `ReactionEmoji` type objects here
];

const customReactionHandler = (reactionType, event) => {
  // add custom handler logic here
};

const CustomMessage = () => {
  // consume `MessageContext`
  const { message, showDetailedReactions } = useMessageContext();

  return (
    <div>
      {showDetailedReactions && (
        <ReactionSelector
          handleReaction={customReactionHandler}
          reactionOptions={customReactions}
        />
      )}
      // render remaining custom Message UI
      {message.latest_reactions && <ReactionsList reactionOptions={customReactions} />}
    </div>
  );
};

<Chat client={client}>
  <Channel channel={channel} Message={CustomMessage}>
    <MessageList />
    <MessageInput />
  </Channel>
</Chat>;
```

To completely override the `ReactionSelector` and `ReactionsList` components in `MessageSimple`, pass your own custom components as props to the [`Channel`](../core-components/channel.mdx).

```jsx
const CustomReactionSelector = (props) => {
  // add custom reaction selector component here
};

const CustomReactionsList = (props) => {
  // add custom reactions list component here
};

<Chat client={client}>
  <Channel
    channel={channel}
    ReactionSelector={CustomReactionSelector}
    ReactionsList={CustomReactionsList}
  >
    <MessageList />
    <MessageInput />
  </Channel>
</Chat>;
```

## Sorting reactions

By default, reactions are sorted alphabetically by type. You can change this behavior by passing the `sortReactions` prop to the `MessageList` (or `VirtualizedMessageList`).

In this example, we sort the reactions in the descending order by the number of users:

```jsx
function sortByReactionCount(a, b) {
  return b.reactionCount - a.reactionCount;
}

<Chat client={client}>
  <Channel
    channel={channel}
    ReactionSelector={CustomReactionSelector}
    ReactionsList={CustomReactionsList}
  >
    <MessageList sortReactions={sortByReactionCount} />
    <MessageInput />
  </Channel>
</Chat>;
```

Similarly, the `sortReactionDetails` prop can be passed to the `MessageList` (or `VirtualizedMessageList`) to sort the list of reacted users. The default implementation used by the reactions list modal dialog sorts users alphabetically by name.

For better performance, keep the sorting functions memoized with `useCallback`, or declare it in either global or module scope.

## ReactionSelector Props

### additionalEmojiProps (removed in `11.0.0`)

Additional props to be passed to the [`NimbleEmoji`](https://github.com/missive/emoji-mart/blob/v3.0.1/src/components/emoji/nimble-emoji.js) component from `emoji-mart`.

| Type   |
| ------ |
| object |

### Avatar

Custom UI component to display a user's avatar.

| Type      | Default                                                    |
| --------- | ---------------------------------------------------------- |
| component | <GHComponentLink text='Avatar' path='/Avatar/Avatar.tsx'/> |

### detailedView

If true, shows the user's avatar with the reaction.

| Type    | Default |
| ------- | ------- |
| boolean | true    |

### handleReaction

Function that adds/removes a reaction on a message (overrides the function stored in `MessageContext`).

| Type                                                                      | Default                                                                                 |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| (reactionType: string, event: React.BaseSyntheticEvent) => Promise<void\> | [MessageContextValue['handleReaction']](../contexts/message-context.mdx#handlereaction) |

### latest_reactions

An array of the reaction objects to display in the list (overrides `message.latest_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |

### own_reactions

An array of own reaction objects to display in the list (overrides `message.own_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |

### reaction_counts

An object that keeps track of the count of each type of reaction on a message (overrides `message.reaction_counts` from `MessageContext`).

| Type                            |
| ------------------------------- |
| { [key: reactionType]: number } |

### reactionOptions

A list of the currently supported reactions on a message.

| Version | Type  | Default                                                                                                        |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| >=4.0.0 | array | <GHComponentLink text='defaultMinimalEmojis' branch="v10.17.0" path='/Channel/emojiData.ts'/>                  |
| ^11.0.0 | array | <GHComponentLink text='defaultReactionOptions' branch="feat/reactions" path='/Reactions/reactionOptions.tsx'/> |

### reverse

If true, adds a CSS class that reverses the horizontal positioning of the selector.

| Type    | Default |
| ------- | ------- |
| boolean | false   |

## ReactionsList Props

### additionalEmojiProps (removed in `11.0.0`)

Additional props to be passed to the [`NimbleEmoji`](https://github.com/missive/emoji-mart/blob/v3.0.1/src/components/emoji/nimble-emoji.js) component from `emoji-mart`.

| Type   |
| ------ |
| object |

### handleFetchReactions

Function that loads the message reactions (overrides the function stored in `MessageContext`).

| Type                 | Default                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| () => Promise<void\> | [MessageContextValue['handleFetchReactions']](../contexts/message-context.mdx#handlefetchreactions) |

The default implementation of `handleFetchReactions`, provided via the [`MessageContext`](../contexts/message-context.mdx#handlefetchreactions), limits the number of loaded reactions to 1200. Use this prop to provide your own loading implementation:

```jsx
const MyCustomReactionsList = (props) => {
  const { channel } = useChannelStateContext();
  const { message } = useMessageContext();

  function fetchReactions() {
    return channel.getReactions(message.id, { limit: 42 });
  }

  return <ReactionsList handleFetchReactions={fetchReactions} />;
};
```

### onClick

Custom on click handler for an individual reaction in the list (overrides the function stored in `MessageContext`).

| Type                                                        | Default                                                                                           |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| (event: React.BaseSyntheticEvent) => Promise<void\> \| void | [MessageContextValue['onReactionListClick']](../contexts/message-context.mdx#onreactionlistclick) |

### own_reactions

An array of the own reaction objects to distinguish own reactions visually (overrides `message.own_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |

### reaction_counts

An object that keeps track of the count of each type of reaction on a message (overrides `message.reaction_counts` from `MessageContext`).

| Type                            |
| ------------------------------- |
| { [key: reactionType]: number } |

### reactionOptions

A list of the currently supported reactions on a message.

| Version | Type  | Default                                                                                                        |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| >=4.0.0 | array | <GHComponentLink text='defaultMinimalEmojis' branch="v10.17.0" path='/Channel/emojiData.ts'/>                  |
| ^11.0.0 | array | <GHComponentLink text='defaultReactionOptions' branch="feat/reactions" path='/Reactions/reactionOptions.tsx'/> |

### reactions

An array of the reaction objects to display in the list (overrides `message.latest_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |

### reverse

If true, adds a CSS class that reverses the horizontal positioning of the selector.

| Type    | Default |
| ------- | ------- |
| boolean | false   |

### sortReactionDetails

Comparator function to sort the list of reacted users. Should have the same signature as an array's `sort` method. This prop overrides the function stored in `MessageContext`.

| Type                                                       | Default            |
| ---------------------------------------------------------- | ------------------ |
| (this: ReactionResponse, that: ReactionResponse) => number | alphabetical order |

### sortReactions

Comparator function to sort reactions. Should have the same signature as an array's `sort` method. This prop overrides the function stored in `MessageContext`.

| Type                                                     | Default            |
| -------------------------------------------------------- | ------------------ |
| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |

## SimpleReactionsList Props

### additionalEmojiProps (removed in `11.0.0`)

Additional props to be passed to the [`NimbleEmoji`](https://github.com/missive/emoji-mart/blob/v3.0.1/src/components/emoji/nimble-emoji.js) component from `emoji-mart`.

| Type   |
| ------ |
| object |

### handleFetchReactions

Function that loads the message reactions (overrides the function stored in `MessageContext`).

| Type                 | Default                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| () => Promise<void\> | [MessageContextValue['handleFetchReactions']](../contexts/message-context.mdx#handlefetchreactions) |

### handleReaction

Function that adds/removes a reaction on a message (overrides the function stored in `MessageContext`).

| Type                                                                      | Default                                                                                 |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| (reactionType: string, event: React.BaseSyntheticEvent) => Promise<void\> | [MessageContextValue['handleReaction']](../contexts/message-context.mdx#handlereaction) |

### own_reactions

An array of the own reaction objects to distinguish own reactions visually (overrides `message.own_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |

### reaction_counts

An object that keeps track of the count of each type of reaction on a message (overrides `message.reaction_counts` from `MessageContext`).

| Type                            |
| ------------------------------- |
| { [key: reactionType]: number } |

### reactionOptions

A list of the currently supported reactions on a message.

| Version | Type  | Default                                                                                                        |
| ------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| >=4.0.0 | array | <GHComponentLink text='defaultMinimalEmojis' branch="v10.17.0" path='/Channel/emojiData.ts'/>                  |
| ^11.0.0 | array | <GHComponentLink text='defaultReactionOptions' branch="feat/reactions" path='/Reactions/reactionOptions.tsx'/> |

### reactions

An array of the reaction objects to display in the list (overrides `message.latest_reactions` from `MessageContext`).

| Type  |
| ----- |
| array |
