Skip to content

Chat UI Component

Jump to bottom
Galina Edinakova edited this page May 21, 2025 · 60 revisions

Chat UI Component Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

CodeX Team

Developer Name

Designer Name

Requires approval from

  • Peer Developer Name | Date:
  • Design Manager Name | Date:

Signed off by

  • Product Owner Radoslav Mirchev | Date:
  • Platform Architect Radoslav Karaivanov| Date:

Revision History

Version Users Date Notes
1 Galina Edinakova April 11, 2025 Initial User and Developer Stories
2 Galina Edinakova May 2, 2025 Updated user stories
3 Galina Edinakova May 5, 2025 Adding API & automation scenarios

1. Overview

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).

End-to-end user experience prototype

PoC: https://github.com/IgniteUI/igniteui-webcomponents/pull/1674

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

General

  1. The component adapts its layout and appearance to different screen sizes (desktop, tablet, mobile).
  2. Localization (i18n)
  • All UI strings (e.g., “Send”, “Typing…”, timestamps) are localizable.
  • The component supports both LTR and RTL text directions.
  1. The component handles unexpected input gracefully (e.g., empty messages, invalid file types).
  2. No console errors or memory leaks during use.
  3. Unit and/or integration tests are written for each feature. ...

2. User Stories

Elaborate more on the multi-facetted use cases

Developer stories:

Core chatting experience

  1. Message Input & Sending
  • 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.
  1. 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.
  1. 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/
  1. 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.
  1. 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.
  1. 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.

Enhanced Chatting Experience

  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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".
  1. 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.
  1. 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.
  1. 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.
  1. 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

  1. 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.
  1. 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.
  1. 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.
  1. 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.

Enhanced Chatting Experience

  1. 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.
  1. 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.
  1. Avatars
  • As a user, I want to see avatars next to usernames to better identify participants.
  1. 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.
  1. 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.
  1. Message formatting
  • 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience

** 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

3.2. Developer Experience

Component structure
  |─────────────────────────────────────────────|
  │             Chat Message Area               │
  │  [msg1] [msg2] [msg3] ...                   │
  ├─────────────────────────────────────────────┤
  │ [ Input Field              ] [ Send Button ]│
  |─────────────────────────────────────────────|
Component declaration
<igc-chat
    .user=${currentUser}
    .messages=${initialMessages}
    header-text="Chat Component"
>
</igc-chat>

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys Description

3.5. API

AI Chat Model

IgcMessage

/**
 * Represents a chat message in the system.
 */
export interface IgcMessage {
  /**
   * A unique identifier for the message.
   */
  id: string;

  /**
   * The raw text content of the message.
   */
  text: string;

  /**
   * Indicates whether the message is a response (e.g., from the assistant or system).
   * If false, the message is assumed to be from the user.
   */
  isResponse: boolean;

  /**
   * The date and time when the message was created or sent.
   */
  timestamp: Date;

  /**
   * Optional list of attachments included with the message.
   * Attachments may include files, images, or other supported data types.
   */
  attachments?: IgcMessageAttachment[];
}

IgcMessageAttachment

/**
 * Represents a file or media attachment associated with a chat message.
 */
export interface IgcMessageAttachment {
  /**
   * A unique identifier for the attachment.
   */
  id: string;

  /**
   * The type of the attachment (e.g., image, video, file).
   */
  type: any;

  /**
   * The URL or path where the attachment can be accessed or downloaded.
   */
  url: string;

  /**
   * The display name of the attachment, typically the original file name.
   */
  name: string;

  /**
   * The size of the attachment in bytes.
   * Optional field that may be used for display or upload validation.
   */
  size?: number;

  /**
   * An optional thumbnail image URL used for previewing media (e.g., images or videos).
   */
  thumbnail?: string;
}

IgcMessageReaction

/**
 * Represents a reaction applied to a chat message, such as an emoji response.
 */
export interface IgcMessageReaction {
  /**
   * A unique identifier for the emoji.
   */
  emojiId: string;

  /**
   * An array of user IDs who reacted with this emoji.
   */
  users: string[];
}

IgcChatComponent

