Skip to main content

Overview

The CometChatMessageHeader component displays the header section of a chat conversation. It shows information about the user or group being chatted with, including real-time status updates, typing indicators, and provides action buttons for calls, search, and AI-powered conversation summary. The component follows a Hybrid Approach architecture where:
  • MessageHeaderService handles all SDK interactions, state management, and real-time updates using Angular Signals
  • Component @Input properties allow developers to override service behavior for flexibility
  • Both service methods and @Input properties are available, with @Input taking priority when provided

Key Features

  • Real-time Updates: Automatic updates for user online/offline status and typing indicators
  • Flexible Customization: Extensive template projection for all UI sections (header, leading, title, subtitle, trailing)
  • Service-Based Architecture: Clean separation of concerns with Angular Signals for reactive state management
  • Keyboard Navigation: Full keyboard accessibility with Tab, Enter, Space, and Escape key support (WCAG 2.1 Level AA compliant)
  • Call Integration: Built-in voice and video call buttons with customizable visibility
  • AI Smart Chat Features: Support for conversation summary generation with configurable message count
  • Search Integration: Optional search functionality with event emission
  • Error Handling: Comprehensive error handling with event propagation

Basic Usage

Simple Implementation with User

Simple Implementation with Group

Live Preview — message header for a user conversation. Open in Storybook ↗

Properties

Entity Configuration Properties

PropertyTypeDefaultDescription
userCometChat.UserundefinedThe user to display in the header (for 1-on-1 conversations). Mutually exclusive with group.
groupCometChat.GroupundefinedThe group to display in the header (for group conversations). Mutually exclusive with user.

Display Control Properties

PropertyTypeDefaultDescription
hideUserStatusbooleanfalseHide the user’s online/offline status indicator
showBackButtonbooleanfalseShow the back button
hideVoiceCallButtonbooleantrueHide the voice call button. Defaults to true (hidden). When calling is enabled via UIKitSettingsBuilder.setCallingEnabled(true), the resolved default becomes false (visible). Set to true explicitly to hide even when calling is enabled.
hideVideoCallButtonbooleantrueHide the video call button. Defaults to true (hidden). When calling is enabled via UIKitSettingsBuilder.setCallingEnabled(true), the resolved default becomes false (visible). Set to true explicitly to hide even when calling is enabled.
showSearchOptionbooleanfalseShow the search option in the header
showConversationSummaryButtonbooleanfalseShow the AI conversation summary button
callSettingsBuilderCallSettingsBuilderundefinedCustom CallSettingsBuilder forwarded to the call buttons and ongoing call screen. Follows the three-tier priority: @Input > GlobalConfig > default.

AI Configuration Properties

PropertyTypeDefaultDescription
summaryGenerationMessageCountnumber1000Number of messages to use for AI summary generation
enableAutoSummaryGenerationbooleanfalseAutomatically generate conversation summary on component initialization

Date/Time Configuration Properties

PropertyTypeDefaultDescription
lastActiveAtDateTimeFormatCalendarObjectundefinedCustom date/time format for the last active timestamp

Template Properties

PropertyTypeDefaultDescription
headerViewTemplateRef<any>undefinedCustom template for the entire header (replaces all default content)
itemViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for the item section (replaces avatar, title, subtitle)
leadingViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for the leading section (avatar area)
titleViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for the title section (name)
subtitleViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for the subtitle section (status/typing/member count)
trailingViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for the trailing section (action buttons)
backButtonViewTemplateRef<any>undefinedCustom template for the back button
auxiliaryButtonViewTemplateRef<{user?: CometChat.User; group?: CometChat.Group}>undefinedCustom template for auxiliary buttons in the trailing section

Events

