cometchat · shreeyajoshi-cometchat · Sep 10, 2026 · Sep 10, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/docs.json b/docs.json
@@ -1533,7 +1533,6 @@
                             "pages": [
                               "ui-kit/ios/guide-overview",
                               "ui-kit/ios/guide-threaded-messages",
-                              "ui-kit/ios/guide-thread-subscription",
                               "ui-kit/ios/guide-pin-save-message",
                               "ui-kit/ios/guide-block-unblock-user",
                               "ui-kit/ios/guide-new-chat",
@@ -6961,6 +6960,10 @@
     }
   },
   "redirects": [
+    {
+      "source": "/ui-kit/ios/guide-thread-subscription",
+      "destination": "/ui-kit/ios/guide-threaded-messages#thread-subscription"
+    },
     {
       "source": "/sdk/flutter/group-kick-member",
       "destination": "/sdk/flutter/group-kick-ban-members"

diff --git a/images/ios-pin.png b/images/ios-pin.png
diff --git a/images/ios-save.png b/images/ios-save.png
@@ -18,7 +18,7 @@
 <Tabs>
 <Tab title="Swift">
 ```swift
 let compactComposer = CometChatCompactMessageComposer()
 compactComposer.set(user: user)
 compactComposer.set(controller: self)
 compactComposer.translatesAutoresizingMaskIntoConstraints = false
@@ -143,13 +143,13 @@
 <Tabs>
 <Tab title="Swift">
 ```swift
 var customStyle = CompactMessageComposerStyle()
 customStyle.activeSendButtonBackgroundColor = UIColor(hex: "#F76808")
 customStyle.attachmentImageTint = UIColor(hex: "#F76808")
 customStyle.voiceRecordingImageTint = UIColor(hex: "#F76808")
 customStyle.stickersImageTint = UIColor(hex: "#F76808")

 let compactComposer = CometChatCompactMessageComposer()
 compactComposer.style = customStyle
 ```
 </Tab>
@@ -340,10 +340,10 @@

 | Property | Description | Code |
 | -------- | ----------- | ---- |
 | backgroundColor | Background color of the toolbar. | `toolbarStyle.backgroundColor = CometChatTheme.backgroundColor02` |
 | borderColor | Border color of the toolbar. | `toolbarStyle.borderColor = CometChatTheme.borderColorLight` |
 | buttonSize | Size of format buttons. | `toolbarStyle.buttonSize = 30` |
 | buttonSpacing | Spacing between format buttons. | `toolbarStyle.buttonSpacing = CometChatSpacing.Spacing.s2` |
 | iconTintColor | Tint color for inactive format icons. | `toolbarStyle.iconTintColor = CometChatTheme.iconColorSecondary` |
 | activeIconTintColor | Tint color for active format icons. | `toolbarStyle.activeIconTintColor = CometChatTheme.primaryColor` |
 | buttonBackgroundColor | Background color for inactive buttons. | `toolbarStyle.buttonBackgroundColor = .clear` |
@@ -351,13 +351,158 @@
 
 ---
 
+### Trailing toolbar actions
+
+`set(richTextToolbarActions:)` appends your own buttons at the trailing end of the built-in toolbar — after the format buttons, separated by a divider — without replacing the toolbar. It takes the same closure shape as `set(attachmentOptions:)`, receiving the current `User?` and `Group?`, and returns a list of `CometChatRichTextToolbarAction` items.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `id` | `String` | Identifies the action, and looks the rendered button up in `CometChatRichTextToolbar.trailingActionButtons`. |
+| `icon` | `UIImage?` | The button glyph. Rendered as-is — apply `.withRenderingMode(.alwaysTemplate)` for `tint` or the toolbar's `iconTintColor` to take effect. |
+| `onClick` | `(CometChatComposerInput) -> Void` | Called on tap with a live handle onto the composer's input. |
+| `tint` | `UIColor?` | Overrides `RichTextToolbarStyle.iconTintColor` when non-nil. |
+| `accessibilityLabel` | `String?` | VoiceOver label. Falls back to `id`, so a button is never unlabelled. |
+
+Each action's `onClick` receives a **`CometChatComposerInput`** — a live handle for reading and mutating the draft, so the composer stays the owner of the field:
+
+| Member | Description |
+| ------ | ----------- |
+| `text: String` | The input's contents without attributes. |
+| `attributedText: NSAttributedString` | The contents, including formatting attributes. |
+| `selectedRange: NSRange` | The current selection, or a zero-length range at the caret. |
+| `hasSelection: Bool` | Whether text is selected, as opposed to a caret being placed. |
+| `typingAttributes: [NSAttributedString.Key: Any]` | Attributes the next typed character inherits — set this to format text typed next rather than a selection. |
+| `mentionRanges: [NSRange]` | The ranges currently occupied by mentions. |
+| `attributes(at:)` | The attributes at a location, or empty if out of bounds. |
+| `insertAtCaret(_:)` | Insert at the caret, replacing any selection; the caret lands after the inserted text. |
+| `setAttributedText(_:preservingSelection:)` | Replace the contents, keeping the selection by default. |
+| `setSelectedRange(_:)` | Move the caret or change the selection, clamped to the current length. |
+| `applyAttributes(_:to:protectingKitRuns:)` / `removeAttributes(_:from:protectingKitRuns:)` | Add or strip attributes over a range. |
+| `applyAttributesToSelection(_:protectingKitRuns:)` / `removeAttributesFromSelection(_:protectingKitRuns:)` | The same over the current selection; each returns whether there was a selection to act on. |
+| `commit()` | Resync the toolbar and send button partway through a long edit. |
+
+<Tabs>
+<Tab title="Swift">
+```swift
+compactComposer.set(richTextToolbarActions: { user, group in
+    [
+        CometChatRichTextToolbarAction(
+            id: "insert_greeting",
+            icon: UIImage(systemName: "hand.wave")?.withRenderingMode(.alwaysTemplate),
+            accessibilityLabel: "Greeting"
+        ) { input in
+            input.insertAtCaret(NSAttributedString(string: "Hello! "))
+        }
+    ]
+})
+```
+</Tab>
+</Tabs>
+
+Actions are registered per composer instance, so a thread composer can offer a different set from the main one.
+
+<Note>
+
+The trailing section lives **inside** the rich-text toolbar — it is not rendered when the toolbar is hidden (`showRichTextFormattingOptions = false`) or rich text is disabled (`enableRichTextFormatting = false`).
+
+The `CometChatComposerInput` is valid only for the duration of the `onClick` call; don't retain it. The action itself is retained by the toolbar, so capture `self` weakly.
+
+The composer serializes to markdown on send. The built-in formats survive. Every other attribute you apply is composer-local: markdown has no representation for it, so it is dropped from the sent message. Use attributes for affordances that are meant to be transient, such as marking a range while the action's own picker or sheet is open — and to send styling of your own, insert text your formatter understands. See [Sending styling of your own](#sending-styling-of-your-own).
+
+</Note>
+
+Mutations apply immediately, but composer state that derives from the text — the toolbar's active formats and the send button — resyncs once when `onClick` returns rather than per mutation, so a multi-step edit resyncs once. Call `commit()` to resync earlier.
+
+#### Leaving Kit-owned runs alone
+
+An action that restyles a range will happily run over a mention or a link, which the Kit repaints on its own schedule — so your attribute is reverted on the next repaint anyway, and removing one of the Kit's attributes deletes it rather than restoring the Kit's value.
+
+The mutating methods therefore take `protectingKitRuns`, which defaults to `true`. With it on, **mention ranges** are carved out of the target range and left untouched; the mutation is applied to the gaps between them.
+
+<Warning>
+
+`protectingKitRuns` protects mentions, and only mentions. Links, inline code, code blocks and every other run the Kit repaints are **yours to skip** — the Kit leaves that decision to you, as the Android and Compose Kits do.
+
+If your action restyles a range that spans a link or a code block, do the check yourself before mutating.
+
+</Warning>
+
+To make that decision, read `mentionRanges` for mentions and `attributes(at:)` for everything else — inspect the run's own attributes (`.link`, the monospaced font, and so on) and narrow your range accordingly. Ranges are read at call time, so re-read them after a mutation rather than caching, as they shift with the text.
+
+Pass `protectingKitRuns: false` to opt out and write over the whole range in one go.
+
+Two behaviours worth knowing before you write an action:
+
+- `applyAttributes` is **additive**. It adds your keys and leaves existing ones in place, so a colour applied over bold text keeps the bold.
+- `removeAttributes` **strips keys rather than resetting values**. The text falls back to the input's own styling, not to a value you choose. To reset to something specific, call `applyAttributes` with it.
+
+<Tabs>
+<Tab title="Swift">
+```swift
+CometChatRichTextToolbarAction(
+    id: "highlight",
+    icon: UIImage(systemName: "highlighter")?.withRenderingMode(.alwaysTemplate),
+    accessibilityLabel: "Highlight"
+) { input in
+    // Highlighting applies to a selection; with only a caret there is nothing
+    // to restyle, so leave the text alone rather than guessing at a range.
+    guard input.hasSelection else { return }
+
+    // Mentions are skipped by default. This is composer-local: it marks the
+    // range on screen and is dropped on send.
+    input.applyAttributesToSelection([
+        .backgroundColor: UIColor.systemYellow.withAlphaComponent(0.3)
+    ])
+}
+```
+</Tab>
+</Tabs>
+
+#### Sending styling of your own
+
+Attributes are composer-local, so styling that has to reach the recipient travels as **text**, not as an `NSAttributedString` attribute. Your action inserts a token the message carries, and a `CometChatTextFormatter` — see [setTextFormatters](#settextformatters) below, and the [Mentions formatter guide](/ui-kit/ios/mentions-formatter-guide) for a worked subclass — renders that token in the bubble. The token and its rendering are both yours — the Kit carries the characters and stays out of the way.
+
+The documented convention for text colour is `{color:#hex}…{/color}`:
+
+<Tabs>
+<Tab title="Swift">
+```swift
+CometChatRichTextToolbarAction(
+    id: "red_text",
+    icon: UIImage(systemName: "paintpalette")?.withRenderingMode(.alwaysTemplate),
+    accessibilityLabel: "Red text"
+) { input in
+    guard input.hasSelection else { return }
+
+    // Wrap the selection in a token your formatter understands. This is
+    // ordinary text, so it survives send.
+    input.replaceSelection("{color:#ff0000}\(input.selectedText){/color}")
+}
+```
+</Tab>
+</Tabs>
+
+`replaceSelection(_:)` degrades to an insertion when only a caret is placed, and leaves the caret after the inserted text.
+
+<Note>
+
+Pair the button with a formatter that renders the token, on **every** platform your users are on. Without one the recipient sees the literal `{color:#ff0000}…{/color}` braces in the message.
+
+Because the token is plain text, a user can also type it by hand, and it will render the same way. Choose a delimiter you are comfortable having interpreted anywhere it appears.
+
+</Note>
+
+The UI Kit ships no colour button of its own, and no colour parsing: the composer handle and the formatter API are provided, the token and its rendering are yours. That is what the trailing-actions slot is for.
+
+---
+
 ## Advanced
 
 For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

 ### setTextFormatters

 Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel check out [CometChatMentionsFormatter](/ui-kit/ios/mentions-formatter-guide)

 **Example**

@@ -373,7 +518,7 @@

 let customMentionFormatter = CometChatMentionsFormatter()
    .set(composerTextStyle: composerTextStyle)

 let compactComposer = CometChatCompactMessageComposer()
 compactComposer.set(textFormatter: [customMentionFormatter])
 ```
@@ -402,7 +547,7 @@

 <Tabs>
 <Tab title="Swift">
 ```swift
 let compactComposer = CometChatCompactMessageComposer()

 compactComposer.set(attachmentOptions: { user, group, controller in
@@ -455,7 +600,7 @@
 <Tabs>
 <Tab title="Swift">
 ```swift
 compactComposer.reply(message: baseMessage)
 ```
 </Tab>
 </Tabs>
@@ -465,9 +610,9 @@
 <Tabs>
 <Tab title="Swift">
 ```swift
 compactComposer.preview(message: baseMessage, mode: .edit)
 // or
 compactComposer.preview(message: baseMessage, mode: .reply)
 ```
 </Tab>
 </Tabs>

@@ -32,11 +32,11 @@
    "callbacks": {
      "onItemClick": "(Conversation, IndexPath) -> Void",
      "onItemLongClick": "(Conversation, IndexPath) -> Void",
      "onBack": "() -> Void",
      "onSelection": "([Conversation]) -> Void",
      "onError": "(CometChatException) -> Void",
      "onEmpty": "() -> Void",
      "onLoad": "([Conversation]) -> Void"
    },
    "visibility": {
      "hideSearch": { "type": "Bool", "default": false },
@@ -52,7 +52,7 @@
      "customSoundForMessages": { "type": "URL?", "default": "nil" }
    },
    "selection": {
      "selectionMode": { "type": "SelectionMode", "default": ".none" }
    },
    "viewSlots": {
      "listItemView": "(Conversation) -> UIView",
@@ -398,15 +398,67 @@
 
 ---
 
+## Pinning Conversations
+
+*Available since v5.1.22*
+
+A pinned conversation sits at the top of the list with a pin indicator on the row, and holds that position as new messages arrive in other chats. A personal pin is **private to the logged-in user** — nobody else sees it — and syncs to that user's other devices.
+
+<Warning>
+**Two gates, both required.** Pin Conversation needs the `features.ux.conversations.pinned.enabled` app setting mapped for your app, *and* your own opt-in via `enablePinConversation`. With either missing the swipe action never appears. The kit reads the app setting through `CometChat.isPinConversationEnabled()`.
+</Warning>
+
+```swift lines
+import CometChatUIKitSwift
+
+let conversations = CometChatConversations()
+conversations.enablePinConversation = true      // off by default
+```
+
+Pinning applies immediately; **unpinning asks for confirmation first**. Hide the action on a single list with [`hidePinConversationOption`](#hidepinconversationoption) while it stays available elsewhere.
+
+### Admin Pins
+
+An app can also pin a conversation **for everyone**. A system pin sorts above every personal pin, and is not the user's to remove — the kit does not offer the unpin affordance on those rows at all.
+
+To reflect the same distinction in a view of your own, read the two properties the SDK exposes on `Conversation`:
+
+```swift lines
+import CometChatSDK
+
+// `pinnedAt` uses a 0 sentinel, so presence — not `> 0` — is the pinned test.
+let isPinned = conversation.pinnedAt != 0
+
+// An admin/global pin. A user cannot unpin one, so hide or disable your unpin control.
+let isSystemPinned = isPinned && conversation.pinnedBy == "app_system"
+```
+
+<Note>
+The UI Kit has no public helper for this yet — unlike the React Native kit's `isSystemPinnedConversation()` — so the `"app_system"` sentinel has to be compared directly for now.
+</Note>
+
+### Errors
+
+A failed pin surfaces as a toast. `PinConversationErrorCodes` names the codes the backend emits, so you can match them in your own handling:
+
+| Code | Meaning |
+|---|---|
+| `ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED` | The user is at the per-user pinned cap. The real cap rides in `errorParams` — never hard-code it. |
+| `ERR_CONVERSATION_NOT_ACCESSIBLE` | No conversation row yet (never messaged), or deleted-for-me. |
+| `ERR_PERMISSION_DENIED` | RBAC denial. |
+| `ERR_BAD_REQUEST` | Invalid `pinnedBy` filter or malformed body. |
+
+---
+
 ## Custom View Slots
 
 | Slot | Signature | Replaces |
 |------|-----------|----------|
 | `listItemView` | `(Conversation) -> UIView` | Entire conversation row |
 | `leadingView` | `(Conversation) -> UIView` | Avatar / left section |
 | `titleView` | `(Conversation) -> UIView` | Name / title text |
 | `subtitleView` | `(Conversation) -> UIView` | Last message preview |
 | `trailView` | `(Conversation) -> UIView` | Right side (time, badge) |
 | `emptyStateView` | `UIView` | Empty state display — assign a view, not a closure |
 | `errorStateView` | `UIView` | Error state display — assign a view, not a closure |
 | `loadingView` | `UIView` | Loading state display — assign a view, not a closure |
@@ -740,7 +792,7 @@
 | List item look | Style | `listItemBackground` | `UIColor(white: 0.95, alpha: 1.0)` |
 | Unread badge | Style | `badgeStyle` | `BadgeStyle()` with custom colors |
 | Avatar appearance | Style | `avatarStyle` | `AvatarStyle()` with custom radius |
 | Hide search | Property | `hideSearch` | `conversations.hideSearch = true` |
 | Hide receipts | Property | `hideReceipts` | `conversations.hideReceipts = true` |
 | Custom row | View Slot | `set(listItemView:)` | See Custom View Slots section |

@@ -938,7 +990,7 @@

 #### set(textFormatters:)

 Sets custom text formatters for processing and displaying message text in conversation subtitles.

 ```swift lines
 @discardableResult
@@ -947,7 +999,7 @@

 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `textFormatters` | `[CometChatTextFormatter]` | Array of text formatters to apply to message text |

 ```swift lines
 import CometChatUIKitSwift
@@ -967,7 +1019,7 @@

 All props are optional. Sorted alphabetically.

 ### avatarStyle

 Customizes the appearance of avatars in conversation list items.

@@ -990,7 +1042,7 @@
 conversations.avatarStyle = avatarStyle
 ```

 ### badgeStyle

 Customizes the appearance of unread message count badges.

@@ -1022,7 +1074,7 @@
 | Type | `ConversationRequest.ConversationRequestBuilder?` |
 | Default | `nil` |

 ### dateStyle

 Customizes the appearance of date/time labels in conversation list items.

@@ -1083,7 +1135,7 @@
 | Type | `Bool` |
 | Default | `false` |

 ### disableTyping

 Disables typing indicators in the conversation list.

@@ -1099,6 +1151,24 @@
 conversations.disableTyping = true
 ```
 
+### enablePinConversation
+
+*Available since v5.1.22*
+
+Adds the **Pin / Unpin** swipe action to each row. Off by default — see [Pinning Conversations](#pinning-conversations) for the feature, including the app setting it also requires.
+
+| | |
+|---|---|
+| Type | `Bool` |
+| Default | `false` |
+
+```swift lines
+import CometChatUIKitSwift
+
+let conversations = CometChatConversations()
+conversations.enablePinConversation = true
+```
+
 ### hideBackButton
 
 Hides the back button in the navigation bar.
@@ -1135,7 +1205,25 @@
 | Type | `Bool` |
 | Default | `false` |
 
+### hidePinConversationOption
+
+*Available since v5.1.22*
+
+Hides the Pin / Unpin swipe action on one list while the feature stays on elsewhere. ANDed with `enablePinConversation` and the app setting — see [Pinning Conversations](#pinning-conversations).
+
+| | |
+|---|---|
+| Type | `Bool` |
+| Default | `false` |
+
+```swift lines
+import CometChatUIKitSwift
+
+let conversations = CometChatConversations()
+conversations.hidePinConversationOption = true
+```
+
 ### hideReceipts
 
 Hides read/delivered receipt indicators.

@@ -1214,7 +1302,7 @@
 conversations.protectedGroupIcon = UIImage(systemName: "lock.shield.fill")
 ```

 ### receiptStyle

 Customizes the appearance of message receipt indicators (sent, delivered, read).

@@ -1269,7 +1357,7 @@

 ### textFormatters

 Array of text formatters for customizing message text display.

 | | |
 |---|---|
@@ -1362,7 +1450,7 @@
 })
 ```

 ### Available Formatters

 | Formatter | Purpose | Default Format |
 |-----------|---------|----------------|