Skip to content

Chat UI Component

Teodosia Hristodorova edited this page Jul 8, 2025 · 67 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
3.1 George Abraham Jun 26, 2025 User experience when using AI chat
3.2 Teodosia Hristodorova Jul 2, 2025 Update API

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

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

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.

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

3.1. End-User Experience

Figma specification:

  1. Material light
  2. Indigo theme

** 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
    .currentUserId=${currentUserId}
    .messages=${initialMessages}
    .options=${initialOptions}
>
</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

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 })
   public options?: IgcChatOptions;

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 id of the user who sent the message.
   */
  sender: string;

  /**
   * 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 display name of the attachment, typically the original file name.
   */
  name: string;

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

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

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

  /**
   * 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[];
}

IgcChatOptions

export type IgcChatOptions = {
  /**
   * The unique identifier of the chat's current user.
   */
  currentUserId?: string;
  /**
   * Controls whether the user's avatar is hidden in the chat UI.
   */
  hideAvatar?: boolean;
  /**
   * Controls whether the message's timestamp is hidden in the chat UI.
   */
  hideTimestamp?: boolean;
  /**
   * Controls whether the user's name is hidden in the chat UI.
   */
  hideUserName?: boolean;
  /**
   * Disables automatic scrolling to the bottom when new messages are added.
   */
  disableAutoScroll?: boolean;
  /**
   * Disables attachment support in the chat input.
   */
  disableAttachments?: boolean;
  /**
   * Defines whether the message composing indicator would be displayed.
   */
  isComposing?: boolean;
  /**
   * The accepted files that could be attached.
   * Defines the file types as a list of comma-separated values that the file input should accept.
   */
  acceptedFiles?: string;
  /**
   * Defines the text displayed in the chat header.
   */
  headerText?: string;
  /**
   * Defines the answer suggestions.
   */
  suggestions?: string[];
  /**
   * Defines the custom templates that would be rendered in the chat UI.
   */
  templates?: IgcChatTemplates;
};

IgcChatTemplates

export type IgcChatTemplates = {
  /*
   * The custom template, which should be used when rendering the attachments in the chat message list.
   */
  attachmentTemplate?: AttachmentTemplate;
  /*
   * The custom template, which should be used when rendering the attachments' header in the chat message list.
   */
  attachmentHeaderTemplate?: AttachmentTemplate;
  /*
   * The custom template, which should be used when rendering the attachments' actions area in the chat message list.
   */
  attachmentActionsTemplate?: AttachmentTemplate;
  /*
   * The custom template, which should be used when rendering the attachments' content area in the chat message list.
   */
  attachmentContentTemplate?: AttachmentTemplate;
  /*
   * The custom template, which should be used when rendering the message.
   */
  messageTemplate?: MessageTemplate;
  /*
  /*
   * The custom template, which should be used when rendering the message's footer action area.
   */
  messageActionsTemplate?: MessageTemplate;
  /*
   * The custom template, which should be used when rendering the message composing indicator.
   */
  composingIndicatorTemplate?: TemplateResult;
};

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

Methods

Name Type signature Description

Events

Name Description Cancelable Parameters
igcMessageCreated Emitted when a message is created. true { detail: IgcMessage, cancelable: true }
igcTypingChange Emitted when the user starts/stops typing a message. false { typing: boolean}
igcAttachmentChange Emitted when the file input checked state changes, it is removed or dropped. false { detail: IgcMessageAttachment, cancelable: true }
igcAttachmentDrag 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 }
igcReactionChange Emitted 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 Emitted when a message is copied. false { detail: IgcMessage }

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.

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.

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

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

Automation

Rendering & Initialization
  • Verify that the component renders without errors.
  • Verify that the chat is displayed correctly and behaves as expected depending on the defined options.
  • Verify that an empty message list shows the appropriate empty state or nothing.
User identity
  • Verify that sent messages are displayed as the current user's 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 the component with a list of messages and verify they render correctly.
  • Verify messages align based on the sender (left for other users, right for the current one).
  • Verify message-created event is emitted with correct payload on clicking the send button.
  • Verify message-created event is emitted with correct payload on pressing the "Enter" key.
  • Append a new message and verify the component auto-scrolls if scrollBottom is true.
Message display
  • Verify that one's 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.
Suggestions
  • Verify the suggestions are rendered correctly.
  • Verify message-created event is emitted on clicking a suggestion.
Composing indicator
  • Verify that the composing indicator is rendered correctly (e.g., "Alice is typing...").
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 that throttling/debouncing works properly.
Accessibility
  • 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.

ARIA Support

RTL Support

Assumptions Limitation Notes

Specify all referenced external sources

Clone this wiki locally