EventPayload TypeDescription
backClickvoidEmitted when the back button is clicked
itemClickCometChat.User | CometChat.GroupEmitted when the header item (avatar/name area) is clicked
searchClickvoidEmitted when the search option is clicked
conversationSummaryClick{ messageCount: number }Emitted when the conversation summary button is clicked or auto-generation is triggered
voiceCallClickCometChat.User | CometChat.GroupEmitted when the voice call button is clicked
videoCallClickCometChat.User | CometChat.GroupEmitted when the video call button is clicked
errorCometChat.CometChatExceptionEmitted when an error occurs in the component or service

Usage Patterns

CometChatMessageHeader supports two usage patterns for receiving the active user or group context.
When used alongside cometchat-conversations, the message header automatically subscribes to ChatStateService. No explicit [user] or [group] input is needed — the component reacts to conversation selection changes.
This is the recommended approach. The header stays in sync with the conversation list without manual wiring.

Advanced Usage

With AI Conversation Summary

Enable AI-powered conversation summary with custom message count:

Auto-Generate Summary on Load

With Search and Summary (Overflow Menu)

When both search and summary options are enabled, they appear in an overflow menu:

Custom Call Settings

Override the default CallSettingsBuilder used when calls are initiated from the message header:
You can also set callSettingsBuilder globally via GlobalConfig so all call components use the same settings without passing the input to each one.

Custom Last Active Date Format

Customization with Templates

Custom Subtitle View

Customize the status/typing indicator section:

Custom Leading View with Badge

Custom Trailing View with Additional Actions

Custom Back Button

Live Preview — message header with a custom back button. Open in Storybook ↗

Keyboard Accessibility

CometChatMessageHeader is fully keyboard accessible and meets WCAG 2.1 Level AA standards.

Keyboard Shortcuts

KeyActionContext
TabNavigate between interactive elementsGlobal
Shift + TabNavigate backwardsGlobal
EnterActivate focused element (back button, item, call buttons)When element is focused
SpaceActivate focused elementWhen element is focused
EscapeClose overflow menuWhen menu is open

Accessibility Features

ARIA Attributes:
  • role="banner" on the header container
  • role="button" on the clickable item section
  • role="status" on status indicators and typing indicators
  • aria-label with user/group name and status information
  • aria-live="polite" for typing indicator announcements
  • Proper tabindex management for keyboard navigation
Screen Reader Support:
  • Announces user/group name and status when focused
  • Announces typing indicator changes
  • Announces status changes (online/offline) via live region
  • Semantic HTML structure with proper heading hierarchy
Focus Management:
  • Visible focus indicators (2px border) meeting WCAG contrast requirements
  • Logical tab order through interactive elements
  • Focus trap within overflow menu when open
WCAG 2.1 Compliance:
  • ✅ 2.1.1 Keyboard (Level A) - All functionality available via keyboard
  • ✅ 2.1.2 No Keyboard Trap (Level A) - Users can navigate away using keyboard
  • ✅ 2.4.3 Focus Order (Level A) - Logical focus order
  • ✅ 2.4.7 Focus Visible (Level AA) - Visible focus indicators
  • ✅ 4.1.2 Name, Role, Value (Level A) - Proper ARIA attributes
  • ✅ 4.1.3 Status Messages (Level AA) - Screen reader announcements

Styling with CSS Variables

The CometChatMessageHeader component uses CSS variables for comprehensive theming:

Dark Theme Example

Custom Brand Colors

Real-Time Features

Automatic Updates

The component automatically updates in real-time for:
  • User Status: Online/offline status changes are reflected immediately
  • Typing Indicators: Shows when the user is typing (for 1-on-1 conversations)
  • Group Typing: Shows who is typing in group conversations with support for multiple users
  • Member Count: Updates when members join or leave a group
  • Last Active: Updates the last active timestamp for offline users

Typing Indicator Display

For user conversations:
  • Shows “Typing…” when the user is typing
For group conversations:
  • Single user: “John is typing…”
  • Two users: “John and Jane are typing…”
  • Multiple users: “John and 2 others are typing…”

Error Handling

The component provides comprehensive error handling through the onError event:
For troubleshooting tips, see the Troubleshooting Guide.