The chat component is a reusable web component that provides a chat interface for user input and message display. It is designed to be flexible, themeable, and easy to integrate into various web applications.
Objectives
High-level goals
Render a user-friendly chat interface.
Support sending and receiving messages.
Allow customization of styles and behavior via attributes and slots.
Emit events for external interaction (e.g., sending messages).
As a developer, I want to implement a multi-line text input field that grows with content so users can compose comfortably.
As a developer, I want to create a customizable slot or config for action buttons so features like attachments can be plugged in.
As a developer, I want to conditionally render context chips near the input area based on passed props or application state.
As a developer, I want to handle both keyboard (Enter) and button-based sends, emitting a message-created event with the message payload.
As a developer, I want to optimistically render the message in the list upon send to ensure snappy user experience.
Message List Rendering
As a developer, I want to render messages in a scrollable container in chronological order with appropriate metadata (sender, avatar, timestamp).
As a developer, I want to differentiate message styling based on the sender (e.g., "self" vs "others") using dynamic class binding or slots.
As a developer, I want to auto-scroll to the newest message when new content arrives, unless the user has scrolled away from the bottom.
As a developer, I want to support custom content render areas for context chips or attachments beneath message bubbles.
Typing Indicator
As a developer, I want to show a typing indicator based on backend events or input debounce, and hide it after a timeout or message send.
As a developer, I want the typing state to be synchronized across clients using a publish-subscribe or socket event system. /Application scenario/
File Attachment Support
As a developer, I want to implement file input and drag-drop support that allows file selection and previews before sending.
As a developer, I want to emit a file-upload event with file metadata to allow upload handling externally.
Answer Suggestions
As a developer, I want to support quick-reply suggestions passed as props or received via events.
As a developer, I want to send a message immediately when a quick reply is selected, using the same message-created logic.
Message rendering
As a developer, I want to define a common Renderer interface (or base class) for message rendering, so that new rendering formats can be added easily in the future.
As a developer, I want to implement a PlainTextRenderer that outputs unformatted text, so that it can be used as the default fallback.
As a developer, I want to implement a MarkdownRenderer that parses and renders Markdown syntax, so that users can send formatted messages using Markdown.
As a developer, I want to implement a mechanism that selects the appropriate renderer based on user settings or message metadata, so that messages are rendered consistently according to user preferences.
As a developer, I want to sanitize Markdown-rendered output to prevent XSS or unsafe HTML injection, so that the chat remains secure for all users.
Basic Styling Customization
As a developer, I want to expose CSS variables or use ::part selectors for theming support.
As a developer, I want to allow passing a theme config object or inherit from global styles for flexible design integration.
Lifecycle & Events
As a developer, I want to emit structured lifecycle events (message-created, user-typing) with full metadata for external service integration.
As a developer, I want to validate and sanitize all emitted event payloads to ensure consistency and reliability.
Accessibility
As a developer, I want to support keyboard shortcuts and tab navigation for all interactive elements.
As a developer, I want to use proper ARIA roles and labels (e.g., role="log") for screen reader support.
Chatting experience - Planned features
Message Status (Pending, Sent, Delivered, Read)
As a developer, I want to support message states via status flags and update message rendering accordingly.
As a developer, I want to expose an API to update message statuses dynamically based on backend responses.
Avatars
As a developer, I want to allow passing avatar URLs for each user.
As a developer, I want to render avatars alongside sender names within each message item.
Emojis
As a developer, I want to integrate an emoji picker component that inserts emojis into the input field.
As a developer, I want emojis to render inline within message content using Unicode or image fallback.
As a developer, I want to support emoji reactions through a contextual reaction menu per message.
URL & File Preview
As a developer, I want to detect and parse pasted URLs and generate preview cards (title, description, image) using a metadata fetch API.
As a developer, I want to display file thumbnails or icons for supported types in a visually consistent way.
As a developer, I want to ensure that URLs open in a new, secure tab using rel="noopener noreferrer".
Search
As a developer, I want to implement a search function over message content using keyword indexing or text filtering.
As a developer, I want to highlight matched keywords in the message list for better visibility.
As a developer, I want to implement navigation (next/previous) through search results and scroll to the relevant message.
Contextual Actions
As a developer, I want to implement a contextual menu on right-click or long-press with actions like Copy and Reply.
As a developer, I want each contextual action to emit corresponding events or trigger internal handlers.
End-user stories:
Core Chatting Experience
Message Input & Sending
As a user, I want to type multi-line messages in the input field so I can write longer thoughts without interruption.
As a user, I want to use action buttons (like attach) to perform additional actions while composing a message.
As a user, I want to see helpful context chips next to action buttons when relevant so I can better understand the current conversation state.
As a user, I want to send messages using either the Enter key or a Send button so I can choose my preferred input method.
As a user, I want my message to appear instantly in the chat after sending so the interaction feels responsive.
As a user, I want unsent messages content to be preserved across sessions.
Message List Rendering
As a user, I want to see messages displayed in order from oldest to newest, with the most recent at the bottom, so I can follow the conversation easily.
As a user, I want to see each sender's name, avatar (if available), and timestamp next to their messages to understand who said what and when.
As a user, I want my messages styled differently from others so I can visually distinguish my own contributions.
As a user, I want the chat to scroll to the latest message automatically so I donβt miss any incoming content.
As a user, I want to see additional contextual content (like attachments or chips) beneath the message text when relevant.
As a user, I want to see footer actions for each message so I can interact with them when needed.
Typing Indicator
As a user, I want to see a typing indicator when another person is typing so I know a response is on the way.
As a user, I want the typing indicator to disappear when the person stops typing or sends a message to avoid confusion.
File Attachment Support
As a user, I want to attach files like images or documents to my message so I can share more than just text.
As a user, I want to see a preview of my attached file before sending so I know I picked the right one.
Answer Suggestions
As a user, I want to see quick-reply buttons based on suggestions so I can respond faster.
As a user, I want clicking a suggestion to immediately send it as a message for smooth interaction.
Message rendering
As a user, I want messages to be rendered as plain text by default, so that my basic communication is reliably displayed without formatting issues.
As a user, I want to be able to use Markdown syntax (like bold, italic, # headings) in my messages, so that I can express myself with simple text formatting.
As a user, I want to have the option to disable Markdown rendering, so that special characters are shown as-is instead of being formatted.
Accessibility
As a user, I want to navigate the chat component using just a keyboard so I can use it without a mouse.
As a user, I want screen readers to describe the chat correctly using ARIA roles (e.g., role="log") so I can stay informed while navigating.
Chatting experience - Planned features
Message Status (Pending, Sent, Delivered, Read)
As a user, I want to see visual indicators showing the status of my messages (e.g., sent, delivered, read) so I know their progress.
Avatars
As a user, I want to see avatars next to usernames to better identify participants.
Emojis
As a user, I want to open an emoji picker and insert emojis into my message to express myself.
As a user, I want emojis to render properly within the message bubble to keep messages visually engaging.
As a user, I want to react to messages using emojis for lightweight feedback.
URL & File Preview
As a user, I want a preview card to show up when I paste a URL so I can get a quick sense of the content.
As a user, I want uploaded images and files to be shown as thumbnails or previews so I can see what was shared at a glance.
As a user, I want links in messages to open in a new tab so I donβt lose my chat session.
Search
As a user, I want to search chat history using keywords to quickly find relevant messages.
As a user, I want matching search results to be highlighted to help me scan quickly.
As a user, I want to navigate through results using "next" and "previous" buttons so I can find the exact message.
Contextual Actions
As a user, I want to right-click (or tap and hold) on a message to bring up options like Copy and Reply so I can take quick actions on individual messages.
Time breaks
As a user, I want to see time breaks in the chat (e.g., βYesterdayβ, β2 hours laterβ), so that I can easily understand the flow and timing of the conversation.
** Integration scenarios or functionality with other features/components prototype
** End-to-end user experienceprototype
** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off
Describe any special localization requirements such as the number of localizable strings, regional formats
3.4. Keyboard Navigation
Keys
Description
Tab / Shift+Tab
Moves the focus between the tabbable elements in the header (if there are such), message list, file upload button, textarea, send button, attachments chips
Enter
On suggestion chip, when the textarea is focused or when the send button is focused, would create new message and add it to the list
When the message list is focused, the recent message in the list is marked as active and the following key combinations are applicable:
Keys
Description
Arrow Down
Activates the message below
Arrow Up
Activates the message above
Home
Activates the first message in the chat
End
Activates the last message in the chat
3.5. API
Generic chat model
IgcChatComponent
/** * The list of chat messages currently displayed. * * This includes both user and response messages. */
@property({reflect: true,attribute: false})public messages: IgcMessage[]=[];/** * Controls the chat configuration and how it will be displayed. */
@property({attribute: false})publicoptions?: IgcChatOptions;/** * The chat message currently being composed but not yet sent. * Includes the draft text and any attachments. */
@property({reflect: true,attribute: false})publicdraftMessage?: { text: string; attachments: IgcMessageAttachment[];};/** The resource strings of the chat. */
@property({attribute: false})publicresourceStrings=IgcChatResourceStringEN;/** * Scrolls the view to a specific message by id. * @param messageId - The id of the message to scroll to. */publicscrollToMessage(messageId: string);
IgcMessage
/** * Represents a message in the chat. */exportinterfaceIgcMessage{/** * A unique identifier for the message. */id: string;/** * The textual content of the message. */text: string;/** * The identifier or name of the sender of the message. */sender: string;/** * The timestamp indicating when the message was sent. */timestamp: Date;/** * Optional list of attachments associated with the message, * such as images, files, or links. */attachments?: IgcMessageAttachment[];}
IgcMessageAttachment
/** * Represents a file or media attachment associated with a chat message. */exportinterfaceIgcMessageAttachment{/** * A unique identifier for the attachment. */id: string;/** * The display name of the attachment (e.g. file name). */name: string;/** * The URL from which the attachment can be downloaded or viewed. * Typically used for attachments stored on a server or CDN. */url?: string;/** * The actual File object, if the attachment was provided locally (e.g. via upload). */file?: File;/** * The MIME type or a custom type identifier for the attachment (e.g. "image/png", "pdf", "audio"). */type?: string;/** * Optional URL to a thumbnail preview of the attachment (e.g. for images or videos). */thumbnail?: string;}
IgcChatOptions
exporttypeIgcChatOptions={/** * The ID of the current user. Used to differentiate between incoming and outgoing messages. */currentUserId?: string;/** * If `true`, prevents the chat from automatically scrolling to the latest message. */disableAutoScroll?: boolean;/** * If `true`, disables the ability to upload and send attachments. * Defaults to `false`. */disableInputAttachments?: boolean;/** * Indicates whether the other user is currently typing a message. */isTyping?: boolean;/** * The accepted files that could be attached. * Defines the file types as a list of comma-separated values (e.g. "image/*,.pdf") that the file input should accept. */acceptedFiles?: string;/** * Optional header text to display at the top of the chat component. */headerText?: string;/** * Optional placeholder text for the chat input area. * Provides a hint to the user about what they can type (e.g. "Type a message..."). */inputPlaceholder?: string;/** * Suggested text snippets or quick replies that can be shown as user-selectable options. */suggestions?: string[];/** * Controls the position of the chat suggestions within the component layout. * * - `"below-input"`: Renders suggestions below the chat input area. * - `"below-messages"`: Renders suggestions below the chat messages area. * * Default is `"below-messages"`. */suggestionsPosition?: 'below-input'|'below-messages';/** * Time in milliseconds to wait before dispatching a stop typing event. * Default is `3000`. */stopTypingDelay?: number;/** * A set of template override functions used to customize rendering of messages, attachments, etc. */templates?: Partial<IgcChatTemplates>;messageRenderer?: ChatMessageRenderer;};
IgcChatTemplates
exporttypeIgcChatTemplates={/** * Template for rendering the attachments of a message. */attachmentsTemplate?: (message: IgcMessage,ctx: {templates: Partial<IgcChatTemplates>})=>unknown;/** * Template for rendering an attachment in a message. * This allows customization of how each attachment is displayed. */attachmentTemplate?: (attachment: IgcMessageAttachment,message: IgcMessage)=>unknown;/** * Template for rendering a custom header above the attachment in a message. */attachmentHeaderTemplate?: (attachment: IgcMessageAttachment,message: IgcMessage)=>unknown;/** * Template for rendering the main content of an attachment, such as a thumbnail or file preview. */attachmentContentTemplate?: (attachment: IgcMessageAttachment)=>unknown;/** * Template for rendering an information in the header of a single chat message. * Use this to display data about the author of the message. */messageHeaderTemplate?: (message: IgcMessage)=>unknown;/** * Template for rendering a single chat message. * Use this to customize message layout, formatting, or metadata. */messageTemplate?: MessageTemplate;/** * Template for rendering the actions available for a message (e.g. copy, like, dislike, regenerate). * This allows customization of the buttons or controls shown for each message. */messageActionsTemplate?: (message: IgcMessage)=>unknown;/** * Template used to show an indicator when the other user is typing (e.g. βUser is typing...β). */typingIndicatorTemplate?: unknown;/** * Template for customizing the text input element (usually a `<textarea>` or `<input>`). * * @param text - The current value of the text input. * @returns {unknown} A custom rendered representation of the text input. */textInputTemplate?: (text: string)=>unknown;/** * Template for rendering additional controls in the message input area, * such as send buttons, emoji pickers, or voice recorders. */textAreaActionsTemplate?: ()=>unknown;/** * Template for rendering attachments that are currently queued for sending (in the input area). */textAreaAttachmentsTemplate?: AttachmentTemplate;/** * Template for rendering the suggestion prefix. */suggestionPrefixTemplate?: unknown;};
Chat model - Planned features
IgcUser
/** * Represents a user in the chat application.*/exportinterfaceIgcUser{/** * Unique identifier for the user. */id: string;/** * Display name of the user. */name: string;/** * Optional URL or path to the user's avatar image. */avatarUrl?: string;/** * Optional status of the user i.e., 'online', 'offline', 'away', etc. */status?: any;}
IgcMessageStatusType
/** * Defines the status of a chat message in its delivery lifecycle. * * - `'sent'`: The message has been sent by the client. * - `'delivered'`: The message was successfully delivered to the recipient. * - `'read'`: The recipient has seen or opened the message. */exporttypeIgcMessageStatusType='sent'|'delivered'|'read';
IgcMessageAttachmentType
/** * Defines the type of a message attachment. * * - `'image'`: A visual attachment such as a photo or screenshot. * - `'file'`: A general file attachment (e.g., PDF, DOCX, ZIP). */exporttypeIgcMessageAttachmentType='image'|'file';
IgcChatComponent
Properties
Property
Attribute
Reflected
Property Type
Default
Description
messages
-
No
IgcMessage[]
[]
An array of messages to display in the chat window. Each message must conform to the IgcMessage interface.
options
-
No
IgcChatOptions
-
An object that defines the chat configuration and appearance.
Fired when files are dragged over the chat input area.
false
igcAttachmentDrop
Fired when files are dropped in the chat input area.
false
igcAttachmentClick
Emitted on clicking a message attachment.
false
{ detail: IgcMessage }
igcInputFocus
Fired when the input element gains focus.
false
igcInputBlur
Fired when the input element loses focus.
false
igcInputChange
Fired when the input value changes.
false
Slots
Name
Description
prefix
The prefix area of the chat header.
title
The title area of the chat header.
action
The action buttons area of the chat header.
empty-state
The message list when there are no messages.
suggestions
The suggestions area of the chat.
suggestions-header
The header of the suggestions area.
suggestions-actions
The actions area in the suggestions area.
suggestion
Each suggestion in the suggestions area.
CSS parts
Name
Description
CSS variables
Name
Description
IgcChatMessageListComponent
Properties
Property
Attribute
Reflected
Property Type
Default
Description
Methods
Name
Type signature
Description
Events
Name
Description
Cancelable
Parameters
Slots
Name
Description
CSS parts
Name
Description
CSS variables
Name
Description
IgcChatMessageComponent
Represents a single chat message component for use within a chat interface.
This component displays a message, supports user-based styling, and optionally allows reactions.
Message's text is sanitized with DOMPurify and formatting is processed with marked. If a custom markdownRenderer is provided in IgcChatOptions, message's text will be formatted accordingly.
Properties
Property
Attribute
Reflected
Property Type
Default
Description
message
-
No
IgcMessage | undefined
-
The message object to render within the chat message component. Contains content, sender, and optional metadata like timestamp or attachments.
Methods
Name
Type signature
Description
Events
Name
Description
Cancelable
Parameters
Slots
Name
Description
CSS parts
Name
Description
CSS variables
Name
Description
IgcChatInputComponent
A chat input component for composing and sending messages in a chat interface.