From 1f96a83f2c77cea1f10372c61fc41f504ae43247 Mon Sep 17 00:00:00 2001 From: Hritika Date: Fri, 20 Nov 2026 16:02:13 +0530 Subject: [PATCH] docs(ENG-41248): add RTL Support for the Android UI Kit New page ui-kit/android/rtl-support: layout direction vs language, android:supportsRtl, the global setting (UIKitSettingsBuilder / CometChatUIKit.setLayoutDirection) and the per-component setting (Compose layoutDirection, Views setCometChatLayoutDirection / app:cometchatLayoutDirection), which setting wins, base components, what mirrors and what doesn't, digits and dates, custom views and overlays, and upgrading notes. Also: a Layout Direction section and Functionality row on 18 component pages; Localize (setLocale is language-only, isRtl removed), Methods, Troubleshooting, View Slots and the llms index; kit "toast" wording changed to snackbar; nav entry after Localize. Matches uikit-android PR #984 @ a4b44a10c. Co-Authored-By: Claude Opus 5.5 --- docs.json | 1 + ui-kit/android/ai-assistant-chat-history.mdx | 30 ++ ui-kit/android/call-buttons.mdx | 30 ++ ui-kit/android/call-logs.mdx | 30 ++ ui-kit/android/conversations.mdx | 32 +- ui-kit/android/core-features.mdx | 2 +- ui-kit/android/customization-view-slots.mdx | 6 + ui-kit/android/group-members.mdx | 30 ++ ui-kit/android/groups.mdx | 30 ++ .../android/guide-pin-and-save-messages.mdx | 12 +- ui-kit/android/guide-threaded-messages.mdx | 4 +- ui-kit/android/incoming-call.mdx | 30 ++ ui-kit/android/llms-android-v6.mdx | 1 + ui-kit/android/localize.mdx | 8 +- ui-kit/android/message-composer.mdx | 30 ++ ui-kit/android/message-header.mdx | 30 ++ ui-kit/android/message-list.mdx | 36 ++- ui-kit/android/methods.mdx | 27 ++ ui-kit/android/notification-feed.mdx | 30 ++ ui-kit/android/ongoing-call.mdx | 30 ++ ui-kit/android/outgoing-call.mdx | 30 ++ ui-kit/android/pinned-messages.mdx | 29 ++ ui-kit/android/rtl-support.mdx | 293 ++++++++++++++++++ ui-kit/android/saved-messages.mdx | 31 +- ui-kit/android/search.mdx | 30 ++ ui-kit/android/threaded-messages-header.mdx | 32 +- ui-kit/android/troubleshooting.mdx | 14 + ui-kit/android/users.mdx | 30 ++ 28 files changed, 901 insertions(+), 17 deletions(-) create mode 100644 ui-kit/android/rtl-support.mdx diff --git a/docs.json b/docs.json index 58788a8cd..f84d2abc5 100644 --- a/docs.json +++ b/docs.json @@ -1753,6 +1753,7 @@ "ui-kit/android/component-styling", "ui-kit/android/message-bubble-styling", "ui-kit/android/localize", + "ui-kit/android/rtl-support", "ui-kit/android/sound-manager" ] }, diff --git a/ui-kit/android/ai-assistant-chat-history.mdx b/ui-kit/android/ai-assistant-chat-history.mdx index b35514831..0d5ee7e02 100644 --- a/ui-kit/android/ai-assistant-chat-history.mdx +++ b/ui-kit/android/ai-assistant-chat-history.mdx @@ -314,6 +314,7 @@ What you're changing: Small functional customizations such as setting the user a | `setUser` | Sets the user whose chat histories with the AI assistant need to be fetched. This is a required property for the component to function. The user's role must be `@agentic`. | `.setUser(user);` | | `setErrorStateVisibility` | Toggles the visibility of the error state of the component | `.setErrorStateVisibility(View.GONE);` | | `setEmptyStateVisibility` | Toggles the visibility of the empty state of the component | `.setEmptyStateVisibility(View.GONE);` | +| `setCometChatLayoutDirection` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | `.setCometChatLayoutDirection(CometChatLayoutDirection.RTL);` | - **Verify**: After calling `setUser(user)`, confirm the component fetches and displays the AI assistant chat histories for that user. After calling a visibility method, confirm the corresponding UI state is shown or hidden. @@ -339,6 +340,35 @@ What you're changing: Small functional customizations such as setting the user a | Error state visibility | Activity/Fragment | `setErrorStateVisibility(int)` | `.setErrorStateVisibility(View.GONE);` | | Empty state visibility | Activity/Fragment | `setEmptyStateVisibility(int)` | `.setEmptyStateVisibility(View.GONE);` | +## Layout Direction + +`CometChatAIAssistantChatHistory` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatAIAssistantChatHistory` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +chatHistory.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatAIAssistantChatHistory( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/call-buttons.mdx b/ui-kit/android/call-buttons.mdx index 9a26bcdcf..816664d4e 100644 --- a/ui-kit/android/call-buttons.mdx +++ b/ui-kit/android/call-buttons.mdx @@ -250,6 +250,7 @@ A second call is refused with `ACTIVE_CALL` while a Calls SDK session is prepare | `setOnError { }` | `onError = { }` | Error callback | | `setVoiceCallButtonVisibility(View.GONE)` | `hideVoiceCallButton = true` | Toggle voice call button | | `setVideoCallButtonVisibility(View.GONE)` | `hideVideoCallButton = true` | Toggle video call button | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -326,6 +327,35 @@ See [ViewModel & Data](/ui-kit/android/customization-viewmodel-data) for state o --- +## Layout Direction + +`CometChatCallButtons` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatCallButtons` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +callButtons.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatCallButtons( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/call-logs.mdx b/ui-kit/android/call-logs.mdx index 88ddb3f8b..22ddce532 100644 --- a/ui-kit/android/call-logs.mdx +++ b/ui-kit/android/call-logs.mdx @@ -393,6 +393,7 @@ CometChatCallLogs( | `setSeparatorVisibility(View.GONE)` | `hideSeparator = true` | Toggle list separators | | `setTitle("Call History")` | `title = "Call History"` | Custom toolbar title | | `setOnCallTypeIconClick { }` | `onCallIconClick = { }` | Override the call-back on the row's call icon | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | ### Call status @@ -912,6 +913,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatCallLogs` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatCallLogs` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +callLogs.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatCallLogs( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/conversations.mdx b/ui-kit/android/conversations.mdx index 502f2a689..034ce7718 100644 --- a/ui-kit/android/conversations.mdx +++ b/ui-kit/android/conversations.mdx @@ -432,7 +432,7 @@ The component listens to these SDK events internally. No manual setup needed. A pinned conversation sits at the top of the list and holds that position even as new messages arrive in other chats. The pin is **private to the logged-in user** — nobody else sees it — and it syncs to that user's other devices. -When the feature is enabled for your app, the long-press menu includes **Pin conversation** / **Unpin conversation** with no wiring needed: pinning applies immediately with a toast, unpinning asks for confirmation first, and a pinned row shows a pin indicator next to its timestamp. +When the feature is enabled for your app, the long-press menu includes **Pin conversation** / **Unpin conversation** with no wiring needed: pinning applies immediately with a snackbar, unpinning asks for confirmation first, and a pinned row shows a pin indicator next to its timestamp. **Pin Conversation must be enabled for your app** through the `features.ux.conversations.pinned.enabled` app setting in the CometChat Dashboard. Until it is, the option never renders, and a direct SDK call rejects with `ERR_FEATURE_NOT_ACCESSIBLE`. The UI Kit reads that setting itself at login and on every reconnect — there is no app code to write. Read it yourself with `CometChatUIKit.isPinConversationEnabled()` when you need to gate your own entry point. @@ -487,6 +487,7 @@ For pins made elsewhere, the Chat SDK exposes `CometChat.ConversationListener` w | `setTitle("Chats")` | `title = "Chats"` | Custom toolbar title | | `setSearchPlaceholderText("Search...")` | `searchPlaceholderText = "Search..."` | Search placeholder | | `setPinConversationOptionVisibility(View.GONE)` | `hidePinOption = true` | Hide the built-in Pin/Unpin conversation option | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -990,6 +991,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatConversations` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatConversations` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +conversations.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatConversations( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/core-features.mdx b/ui-kit/android/core-features.mdx index 7f50bf8a4..0d26a5f74 100644 --- a/ui-kit/android/core-features.mdx +++ b/ui-kit/android/core-features.mdx @@ -160,7 +160,7 @@ Each feature is switched on per app, and each carries its own cap: | `features.ux.messages.saved.enabled` | Whether the save options and screen render at all | | `features.ux.messages.saved.limit` | Saved messages per user | -The UI Kit reads the feature flags at login, so no wiring is needed to show or hide the options. When a user reaches a cap, the kit shows a toast naming the limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/android/guide-pin-and-save-messages). +The UI Kit reads the feature flags at login, so no wiring is needed to show or hide the options. When a user reaches a cap, the kit shows a snackbar naming the limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/android/guide-pin-and-save-messages). ## Pin Conversations diff --git a/ui-kit/android/customization-view-slots.mdx b/ui-kit/android/customization-view-slots.mdx index 0ae6b78ff..f7b9dccf0 100644 --- a/ui-kit/android/customization-view-slots.mdx +++ b/ui-kit/android/customization-view-slots.mdx @@ -260,6 +260,12 @@ The composer's trailing-toolbar slot additionally hands your view a live `Compos --- +## View Slots in RTL + +Views you pass into a slot are placed inside the component's layout direction. Use start/end values (`paddingStart`, `layout_marginEnd`, `Modifier.padding(start = …)`, `Alignment.Start`) so they mirror with the rest of the component in RTL. See [Custom Views in RTL](/ui-kit/android/rtl-support#custom-views-in-rtl). + +--- + ## Related - [Styles](/ui-kit/android/customization-styles) — Customize visual appearance without replacing views. diff --git a/ui-kit/android/group-members.mdx b/ui-kit/android/group-members.mdx index 3fff510e2..fabfca2b6 100644 --- a/ui-kit/android/group-members.mdx +++ b/ui-kit/android/group-members.mdx @@ -423,6 +423,7 @@ The component listens to these SDK events internally. No manual setup needed. | `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | | `setTitle("Members")` | `title = "Members"` | Custom toolbar title | | `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -976,6 +977,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatGroupMembers` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatGroupMembers` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +groupMembers.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatGroupMembers( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/groups.mdx b/ui-kit/android/groups.mdx index 7c29f21fd..2860383b2 100644 --- a/ui-kit/android/groups.mdx +++ b/ui-kit/android/groups.mdx @@ -412,6 +412,7 @@ The component listens to these SDK events internally. No manual setup needed. | `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | | `setTitle("My Groups")` | `title = "My Groups"` | Custom toolbar title | | `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -956,6 +957,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatGroups` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatGroups` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +groups.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatGroups( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/guide-pin-and-save-messages.mdx b/ui-kit/android/guide-pin-and-save-messages.mdx index 3bab31a1c..52d493e4e 100644 --- a/ui-kit/android/guide-pin-and-save-messages.mdx +++ b/ui-kit/android/guide-pin-and-save-messages.mdx @@ -14,7 +14,7 @@ Three related features help users keep track of what matters: | **Save Message** | All conversations | Only the acting user | Action-sheet option, bubble indicator, [Saved Messages](/ui-kit/android/saved-messages) screen | | **Pin Conversation** | Conversation list | Only the acting user | Long-press option + pin indicator in [Conversations](/ui-kit/android/conversations) | -The options, confirmation dialogs, toasts and indicators are built into the UI Kit components. The only integration work is wiring the two full-screen views into your navigation. +The options, confirmation dialogs, snackbars and indicators are built into the UI Kit components. The only integration work is wiring the two full-screen views into your navigation. ## Prerequisites @@ -31,9 +31,9 @@ CometChatUIKit.isPinConversationEnabled() With the features enabled, [CometChatMessageList](/ui-kit/android/message-list) automatically adds **Pin message / Unpin message** and **Save message / Unsave message** to the long-press action sheet for text and media messages. The labels toggle with the message's current state. -- **Pin** permission is enforced by the **server**, not by the UI Kit: the Pin/Unpin option is shown to every participant, and a user who lacks permission gets a "you don't have permission" toast (`ERR_PERMISSION_DENIED`) when they tap it. Everyone sees pinned indicators. Build custom pin UI the same way — show the action and handle the denial, rather than trying to predict the verdict client-side. +- **Pin** permission is enforced by the **server**, not by the UI Kit: the Pin/Unpin option is shown to every participant, and a user who lacks permission gets a "you don't have permission" snackbar (`ERR_PERMISSION_DENIED`) when they tap it. Everyone sees pinned indicators. Build custom pin UI the same way — show the action and handle the denial, rather than trying to predict the verdict client-side. - **Save** has no role gating — every user can save any message. -- **Pin** and **Save** apply immediately and show a toast (*Message pinned*, *Message saved*, …); **Unpin** and **Unsave** ask for confirmation first. If a pin or save limit is exceeded, the limit toast is generated from the server's response automatically. +- **Pin** and **Save** apply immediately and show a snackbar (*Message pinned*, *Message saved*, …); **Unpin** and **Unsave** ask for confirmation first. If a pin or save limit is exceeded, the limit snackbar is generated from the server's response automatically. - Pinned and saved messages show **indicators in the bubble footer** (a filled pin / bookmark before the timestamp), updating live for all bubble types. ## Step 1: Open Pinned Messages from the Chat Header @@ -157,11 +157,11 @@ Each feature is switched on per app, and each carries a cap on how many items a | `features.ux.conversations.pinned.enabled` | Whether the pin/unpin conversation option renders | | `features.ux.conversations.pinned.limit` | Pinned conversations per user (see [Conversations](/ui-kit/android/conversations#pinning-conversations)) | -When a user hits a cap, the UI Kit shows a toast explaining the limit — you don't need to handle the error yourself. +When a user hits a cap, the UI Kit shows a snackbar explaining the limit — you don't need to handle the error yourself. ### Error Codes -The built-in options turn these rejections into toasts. If you build custom pin or save UI on the SDK, handle them yourself: +The built-in options turn these rejections into snackbars. If you build custom pin or save UI on the SDK, handle them yourself: | Code | Meaning | | --- | --- | @@ -183,7 +183,7 @@ On the acting user's device, all surfaces stay in sync through the UI Kit event | Capability | Built-in | Your wiring | | --- | --- | --- | -| Action-sheet options, confirm dialogs, toasts | ✅ | — | +| Action-sheet options, confirm dialogs, snackbars | ✅ | — | | Bubble footer indicators | ✅ | — | | Pinned/Saved screens (list, unpin/unsave, empty states, live upkeep) | ✅ | Host + navigate | | Chat-header "Pinned messages" entry | ✅ (opt-in) | `setShowPinnedMessagesOption(true)` + click listener | diff --git a/ui-kit/android/guide-threaded-messages.mdx b/ui-kit/android/guide-threaded-messages.mdx index 85fccb27c..9ed7d5424 100644 --- a/ui-kit/android/guide-threaded-messages.mdx +++ b/ui-kit/android/guide-threaded-messages.mdx @@ -369,7 +369,7 @@ CometChatMessageList( ### The Thread Header Bell -[CometChatThreadHeader](/ui-kit/android/threaded-messages-header) renders a subscription bell as a trailing control on the reply-count bar. It flips optimistically on tap and reverts with a toast if the request fails. +[CometChatThreadHeader](/ui-kit/android/threaded-messages-header) renders a subscription bell as a trailing control on the reply-count bar. It flips optimistically on tap and reverts with a snackbar if the request fails. @@ -439,7 +439,7 @@ CometChat.subscribeToThread(parentMessage.id, object : CometChat.CallbackListene ### Subscription Behavior -- **Optimistic with revert** — both surfaces flip instantly on tap, keep one request in flight per thread, and revert with a toast if the server rejects the change. An offline tap fails visibly and reverts; nothing is queued. +- **Optimistic with revert** — both surfaces flip instantly on tap, keep one request in flight per thread, and revert with a snackbar if the server rejects the change. An offline tap fails visibly and reverts; nothing is queued. - **Auto-subscribe on reply** — sending a reply in a thread subscribes the user, and every surface flips to the subscribed state automatically. - **Unsubscribing is not sticky** — replying again, or being @-mentioned, re-subscribes the user. - **Unknown state renders as unsubscribed** — a message whose subscription state hasn't been learned yet (for example, one that just arrived in real time) shows the enabled subscribe control, never a spinner. diff --git a/ui-kit/android/incoming-call.mdx b/ui-kit/android/incoming-call.mdx index 0821e08c2..3dd9396ef 100644 --- a/ui-kit/android/incoming-call.mdx +++ b/ui-kit/android/incoming-call.mdx @@ -216,6 +216,7 @@ The component does not open itself on an incoming call. The Push SDK launches th | — | `onAcceptRequested = { proceed -> }` | Compose only: gate the answer (e.g. a permission prompt), then call `proceed()` | | `setDisableSoundForCalls(true)` | `disableSoundForCalls = true` | No effect when the Push SDK is present: the Push SDK plays the ringtone and the component stays silent to avoid two ringtones | | `setCustomSoundForCalls(R.raw.tone)` | `customSoundForCalls = R.raw.tone` | Only used without the Push SDK calls module | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -434,6 +435,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatIncomingCall` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatIncomingCall` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +incomingCall.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatIncomingCall( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/llms-android-v6.mdx b/ui-kit/android/llms-android-v6.mdx index db8d2aa8c..8900d0131 100644 --- a/ui-kit/android/llms-android-v6.mdx +++ b/ui-kit/android/llms-android-v6.mdx @@ -84,6 +84,7 @@ attributes, long-tail components, theming tokens, or feature enablement. - [Component Styling](/ui-kit/android/component-styling) - [Message Bubble Styling](/ui-kit/android/message-bubble-styling) - [Localization](/ui-kit/android/localize) +- [RTL Support](/ui-kit/android/rtl-support) - [Sound Manager](/ui-kit/android/sound-manager) ## Customization diff --git a/ui-kit/android/localize.mdx b/ui-kit/android/localize.mdx index acd27484c..8de5c472f 100644 --- a/ui-kit/android/localize.mdx +++ b/ui-kit/android/localize.mdx @@ -12,7 +12,8 @@ description: "Set the UI Kit language and override text labels to match your use | Get language | `CometChatLocalize.getLocale(context)` | | Supported languages | 19: ar, de, en, es, fr, hi, hu, it, ja, ko, lt, ms, nl, pl, pt, ru, sv, tr, zh | | Override labels | `res/values/strings.xml` — override UI Kit string resource keys | -| Related | [Theme Introduction](/ui-kit/android/theme-introduction) · [Sound Manager](/ui-kit/android/sound-manager) | +| Layout direction | Separate from the language. See [RTL Support](/ui-kit/android/rtl-support) | +| Related | [Theme Introduction](/ui-kit/android/theme-introduction) · [Sound Manager](/ui-kit/android/sound-manager) · [RTL Support](/ui-kit/android/rtl-support) | @@ -47,6 +48,10 @@ Set the CometChat UI Kit language and override UI text so your app matches your Call `CometChatLocalize.setLocale()` before rendering any UI Kit components. + +`setLocale` changes the UI Kit's language only, not its layout direction. To show Arabic right to left, set the app's language with `AppCompatDelegate.setApplicationLocales`, or set the UI Kit's direction. See [RTL Support](/ui-kit/android/rtl-support). + + @@ -168,6 +173,5 @@ CometChatMessageList( | `CometChatLocalize.setLocale(context, language)` | Sets the UI Kit language | | `CometChatLocalize.getLocale(context)` | Returns the current locale country code | | `CometChatLocalize.getLanguage(context)` | Returns the current locale language code | -| `CometChatLocalize.isRtl(context)` | Checks if the current locale is right-to-left | | `CometChatLocalize.resetToDefault()` | Resets locale to system default | | `CometChatLocalize.createLocalizedContext(context, language)` | Creates a context with a specific locale without affecting the app globally | diff --git a/ui-kit/android/message-composer.mdx b/ui-kit/android/message-composer.mdx index be79a7075..bdc4aff06 100644 --- a/ui-kit/android/message-composer.mdx +++ b/ui-kit/android/message-composer.mdx @@ -172,6 +172,7 @@ The MessageComposer does not attach SDK listeners directly. Typing indicators ar | `setTextFormatters(list)` | `textFormatters = list` | Custom text formatters (mentions, etc.) | | `setEnableRichTextFormatting(true)` | `enableRichTextFormatting = true` | Enable rich text formatting | | `setEnableMultipleAttachments(true)` | `enableMultipleAttachments = true` | Multi-select attachment picking with a preview tray (default `true`); `false` reverts to legacy single-attachment, send-immediately behavior. See [Multiple Attachments](#multiple-attachments) | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -602,6 +603,35 @@ See [ViewModel & Data](/ui-kit/android/customization-viewmodel-data) for state o --- +## Layout Direction + +`CometChatMessageComposer` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatMessageComposer` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +messageComposer.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatMessageComposer( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/message-header.mdx b/ui-kit/android/message-header.mdx index a54fe4aa2..972e1babf 100644 --- a/ui-kit/android/message-header.mdx +++ b/ui-kit/android/message-header.mdx @@ -203,6 +203,7 @@ The component listens to these SDK events internally. No manual setup needed. | `setOnBackPress { }` | `onBackPress = { }` | Back button callback | | `setShowPinnedMessagesOption(true)` | — | Show the built-in "Pinned messages" menu item (Views only; requires the Pin Message feature) | | `setOnPinnedMessagesClickListener { }` | — | Callback for the "Pinned messages" menu item | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -473,6 +474,35 @@ See [ViewModel & Data](/ui-kit/android/customization-viewmodel-data) for state o --- +## Layout Direction + +`CometChatMessageHeader` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatMessageHeader` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +messageHeader.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatMessageHeader( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/message-list.mdx b/ui-kit/android/message-list.mdx index 850bc3e3c..88e2c2876 100644 --- a/ui-kit/android/message-list.mdx +++ b/ui-kit/android/message-list.mdx @@ -280,6 +280,7 @@ The component listens to SDK message events internally. No manual setup needed. | `setOnThreadRepliesClick { }` | `onThreadRepliesClick = { }` | Thread reply tap callback | | `setThreaded(true)` | `threaded = true` | Mark the list as a thread view: a missing or invalid parent message shows the empty state instead of the whole conversation. A valid `setParentMessageId` / `setParentMessage` marks it threaded automatically (from v6.1.1) | | `setEnableMultipleAttachments(true)` | `enableMultipleAttachments = true` | Render multi-attachment messages with per-type bubbles and batch grouping (default `true`). See [Multiple Attachments](#multiple-attachments) | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -861,11 +862,11 @@ In Compose, hide the thread subscription option with `hideThreadSubscriptionOpti Three groups of options appear automatically when their feature is enabled for the app — no wiring needed: -- **Pin message / Unpin message** — shown on text and media messages when `CometChatUIKit.isPinMessageEnabled()`. The option is shown to **every** participant: permission is enforced by the server, and a user who lacks it gets a "you don't have permission" toast (`ERR_PERMISSION_DENIED`) rather than a hidden option. Pinning applies immediately with a toast; unpinning asks for confirmation first. Pinned messages get a pin indicator in the bubble footer. -- **Save message / Unsave message** — shown on text and media messages when `CometChatUIKit.isSaveMessageEnabled()`, for every user. Saving applies immediately with a toast; unsaving asks for confirmation first. Saved messages get a bookmark indicator in the bubble footer. +- **Pin message / Unpin message** — shown on text and media messages when `CometChatUIKit.isPinMessageEnabled()`. The option is shown to **every** participant: permission is enforced by the server, and a user who lacks it gets a "you don't have permission" snackbar (`ERR_PERMISSION_DENIED`) rather than a hidden option. Pinning applies immediately with a snackbar; unpinning asks for confirmation first. Pinned messages get a pin indicator in the bubble footer. +- **Save message / Unsave message** — shown on text and media messages when `CometChatUIKit.isSaveMessageEnabled()`, for every user. Saving applies immediately with a snackbar; unsaving asks for confirmation first. Saved messages get a bookmark indicator in the bubble footer. - **Subscribe to thread / Unsubscribe from thread** — shown on regular messages (not agent or moderation-blocked ones) from **v6.1.0**, where thread subscription is on by default; on **v6.0.x** it appears only after `UIKitSettings.setEnableThreadSubscription(true)`. On a thread reply the action targets the thread's root message. Hide it with `setThreadSubscriptionOptionVisibility(View.GONE)`. -Pin and Save are withheld on messages where the action is meaningless or would fail — deleted messages, messages that have not finished sending, and messages held or rejected by moderation. The labels toggle with the message's current state, and if a pin/save limit is exceeded the limit toast is generated from the server response automatically. See the [Pin & Save Messages](/ui-kit/android/guide-pin-and-save-messages) guide and [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription). +Pin and Save are withheld on messages where the action is meaningless or would fail — deleted messages, messages that have not finished sending, and messages held or rejected by moderation. The labels toggle with the message's current state, and if a pin/save limit is exceeded the limit snackbar is generated from the server response automatically. See the [Pin & Save Messages](/ui-kit/android/guide-pin-and-save-messages) guide and [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription). ### Replacing All Options (`setOptions`) @@ -1105,6 +1106,35 @@ See [ViewModel & Data](/ui-kit/android/customization-viewmodel-data) for state o --- +## Layout Direction + +`CometChatMessageList` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatMessageList` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +messageList.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatMessageList( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/methods.mdx b/ui-kit/android/methods.mdx index 67a6bc879..7466dcd59 100644 --- a/ui-kit/android/methods.mdx +++ b/ui-kit/android/methods.mdx @@ -76,6 +76,7 @@ The `UIKitSettings` is an important parameter of the `init()` function. It serve | **dateTimeFormatterCallback** | `DateTimeFormatterCallback` | Interface containing callback methods to format different types of timestamps. | | **setEnableCalling** | `Boolean` | Turns on calling: the UI Kit initialises the Calls SDK during `init()` and logs the user into it during `login()`. Default `false`. See [Calling Integration](/ui-kit/android/calling-integration) | | **setCallSettingsBuilder** | `Any` (a `CometChatCalls.SessionSettingsBuilder`) | Default session settings for the call screens. Typed `Any` so the UI Kit compiles without the Calls SDK, which your app adds | +| **setLayoutDirection** | `CometChatLayoutDirection` | Layout direction for every UI Kit component: `AUTO` (default, follows the app's direction), `LTR` or `RTL`. See [RTL Support](/ui-kit/android/rtl-support) | | **setEnableThreadSubscription** | `Boolean` | *Deprecated in v6.1.0.* Global switch for the thread subscription feature. Default `true` from v6.1.0 (`false` on v6.0.x, where it is the opt-in). Kept as the only app-wide opt-out — pass `false` to turn the feature off everywhere. To hide a single surface, prefer the per-screen visibility methods. See [Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription) | **Usage:** @@ -317,6 +318,32 @@ CometChatUIKit.init(context, uiKitSettings, object : CometChat.CallbackListener< --- +### Layout Direction + +Set the layout direction for every UI Kit component with `setLayoutDirection` at init, and change it later with `CometChatUIKit.setLayoutDirection`. A component's own setting overrides it. See [RTL Support](/ui-kit/android/rtl-support). + +| Method | Description | +| --- | --- | +| `UIKitSettings.UIKitSettingsBuilder().setLayoutDirection(direction)` | Direction at init: `CometChatLayoutDirection.AUTO` (default), `LTR` or `RTL` | +| `CometChatUIKit.setLayoutDirection(direction)` | Changes the direction at runtime. Applies to components created afterwards, so recreate open screens | +| `CometChatUIKit.getLayoutDirection()` | The current global direction | + +```kotlin +import com.cometchat.uikit.core.CometChatLayoutDirection + +val uiKitSettings = UIKitSettings.UIKitSettingsBuilder() + .setRegion(your_region) + .setAppId(your_appID) + .setAuthKey(your_authKey) + .setLayoutDirection(CometChatLayoutDirection.RTL) + .build() + +// Later, for example from a settings screen: +CometChatUIKit.setLayoutDirection(CometChatLayoutDirection.LTR) +``` + +--- + ### Base Message #### Text Message diff --git a/ui-kit/android/notification-feed.mdx b/ui-kit/android/notification-feed.mdx index 93c4343cd..11f083c9d 100644 --- a/ui-kit/android/notification-feed.mdx +++ b/ui-kit/android/notification-feed.mdx @@ -252,6 +252,7 @@ The component handles these automatically — no manual setup needed: | `setShowFilterChips(true)` | `showFilterChips = true` | Toggle category filter chips | | `setFeedRequestBuilder(...)` | `feedRequestBuilder = ...` | Custom feed request | | `setCategoriesRequestBuilder(...)` | `categoriesRequestBuilder = ...` | Custom categories request | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -460,6 +461,35 @@ CometChatNotificationFeed( --- +## Layout Direction + +`CometChatNotificationFeed` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatNotificationFeed` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +notificationFeed.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatNotificationFeed( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/ongoing-call.mdx b/ui-kit/android/ongoing-call.mdx index e91a4963f..f108afb9b 100644 --- a/ui-kit/android/ongoing-call.mdx +++ b/ui-kit/android/ongoing-call.mdx @@ -254,6 +254,7 @@ CometChatOngoingCall( | `setOnError { }` | `onError` | Error callback | | `setStyle(style)` | `style` | Container styling | | `getViewModel()` | `viewModel` | Access to state and events | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -320,6 +321,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatOngoingCall` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatOngoingCall` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +ongoingCall.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatOngoingCall( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/outgoing-call.mdx b/ui-kit/android/outgoing-call.mdx index cd9ef3cef..b8f5fc3f4 100644 --- a/ui-kit/android/outgoing-call.mdx +++ b/ui-kit/android/outgoing-call.mdx @@ -207,6 +207,7 @@ The Chat SDK's `CallListener` is superseded and not used. | `setDisableSoundForCalls(true)` | `disableSoundForCalls = true` | Disable the outgoing ringback tone | | `setCustomSoundForCalls(R.raw.tone)` | `customSoundForCalls = R.raw.tone` | Custom ringback tone | | `getViewModel()` | `viewModel` | Access to the state flows below | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | ### ViewModel (`CometChatOutgoingCallViewModel`) @@ -415,6 +416,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatOutgoingCall` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatOutgoingCall` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +outgoingCall.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatOutgoingCall( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/pinned-messages.mdx b/ui-kit/android/pinned-messages.mdx index 47e63f85e..9363443c8 100644 --- a/ui-kit/android/pinned-messages.mdx +++ b/ui-kit/android/pinned-messages.mdx @@ -148,6 +148,35 @@ The list keeps itself up to date — when the logged-in user pins or unpins a me The screen is backed by `CometChatPinnedMessagesViewModel` (in the shared core module), which fetches via `MessagesRequestBuilder().setPinned(true)` scoped to the set user or group, applies optimistic unpin with revert-on-error, and observes the event bus for live upkeep. In Compose you can inject your own instance through the `viewModel` parameter. +## Layout Direction + +`CometChatPinnedMessages` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatPinnedMessages` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +pinnedMessages.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatPinnedMessages( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps - [Message List](/ui-kit/android/message-list) — where messages are pinned and unpinned, and where the bubble pin indicator appears. diff --git a/ui-kit/android/rtl-support.mdx b/ui-kit/android/rtl-support.mdx new file mode 100644 index 000000000..ad32f96ea --- /dev/null +++ b/ui-kit/android/rtl-support.mdx @@ -0,0 +1,293 @@ +--- +title: "RTL Support" +description: "Show CometChat Android UI Kit components right to left for Arabic and other RTL languages, globally or per component, with layoutDirection." +--- + + + +| Field | Value | +| --- | --- | +| Modules | `chatuikit-core` (setting), `chatuikit-kotlin` (XML Views), `chatuikit-compose` (Jetpack Compose) | +| Import | `com.cometchat.uikit.core.CometChatLayoutDirection` | +| Global setting | `UIKitSettings.UIKitSettingsBuilder().setLayoutDirection(...)` at init, `CometChatUIKit.setLayoutDirection(...)` at runtime | +| Per component | Compose: `layoutDirection` parameter · Views: `setCometChatLayoutDirection(...)` or XML `app:cometchatLayoutDirection` | +| Values | `CometChatLayoutDirection.AUTO` (default) · `LTR` · `RTL` | +| Default behavior | `AUTO` follows the app's own direction, so an app in Arabic is RTL with no extra code | +| Manifest | `android:supportsRtl="true"` on `` | +| Related | [Localize](/ui-kit/android/localize) · [Methods](/ui-kit/android/methods) · [Customization Overview](/ui-kit/android/customization-overview) | + + + +## Overview + +Languages such as Arabic are read right to left. In an RTL layout, the UI Kit mirrors every component: avatars, names, buttons, message bubbles, menus and sheets swap sides, and arrows point the other way. + +Mirroring the layout doesn't flip the content. The UI Kit keeps every piece of content readable: + +* Each message reads in its own direction, so an English message in an Arabic chat still reads left to right. +* Names inside sentences the UI Kit writes keep their order. +* Audio and video players and code blocks stay left to right. + +## Layout Direction and Language + +Layout direction and language are two separate settings: + +| Setting | Decides | Set with | +| --- | --- | --- | +| Layout direction | Which side things sit on | `layoutDirection` (this page) | +| Language | Which strings are shown | The app's locale, or `CometChatLocalize.setLocale` (see [Localize](/ui-kit/android/localize)) | + +With the default, `AUTO`, the UI Kit takes the direction Android gives your app, and Android makes an app RTL when its language is RTL. `CometChatLocalize.setLocale` changes the UI Kit's language only, never its direction. + +## Before You Start + +Declare RTL support in your app's manifest: + +```xml AndroidManifest.xml + +``` + +Without it, Android lays every `View` out left to right. The Kotlin (XML Views) UI Kit can't mirror at all, and the Jetpack Compose UI Kit can't follow an Arabic app under `AUTO`. The UI Kit doesn't add the flag for you, because it would also mirror your app's own screens. + +## Turn On RTL + +### Follow the app's language (default) + +With `AUTO`, the UI Kit uses the direction the app is already in. Set the app's language with the platform API, and Android makes the whole app RTL, UI Kit included: + + + +```kotlin +import androidx.appcompat.app.AppCompatDelegate +import androidx.core.os.LocaleListCompat + +AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags("ar")) +``` + + + +A phone set to Arabic has the same effect. See [Localize](/ui-kit/android/localize) for the UI Kit's strings. + +### Set it for the whole UI Kit + +Pass `setLayoutDirection` to `UIKitSettings` to give every UI Kit component a fixed direction, whatever the language: + + + +```kotlin +import com.cometchat.uikit.core.CometChatLayoutDirection +import com.cometchat.uikit.core.CometChatUIKit +import com.cometchat.uikit.core.UIKitSettings + +val uiKitSettings = UIKitSettings.UIKitSettingsBuilder() + .setRegion(your_region) + .setAppId(your_appID) + .setAuthKey(your_authKey) + .setLayoutDirection(CometChatLayoutDirection.RTL) + .build() + +CometChatUIKit.init(context, uiKitSettings, callbackListener) +``` + + + +| Value | Result | +| --- | --- | +| `CometChatLayoutDirection.AUTO` | Follows the app's direction. This is the default, so apps that don't set it see no change. | +| `CometChatLayoutDirection.LTR` | Every UI Kit component is left to right. | +| `CometChatLayoutDirection.RTL` | Every UI Kit component is right to left. | + +### Change it at runtime + +Use `CometChatUIKit.setLayoutDirection` to change the direction while the app is running, for example from a settings screen. Read the current value with `CometChatUIKit.getLayoutDirection()`. + + + +```kotlin +CometChatUIKit.setLayoutDirection(CometChatLayoutDirection.RTL) +activity.recreate() // components on screen keep the direction they started with + +val current = CometChatUIKit.getLayoutDirection() // CometChatLayoutDirection.RTL +``` + + + + +Each component reads the global direction when it is created. A screen that is already open keeps its direction until it is recreated. Calling `init()` again keeps the runtime value unless its `UIKitSettings` sets `setLayoutDirection` itself. + + +## Set It Per Component + +Every main UI Kit component takes its own direction. It overrides the global setting for that component and everything inside it. + + + +```xml + +``` + +```kotlin +// or in code +messageList.setCometChatLayoutDirection(CometChatLayoutDirection.LTR) +``` + + +```kotlin +// The whole kit is RTL, but this list stays LTR. +CometChatMessageList( + user = user, + layoutDirection = CometChatLayoutDirection.LTR +) +``` + + + +Leave it unset, or pass `AUTO`, to inherit the direction from the UI Kit component around it, or from the global setting. In Compose, pass `layoutDirection` by name. + +These components take a direction of their own: + +| Chat | Messages | Calls and more | +| --- | --- | --- | +| [Conversations](/ui-kit/android/conversations) | [Message Header](/ui-kit/android/message-header) | [Call Buttons](/ui-kit/android/call-buttons) | +| [Users](/ui-kit/android/users) | [Message List](/ui-kit/android/message-list) | [Call Logs](/ui-kit/android/call-logs) | +| [Groups](/ui-kit/android/groups) | [Message Composer](/ui-kit/android/message-composer) | [Incoming Call](/ui-kit/android/incoming-call) | +| [Group Members](/ui-kit/android/group-members) | [Threaded Messages Header](/ui-kit/android/threaded-messages-header) | [Outgoing Call](/ui-kit/android/outgoing-call) | +| [Search](/ui-kit/android/search) | [Pinned Messages](/ui-kit/android/pinned-messages) | [Ongoing Call](/ui-kit/android/ongoing-call) | +| [Notification Feed](/ui-kit/android/notification-feed) | [Saved Messages](/ui-kit/android/saved-messages) | [AI Assistant Chat History](/ui-kit/android/ai-assistant-chat-history) | + +Message bubbles, the reaction list, the create-poll and message-information screens, the sticker keyboard, the media recorder and the AI views take one too. + +### Base components + +Base components (avatar, badge, date, receipts, status indicator, search box, toolbar, list items, popup menus) have no direction setting. Inside a UI Kit component they follow it. Used on their own, they follow the global setting, and under `AUTO` the app. + +## Which Setting Wins + +When settings disagree, the first rule that gives a direction wins: + +1. Audio and video players are always left to right. +2. The component's own direction, when it is `LTR` or `RTL`. +3. The nearest UI Kit component around it that has its own direction. +4. The global setting, when it is `LTR` or `RTL`. +5. The app's own direction. + +Use the UI Kit's setting to change a component's direction. With a global `LTR` or `RTL`, setting `android:layoutDirection` on a parent view or providing `LocalLayoutDirection` around a component doesn't change it, because each component applies the global setting at its root. + +| I want | Global | Component | Language | +| --- | --- | --- | --- | +| My app is already Arabic and RTL | leave `AUTO` | nothing | the app's | +| An English app with the chat in Arabic and RTL | `RTL` | nothing | `CometChatLocalize.setLocale(context, Language.ARABIC)` | +| Everything RTL except one component | `RTL` | `LTR` on that one | any | +| An RTL app with one component LTR | leave `AUTO` | `LTR` on that one | any | +| Only the chat screen RTL in an LTR app | leave `AUTO` | `RTL` on the screen's components | optional | + +## What the UI Kit Does for You + +* **Overlays follow the component that opens them.** Menus, dialogs, bottom sheets and popups a UI Kit component opens use that component's direction, even though they draw in a window of their own. +* **Screens the UI Kit starts keep the direction.** The image and video viewers open in the direction of the component that started them. Call screens follow the global setting. +* **Short messages follow the component.** Messages such as "Message pinned" appear as a snackbar in the component's direction. In the Compose UI Kit the bar is drawn in Compose, so it mirrors without `supportsRtl`. +* **Your app's own screens don't change.** The UI Kit never changes the app's direction or locale. + +## What Changes in RTL + +### Layout + +Everything that has a side moves to the other one: avatars, titles, subtitles, timestamps, unread badges, receipts, buttons, the composer's actions, message bubbles, menus, sheets, swipe actions and horizontal lists. Sent messages sit on the left and received messages on the right. Swipe to reply goes toward the left. + +Labels the UI Kit draws (toolbar titles, dialog titles and text, menu items, search hints, section headers, empty and error states) sit at the component's start, which is the right in RTL. + +### Icons + +| Icon | In RTL | +| --- | --- | +| Back and forward arrows, send, reply, reply in thread, call-direction arrows (incoming, outgoing, missed), video camera, copy, new chat, chat history, sticker, bullet list | Mirror | +| Phone handset, microphone, attach, emoji, close, search, receipt ticks, pin, media controls, file types, logos, flags | Stay as drawn | + +Icons you pass into the UI Kit are drawn as you give them. For an arrow that should mirror, use a vector drawable with `android:autoMirrored="true"`. + +### What doesn't mirror + +* **Audio and video players**, including voice notes and the recorder's playback row: controls and progress bars stay left to right in every language. The card around them follows the component. +* **Code blocks and inline code** stay left to right. + +### Text, numbers and dates + +* **Each text reads in its own direction.** Its first letter decides: a message that starts with an English letter reads left to right, one that starts with an Arabic letter reads right to left, in an RTL or an LTR screen. +* **Names keep their place.** Sentences the UI Kit writes, such as group action lines ("X added Y"), are translated, and the names inside them can't scramble the sentence. +* **Numbers use the language's own digits.** In Arabic, dates, times, counts and durations use Arabic digits (٠١٢٣٤٥٦٧٨٩), even where the phone's region uses Western digits. Hindi uses Devanagari digits (०–९), and every other language uses 0–9. An English app set to RTL keeps 0–9. +* **Dates follow the app's language**, including after an in-app language switch. Text you supply yourself, for example through a date formatter callback, is shown as given. + +## Custom Views in RTL + +Views you pass into the UI Kit (view slots, custom message templates, custom bubbles) are placed inside the component's direction. Use direction-aware values so they mirror with the rest of the UI Kit: + +| Instead of | Use (Views) | Use (Compose) | +| --- | --- | --- | +| `paddingLeft`, `layout_marginRight` | `paddingStart`, `layout_marginEnd` | `Modifier.padding(start = …, end = …)` | +| `setPadding(left, top, right, bottom)` | `setPaddingRelative(start, top, end, bottom)` | `PaddingValues(start = …, end = …)` | +| `gravity="left"` | `gravity="start"` | `Alignment.Start`, `Alignment.CenterStart` | +| `textAlignment="textStart"` for labels | `textAlignment="viewStart"` | `TextAlign.Start` | +| `resources.configuration.layoutDirection` | `view.layoutDirection` | `LocalLayoutDirection.current` | + +Read the direction from the view or the composition, never from the app's configuration: a UI Kit component can be set the other way from the app. + +### Your own overlays + +A dialog or popup you open from a custom view starts a new window, which follows the app, not the component. Copy the direction across: + + + +```kotlin +dialog.window?.decorView?.layoutDirection = anchorView.layoutDirection +dialog.show() +``` + + +```kotlin +val direction = LocalLayoutDirection.current // the opener's +Dialog(onDismissRequest = onDismiss) { + CompositionLocalProvider(LocalLayoutDirection provides direction) { + MyDialogContent() + } +} +``` + + + +## Upgrading From an Earlier Version + +| Change | What to do | +| --- | --- | +| The Views UI Kit no longer adds `android:supportsRtl` to your app | Add `android:supportsRtl="true"` to your `` to keep RTL. | +| `CometChatLocalize.setLocale` no longer changes the layout direction | For RTL, set the app language with `AppCompatDelegate.setApplicationLocales`, or call `setLayoutDirection(CometChatLayoutDirection.RTL)`. | +| `CometChatLocalize.isRtl(context)` is removed | Read `view.layoutDirection` (Views) or `LocalLayoutDirection.current` (Compose). | +| Views: `setBubbleMargin`, `setLeftBubbleMargin` and `setRightBubbleMargin` take `start` and `end` instead of `left` and `right` | Rename named arguments; the margins now apply as start and end, so they mirror in RTL. | +| Compose components take a new `layoutDirection` parameter | Existing calls compile unchanged. Rebuild any library compiled against the earlier version. | +| Short messages are snackbars instead of toasts | No code change. | + +## Languages + +The UI Kit ships Arabic translations. For another RTL language, such as Hebrew, Persian or Urdu, add its strings as described in [Localize](/ui-kit/android/localize). With the app's language set to it, `AUTO` lays the UI Kit out right to left. + +## Next Steps + + + + Set the UI Kit's language and translations + + + UIKitSettings and CometChatUIKit reference + + + Replace parts of a component with your own views + + + Common RTL questions + + diff --git a/ui-kit/android/saved-messages.mdx b/ui-kit/android/saved-messages.mdx index f98205673..4ccb29d7f 100644 --- a/ui-kit/android/saved-messages.mdx +++ b/ui-kit/android/saved-messages.mdx @@ -130,7 +130,7 @@ The list keeps itself up to date on this device — saving or unsaving a message ## Functionality - **Conversation-style rows** — because saved messages come from many conversations, each row shows where the message lives: the peer's or group's avatar and name, a message preview with its type icon, and the sent date. This mirrors a conversation list row (without the unread badge). -- **Unsave** — long-press a row to get the **Unsave** action, which asks for confirmation before it is performed; a toast reports the result. This mirrors the Unpin flow on the [Pinned Messages](/ui-kit/android/pinned-messages) screen. +- **Unsave** — long-press a row to get the **Unsave** action, which asks for confirmation before it is performed; a snackbar reports the result. This mirrors the Unpin flow on the [Pinned Messages](/ui-kit/android/pinned-messages) screen. - **Jump to message** — tapping a row emits the message through the click callback. Use the message's receiver type and receiver to resolve which conversation to open. - **Empty state** — a built-in empty state ("No saved messages yet") is shown when the user has not saved anything. - **Private and read-only** — nobody else can see a user's saved messages; the screen never marks messages as read and does not affect unread counts or receipts. @@ -139,6 +139,35 @@ The list keeps itself up to date on this device — saving or unsaving a message The screen is backed by `CometChatSavedMessagesViewModel` (in the shared core module), which fetches via `MessagesRequestBuilder().setSaved(true)`, applies optimistic unsave with revert-on-error, and observes the event bus for live upkeep. In Compose you can inject your own instance through the `viewModel` parameter. +## Layout Direction + +`CometChatSavedMessages` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatSavedMessages` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +savedMessages.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatSavedMessages( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps - [Message List](/ui-kit/android/message-list) — where messages are saved and unsaved, and where the bubble saved indicator appears. diff --git a/ui-kit/android/search.mdx b/ui-kit/android/search.mdx index 7d0d6a4b5..f385b9795 100644 --- a/ui-kit/android/search.mdx +++ b/ui-kit/android/search.mdx @@ -386,6 +386,7 @@ Small functional customizations such as toggling visibility of UI elements and c | `setSearchIn` | List of entities in which the search should be performed | `.setSearchIn(scopes);` | | `setHideGroupType` | Hides the group type icon in conversation leading view | `.setHideGroupType(true);` | | `setHideUserStatus` | Hides the user's online/offline status indicator | `.setHideUserStatus(true);` | +| `setCometChatLayoutDirection` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | `.setCometChatLayoutDirection(CometChatLayoutDirection.RTL);` | - **Verify**: After calling a visibility or functionality method, confirm the corresponding UI element is shown or hidden, or the search scope is correctly applied. @@ -1118,6 +1119,35 @@ In addition to XML theme styles, the component exposes programmatic setters for | Callback on messages loaded | Activity/Fragment | `setOnLoadMessages(((List) -> Unit)?)` | `.setOnLoadMessages { list -> ... }` | | Callback on conversations loaded | Activity/Fragment | `setOnLoadConversations(((List) -> Unit)?)` | `.setOnLoadConversations { list -> ... }` | +## Layout Direction + +`CometChatSearch` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatSearch` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +search.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatSearch( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/threaded-messages-header.mdx b/ui-kit/android/threaded-messages-header.mdx index 715e74199..355ee21ac 100644 --- a/ui-kit/android/threaded-messages-header.mdx +++ b/ui-kit/android/threaded-messages-header.mdx @@ -121,12 +121,13 @@ The component listens to SDK events internally via its ViewModel. No manual setu | `setThreadSubscriptionVisibility(View.GONE)` | `hideThreadSubscription = true` | Toggle the subscription bell | | `setOnThreadSubscriptionChange { }` | `onSubscriptionToggle = { }` | Subscription-state change callback | | — | `threadSubscriptionView = { }` | Replace the bell with a custom composable | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- ## Thread Subscription -On Android the subscription bell belongs to `CometChatThreadHeader` — it renders as a trailing control on this component's reply-count row. Thread subscription is enabled by default from **v6.1.0**; on **v6.0.x** the bell renders only after `UIKitSettings.setEnableThreadSubscription(true)`. It flips optimistically on tap, reverts with a toast if the server rejects the change, and stays in step with the message list's Subscribe / Unsubscribe action sheet option. +On Android the subscription bell belongs to `CometChatThreadHeader` — it renders as a trailing control on this component's reply-count row. Thread subscription is enabled by default from **v6.1.0**; on **v6.0.x** the bell renders only after `UIKitSettings.setEnableThreadSubscription(true)`. It flips optimistically on tap, reverts with a snackbar if the server rejects the change, and stays in step with the message list's Subscribe / Unsubscribe action sheet option. @@ -264,6 +265,35 @@ See [ViewModel & Data](/ui-kit/android/customization-viewmodel-data) for state o --- +## Layout Direction + +`CometChatThreadHeader` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatThreadHeader` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +threadHeader.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatThreadHeader( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps diff --git a/ui-kit/android/troubleshooting.mdx b/ui-kit/android/troubleshooting.mdx index 8922b085d..273177ee9 100644 --- a/ui-kit/android/troubleshooting.mdx +++ b/ui-kit/android/troubleshooting.mdx @@ -130,6 +130,20 @@ description: "Common failure modes and fixes for the CometChat Android V6 UI Kit --- +## RTL + +| Symptom | Cause | Fix | +| --- | --- | --- | +| Kotlin (XML Views) components stay left to right in Arabic | The app manifest doesn't declare RTL support | Add `android:supportsRtl="true"` to ``. See [RTL Support](/ui-kit/android/rtl-support#before-you-start) | +| Arabic text, but a left-to-right layout | `setLocale` changes the language only, or the direction is set to `LTR` | Set the app language with `AppCompatDelegate.setApplicationLocales`, or use `CometChatLayoutDirection.RTL` | +| An open screen didn't flip after `setLayoutDirection` | A new direction applies to components created afterwards | Recreate the activity | +| Setting `android:layoutDirection` or `LocalLayoutDirection` around a component has no effect | A global `LTR` or `RTL` wins over the parent's direction | Set the component's own direction instead | +| A custom view doesn't mirror | It uses left/right values | Use start/end values. See [Custom Views in RTL](/ui-kit/android/rtl-support#custom-views-in-rtl) | +| A dialog you open from a custom view stays left to right | A dialog window follows the app, not the component | Copy the direction to it. See [Your own overlays](/ui-kit/android/rtl-support#your-own-overlays) | +| `CometChatLocalize.isRtl` doesn't compile | It was removed | Read `view.layoutDirection` or `LocalLayoutDirection.current` | + +--- + ## Sound | Symptom | Cause | Fix | diff --git a/ui-kit/android/users.mdx b/ui-kit/android/users.mdx index 92b61c7d7..09806432a 100644 --- a/ui-kit/android/users.mdx +++ b/ui-kit/android/users.mdx @@ -411,6 +411,7 @@ The component listens to these SDK events internally. No manual setup needed. | `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode | | `setTitle("Contacts")` | `title = "Contacts"` | Custom toolbar title | | `setSearchPlaceholderText("Find...")` | `searchPlaceholderText = "Find..."` | Search placeholder | +| `setCometChatLayoutDirection(CometChatLayoutDirection.RTL)` | `layoutDirection = CometChatLayoutDirection.RTL` | Layout direction for this component and everything inside it: `LTR` or `RTL`. Overrides the global setting; unset inherits it. See [RTL Support](/ui-kit/android/rtl-support) | --- @@ -949,6 +950,35 @@ See [Component Styling](/ui-kit/android/component-styling) for the full referenc --- +## Layout Direction + +`CometChatUsers` follows the UI Kit's layout direction. Set it for this component only to override the global setting for `CometChatUsers` and everything inside it. See [RTL Support](/ui-kit/android/rtl-support). + + + +```xml + +``` + +```kotlin +users.setCometChatLayoutDirection(CometChatLayoutDirection.RTL) +``` + + +```kotlin +CometChatUsers( + // ...your other parameters + layoutDirection = CometChatLayoutDirection.RTL +) +``` + + + +--- + ## Next Steps