devextreme/ui/chat.d.ts

HTML5 JavaScript Component Suite for Responsive Web Development

/**
* DevExtreme (ui/chat.d.ts)
* Version: 25.1.3
* Build date: Wed Jun 25 2025
*
* Copyright (c) 2012 - 2025 Developer Express Inc. ALL RIGHTS RESERVED
* Read about DevExtreme licensing here: https://js.devexpress.com/Licensing/
*/
import {
    Format,
} from '../common/core/localization';

import {
    UserDefinedElement,
    DxElement,
} from '../core/element';

import {
    template,
} from '../common';

import Widget, { WidgetOptions } from './widget/ui.widget';
import {
    EventInfo,
    NativeEventInfo,
    InitializedEventInfo,
    ChangedOptionInfo,
    AsyncCancelable,
} from '../common/core/events';
import DataSource, { DataSourceLike } from '../data/data_source';

/**
 * The type of the disposing event handler's argument.
 */
export type DisposingEvent = EventInfo<dxChat>;

/**
 * The type of the initialized event handler&apos;s argument.
 */
export type InitializedEvent = InitializedEventInfo<dxChat>;

/**
 * The argument type in the optionChanged event.
 */
export type OptionChangedEvent = EventInfo<dxChat> & ChangedOptionInfo;

/**
 * The argument type in the messageEntered event.
 */
export type MessageEnteredEvent = NativeEventInfo<dxChat, KeyboardEvent | PointerEvent | MouseEvent | TouchEvent> & {
    /**
     * The message that was entered into the chat.
     */
    readonly message: Message;
};

/**
 * The argument type in the typingStart.
 */
export type TypingStartEvent = NativeEventInfo<dxChat, UIEvent & { target: HTMLInputElement }> & {
    /**
     * The user who started typing.
     */
    readonly user?: User;
};

/**
 * The argument type in the typingEnd event.
 */
export type TypingEndEvent = EventInfo<dxChat> & {
    /**
     * The user who stopped typing.
     */
    readonly user: User;
};

/**
 * The argument type in the messageDeleting event.
 */
export type MessageDeletingEvent = AsyncCancelable & EventInfo<dxChat> & {
  /**
   * The message that is being deleted.
   */
  readonly message: Message;
};

/**
 * The argument type in the messageDeleted event.
 */
export type MessageDeletedEvent = EventInfo<dxChat> & {
  /**
   * The message that was deleted.
   */
  readonly message: Message;
};

/**
 * The argument type in the messageEditingStart event.
 */
export type MessageEditingStartEvent = AsyncCancelable & EventInfo<dxChat> & {
  /**
   * The message which editing started.
   */
  readonly message: Message;
};

/**
 * The argument type in the messageEditCanceled event.
 */
export type MessageEditCanceledEvent = EventInfo<dxChat> & {
  /**
   * The message which editing was canceled.
   */
  readonly message: Message;
};

/**
 * The argument type in the messageUpdating event.
 */
export type MessageUpdatingEvent = AsyncCancelable & EventInfo<dxChat> & {
  /**
   * The message to be updated.
   */
  readonly message: Message;
  /**
   * The updated text from the input field.
   */
  readonly text: string;
};

/**
 * The argument type in the messageUpdated event.
 */
export type MessageUpdatedEvent = EventInfo<dxChat> & {
  /**
   * The message that was updated.
   */
  readonly message: Message;
  /**
   * The updated text from the input field.
   */
  readonly text: string;
};

/**
 * A configuration object for a user.
 */
export type User = {
    /**
     * User&apos;s identification number or string.
     */
    id?: number | string;
    /**
     * A user&apos;s name displayed in the chat.
     */
    name?: string;
    /**
     * An avatar URL.
     */
    avatarUrl?: string;
    /**
     * `alt` attribute for avatar image.
     */
    avatarAlt?: string;
};

/**
 * A configuration object for an alert.
 */
export type Alert = {
    /**
     * Alert&apos;s identification number or string.
     */
    id?: number | string;
    /**
     * The alert&apos;s message.
     */
    message?: string;
};

/**
 * A configuration object for a message.
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type MessageBase = {
    /**
     * Message&apos;s identification number or string.
     */
    id?: number | string;
    /**
     * The message type.
     */
    type?: 'text' | 'image' | undefined;
    /**
     * A timestamp of when the message was sent.
     */
    timestamp?: Date | number | string;
    /**
     * A user who is the author of the message.
     */
    author?: User;
    /**
     * Marks a message as deleted in the UI.
     */
    isDeleted?: boolean;

    [key: string]: any;
};

/**
 * Configures a text message.
 */
export type TextMessage = MessageBase & {
    /**
     * The message text. Only applies to `text` type messages.
     */
    text?: string;
    /**
     * Marks a message as edited in the UI.
     */
    isEdited?: boolean;
};

