useRoomReactions

Open in

The useRoomReactions hook enables sending and subscribing to ephemeral room-level reactions. Room reactions are commonly used for live interactions like floating emojis, applause, or other realtime audience feedback. Unlike message reactions, room reactions are not persisted.

React

import { useRoomReactions } from '@ably/chat/react';

const MyComponent = () => {
  const { sendRoomReaction } = useRoomReactions({
    listener: (event) => {
      console.log(`${event.reaction.clientId} reacted with ${event.reaction.name}`);
    },
  });

  return <button onClick={() => sendRoomReaction({ name: '👍' })}>React</button>;
};

This hook must be used within a ChatRoomProvider.

Parameters

The useRoomReactions hook accepts an optional configuration object:

listeneroptionalRoomReactionListener

A callback invoked whenever a room reaction is received. Removed when the component unmounts.

onDiscontinuityoptionalDiscontinuityListener

A callback to detect and respond to discontinuities.

onRoomStatusChangeoptionalRoomStatusChange

A callback invoked when the room status changes. Removed when the component unmounts.

onConnectionStatusChangeoptionalConnectionStatusChange

A callback invoked when the connection status changes. Removed when the component unmounts.

Returns

The useRoomReactions hook returns an object with the following properties:

sendRoomReactionsendRoomReaction()

Sends a room-level reaction.

roomStatusRoomStatus

The current status of the room, kept up to date by the hook.

roomErrorErrorInfo or Undefined

An error object if the room is in an errored state.

connectionStatusConnectionStatus

The current connection status, kept up to date by the hook.

connectionErrorErrorInfo or Undefined

An error object if there is a connection error.

Send a room reaction

sendRoomReaction(params: SendReactionParams): Promise<void>

Sends a room-level reaction. Room reactions are ephemeral events that are not associated with specific messages.

Parameters

paramsrequiredSendReactionParams

The reaction parameters.

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the reaction has been sent, or rejected with an ErrorInfo object.

Example

React

import { useRoomReactions } from '@ably/chat/react';
import { useState, useCallback } from 'react';

function ReactionBar() {
  const [recentReactions, setRecentReactions] = useState([]);

  const { sendRoomReaction } = useRoomReactions({
    listener: (event) => {
      const { reaction } = event;
      setRecentReactions((prev) => [
        ...prev.slice(-9),
        { name: reaction.name, clientId: reaction.clientId, isSelf: reaction.isSelf },
      ]);
    },
  });

  const emojis = ['👍', '❤️', '😂', '🎉', '👏'];

  return (
    <div>
      <div>
        {emojis.map((emoji) => (
          <button key={emoji} onClick={() => sendRoomReaction({ name: emoji })}>
            {emoji}
          </button>
        ))}
      </div>
      <div>
        {recentReactions.map((r, i) => (
          <span key={i}>{r.name}</span>
        ))}
      </div>
    </div>
  );
}