/**
   * The list of chat messages currently displayed.
   * 
   * This includes both user and response messages.
   */
  @property({ reflect: true, attribute: false })
  public messages: IgcMessage[] = [];

  /**
   * Indicates whether the AI or system is currently generating a response.
   */
  @property({ reflect: true, attribute: false })
  public isAiResponding = false;

  /**
   * Controls whether the user's avatar is hidden in the chat UI.
   */
  @property({ type: Boolean, attribute: 'hide-avatar' })
  public hideAvatar = false;

  /**
   * Controls whether the user's name is hidden in the chat UI.
   */
  @property({ type: Boolean, attribute: 'hide-user-name' })
  public hideUserName = false;

  /**
   * Disables automatic scrolling to the bottom when new messages are added.
   */
  @property({ type: Boolean, attribute: 'disable-auto-scroll' })
  public disableAutoScroll = false;

  /**
   * Disables attachment support in the chat input.
   */
  @property({ type: Boolean, attribute: 'disable-attachments' })
  public disableAttachments = false;

  /**
   * Optional text displayed in the chat header.
   */
  @property({ type: String, attribute: 'header-text', reflect: true })
  public headerText = '';

Generic chat model

IgcUser

/**
 * Represents a user in the chat application.
*/
export interface IgcUser {
  /**
   * 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;
}

IgcMessage

/**
 * Represents a message in the chat.
 */
export interface IgcMessage {
  /**
   * Unique identifier for the message.
   */
  id: string;

  /**
   * The user who sent the message.
   */
  sender: IgcUser;

  /**
   * The text content of the message.
   */
  text: string;

  /**
   * The timestamp of the message.
   */
  timestamp: Date;

  /**
   * Optional array of emoji reactions.
   */
  reactions?: IgcMessageReaction[];

  /**
   * Optional list of file attachments or URLs.
   */
  attachments?: IgcMessageAttachment[];

  /**
   * The status of the message.
   */
  status?: IgcMessageStatusType;
}

IgcMessageAttachment

/**
 * Represents a file or media attachment associated with a chat message.
 */
export interface IgcMessageAttachment {
  /**
   * A unique identifier for the attachment.
   */
  id: string;

  /**
   * The type of the attachment (e.g., image, video, file).
   * Must be a valid `IgcMessageAttachmentType` enum value.
   */
  type: IgcMessageAttachmentType;

  /**
   * The URL or path where the attachment can be accessed or downloaded.
   */
  url: string;

  /**
   * The display name of the attachment, typically the original file name.
   */
  name: string;

  /**
   * The actual file.
   */
  file?: File;

  /**
   * The size of the attachment in bytes.
   * Optional field that may be used for display or upload validation.
   */
  size?: number;

  /**
   * An optional thumbnail image URL used for previewing media (e.g., images or videos).
   */
  thumbnail?: string;
}

IgcMessageReaction

/**
 * Represents a reaction applied to a chat message, such as an emoji response.
 */
export interface IgcMessageReaction {
  /**
   * A unique identifier for the emoji.
   */
  emojiId: string;

