Error Boundary

A reusable wrapper component that catches rendering errors from child components and displays a fallback UI instead of crashing the entire view.

The CometChatErrorBoundary component wraps child content and automatically catches rendering errors in the React component tree below it. When an error is caught, it displays a fallback UI with a retry button instead of crashing the entire view. It supports custom fallback views and emits structured error context for logging and analytics.

AI Integration Quick Reference

{
  "component": "CometChatErrorBoundary",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatErrorBoundary } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A reusable wrapper component that catches rendering errors from child components and displays a fallback UI instead of crashing the entire view.",
  "cssRootClass": ".cometchat-error-boundary",
  "primaryOutput": {
    "prop": "onError",
    "type": "(context: CometChatErrorContext) => void"
  },
  "props": {
    "data": {
      "componentName": { "type": "string", "default": "'Unknown'" }
    },
    "callbacks": {
      "onError": { "type": "(context: CometChatErrorContext) => void", "default": "undefined" }
    },
    "viewSlots": {
      "fallbackView": { "type": "(context: CometChatErrorContext, retry: () => void) => ReactNode", "default": "undefined" }
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {
    "CometChatErrorContext": {
      "error": "Error",
      "componentName": "string",
      "timestamp": "number"
    }
  }
}

Where It Fits

CometChatErrorBoundary is a base component that provides centralised error isolation across the UI Kit. Wrap it around any component that could potentially throw during rendering — message bubbles, conversation items, or entire feature sections. When a child throws, only the wrapped section shows the fallback UI while the rest of the application continues working.

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

function MessageList({ messages }) {
  return (
    <div>
      {messages.map((msg) => (
        <CometChatErrorBoundary.Root
          key={msg.getId()}
          componentName={`MessageBubble-${msg.getId()}`}
          onError={(ctx) => console.error("Bubble error:", ctx)}
        >
          <MessageBubble message={msg} />
        </CometChatErrorBoundary.Root>
      ))}
    </div>
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatErrorBoundary.Root>
      <MyComponent />
    </CometChatErrorBoundary.Root>
  );
}

Root CSS class: .cometchat-error-boundary

Common Patterns

Wrapping message bubbles

Wrap each message bubble individually so one broken bubble does not crash the entire message list.

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

function SafeMessageList({ messages }) {
  return (
    <div>
      {messages.map((msg) => (
        <CometChatErrorBoundary.Root
          key={msg.getId()}
          componentName={`Bubble-${msg.getId()}`}
        >
          <MessageBubble message={msg} />
        </CometChatErrorBoundary.Root>
      ))}
    </div>
  );
}

Custom fallback with error details

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

function App() {
  return (
    <CometChatErrorBoundary.Root
      componentName="Dashboard"
      fallbackView={(ctx, retry) => (
        <div style={{ padding: 20, textAlign: "center" }}>
          <p>Error in {ctx.componentName}: {ctx.error.message}</p>
          <button onClick={retry}>Try Again</button>
        </div>
      )}
    >
      <Dashboard />
    </CometChatErrorBoundary.Root>
  );
}

Error logging and analytics

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

function App() {
  const handleError = (ctx) => {
    analytics.track("ui_error", {
      component: ctx.componentName,
      message: ctx.error.message,
      timestamp: ctx.timestamp,
    });
  };

  return (
    <CometChatErrorBoundary.Root componentName="App" onError={handleError}>
      <MainContent />
    </CometChatErrorBoundary.Root>
  );
}

CSS Architecture

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

1. Global tokens set on the .cometchat root wrapper.
2. Component CSS (.cometchat-error-boundary) consumes these tokens via var().
3. Overrides target .cometchat-error-boundary descendant selectors.

Key Selectors

Target	Selector
Root wrapper	.cometchat-error-boundary
Fallback container	.cometchat-error-boundary__fallback
Error message	.cometchat-error-boundary__message
Retry button	.cometchat-error-boundary__retry

Example: Brand-themed error boundary

App.css

.cometchat-error-boundary__fallback {
  --cometchat-error-boundary-fallback-background: #fef2f2;
  --cometchat-error-boundary-message-color: #991b1b;
}

.cometchat-error-boundary__retry {
  --cometchat-error-boundary-retry-background: #dc2626;
  --cometchat-error-boundary-retry-background-hover: #b91c1c;
}

Customization Matrix

What to change	Where	Property/API	Example
Error callback	Component props	onError	onError={(ctx) => log(ctx)}
Custom fallback UI	Component props	fallbackView	fallbackView={(ctx, retry) => <Custom />}
Component name in context	Component props	componentName	componentName="MessageBubble"
Fallback background	Global CSS	.cometchat-error-boundary__fallback	--cometchat-error-boundary-fallback-background
Message text style	Global CSS	.cometchat-error-boundary__message	--cometchat-error-boundary-message-font
Retry button style	Global CSS	.cometchat-error-boundary__retry	--cometchat-error-boundary-retry-background

Props

All props are optional unless noted otherwise.

---

children

The child components to render, wrapped by the error boundary.

Type	ReactNode
Default	—

Required.

---

className

Optional custom CSS class name applied to the root wrapper element.

Type	string
Default	undefined

---

componentName

Name identifying the wrapped component. Included in the CometChatErrorContext when an error is caught, useful for logging and debugging.

Type	string
Default	'Unknown'

---

fallbackView

Custom fallback render function. When provided, overrides the default fallback UI. Receives the error context and a retry function.

Type	(context: CometChatErrorContext, retry: () => void) => ReactNode
Default	undefined

<CometChatErrorBoundary.Root
  fallbackView={(ctx, retry) => (
    <div>
      <p>{ctx.error.message}</p>
      <button onClick={retry}>Retry</button>
    </div>
  )}
>
  <MyComponent />
</CometChatErrorBoundary.Root>

---

onError

Callback invoked when an error is caught. Receives the structured CometChatErrorContext.

Type	(context: CometChatErrorContext) => void
Default	undefined

interface CometChatErrorContext {
  error: Error;           // The original error
  componentName: string;  // Name of the wrapped component
  timestamp: number;      // Epoch milliseconds when the error occurred
}

---

CSS Selectors

Target	Selector
Root wrapper	.cometchat-error-boundary
Fallback container	.cometchat-error-boundary__fallback
Error message text	.cometchat-error-boundary__message
Retry button	.cometchat-error-boundary__retry
Retry button (hover)	.cometchat-error-boundary__retry:hover
Retry button (focus)	.cometchat-error-boundary__retry:focus-visible