Skip to content

Chat UI Component

Jump to bottom
Galina Edinakova edited this page May 5, 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-send 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.
  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-send, message-received, 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 using a component or slot.
  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. 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-send 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. 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

IgcChatComponent

Properties

Property Attribute Reflected Property Type Default Description
messages - No IgcMessage[] [] List of message objects.
typingUsers - No string - 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.
disableAttachments disable-attachments Yes Boolean false Disables the ability to attach files or images to messages.
hideEmojiPicker - No Boolean - Hides the emoji picker from the input area.
headerText header-text Yes Boolean - Text to display in the header section of the chat UI.

Methods

Name Type signature Description

Slots

Name Description

CSS parts

Name Description

CSS variables

Name Description

Methods

Name Description Return type Parameters

Events

Name Description Cancelable Parameters

IgcChatMessageListComponent

Options

Name Description Type Default value Valid values
messages An array of messages to display in the chat window. Each message must conform to the IgcMessage interface. IgcMessage[] []
user Represents the current user of the chat. Used to determine message ownership, alignment, and typing status. IgcUser | undefined
typingUsers A list of users who are currently typing. IgcUser[] []
scrollBottom Whether to automatically scroll to the bottom when new messages arrive. Boolean true 'true' | 'false'
disableReactions Disables the support for reactions (e.g. emoji, likes) on messages. Boolean false 'true' | 'false'

Methods

Name Description Return type Parameters

Events

Name Description Cancelable Parameters

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.

Options

Name Description Type Default value Valid values
message The message object to render within the chat message component. Contains content, sender, and optional metadata like timestamp or attachments. IgcMessage | undefined
user The current user viewing the chat. Used to determine message alignment or styling based on ownership. IgcUser | undefined
disableReactions Disables reactions (e.g. emoji, likes) for this message. Boolean false 'true' | 'false'

Methods

Name Description Return type Parameters

Events

Name Description Cancelable Parameters

IgcChatInputComponent

  • A chat input component for composing and sending messages in a chat interface.
  • Includes support for emoji selection and file attachments.

Options

Name Description Type Default value Valid values
disableAttachments Enables or disables the ability to attach files to a message. Boolean false 'true' | 'false'
disable(hide)EmojiPicker Enables or disables the emoji picker in the chat input. Boolean false 'true' | 'false'

Methods

Name Description Return type Parameters

Events

Name Description Cancelable Parameters

Types

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;
}

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;

  /**
   * Optional timestamp in ISO format or localized string.
   */
  timestamp?: string;

  /**
   * Optional array of emoji or text reactions.
   */
  reactions?: string[];

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

  /**
   * True if the message is still being sent or is pending.
   */
  pending?: boolean;
}

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