Conversation Starter - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatConversationStarter",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatConversationStarter } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Displays AI-generated conversation starter suggestions as clickable pill-shaped buttons.",
  "cssRootClass": ".cometchat-conversation-starter",
  "subComponents": ["Root", "Item", "Loading", "Error", "Empty"],
  "primaryOutput": {
    "prop": "onSuggestionClick",
    "type": "(suggestion: string) => void"
  },
  "props": {
    "Root": {
      "getConversationStarters": { "type": "() => Promise<string[]>", "note": "Required." },
      "onSuggestionClick": { "type": "(suggestion: string) => void", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Item": {
      "suggestion": { "type": "string", "note": "Required." },
      "onClick": { "type": "(suggestion: string) => void", "default": "undefined" },
      "disabled": { "type": "boolean", "default": "false" },
      "className": { "type": "string", "default": "undefined" }
    },
    "Loading": {
      "count": { "type": "number", "default": "3" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Error": {
      "message": { "type": "string", "default": "\"Failed to load conversation starters.\"" },
      "onRetry": { "type": "() => void", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Empty": {
      "message": { "type": "string", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    }
  },
  "types": {
    "CometChatConversationStarterState": "'loading' | 'loaded' | 'error' | 'empty'",
    "CometChatConversationStarterContextValue": {
      "state": "CometChatConversationStarterState",
      "suggestions": "string[]",
      "error": "Error | null",
      "onSuggestionClick": "(suggestion: string) => void | undefined",
      "retry": "() => void"
    }
  }
}

Where It Fits

CometChatConversationStarter is a base component that displays AI-generated conversation suggestions as pill-shaped buttons. It is typically used inside a message composer area or an empty chat view to help users start a conversation. The consumer provides a getConversationStarters function (usually from an AI plugin or custom service), and the component handles loading, error, and empty states automatically.

import { CometChatConversationStarter } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function ChatView() {
  const fetchStarters = () =>
    fetch("/api/ai/starters").then((r) => r.json());

  const handleSuggestionClick = (suggestion: string) => {
    console.log("Send message:", suggestion);
  };

  return (
    <div style={{ maxWidth: 500 }}>
      <CometChatConversationStarter.Root
        getConversationStarters={fetchStarters}
        onSuggestionClick={handleSuggestionClick}
      >
        <CometChatConversationStarter.Loading />
        <CometChatConversationStarter.Error />
        <CometChatConversationStarter.Empty />
      </CometChatConversationStarter.Root>
    </div>
  );
}

Minimal Render

import { CometChatConversationStarter } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function Demo() {
  return (
    <CometChatConversationStarter.Root
      getConversationStarters={() => Promise.resolve(["How are you?", "What's new?"])}
      onSuggestionClick={(s) => console.log(s)}
    >
      <CometChatConversationStarter.Loading />
      <CometChatConversationStarter.Error />
    </CometChatConversationStarter.Root>
  );
}

Root CSS class: .cometchat-conversation-starter

Actions and Events

Callback Props

onSuggestionClick

Called when a user clicks a suggestion button. Receives the suggestion string as the argument.

<CometChatConversationStarter.Root
  getConversationStarters={fetchStarters}
  onSuggestionClick={(suggestion) => {
    sendMessage(suggestion);
  }}
>
  <CometChatConversationStarter.Loading />
</CometChatConversationStarter.Root>

onRetry (Error sub-component)

Called when the user clicks the retry button in the error state. If not provided, the component uses the built-in retry() method from context which re-calls getConversationStarters.

<CometChatConversationStarter.Error
  message="Could not load suggestions"
  onRetry={() => {
    console.log("Retrying...");
  }}
/>

Custom View Slots

Slot	Signature	Replaces
`Loading`	`{ count?, className?, children? }`	Shimmer loading state
`Error`	`{ message?, onRetry?, className?, children? }`	Error state view
`Empty`	`{ message?, className?, children? }`	Empty state view

Loading

Renders shimmer placeholder pills while suggestions are being fetched. Defaults to 3 shimmer items.

Default
Custom count
Custom content

<CometChatConversationStarter.Loading />

<CometChatConversationStarter.Loading count={5} />

<CometChatConversationStarter.Loading>
  <div className="my-spinner">Loading suggestions...</div>
</CometChatConversationStarter.Loading>

Error

Renders when getConversationStarters rejects. Shows a localized error message and an optional retry button.

Default
Custom message with retry
Fully custom

<CometChatConversationStarter.Error />

<CometChatConversationStarter.Error
  message="Could not load suggestions"
  onRetry={() => console.log("retry")}
/>

<CometChatConversationStarter.Error>
  <div>
    <p>Something went wrong</p>
    <button onClick={() => window.location.reload()}>Reload</button>
  </div>
</CometChatConversationStarter.Error>

Empty

Renders when getConversationStarters resolves with an empty array. By default renders nothing unless a message or children is provided.

<CometChatConversationStarter.Empty message="No suggestions available" />

Common Patterns

Retry on error

import { CometChatConversationStarter } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function StartersWithRetry() {
  const fetchStarters = () =>
    fetch("/api/ai/starters").then((r) => r.json());

  return (
    <CometChatConversationStarter.Root
      getConversationStarters={fetchStarters}
      onSuggestionClick={(s) => console.log(s)}
    >
      <CometChatConversationStarter.Loading />
      <CometChatConversationStarter.Error message="Failed to load. Try again?" />
      <CometChatConversationStarter.Empty message="No suggestions right now" />
    </CometChatConversationStarter.Root>
  );
}

Using context in custom children

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

function CustomSuggestionList() {
  const { state, suggestions, onSuggestionClick } =
    useCometChatConversationStarterContext();

  if (state !== "loaded") return null;

  return (
    <ul>
      {suggestions.map((s) => (
        <li key={s}>
          <button onClick={() => onSuggestionClick?.(s)}>{s}</button>
        </li>
      ))}
    </ul>
  );
}

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-conversation-starter) consumes these tokens via var().
Overrides target .cometchat-conversation-starter descendant selectors.

Key Selectors

Target	Selector
Root container	`.cometchat-conversation-starter`
Suggestion pill	`.cometchat-conversation-starter__item`
Suggestion button	`.cometchat-conversation-starter__item-button`
Shimmer container	`.cometchat-conversation-starter__shimmer-container`
Shimmer pill	`.cometchat-conversation-starter__shimmer-item`
Error view	`.cometchat-conversation-starter__error-view`
Retry button	`.cometchat-conversation-starter__error-retry`
Empty view	`.cometchat-conversation-starter__empty-view`
Disabled modifier	`.cometchat-conversation-starter__item--disabled`

Example: Brand-themed conversation starters

App.css

.cometchat-conversation-starter__item {
  border-color: var(--brand-border);
}

.cometchat-conversation-starter__item:hover {
  background: var(--brand-hover);
}

.cometchat-conversation-starter__item-button {
  color: var(--brand-text);
  font-family: var(--brand-font);
}

Customization Matrix

What to change	Where	Property/API	Example
Data source	Component props	`getConversationStarters` on `Root`	`<Root getConversationStarters={fn}>`
Click handler	Component props	`onSuggestionClick` on `Root`	`<Root onSuggestionClick={fn}>`
Loading count	Component props	`count` on `Loading`	`<Loading count={5} />`
Error message	Component props	`message` on `Error`	`<Error message="Custom error" />`
Retry behavior	Component props	`onRetry` on `Error`	`<Error onRetry={fn} />`
Replace loading UI	Component props	`children` on `Loading`	`<Loading><Spinner /></Loading>`
Replace error UI	Component props	`children` on `Error`	`<Error><Custom /></Error>`
Change visual styling	Global CSS	`.cometchat-conversation-starter` selectors	See example above

Props

All props are optional unless noted otherwise.

CometChatConversationStarter.Root

getConversationStarters

Async function that returns an array of suggestion strings. Called on mount and on retry.


Type	`() => Promise<string[]>`
Default	`undefined`

Required.

onSuggestionClick

Called when a suggestion button is clicked. Receives the suggestion string.


Type	`(suggestion: string) => void`
Default	`undefined`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

children

Sub-components for custom composition (Loading, Error, Empty).


Type	`ReactNode`
Default	`undefined`

CometChatConversationStarter.Item

suggestion

The suggestion text to display inside the button.


Type	`string`
Default	`undefined`

Required.

onClick

Called when this specific item is clicked. Receives the suggestion string.


Type	`(suggestion: string) => void`
Default	`undefined`

disabled

Whether the item is disabled. Disabled items cannot be clicked and show reduced opacity.


Type	`boolean`
Default	`false`

className

Custom CSS class appended to the item container.


Type	`string`
Default	`undefined`

CometChatConversationStarter.Loading

count

Number of shimmer placeholder items to display.


Type	`number`
Default	`3`

className

Custom CSS class appended to the shimmer container.


Type	`string`
Default	`undefined`

children

Custom loading content. When provided, replaces the default shimmer animation.


Type	`ReactNode`
Default	`undefined`

CometChatConversationStarter.Error

message

Custom error message text. Overrides the default localized error text.


Type	`string`
Default	`"Failed to load conversation starters."`

onRetry

Callback for the retry button. If not provided, uses the built-in retry() from context.


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

className

Custom CSS class appended to the error container.


Type	`string`
Default	`undefined`

children

Custom error content. When provided, replaces the default error message and retry button.


Type	`ReactNode`
Default	`undefined`

CometChatConversationStarter.Empty

message

Text to display when no suggestions are available. If not provided and no children, renders nothing.


Type	`string`
Default	`undefined`

className

Custom CSS class appended to the empty container.


Type	`string`
Default	`undefined`

children

Custom empty content. When provided, replaces the default empty message.


Type	`ReactNode`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-conversation-starter`
Suggestion pill	`.cometchat-conversation-starter__item`
Suggestion button	`.cometchat-conversation-starter__item-button`
Disabled item	`.cometchat-conversation-starter__item--disabled`
Shimmer container	`.cometchat-conversation-starter__shimmer-container`
Shimmer pill	`.cometchat-conversation-starter__shimmer-item`
Error view	`.cometchat-conversation-starter__error-view`
Retry button	`.cometchat-conversation-starter__error-retry`
Empty view	`.cometchat-conversation-starter__empty-view`

Documentation Index

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onSuggestionClick

​onRetry (Error sub-component)

​Custom View Slots

​Loading

​Error

​Empty

​Common Patterns

​Retry on error

​Using context in custom children

​CSS Architecture

​Key Selectors

​Example: Brand-themed conversation starters

​Customization Matrix

​Props

​CometChatConversationStarter.Root

​getConversationStarters

​onSuggestionClick

​className

​children

​CometChatConversationStarter.Item

​suggestion

​onClick

​disabled

​className

​CometChatConversationStarter.Loading

​count

​className

​children

​CometChatConversationStarter.Error

​message

​onRetry

​className

​children

​CometChatConversationStarter.Empty

​message

​className

​children

​CSS Selectors

Where It Fits

Minimal Render

Actions and Events

Callback Props

onSuggestionClick

onRetry (Error sub-component)

Custom View Slots

Loading

Error

Empty

Common Patterns

Retry on error

Using context in custom children

CSS Architecture

Key Selectors

Example: Brand-themed conversation starters

Customization Matrix

Props

CometChatConversationStarter.Root

getConversationStarters

onSuggestionClick

className

children

CometChatConversationStarter.Item

suggestion

onClick

disabled

className

CometChatConversationStarter.Loading

count

className

children

CometChatConversationStarter.Error

message

onRetry

className

children

CometChatConversationStarter.Empty

message

className

children

CSS Selectors