From 40ca8c860609ebf9dcf1606bf4bac5c06bb45789 Mon Sep 17 00:00:00 2001 From: Stamen Stoychev Date: Thu, 16 Jul 2026 18:56:27 +0300 Subject: [PATCH] fix(chat): elaborate the bidirectionality of the messages array --- .../src/content/en/components/chat.mdx | 16 ++++- .../en/components/interactivity/chat.mdx | 58 ++++++++++++++++--- 2 files changed, 65 insertions(+), 9 deletions(-) diff --git a/docs/angular/src/content/en/components/chat.mdx b/docs/angular/src/content/en/components/chat.mdx index a1dd4e0ddd..5c86855aa5 100644 --- a/docs/angular/src/content/en/components/chat.mdx +++ b/docs/angular/src/content/en/components/chat.mdx @@ -85,13 +85,27 @@ The Chat component exposes several key properties that let you control its state | Name | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messages` | Array of messages (`IgcChatMessage[]`) displayed in the chat. You can bind to this to control which messages are shown. | +| `messages` | Bidirectional array of messages (`IgcChatMessage[]`) displayed in the chat. The Chat updates the supplied collection when the user sends a message. | | `draftMessage` | The current unsent message, represented as an object containing `text` and optional `attachments`. This is useful for saving or restoring message drafts. | | `options` | Chat configuration () such as current user ID, input placeholders, accepted file types, quick reply suggestions and typing behavior. | | `templates` | Custom Angular templates () for message content, input, attachments, and other parts of the chat UI. | These properties make it straightforward to synchronize the Chat’s UI with your application’s state and backend. +#### Bidirectional Messages Collection + +The `messages` collection is bidirectional: the application provides the messages to display, and the Chat updates the original collection as the conversation continues. After the user sends a message, code holding a reference to the collection can access the newly created message. This is an in-place update to the collection rather than Angular two-way binding with `[(messages)]`. + +The `messageCreated` event is a notification for persistence or other side effects. Do not append the created message to the collection again. + +If the original collection must remain unchanged, pass the Chat a shallow copy: + +```ts +public messages = [...this.originalMessages]; +``` + +Existing message objects are still shared. Create a new instance of each message when building the copied collection if those objects must also remain independent. + ### Attachments Modern conversations are rarely limited to text alone. The Chat component includes built-in support for file attachments, allowing users to share images, documents, and other files. By default, the input area includes an attachment button. You can control which file types are allowed by setting the `acceptedFiles` property: diff --git a/docs/xplat/src/content/en/components/interactivity/chat.mdx b/docs/xplat/src/content/en/components/interactivity/chat.mdx index 6cdcd58dfb..ce124fbc73 100644 --- a/docs/xplat/src/content/en/components/interactivity/chat.mdx +++ b/docs/xplat/src/content/en/components/interactivity/chat.mdx @@ -234,12 +234,12 @@ const ChatExample = () => { } ``` -You can then sync messages coming from the client, by hooking to the `messageCreated` event and adding the created messages to the collection: +The `Messages` collection is updated automatically when the user sends a message. You can handle the `MessageCreated` event to persist the message or perform other side effects; do not append the event detail to `Messages` again: ```cs public void OnMessageCreated(IgbChatMessageEventArgs e) { - Messages = Messages.Append(e.Detail).ToArray(); + Console.WriteLine($"Message created: {e.Detail.Text}"); } ``` @@ -250,15 +250,57 @@ This approach makes it easy to plug the Chat into your own data source, such as ### Properties The component exposes several key properties that let you control its state and configuration: -| Name | Description | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messages` | Array of messages ([]) displayed in the chat. You can bind to this to control which messages are shown. | -| `draftMessage` | The current unsent message, represented as an object containing `text` and optional `attachments`. This is useful for saving or restoring message drafts. | -| `options` | Chat configuration () such as current user ID, input placeholders, accepted file types, quick reply suggestions, typing delay, and custom renderers. | -| `resourceStrings` | Localized resource strings for labels, headers, and system text. Use this property to adapt the component for different languages. | +| Name | Description | +| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Messages``messages` | Bidirectional array of messages ([]) displayed in the chat. The Chat updates the supplied collection when the user sends a message. | +| `DraftMessage``draftMessage` | The current unsent message, represented as an object containing `text` and optional `attachments`. This is useful for saving or restoring message drafts. | +| `Options``options` | Chat configuration () such as current user ID, input placeholders, accepted file types, quick reply suggestions, typing delay, and custom renderers. | +| `ResourceStrings``resourceStrings` | Localized resource strings for labels, headers, and system text. Use this property to adapt the component for different languages. | These properties make it straightforward to synchronize the Chat’s UI with your application’s state and backend. +#### Bidirectional Messages Collection + +The `messages``Messages` collection is bidirectional: the application provides the messages to display, and the Chat updates the original collection as the conversation continues. After the user sends a message, code holding a reference to the collection can access the newly created message. + +The `igcMessageCreated``onMessageCreated``MessageCreated` event is a notification for persistence or other side effects. Do not append the created message to the collection again. + +If the original collection must remain unchanged, pass the Chat a shallow copy. Existing message objects are still shared; create a new instance of each message when building the copied collection if those objects must also remain independent. + + + + +```ts +const chatMessages = [...originalMessages]; +chat.messages = chatMessages; +``` + + + + + + +```tsx +const chatMessages = [...originalMessages]; + +return ; +``` + + + + + + +```cs +IgbChatMessage[] chatMessages = originalMessages.ToArray(); +``` + +```razor + +``` + + + ### Attachments