  /**
   * An array of user IDs who reacted with this emoji.
   */
  users: string[];
}

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.
 */
export type IgcMessageStatusType = '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).
 */
export type IgcMessageAttachmentType = 'image' | 'file';

IgcChatComponent

Properties

Property Attribute Reflected Property Type Default Description
user - No IgcUser undefined Specifies the current chat user (messages displayed on the right side).
messages - No IgcMessage[] [] An array of messages to display in the chat window. Each message must conform to the IgcMessage interface.
typingUsers - No IgcUser[] [] A list of users who are currently typing.
disableAutoScroll disable-auto-scroll Yes Boolean false Whether to automatically scroll to the bottom when new messages arrive.
disableReactions disable-reactions Yes Boolean false Disables the support for reactions (e.g. emoji, likes) on messages.
disableAttachments disable-attachments Yes Boolean false Disables the ability to attach files or images to messages.
disableEmojis - disable-emojis Boolean - Hides the emoji picker from the input area.
headerText? (slot should be enough) header-text Yes String - Text to display in the header section of the chat UI.

Methods

Name Type signature Description

Events

Name Description Cancelable Parameters
igcMessageCreated Emitted when a message is created. true { detail: IgcMessage }
igcTypingStart Emitted when the user starts typing a message. false { userId: string }
igcTypingEnd Emmited when the user ends typing a message. false { userId: string }
igcAttachmentChange Emmited when file input checked state changes. false { detail: string }
igcAttachmentClick Emmited on clicking a message attachment. false { detail: IgcMessage }
igcReactionChange Emmited when a message reaction is changed. false { messageId: string, action: 'add'|'change'|'remove', reactionId: string }
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
igcMessageCopied Emmited when a message is copied. false { detail: IgcMessage }

Slots

Name Description

CSS parts

Name Description

CSS variables

Name Description

IgcChatMessageListComponent

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.
user - No IgcUser | undefined Represents the current user of the chat. Used to determine message ownership, alignment, and typing status.
typingUsers - No IgcUser[] [] A list of users who are currently typing.
scrollBottom scroll-bottom Yes Boolean true Whether to automatically scroll to the bottom when new messages arrive.
disableReactions disable-reactions Yes Boolean false Disables the support for reactions (e.g. emoji, likes) on messages.

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.

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.
user - No IgcUser | undefined - The current user viewing the chat. Used to determine message alignment or styling based on ownership.
disableReactions disable-reactions Yes Boolean false Disables reactions (e.g. emoji, likes) for this message.

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.
  • Includes support for emoji selection and file attachments.

Properties

Property Attribute Reflected Property Type Default Description
disableAttachments disable-attachments Yes Boolean Enables or disables the ability to attach files to a message.
disableEmojis disable-emojis Yes Boolean false Enables or disables the emoji picker in the chat input.

Methods

Name Type signature Description

Events

Name Description Cancelable Parameters

Slots

Name Description

CSS parts

Name Description

CSS variables

Name Description

IgcChatHeaderComponent

  • A component that displays a header section for a chat interface.
  • Common use cases include showing the chat title, participant name, or custom labels.

Properties

Property Attribute Reflected Property Type Default Description
text text Yes string The text displayed in the header. This can be used to show chat titles, conversation subjects, or participant names.

Methods

Name Type signature Description

Events

Name Description Cancelable Parameters

Slots

Name Description

CSS parts

Name Description

CSS variables

Name Description

4. Test Scenarios

Automation

Rendering & Initialization
  • Verify that the component renders without errors.
  • Verify that the header displays the correct headerText.
  • Verify that an empty message list shows appropriate empty state or nothing.
User identity
  • Verify sent messages are displayed as current user messages.
  • Verify the user can be changed at runtime & reflected correctly in the UI.
  • Verify the component handles gracefully setting the user to undefined.
Message handling
  • Load component with a list of messages and verify they render correctly.
  • Verify messages align based on the sender (left for other user, right for current one).
  • Verify message-send event is emitted with correct payload on clicking the send button.
  • Verify message-send event is emitted with correct payload on pressing "Enter" key.
  • Append a new message and verify the component auto-scrolls if scrollBottom is true.
Message display
  • Verify own messages appear on the right.
  • Verify incoming messages appear on the left.
  • Verify messages with special characters and emojis render correctly.
  • Verify long messages wrap & scroll correctly.
Typing indicator
  • Verify that typingUsers are rendered correctly (e.g., "Alice is typing...").
  • Verify that multiple typing users are handled correctly in display.
Emoji and reactions
  • Enable emoji picker and verify that it's visible and functional.
  • Enable reactions and verify that clicking a message displays reaction options.
  • Verify that selecting a reaction emits a reaction-add event.
Attachments
  • Enable attachments and verify that an attachment button is visible.
  • Simulate clicking the attachment button and check file selection dialog appears.
  • Upload a mock file and verify it shows in the message preview and/or fires an event.
States
  • Set disabled=true and verify input and send button are disabled.
  • Verify send button is disabled while the message input is empty.
  • Rapidly send multiple messages and verify throttling/debouncing works properly.
Accessiblity
  • Verify all interactive elements have accessible labels (e.g., aria-label).
  • Navigate using keyboard and ensure focus moves correctly.
  • Screen reader reads the latest message when added.

5. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions Limitation Notes

7. References

Specify all referenced external sources

Clone this wiki locally