cometchat-ios-components— agent skill

Companion skills (read first)

• cometchat-ios-core owns install, credentials, init → login → render and the golden-path chat surface. This skill ADDS the per-component catalogue; it never restates core's setup. Fetch exact API via cometchat-ios-core/references/docs-map.md.

Use this skill when

Choosing a component, or customising one: "what shows the member list?", "put a badge on the conversation row", "swap the message bubble".

The catalogue (catalog-verified — nothing else exists)

There is NO composite component. CometChatMessages, CometChat{Users,Groups,Conversations}WithMessages, CometChatAddMembers, CometChatMessageHeaderOption are v4 or non-existent — never emit them. If a symbol is not in catalogs/ios-v5.json, it does not exist in v5, whatever a page says.

Three API shapes — get this right or nothing compiles

1. Setters return Self and are chainable: set(user:), set(onItemClick:), set(subtitle:).
2. Properties are assigned: list.avatarStyle = …, conversations.onSearchClick = { … }, groups.onSelectedItemProceed = { … }.
3. Named setters — setXxx(xxx:) with the label repeated: CometChatMessageInformation uses setSubtitle(subtitle:), setBubbleView(bubbleView:), setListItemView(listItemView:), setOnError(onError:). Writing them in shape-1 form (set(subtitle:)) does not compile on that component.

Which is which is per component, and the kit is not consistent — CometChatConversations has set(subtitleView:)/set(trailView:) while CometChatUsers and CometChatGroups have set(subtitle:)/set(trailingView:), and CometChatGroupMembers uses the Conversations spelling. Never generalise a name across components — fetch the component's `.md` twin.

Where custom UI goes — IN the component's slot, never beside it

Every list component exposes: set(listItemView:) (whole row) · set(leadingView:) · set(titleView:) · subtitle · trailing · set(options:) (swipe/overflow actions). Use these instead of building your own row above the list. Empty/error/loading are assignable views inherited from CometChatListBase: emptyStateView, errorStateView, loadingView, plus emptyStateTitleText / emptyStateSubTitleText to retitle the built-in one. CometChatSearch is the exception — it does NOT inherit CometChatListBase, so it has none of that chrome; it uses set(emptyView:) / set(errorView:) / set(loadingView:) instead.

Gotchas

• `set(controller:)` on any component that presents something (header, list, composer) or its built-in affordances render and do nothing.
• `CometChatAvatar` — use `setAvatar(avatarUrl:with:)`. `set(image:)` and `init(image:)` compile but render NOTHING. There is no set(user:). Measured on 5.1.19: an avatar given a UIImage through either set(image:) or init(image:) draws an empty circle — the image never appears, with no warning and no error, because the kit paints its own content over it. setAvatar(avatarUrl:with:) is the working path, and its with: name renders initials when no URL loads. There is also no no-arg init: CometChatAvatar() does not compile — construct with CometChatAvatar(image: nil) or CometChatAvatar(frame:) and then call setAvatar.
• Search slots are per result TYPE: set(listItemViewForMessage:) plus …ForImage/Video/Audio/Document/Link/Conversation. There are no *ForMessage granular (title/subtitle/leading/trailing) slots — those exist for conversations only, as properties.

Verify it works

The component renders at full size, its custom slot appears in the right place (inside the row, not above the list), and every rendered control does something when tapped.