Saved Messages - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatSavedMessages",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatSavedMessages } from \"@cometchat/chat-uikit-react\";",
  "description": "A standalone screen that lists the messages the current user has saved across all of their conversations. The host app mounts it directly; it is not opened from a built-in header menu.",
  "cssRootClass": ".cometchat-saved-messages",
  "primaryOutput": {
    "prop": "onItemClick",
    "type": "(message: CometChat.BaseMessage) => void"
  },
  "props": {
    "data": {
      "messagesRequestBuilder": {
        "type": "CometChat.MessagesRequestBuilder",
        "default": "undefined"
      },
      "textFormatters": {
        "type": "CometChatTextFormatter[]",
        "default": "undefined"
      }
    },
    "visibility": {
      "hideCloseButton": { "type": "boolean", "default": false },
      "hideUnsaveMessageOption": { "type": "boolean", "default": false }
    },
    "callbacks": {
      "onItemClick": "(message: CometChat.BaseMessage) => void",
      "onClose": "() => void"
    },
    "viewSlots": {
      "itemView": "(message: CometChat.BaseMessage) => ReactNode",
      "headerView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode",
      "loadingView": "ReactNode"
    }
  },
  "events": {
    "emitted": [],
    "emittedNote": "The component itself publishes nothing, but the unsave action it renders (via the shared message options) publishes ui:message/save-changed, which keeps other surfaces in sync.",
    "received": [
      {
        "name": "ui:message/save-changed",
        "payload": "{ message, saved }",
        "description": "Optimistic local flip: adds on save, removes on unsave"
      },
      {
        "name": "message/saved",
        "payload": "{ message }",
        "description": "Adds the message to the list (network-confirmed)"
      },
      {
        "name": "message/unsaved",
        "payload": "{ message }",
        "description": "Removes the message from the list (network-confirmed)"
      }
    ]
  }
}

Overview

CometChatSavedMessages lists every message the current user has saved, across all of their conversations. Unlike pinned messages, saves are personal and conversation-agnostic — so this component takes no user/group; it always shows the signed-in user’s own saves and keeps them in sync in real time. It is a standalone screen: the UI Kit does not open it from any built-in header or menu. Mount it wherever your app wants a “Saved” destination — a route, a tab, or a side panel.

Live Preview — interact with the default saved messages screen.Open in Storybook ↗

The component handles:

Fetching the current user’s saved messages
Real-time updates when a message is saved or unsaved
An unsave action per row
Empty, loading, and error states

Saving must be enabled for your app through the features.ux.messages.saved.enabled app setting for saves to load. See Core Features.

Usage

Flat API

import { CometChatSavedMessages } from "@cometchat/chat-uikit-react";

function SavedScreen({ onClose }: { onClose: () => void }) {
  return <CometChatSavedMessages onClose={onClose} />;
}

Compound Composition

For full layout control, compose the sub-components under Root. Omit any sub-component to drop it.

import { CometChatSavedMessages } from "@cometchat/chat-uikit-react";

<CometChatSavedMessages.Root onClose={onClose}>
  <CometChatSavedMessages.Header />
  <CometChatSavedMessages.List />
  <CometChatSavedMessages.EmptyState />
  <CometChatSavedMessages.ErrorState />
  <CometChatSavedMessages.LoadingState />
</CometChatSavedMessages.Root>

Mounting as a Screen

Because there is no built-in trigger, wire it into your own navigation — for example, a button that toggles a panel:

import { useState } from "react";
import { CometChatSavedMessages } from "@cometchat/chat-uikit-react";

function AppShell() {
  const [showSaved, setShowSaved] = useState(false);

  return (
    <>
      <button onClick={() => setShowSaved(true)}>Saved</button>
      {showSaved && <CometChatSavedMessages onClose={() => setShowSaved(false)} />}
    </>
  );
}

Filtering

Pass a messagesRequestBuilder to customize the fetch (for example, the page size). Call setSaved(true) on the builder: it is what scopes the request to the current user’s saved messages, and without it the request is an ordinary history read.

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatSavedMessages } from "@cometchat/chat-uikit-react";

<CometChatSavedMessages
  messagesRequestBuilder={
    new CometChat.MessagesRequestBuilder()
      .setSaved(true) // required — scopes the fetch to saved messages
      .setLimit(30)
  }
/>

The component re-asserts setSaved(true) on whatever builder you pass, so it is safe even if you omit it — but keep it in your code to make the intent explicit.

Actions and Events

Callback Props

Prop	Signature	Fires when
`onItemClick`	`(message: CometChat.BaseMessage) => void`	A saved row is clicked (e.g. open the source conversation)
`onClose`	`() => void`	The close button is clicked

Events

