Skip to main content
Version: v2.x

Events

NLUX emits events when the user interacts with the UI, when server sends messages, or when errors occur. You can register event callbacks to listen to these events.

Listening to Events​

You can register event callbacks to listen to events emitted by NLUX.

Adding Event Callbacks​

You can listen to an event by using the events property when defining your <AiChat /> component.

The events property is an object where the key is the event name and the value is a callback function that will be called when the event is triggered. Here is an example of how to listen to the messageSent and messageReceived events:

import {useCallback} from 'react';
import {AiChat, EventsConfig, MessageReceivedCallback, MessageSentCallback} from '@nlux/react';

// We define an event callback using the `useCallback` hook
const messageReceivedCallback = useCallback<MessageReceivedCallback>((eventDetails) => {
    console.log('Message received:', eventDetails.message);
}, [/* Your callback code dependencies */]);

const messageSentCallback = useCallback<MessageSentCallback>((eventDetails) => {
    console.log('Message sent:', eventDetails.message);
}, [/* Your callback code dependencies */]);

const eventCallbacks: EventsConfig = {
    messageReceived: messageReceivedCallback,
    messageSent: messageSentCallback
};

<AiChat adapter={adapter} events={eventCallbacks} />

You can only register one event callback for each event.

Removing Event Callbacks​

In order to remove an event callback, you can simply update the object passed to events property of <AiChat /> component. For example, if you want to remove the messageSent event listener, you can pass a new object that does not contain the messageSent key:

import {useCallback} from 'react';
import {AiChat, EventsConfig, MessageReceivedCallback} from '@nlux/react';

// We define an event callback using the `useCallback` hook
const messageReceivedCallback: MessageReceivedCallback = useCallback((event) => {
    console.log('Message received:', event.message);
}, [/* Your callback code dependencies */]);

const eventCallbacks: EventsConfig = {
    messageReceived: messageReceivedCallback,
    // We remove the messageSent event listener by not including it in the object
};

<AiChat adapter={adapter} events={eventCallbacks} />

Whenever the events property is updated, <AiChat /> component will automatically remove the previous event listeners and add the new ones.

If you want to remove all event listeners, you can simply remove the events property:

<AiChat adapter={adapter} />

Events​

Below is a list of events emitted by NLUX.

Ready​

This event is emitted when the AiChat component is mounted and ready to use.

  • Event Name: ready
  • Callback Type:
type ReadyCallback<AiMsg = string> = (readyDetails: ReadyEventDetails<AiMsg>) => void;

type ReadyEventDetails<AiMsg> = {
    // Props used to initialize the AiChat component (excluding event listeners and adapter)
    aiChatProps: AiChatPropsInEvents<AiMsg>
}
  • Usage:
import {AiChat, ReadyCallback, ReadyEventDetails} from '@nlux/react';
import {useCallback} from 'react';

const readyCallback = useCallback<ReadyCallback>((readyDetails: ReadyEventDetails) => {
    console.log('Chat is ready. Props used to initialize the chat:', readyDetails.aiChatProps);
}, [/* Callback dependencies */]);
// Provide the readyCallback callback as part of the events prop
<AiChat events={{ready: readyCallback}} adapter={adapter} />

Pre-Destroy​

This event is emitted when the AiChat component is about to be destroyed. It allows access to the component's state, conversation history, and props before it is destroyed.

  • Event Name: preDestroy
  • Callback Type:
type PreDestroyCallback<AiMsg = string> = (preDestroyDetails: PreDestroyEventDetails<AiMsg>) => void;

type PreDestroyEventDetails<AiMsg = string> = {
    aiChatProps: AiChatPropsInEvents<AiMsg>;
    conversationHistory: Readonly<ChatItem<AiMsg>[]>;
}
  • Usage:
import {AiChat, PreDestroyCallback, PreDestroyEventDetails} from '@nlux/react';
import {useCallback} from 'react';

const preDestroyCallback = useCallback<PreDestroyCallback>((preDestroyDetails: PreDestroyEventDetails) => {
    if (preDestroyDetails.conversationHistory > 0) {
        // Do something with the conversation history before it is destroyed
    }
}, [/* Callback dependencies */]);
// Provide the preDestroy callback as part of the events prop
<AiChat events={{preDestroy: preDestroyCallback}} adapter={adapter} />

Message Sent​

This event is emitted when the user sends a message. The event only gets triggered when the adapter method responsible for sending the message to the backend runs successfully. For standard adapters, this means that the message was successfully sent to the backend.

  • Event Name: messageSent
  • Callback Type:
type MessageSentCallback = (event: MessageSentEventDetails) => void;

type MessageSentEventDetails = {
    uid: string;
    message: string;
};
  • Usage:
import {AiChat, MessageSentCallback, MessageSentEventDetails} from '@nlux/react';
import {useCallback} from 'react';

const messageSentCallback = useCallback<MessageSentCallback>((event: MessageSentEventDetails) => {
    console.log('Message sent:', event.message);
}, [/* Callback dependencies */]);
// Provide the messageSentCallback callback as part of the events prop
<AiChat events={{messageSent: messageSentCallback}} adapter={adapter} />

Message Received​

This event is emitted when a message is received from the server. For the case of streamed messages, this message is emitted when the streaming is complete and the message is fully received.

Please note that messageReceived does not mean that the message has fully rendered on the screen. Depending on your configuration, NLUX may render messages in a character-by-character animation, so the message may still being rendered when this event is emitted. You can use the messageRendered event to listen to when the message has fully rendered on the screen.

  • Event Name: messageReceived
  • Callback Type:
type MessageReceivedCallback<AiMsg = string> = (event: MessageReceivedEventDetails<AiMsg>) => void;

type MessageReceivedEventDetails<AiMsg = string> = {
    uid: string;
    message: AiMsg;
};
  • Usage:
import {AiChat, MessageReceivedCallback, MessageReceivedEventDetails, } from '@nlux/react';
import {useCallback} from 'react';

const messageReceivedCallback = useCallback<MessageReceivedCallback>((eventDetails: MessageReceivedEventDetails) => {
    console.log(eventDetails.message);
}, [/* Callback dependencies */]);
// Provide the messageReceived callback as part of the events prop
<AiChat events={{messageReceived: messageReceivedCallback}} adapter={adapter} />

Message Rendered​

  • Event Name: messageRendered

This event is emitted when the message has been fully rendered, including any animations that may be applied to the message. This event is emitted after the messageReceived event, and will only be emitted once per message.

  • Callback Type:
type MessageRenderedCallback<AiMsg = string> = (event: MessageRenderedEventDetails<AiMsg>) => void;

type MessageRenderedEventDetails<AiMsg = string> = {
    uid: string;
};
  • Usage:
import {MessageRenderedCallback, MessageRenderedEventDetails, } from '@nlux/react';
import {useCallback} from 'react';

const messageRenderedCallback = useCallback<MessageRenderedCallback>((eventDetails: MessageRenderedEventDetails) => {
    // On message rendered, log the message to the console
    console.log(eventDetails.uid);
}, [/* Callback dependencies */]);
// Provide the messageRendered callback as part of the events prop
<AiChat events={{messageRendered: messageRenderedCallback}} adapter={adapter} />

Message Stream Started​

This event is emitted when the server starts sending streaming a response back to the client, for when the adapter is configured to use stream data transfer mode. The event will be emitted when the first chunk of the message is received, and will only be emitted once per message.

  • Event Name: messageStreamStarted
  • Callback Type:
type MessageStreamStartedCallback = (event: MessageStreamStartedEventDetails) => void;

type MessageStreamStartedEventDetails = {
    uid: string;
};
  • Usage:
import {AiChat, MessageStreamStartedCallback, MessageStreamStartedEventDetails, } from '@nlux/react';
import {useCallback} from 'react';

const messageStreamStartedCallback = useCallback<MessageStreamStartedCallback>((eventDetails: MessageStreamStartedEventDetails) => {
    console.log(eventDetails.message);
}, [/* Callback dependencies */]);
// Provide the streamStarted callback as part of the events prop
<AiChat events={{streamStarted: messageStreamStartedCallback}} adapter={adapter} />

Error​

This event is emitted when an exception occurs. The event listener receives the ErrorEventDetails object as a parameter.

  • Event Name: error
  • Callback Type:
type ErrorCallback = (errorDetails: ErrorEventDetails) => void;

type ErrorEventDetails = {
    errorId: string;
    message: string;
    errorObject?: Error;
};
  • Usage:
import {AiChat, ErrorCallback, ErrorEventDetails} from '@nlux/react';
import {useCallback} from 'react';

const errorCallback = useCallback<ErrorCallback>((errorDetails: ErrorEventDetails) => {
    console.log('An error occurred:', errorDetails.message);
    console.log('Error ID:', errorDetails.errorId);
}, [/* Callback dependencies */]);
// Provide the errorCallback callback as part of the events prop
<AiChat events={{error: errorCallback}} adapter={adapter} />