/**
 * Configures image message.
 */
export type ImageMessage = MessageBase & {
    /**
     * Specifies the image source. Accepts URLs and Base64 strings. Only applies to `image` type messages.
     */
    src?: string;
    /**
     * Image alternative text. Specifies the value of the image `alt` attributes. Screen readers utilize this property when image messages are focused. Only applies to `image` type messages.
     */
    alt?: string;
};

/**
 * A configuration object for a message.
 */
export type Message = TextMessage | ImageMessage;

export type MessageTemplateData = {
    readonly component: dxChat;
    readonly message?: Message;
};

/**
 * 
 * @deprecated 
 */
export interface dxChatOptions extends WidgetOptions<dxChat> {
    /**
     * Specifies whether the UI component changes its visual state as a result of user interaction.
     */
    activeStateEnabled?: boolean;
    /**
     * Specifies whether the Chat&apos;s input element can be focused using keyboard navigation.
     */
    focusStateEnabled?: boolean;
    /**
     * Specifies whether the UI component changes its state when a user pauses on it.
     */
    hoverStateEnabled?: boolean;
    /**
     * Specifies the current chat user (messages displayed on the right side).
     */
    user?: User;
    /**
     * Specifies an array of chat messages.
     */
    items?: Array<Message>;
    /**
     * Configures editing.
     */
    editing?: {
      /**
       * Specifies whether a user can update messages. Called for each message when defined as a function.
       */
      allowUpdating?: boolean | ((options: { component?: dxChat; message?: Message }) => boolean);
      /**
       * Specifies whether a user can delete messages. Called for each message when defined as a function.
       */
      allowDeleting?: boolean | ((options: { component?: dxChat; message?: Message }) => boolean);
    };
    /**
     * Binds the UI component to data.
     */
    dataSource?: DataSourceLike<Message> | null;
    /**
     * Specifies the day header format.
     */
    dayHeaderFormat?: Format;
    /**
     * Specifies whether the Chat UI component displays newly entered messages immediately. This property only applies if dataSource is used.
     */
    reloadOnChange?: boolean;
    /**
     * A list of available alerts.
     */
    alerts?: Array<Alert>;
    /**
     * Specifies a custom template for a chat message.
     */
    messageTemplate?: template | null | ((data: MessageTemplateData, messageBubbleElement: DxElement) => string | UserDefinedElement);
    /**
     * Specifies the message timestamp format.
     */
    messageTimestampFormat?: Format;
    /**
     * An array of users who are currently typing.
     */
    typingUsers?: Array<User>;
    /**
     * Specifies whether to show day headers.
     */
    showDayHeaders?: boolean;
    /**
     * Specifies whether to show user names.
     */
    showUserName?: boolean;
    /**
     * Specifies whether to show avatars.
     */
    showAvatar?: boolean;
    /**
     * Specifies whether to show message time stamps.
     */
    showMessageTimestamp?: boolean;
    /**
     * A function that is executed after a message is entered into the chat.
     */
    onMessageEntered?: ((e: MessageEnteredEvent) => void) | undefined;
    /**
     * A function that is called after a user starts typing.
     */
    onTypingStart?: ((e: TypingEndEvent) => void) | undefined ;
    /**
     * A function that is called 2 seconds after a user stops typing or after a message is entered.
     */
    onTypingEnd?: ((e: TypingEndEvent) => void) | undefined;
    /**
     * A function that is executed before a message is removed from the UI.
     */
    onMessageDeleting?: ((e: MessageDeletingEvent) => void) | undefined;
    /**
     * A function that is executed after a message was removed from the UI.
     */
    onMessageDeleted?: ((e: MessageDeletedEvent) => void) | undefined;
    /**
     * A function that is executed before a message switches to the editing state.
     */
    onMessageEditingStart?: ((e: MessageEditingStartEvent) => void) | undefined;
    /**
     * A function that is executed after message changes are discarded.
     */
    onMessageEditCanceled?: ((e: MessageEditCanceledEvent) => void) | undefined;
    /**
     * A function that is executed before a message is edited in the UI.
     */
    onMessageUpdating?: ((e: MessageUpdatingEvent) => void) | undefined;
    /**
     * A function that is executed after a message was edited in the UI.
     */
    onMessageUpdated?: ((e: MessageUpdatedEvent) => void) | undefined;
}

/**
 * The Chat UI component is an interactive interface that allows users to send and receive messages in real time.
 */
export default class dxChat extends Widget<Properties> {
    /**
     * Renders a new message.
     */
    renderMessage(message: Message): void;

    getDataSource(): DataSource<Message>;
}

export type ExplicitTypes = {
    Properties: Properties;
    DisposingEvent: DisposingEvent;
    InitializedEvent: InitializedEvent;
    OptionChangedEvent: OptionChangedEvent;
};

export type Properties = dxChatOptions;