The component itself publishes nothing, but the unsave action it renders (through the shared message options) publishes ui:message/save-changed, which keeps other surfaces in sync. It subscribes to the kit event bus and updates its list automatically — an optimistic ui: flip the moment a save/unsave succeeds locally, then the network-confirmed SDK event:

Event	Payload	Behavior
`ui:message/save-changed`	`{ message, saved }`	Optimistic: adds on save, removes on unsave
`message/saved` / `message/unsaved`	`{ message }`	Network-confirmed add / remove

See the Event System for the full list.

Customization

Per-message Options

Each saved row exposes an unsave action. Hide it with hideUnsaveMessageOption:

<CometChatSavedMessages hideUnsaveMessageOption />

Saved rows are list items rather than full message bubbles, so they carry only the unsave action — there is no full per-message options menu here.

View Props

Replace parts of the UI while keeping the component’s behavior:

<CometChatSavedMessages
  itemView={(message) => <MySavedRow message={message} />}
  emptyView={<div>You haven't saved anything yet</div>}
/>

Slot	Type	Replaces
`itemView`	`(message: CometChat.BaseMessage) => ReactNode`	A saved row
`headerView`	`ReactNode`	The panel header
`emptyView`	`ReactNode`	The empty state
`errorView`	`ReactNode`	The error state
`loadingView`	`ReactNode`	The loading state

Compound Composition

Use sub-components for full layout control:

Sub-component	Description	Flat API equivalent
`Root`	Context provider and container	—
`Header`	Panel header with title and close button	`headerView`
`List`	The scrollable list of saved rows	—
`Item`	A single saved row (`message`, `index`)	`itemView`
`EmptyState`	Shown when nothing is saved	`emptyView`
`ErrorState`	Shown on a load error	`errorView`
`LoadingState`	Shown while loading	`loadingView`

CSS Styling

Override design tokens on the component selector:

.cometchat-saved-messages {
  --cometchat-background-color-01: #ffffff;
  --cometchat-text-color-primary: #141414;
}

Props

All props are optional.

View slot props (itemView, headerView, emptyView, errorView, loadingView) are convenience props on the flat API. In compound composition mode, use the corresponding sub-components directly.

messagesRequestBuilder

Customize the request used to fetch saved messages (for example, the page size).


Type	`CometChat.MessagesRequestBuilder`
Default	`undefined`

textFormatters

Text formatters applied when rendering the saved message previews. See Text Formatters.


Type	`CometChatTextFormatter[]`
Default	`undefined`

hideCloseButton

Hide the close button in the panel header.


Type	`boolean`
Default	`false`

hideUnsaveMessageOption

Remove the unsave action from each saved row.


Type	`boolean`
Default	`false`

onItemClick

Callback when a saved row is clicked.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

onClose

Callback when the close button is clicked.


Type	`() => void`
Default	`undefined`

className

Additional CSS class for the root element.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root container	`.cometchat-saved-messages`
Header	`.cometchat-saved-messages__header`
Header title	`.cometchat-saved-messages__header-title`
Header close button	`.cometchat-saved-messages__header-close`
List	`.cometchat-saved-messages__list`
Row	`.cometchat-saved-messages__item`
Row sender	`.cometchat-saved-messages__item-sender`
Row preview	`.cometchat-saved-messages__item-preview`
Row subtitle	`.cometchat-saved-messages__item-subtitle`
Row media-type icon	`.cometchat-saved-messages__item-subtitle-icon` (`--image`, `--video`, `--audio`, `--file`)
Row unsave button	`.cometchat-saved-messages__item-unsave`
Empty state	`.cometchat-saved-messages__empty`
Empty title	`.cometchat-saved-messages__empty-title`
Empty subtitle	`.cometchat-saved-messages__empty-subtitle`
Error state	`.cometchat-saved-messages__error`
Loading shimmer	`.cometchat-saved-messages__shimmer`

Next Steps

Pin & Save Messages Guide

Build a full pin/save screen end to end

Pinned Messages

The messages pinned in a conversation

Message List

Toggle the save/unsave message options

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​Compound Composition

​Mounting as a Screen

​Filtering

​Actions and Events

​Callback Props

​Events

​Customization

​Per-message Options

​View Props

​Compound Composition

​CSS Styling

​Props

​messagesRequestBuilder

​textFormatters

​hideCloseButton

​hideUnsaveMessageOption

​onItemClick

​onClose

​className

​CSS Selectors

​Next Steps

Pin & Save Messages Guide

Pinned Messages

Message List

Theming

Overview

Usage

Flat API

Compound Composition

Mounting as a Screen

Filtering

Actions and Events

Callback Props

Events

Customization

Per-message Options

View Props

Compound Composition

CSS Styling

Props

messagesRequestBuilder

textFormatters

hideCloseButton

hideUnsaveMessageOption

onItemClick

onClose

className

CSS Selectors

Next Steps