cometchat-react-native-customization
Theme, restyle and extend the CometChat React Native UI Kit v5 — theme modes and color tokens, per-component style objects, view slots, and the DataSource decorator chain for custom message types. Triggers: change CometChat colors React Native, dark mode RN chat, custom message bubble RN, brand the RN chat UI, custom message type React Native, restyle the message bubble, change the chat font, add a custom bubble RN.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- cometchat-react-native-customization
- license
- MIT
- metadata
- { "tags": "chat cometchat react-native customization theming styling datasource decorator", "author": "CometChat", "version": "1.0.0" }
- description
- Theme, restyle and extend the CometChat React Native UI Kit v5 — theme modes and color tokens, per-component style objects, view slots, and the DataSource decorator chain for custom message types. Triggers: change CometChat colors React Native, dark mode RN chat, custom message bubble RN, brand the RN chat UI, custom message type React Native, restyle the message bubble, change the chat font, add a custom bubble RN.
- compatibility
- React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0
02 资源文件 1
- 参考文档references/message-chrome.md4.4 KB
03 SKILL.md 正文
Ground truth:
@cometchat/chat-uikit-react-native@5+ catalogrn-v5.json. Docs:/ui-kit/react-native/theme·colors·component-styling·message-bubble-styling. Fetch token names and style keys from docs — never invent them.
Companion skills (read first)
cometchat-react-native-core— install, provider chain, init→login→render. Assumed, not repeated here.
Use this skill when
- "change the chat colors" · "brand the chat UI" · "dark mode" · "restyle the bubbles"
- "custom message type" · "render my own bubble" · "add an option to the message menu"
Cloning a named app, or mixing kit components with your own UI? Measure the target's colors, type, spacing and radii into ONE token source, theme the kit from it, and style every custom component from the same tokens so kit and custom parts look like one design; host a kit component in your own dialog/panel when only its placement differs. Flow: cometchat-onboarding → references/clone-mode.md (Design sync, build levels L0–L6).
Avatar + sender name on every message (own and others', 1:1 and group): the kit default shows them only on others' messages in groups. Fix it yourself whenever the target shows them: references/message-chrome.md (alignment="leftAligned", then per-message LeadingView / HeaderView via a decorator).
Prerequisites & install
None beyond core. Theming needs CometChatThemeProvider already in the chain (see core).
Customization mechanism — three layers, cheapest first
There is no CSS. No stylesheets, no className, no --cometchat-* variables. If you are
holding a React snippet with CSS custom properties, it does not apply here.
Layer 1 — theme mode + color tokens (whole app)
The provider takes a theme prop shaped { mode, light, dark }. mode is "light" · "dark" ·
"auto" — "auto" is what makes the kit follow the device (OS) light/dark setting (it reads
useColorScheme()); the provider default is already "auto".
// Fixed dark for the whole app.
<CometChatThemeProvider theme={{ mode: "dark" }}>{/* ... */}</CometChatThemeProvider>
// Follow the OS, branded in BOTH schemes. mode:"auto" is the switch;
// set BOTH light and dark or dark falls back to defaults.
<CometChatThemeProvider
theme={{
mode: "auto",
light: { color: { primary: "#F76808" } },
dark: { color: { primary: "#F8935B" } },
}}
>
{/* ... */}
</CometChatThemeProvider>
primary drives buttons, outgoing bubbles and active states — it is usually the only token a brand
change needs. Other common tokens: textPrimary, background1, neutral50, extendedPrimary500.
Fetch the full list from /ui-kit/react-native/colors.md rather than guessing a token name.
To follow the OS, use mode: "auto" and set both light and dark. Without the provider,
system theme changes are not reflected at all.
Layer 2 — per-component style objects
Every component takes a style prop holding named sub-style objects — plain RN style objects,
not CSS:
<CometChatConversations style={{ containerStyle: { backgroundColor: "#F7F7F7" } }} />
The same style keys can be set globally through the theme instead, which is preferable when the change should apply everywhere:
<CometChatThemeProvider theme={{ light: { conversationStyles: { /* ... */ } } }}>
Style-key names differ per component. Fetch them from that component's page
(/ui-kit/react-native/component-styling.md and the component's own page) — do not pattern-match
from another component.
Layer 3 — read the active theme in your own views
useTheme() returns the resolved theme (already light-or-dark per mode), so custom views match
the kit without re-deriving the palette:
import { useTheme } from "@cometchat/chat-uikit-react-native";
import { Text } from "react-native";
const Label = () => {
const theme = useTheme();
return <Text style={{ color: theme.color.textPrimary }}>Chats</Text>;
};
Custom message types — the DataSource decorator chain
⚠️ RN does NOT have the React plugin API. CometChatMessagePlugin and CometChatPluginRegistry
do not exist in this kit; emitting them will not compile. RN uses a decorator chain.
Extend DataSourceDecorator, override what you need, and register it with ChatConfigurator.enable:
import {
ChatConfigurator, DataSourceDecorator, CometChatMessageTemplate,
} from "@cometchat/chat-uikit-react-native";
const ORDER_TYPE = "order";
class OrderDataSource extends DataSourceDecorator {
// 0. IDENTITY — REQUIRED. The base DataSourceDecorator.getId() THROWS
// ("Method not implemented.") and ChatConfigurator.enable() calls getId() to
// dedupe the registry — so a subclass without this override crashes at
// ChatConfigurator.enable(...), NOT at render. Return a stable, unique id.
getId(): string {
return "order_message_datasource";
}
// 1. RENDER — how the bubble draws.
getAllMessageTemplates(theme?: any, params?: any): CometChatMessageTemplate[] {
const templates = super.getAllMessageTemplates(theme, params);
// append or replace a template here
return templates;
}
// 2. FETCH — WITHOUT THESE TWO THE MESSAGE IS NEVER RETRIEVED.
// CometChatMessageList builds its request from them:
// requestBuilder.setTypes(ChatConfigurator.dataSource.getAllMessageTypes())
// requestBuilder.setCategories(ChatConfigurator.dataSource.getAllMessageCategories())
// A type absent from those filters is excluded server-side. The bubble appears
// optimistically when sent, then vanishes on reload — with no error anywhere.
getAllMessageTypes(): string[] {
return [...super.getAllMessageTypes(), ORDER_TYPE];
}
getAllMessageCategories(): string[] {
const categories = super.getAllMessageCategories();
return categories.includes(CometChat.CATEGORY_CUSTOM)
? categories
: [...categories, CometChat.CATEGORY_CUSTOM];
}
}
// AFTER login(), not merely after init(). CometChatUIKit.login() calls enableExtensions(),
// whose first statement is ChatConfigurator.init() — "re-initialize data source". Anything
// registered earlier is DISCARDED, so a decorator wired at module scope, or straight after
// init(), silently disappears.
await CometChatUIKit.login({ uid: UID });
ChatConfigurator.enable((source) => new OrderDataSource(source));
getId() is REQUIRED on every DataSourceDecorator subclass. It is the ONE base method that
does not delegate to the wrapped source — the base throws Error("Method not implemented."), and
ChatConfigurator.enable() calls getId() to dedupe the registry. Omit it and registration crashes
at ChatConfigurator.enable(...) with Method not implemented. — NOT at render, so it reads as
unrelated. Every built-in decorator (Polls, Stickers, Translation, LinkPreview, Collaborative*)
overrides it; yours must too, returning a stable unique string.
A custom message type is two halves, and only one of them is obvious. Render is
getAllMessageTemplates / getMessageTemplate. Fetch is getAllMessageTypes /
getAllMessageCategories. Ship the render half alone and everything looks right until the first
reload, when every message of your type is gone — no error, no warning.
DataSourceDecorator exposes ~50 overridable methods; the ones you usually want are getId
(mandatory — see above), getAllMessageTemplates, getMessageTemplate, getAllMessageTypes,
getAllMessageCategories, getMessageOptions (the long-press menu) and
getAuxiliaryOptions (composer actions). Always call super.<method>(...) and modify the result —
replacing it wholesale drops every built-in message type.
DOCS GAP (RN-G10):
DataSourceDecorator/MessageDataSource/ExtensionsDataSourceandChatConfigurator.enableare not documented on any RN page — the docs show only mutating existing templates viagetAllMessageTemplates(). Built from the kit source; flag this to the developer rather than presenting it as documented.Partially closed (2026-08-20).
ui-kit/react-native/message-listnow documents the half that actually breaks builds: a custom type must be registered for fetch (getAllMessageTypes/getAllMessageCategories), not only for render, and the decorator must be registered afterlogin()becauseenableExtensions()re-runsChatConfigurator.init(). Still missing: a dedicated RN custom-message-types page coveringDataSourceDecorator/MessageDataSource/ExtensionsDataSourceend to end. Owner: docs.
Customizing an existing bubble without a decorator
To restyle rather than replace, prefer the theme's bubble style keys —
textBubbleStyles, imageBubbleStyles, fileBubbleStyles, pollBubbleStyles and siblings.
Fetch exact keys from /ui-kit/react-native/message-bubble-styling.md.
Common pitfalls
- Reaching for CSS — no stylesheets, no
className, no--cometchat-*. Theme object + RN styles. - Emitting the React plugin API — does not exist; use
ChatConfigurator+DataSourceDecorator. - Omitting
getId()on a decorator — the base throws;ChatConfigurator.enable()calls it → crash at registration withMethod not implemented. - Not calling
superin a decorator override — silently drops all built-in templates. - Setting only
lightwhen the app follows the OS — dark mode then falls back to defaults. - Guessing token or style-key names — fetch them; a wrong key fails silently rather than erroring.
Verify it works
- Every symbol appears in
catalogs/rn-v5.json. npm run verify:fences:rn-v5compiles the examples against the pinned kit.- On device: toggle OS dark mode and confirm the surface follows; confirm a custom template renders and built-in types still render alongside it.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.