@cometchat/cards-react-native

@cometchat/cards-react-native

A React Native renderer for the CometChat Card Schema. Pass in card JSON, get back a native view tree. Taps on interactive elements are emitted to your app through a single callback — the package never executes actions itself.

What it does

• Parses Card Schema JSON into typed models
• Renders 20 element types (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table)
• Resolves theme-aware colors and image URLs for auto, light, and dark modes, with optional theme overrides
• Emits taps on buttons, icon buttons, and links to your onAction callback as typed CometChatCardActionEvents

The package is a pure renderer. It doesn't talk to the CometChat SDK, doesn't manage message lifecycle, and doesn't know about your app's navigation. You decide what each action does.

Installation

npm install @cometchat/cards-react-native

Peer dependencies (must be in your project):

{
  "react": ">=18.0.0",
  "react-native": ">=0.76.0"
}

Usage

import { CometChatCardView } from '@cometchat/cards-react-native';

function CardScreen({ cardJson }: { cardJson: string }) {
  return (
    <CometChatCardView
      cardJson={cardJson}
      themeMode="auto"
      onAction={(event) => {
        // Handle the action — navigate, send a message, open a URL, etc.
        console.log(`action: ${event.action.type} from ${event.elementId}`);
      }}
    />
  );
}

Props

Prop	Type	Default	Description
cardJson	string	—	Card Schema JSON string (required)
themeMode	'auto' | 'light' | 'dark'	'auto'	Theme mode. auto follows the device system theme.
onAction	(event: CometChatCardActionEvent) => void	—	Callback fired when a user taps an interactive element with a valid action
onContainerStyle	(style: CometChatCardResolvedContainerStyle) => void	—	Emits the card's resolved container style (background, borderRadius, padding, etc.) for the consumer to apply to a parent wrapper
themeOverride	CometChatCardThemeOverride	—	Override default theme tokens (colors, typography)
logLevel	'none' | 'error' | 'warning' | 'verbose'	'warning'	Controls internal logging verbosity

Theming

The renderer falls back to a built-in default theme when JSON omits colors. To override defaults, pass a themeOverride:

<CometChatCardView
  cardJson={cardJson}
  themeMode="dark"
  themeOverride={{
    textColor: { light: '#141414', dark: '#F5F5F5' },
    buttonFilledBg: { light: '#1A73E8', dark: '#8AB4F8' },
  }}
/>

Any ColorValue in the schema is resolved to its light or dark variant based on the effective theme mode.

Actions

When a user taps a button, iconButton, or link, the package invokes onAction with a CometChatCardActionEvent containing:

• action — the full action object (type + all parameters)
• elementId — id of the tapped element
• cardJson — the card JSON the action originated from

Supported action types: openUrl, copyToClipboard, downloadFile, apiCall, chatWithUser, chatWithGroup, sendMessage, initiateCall, customCallback.

If you don't pass onAction, taps are ignored.

Container Style

The onContainerStyle callback emits the card's root container style with colors already resolved for the current theme mode:

const [bubbleStyle, setBubbleStyle] = useState({});

<View style={bubbleStyle}>
  <CometChatCardView
    cardJson={cardJson}
    themeMode="auto"
    onContainerStyle={(style) => setBubbleStyle({
      backgroundColor: style.background,   // already resolved hex string
      borderRadius: style.borderRadius,
      borderColor: style.borderColor,
    })}
  />
</View>

This is useful when embedding the card inside a message bubble — the bubble wrapper can match the card's visual settings.

Zero Dependencies

The package has no runtime dependencies beyond React and React Native. Image loading uses RN's built-in <Image>, animations use Animated, markdown is parsed with a custom built-in parser, and shimmer placeholders are rendered with native Views.

More

See the CardRendererDemo/ app for runnable samples and the design documents for the full schema reference.