cometchat-native-placement-316925— agent skill

Purpose

Teaches Claude the five canonical placement patterns for putting chat inside a React Native app. Each pattern specifies:

1. Which CometChat components to compose
2. How to wire the placement into @react-navigation/* (or Expo Router)
3. Platform gotchas (safe-area, keyboard avoiding, gesture handling)
4. When to choose this placement over the alternatives

Ground truth: docs/ui-kit/react-native/react-native-conversation.mdx, react-native-one-to-one-chat.mdx, react-native-tab-based-chat.mdx, their expo-*.mdx equivalents, and the examples/SampleApp/ + examples/SampleAppExpo/ sample apps. Official docs: https://www.cometchat.com/docs/ui-kit/react-native/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP).

Read `cometchat-native-core` and `cometchat-native-components` before this skill — the provider wrapper chain and component catalog are prerequisites.

"What are you building?" — placement recommendation

Use this table to pick a placement. If the user says "add chat to my app" without specifying where, ask them what they're building.

Visual reference — five RN placement patterns

1. Stack screen (full page)

┌───────────────────────────────────┐
│ ← Hiking Group               ⋮    │  ← CometChatMessageHeader
├───────────────────────────────────┤
│                                   │
│                ╭──────────╮       │
│                │ Message  │       │
│                ╰──────────╯       │  ← CometChatMessageList
│                                   │
│  ╭──────────╮                     │
│  │ Reply    │                     │
│  ╰──────────╯                     │
│                                   │
├───────────────────────────────────┤
│ +  Type a message...          ▶   │  ← CometChatMessageComposer
└───────────────────────────────────┘

2. Bottom tab

┌───────────────────────────────────┐
│ ← Hiking Group               ⋮    │  ← header
├───────────────────────────────────┤
│                                   │
│           (messages)              │
│                                   │
├───────────────────────────────────┤
│  Chats  Users  Groups  Calls      │  ← bottom tab bar
└───────────────────────────────────┘

3. Modal (slide-up over current screen)

              ┌─────────────────┐
              │ ═══ Chat  ✕     │  ← drag handle + close
              ├─────────────────┤
              │                 │
              │   (messages)    │
              │                 │
              ├─────────────────┤
              │ Type message ▶  │
              └─────────────────┘
  (parent screen dimmed behind)

4. BottomSheet (swipe-up partial)

parent screen visible at top ─────
              ┌─────────────────┐
              │  ═══ (handle)   │
              │ Hiking Group    │
              ├─────────────────┤
              │   (messages)    │
              ├─────────────────┤
              │ Type message ▶  │
              └─────────────────┘

5. Embedded (inside an existing screen)

┌───────────────────────────────────┐
│ Product details                   │
│ [product image + specs]           │
├───────────────────────────────────┤
│ Contact seller                    │  ← section heading
│ ┌────────────────────────────┐    │
│ │ (CometChatMessageHeader)    │    │
│ │ (CometChatMessageList)      │    │  ← embedded chat
│ │ (CometChatMessageComposer)  │    │
│ └────────────────────────────┘    │
└───────────────────────────────────┘

1. Stack screen

The most common pattern — chat lives in its own screen, pushed via @react-navigation/native-stack.

Pattern A — Conversations list → Messages

Two screens: list + messages.

// ConversationsScreen.tsx
import { CometChatConversations, CometChatUiKitConstants } from "@cometchat/chat-uikit-react-native";
import type { NativeStackNavigationProp } from "@react-navigation/native-stack";

export function ConversationsScreen({ navigation }: { navigation: NativeStackNavigationProp<any> }) {
  return (
    <CometChatConversations
      onItemPress={(conversation) => {
        const type = conversation.getConversationType();
        if (type === CometChatUiKitConstants.ConversationTypeConstants.user) {
          navigation.navigate("Messages", { user: conversation.getConversationWith() });
        } else {
          navigation.navigate("Messages", { group: conversation.getConversationWith() });
        }
      }}
    />
  );
}

// MessagesScreen.tsx
import { Platform, View } from "react-native";
import {
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react-native";

export function MessagesScreen({ route, navigation }: any) {
  const { user, group } = route.params ?? {};
  return (
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader user={user} group={group} onBack={() => navigation.goBack()} showBackButton />
      <CometChatMessageList user={user} group={group} hideReplyInThreadOption />
      <CometChatMessageComposer
        user={user}
        group={group}
        keyboardAvoidingViewProps={Platform.OS === "android" ? {} : { behavior: "padding" }}
      />
    </View>
  );
}

// AppNavigator.tsx
import { NavigationContainer } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
const Stack = createNativeStackNavigator();

// The <Stack.Navigator> MUST be wrapped in <NavigationContainer> (react-navigation
// throws "Couldn't find a navigation object" at runtime without it). One container
// per app, at the root.
<NavigationContainer>
  <Stack.Navigator screenOptions={{ headerShown: false }}>
    <Stack.Screen name="Conversations" component={ConversationsScreen} />
    <Stack.Screen name="Messages" component={MessagesScreen} />
  </Stack.Navigator>
</NavigationContainer>

Pattern B — Single thread (no conversation list)

For support chat, marketplace "Contact seller", or any focused 1-to-1 where the target user/group is known in advance.

export function SupportChatScreen() {
  const [agent, setAgent] = useState<CometChat.User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    CometChat.getUser("support-agent-uid")
      .then((user) => {
        setAgent(user);
        setLoading(false);
      })
      .catch(() => setLoading(false));
  }, []);

  if (loading) return <ActivityIndicator style={{ flex: 1 }} />;
  if (!agent) return <Text style={{ padding: 16 }}>Support unavailable. Try again shortly.</Text>;

  return (
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader user={agent} />
      <CometChatMessageList user={agent} hideReplyInThreadOption />
      <CometChatMessageComposer user={agent} />
    </View>
  );
}

Navigation wiring notes

• The screen is wrapped in a <View style={{ flex: 1 }}> so the composer sits at the bottom and the list fills the middle.
• CometChatMessageHeader's onBack should call navigation.goBack(). Set showBackButton explicitly so the header knows to render it.
• Keyboard avoiding: do not wrap Header/List/Composer in an external KeyboardAvoidingView. The kit composer owns keyboard avoidance via its own keyboardAvoidingViewProps — pass keyboardAvoidingViewProps={Platform.OS === 'android' ? {} : { behavior: 'padding' }} on <CometChatMessageComposer> (this is what the kit sample app does). Android relies on the standard android:windowSoftInputMode="adjustResize" in the manifest, not the prop.

2. Bottom tab

For full-featured messengers with distinct entry points per content type.

// TabsNavigator.tsx
import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
import { createNativeStackNavigator } from "@react-navigation/native-stack";

const Tab = createBottomTabNavigator();
const Stack = createNativeStackNavigator();

function MainTabs() {
  return (
    <Tab.Navigator screenOptions={{ headerShown: false }}>
      <Tab.Screen name="Chats" component={ConversationsScreen} />
      <Tab.Screen name="Users" component={UsersScreen} />
      <Tab.Screen name="Groups" component={GroupsScreen} />
      <Tab.Screen name="Calls" component={CallLogsScreen} />
    </Tab.Navigator>
  );
}

export function AppNavigator() {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen name="Main" component={MainTabs} />
      <Stack.Screen name="Messages" component={MessagesScreen} />
    </Stack.Navigator>
  );
}

Each tab screen pushes to a shared Messages stack screen with the selected entity:

export function UsersScreen({ navigation }: any) {
  return (
    <CometChatUsers onItemPress={(user) => navigation.navigate("Messages", { user })} />
  );
}
export function GroupsScreen({ navigation }: any) {
  return (
    <CometChatGroups onItemPress={(group) => navigation.navigate("Messages", { group })} />
  );
}
export function CallLogsScreen() {
  return <CometChatCallLogs />;
}

Wiring notes

• Tabs use @react-navigation/bottom-tabs. The Messages screen is OUTSIDE the tab navigator (at the stack level) so it presents full-screen without the tab bar.
• For the Calls tab, CometChatCallLogs only works when @cometchat/calls-sdk-react-native is installed. Omit the Calls tab if the project doesn't use calling.

3. Modal

For occasional chat that doesn't belong in the primary navigation. Two approaches — native RN <Modal> or react-navigation's presentation: "modal".

Pattern A — React Navigation modal (recommended)

Cleaner — the modal is a regular stack screen with a modal presentation option.

<Stack.Navigator screenOptions={{ headerShown: false }}>
  <Stack.Screen name="Home" component={HomeScreen} />
  <Stack.Screen
    name="ChatModal"
    component={ChatModalScreen}
    options={{ presentation: "modal" }}
  />
</Stack.Navigator>

function ChatModalScreen({ navigation }: any) {
  const [agent, setAgent] = useState<CometChat.User | null>(null);
  useEffect(() => { CometChat.getUser("support-agent").then(setAgent); }, []);
  if (!agent) return null;
  return (
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader user={agent} onBack={() => navigation.goBack()} showBackButton />
      <CometChatMessageList user={agent} hideReplyInThreadOption />
      <CometChatMessageComposer user={agent} />
    </View>
  );
}

// Trigger from anywhere:
<Button title="Contact support" onPress={() => navigation.navigate("ChatModal")} />

iOS gets the native modal slide-up. Android shows a fade-in full-screen by default — if you need a swipe-to-dismiss feel, use the BottomSheet pattern instead.

Pattern B — RN <Modal> component

For lightweight one-off modals that don't need a separate route.

import { Modal, Pressable, View } from "react-native";

const [visible, setVisible] = useState(false);

<Modal visible={visible} animationType="slide" onRequestClose={() => setVisible(false)}>
  <SafeAreaView style={{ flex: 1 }}>
    <View style={{ flex: 1 }}>
      <CometChatMessageHeader user={agent} onBack={() => setVisible(false)} showBackButton />
      <CometChatMessageList user={agent} hideReplyInThreadOption />
      <CometChatMessageComposer user={agent} />
    </View>
  </SafeAreaView>
</Modal>

Works fine but bypasses navigation state — deep links and back-button handling need extra work.

4. BottomSheet

Native-feel swipe-up chat overlaid on a parent screen. Two library options; pick one based on the project's existing navigation:

Pattern A — @gorhom/bottom-sheet

import BottomSheet, { BottomSheetView } from "@gorhom/bottom-sheet";
import { useRef, useMemo } from "react";

function ProductScreen({ product }: any) {
  const sheetRef = useRef<BottomSheet>(null);
  const snapPoints = useMemo(() => ["25%", "90%"], []);
  const [agent, setAgent] = useState<CometChat.User | null>(null);

  useEffect(() => {
    CometChat.getUser(product.sellerUid).then(setAgent);
  }, [product.sellerUid]);

  return (
    <View style={{ flex: 1 }}>
      <ProductDetails product={product} />
      <Button title="Contact seller" onPress={() => sheetRef.current?.expand()} />

      <BottomSheet ref={sheetRef} snapPoints={snapPoints} index={-1} enablePanDownToClose>
        <BottomSheetView style={{ flex: 1 }}>
          {agent && (
            <>
              <CometChatMessageHeader user={agent} />
              <CometChatMessageList user={agent} hideReplyInThreadOption />
              <CometChatMessageComposer user={agent} />
            </>
          )}
        </BottomSheetView>
      </BottomSheet>
    </View>
  );
}

Pattern B — CometChatBottomSheet

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

const sheetRef = useRef<any>(null);

<CometChatBottomSheet ref={sheetRef}>
  <View style={{ flex: 1, height: "100%" }}>
    <CometChatMessageHeader user={agent} />
    <CometChatMessageList user={agent} hideReplyInThreadOption />
    <CometChatMessageComposer user={agent} />
  </View>
</CometChatBottomSheet>

<Button title="Chat" onPress={() => sheetRef.current?.show()} />

BottomSheet gotchas

• Snap points must be memoized: Always wrap snapPoints in useMemo(() => [...], []) (see Pattern A above). An inline array creates a new reference on every parent render, which forces @gorhom/bottom-sheet to re-measure layout and tears the open/close gesture animation. The example above does this correctly — do NOT "simplify" by inlining the array.
• Keyboard behavior: @gorhom/bottom-sheet has keyboardBehavior + keyboardBlurBehavior props. Without them the composer gets covered by the keyboard on iOS. Use keyboardBehavior="interactive" + keyboardBlurBehavior="restore".
• Gesture handler wrap: BottomSheet requires <GestureHandlerRootView style={{ flex: 1 }}> at the root (already required by the UI Kit — see cometchat-native-core § 3).
• Height: Pass flex: 1 + height: "100%" on the inner View so the message list expands to fill the sheet.

5. Embedded

Chat inside an existing screen, not its own route.

export function ProductDetailScreen({ product }: any) {
  const [agent, setAgent] = useState<CometChat.User | null>(null);
  useEffect(() => { CometChat.getUser(product.sellerUid).then(setAgent); }, [product.sellerUid]);

  return (
    <ScrollView style={{ flex: 1 }} keyboardShouldPersistTaps="handled">
      <ProductImages images={product.images} />
      <ProductSpecs product={product} />

      <View style={{ marginTop: 24 }}>
        <Text style={{ fontSize: 18, fontWeight: "600", padding: 16 }}>Chat with seller</Text>
        <View style={{ height: 480 }}>
          {agent && (
            <>
              <CometChatMessageHeader user={agent} />
              <CometChatMessageList user={agent} hideReplyInThreadOption />
              <CometChatMessageComposer user={agent} />
            </>
          )}
        </View>
      </View>
    </ScrollView>
  );
}

Embedded gotchas

• Fixed height required. CometChat components fill 100% of their parent. If you put them inside a ScrollView without a bounded height, the list collapses to zero height. Wrap in a <View style={{ height: NNN }}> or flex container with an explicit height.
• Scroll conflict. If the parent is a ScrollView, the message list's internal scroll competes with the parent's scroll. Consider the single-thread-as-stack-screen pattern instead if the chat is a primary UX.
• Composer focus. When the user taps the composer, the keyboard rises and can push the embedded chat off-screen on iOS. Set keyboardShouldPersistTaps="handled" on the parent ScrollView, and let the kit composer handle avoidance via keyboardAvoidingViewProps={Platform.OS === 'android' ? {} : { behavior: 'padding' }} — don't add your own root KeyboardAvoidingView.

Usually the embedded pattern is the wrong default — prefer a Modal or BottomSheet trigger from a button on the screen, which gives users a dedicated surface for chatting.

Hard rules

These apply to ALL placement patterns. Violating any of them causes integration bugs or destroys the existing navigation.

1. NEVER modify the project's existing navigator without reading it first. Understand what's there before adding screens or tabs. Don't replace a user's navigation structure unless they explicitly chose "demo mode."

1. ALWAYS use a separate screen / stack entry for chat, not inline replacement of an existing screen. The one exception is embedded placement (§ 5) where chat is explicitly part of a bigger screen.

1. The four-wrapper chain is required at the app root, not per-screen (see cometchat-native-core § 3). Re-wrapping per screen causes duplicate init + login, dropped WebSockets, and a 2–3-second flicker on first mount.

1. `import "react-native-gesture-handler"` must be at the very top of index.js (or Expo entry). Missing this import silently disables swipe gestures in the composer, bottom sheet, and attachment drawer.

1. Every `<CometChatMessageList>` MUST include `hideReplyInThreadOption` unless the integration also wires a full thread panel (CometChatThreadHeader + scoped list + scoped composer with parentMessageId). Drawer / modal / bottom sheet / embedded / stack-screen placements without a thread panel must include the flag — otherwise "Reply in Thread" shows in the message menu and silently does nothing.

1. Resolve user / group before rendering. The component props user and group expect CometChat.User and CometChat.Group instances — not bare UID strings. Fetch via CometChat.getUser(uid) / CometChat.getGroup(guid) in a useEffect and gate the render on the resolved object.

1. Pass either `user` or `group`, never both. Passing both causes runtime errors. Branch in render based on which one is set.

1. Every CometChat container must have explicit flex height. Components fill 100% of parent. If parent has no bounded height (flex: 1, height: N, or inside a flex layout with flex: N), components collapse to zero height and render empty. This is THE most common "why is my chat blank" bug.

1. For modals and bottom sheets, set `keyboardShouldPersistTaps="handled"` on any ScrollView / FlatList parent and configure keyboard behavior explicitly. Otherwise the composer gets hidden by the keyboard on iOS.

1. Never animate a CometChat-containing container with `transform` (including Tailwind's translate-x-* / translate-y-* / scale-* / rotate-* utilities if using NativeWind). transform creates a new containing block for position: "absolute" descendants, which reparents CometChat's absolute-positioned overlays (emoji picker, action sheet, reactions popover) and makes them misalign. In RN this is less common than web (RN has no position: fixed) but the same rule applies to any position: absolute pickers. Animate right / left / top / bottom offsets instead.

Skill routing reference