diff --git a/docs.json b/docs.json index 40eea0779..8f2795304 100644 --- a/docs.json +++ b/docs.json @@ -537,6 +537,7 @@ "ui-kit/react/theme/color-resources", "ui-kit/react/theme/message-bubble-styling", "ui-kit/react/localization", + "ui-kit/react/right-to-left", "ui-kit/react/sound-manager" ] }, @@ -2603,6 +2604,7 @@ "ui-kit/angular/customization/theming", "ui-kit/angular/message-bubble-styling", "ui-kit/angular/customization/localization", + "ui-kit/angular/customization/right-to-left", "ui-kit/angular/customization/global-config", "ui-kit/angular/customization/date-time-formatting", "ui-kit/angular/sound-manager" diff --git a/ui-kit/angular/customization/localization.mdx b/ui-kit/angular/customization/localization.mdx index ee81e9301..494966036 100644 --- a/ui-kit/angular/customization/localization.mdx +++ b/ui-kit/angular/customization/localization.mdx @@ -12,19 +12,20 @@ description: "Configure multi-language support, override translations globally, | Key pipe | `TranslatePipe` (`translate` pipe in templates) | | Required setup | `CometChatUIKit.init(uiKitSettings)` | | Purpose | Multi-language support with runtime switching and global overrides | -| Features | 19 built-in languages, runtime switching, custom translations | -| Related | [Date/Time Formatting](/ui-kit/angular/customization/localization) \| [Theming](/ui-kit/angular/customization/theming) | +| Features | 20 built-in languages, runtime switching, custom translations | +| Related | [Date/Time Formatting](/ui-kit/angular/customization/localization) \| [Theming](/ui-kit/angular/customization/theming) \| [Right-to-Left Layout](/ui-kit/angular/customization/right-to-left) | -CometChat UIKit supports 19 languages out of the box with runtime language switching. You can override translations globally without modifying source files. +CometChat UIKit supports 20 languages out of the box with runtime language switching. You can override translations globally without modifying source files. | Capability | Description | | --- | --- | -| Built-in languages | en-US, en-GB, de, fr, es, ja, ko, zh, zh-TW, ru, hi, ms, pt, sv, lt, hu, it, nl, tr | +| Built-in languages | en-US, en-GB, ar, de, fr, es, ja, ko, zh, zh-TW, ru, hi, ms, pt, sv, lt, hu, it, nl, tr | | Runtime switching | Change language at any time via `setCurrentLanguage` | | Global overrides | Replace any translation key for a language | | Custom languages | Add entirely new languages at runtime | +| Right-to-left | Arabic (`ar`) is included. Layout direction is a separate setting: see [Right-to-Left Layout](/ui-kit/angular/customization/right-to-left) | --- @@ -43,6 +44,10 @@ CometChatLocalize.init({ CometChatLocalize.setCurrentLanguage('fr'); ``` + +Arabic (`ar`) is written right to left, but `setCurrentLanguage('ar')` changes the kit's language, not its layout direction. To lay the kit out right to left, see [Right-to-Left Layout](/ui-kit/angular/customization/right-to-left). + + --- ## Global Translation Overrides diff --git a/ui-kit/angular/customization/right-to-left.mdx b/ui-kit/angular/customization/right-to-left.mdx new file mode 100644 index 000000000..6c719d537 --- /dev/null +++ b/ui-kit/angular/customization/right-to-left.mdx @@ -0,0 +1,284 @@ +--- +title: "Right-to-Left Layout" +description: "Lay out the Angular UI Kit right to left for Arabic and other RTL languages: from your app's direction, for the whole kit, or per component." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-uikit-angular` | +| Default | `'auto'`: components follow your app's own direction (``) | +| Global setting | `UIKitSettingsBuilder.setLayoutDirection('auto' \| 'ltr' \| 'rtl')` at init | +| Change later | `CometChatUIKit.setLayoutDirection('ltr')`: applies to components created afterwards | +| Per component | `layoutDirection` input (`'ltr'` \| `'rtl'`) on every public component. Unset: inherit | +| Language → direction | `CometChatLocalize.getDirection(language)` returns `'rtl'` for `ar`, `he`, `fa`, `ur` (any region) | +| Arabic strings | `CometChatLocalize.setCurrentLanguage('ar')` | +| Who sets `` | Your app. The kit never changes it. | +| Related | [Localization](/ui-kit/angular/customization/localization) \| [Theming](/ui-kit/angular/customization/theming) \| [Global Config](/ui-kit/angular/customization/global-config) | + + + +Every UI Kit component can lay out right to left. Lists, headers, message bubbles, the composer, menus and dialogs mirror, and directional icons such as the back arrow and send point the other way. Text keeps its own direction, so an English message in an Arabic chat still reads left to right. + +Two settings control the layout direction: + +| Setting | Values | Where you set it | +| --- | --- | --- | +| Global | `'auto'` (default), `'ltr'`, `'rtl'` | `UIKitSettingsBuilder.setLayoutDirection()` at init, or `CometChatUIKit.setLayoutDirection()` later | +| Component | `'ltr'`, `'rtl'`. Unset: inherit | The `layoutDirection` input on every public component | + +A component takes its direction from the first of these that is set: + +1. Its own `layoutDirection` input. +2. The `layoutDirection` of the nearest kit component it sits inside. +3. The global setting, when it is `'ltr'` or `'rtl'`. +4. Your app's direction: the `dir` of ``, or of an element the component is inside (global `'auto'`). + +The kit binds the result as `dir` on the component's host element. Base components (avatar, badge, button, list item, date, receipts, popover, ...) have no setting of their own: they follow the component they sit in, and used on their own they follow the global setting. Audio and video players are the one exception: they always lay out left to right (see [Audio and Video Players](#audio-and-video-players-stay-left-to-right)). + +An app that sets no direction and has no `dir="rtl"` on its page lays out left to right, as before. + +--- + +## Follow Your App's Direction (Default) + +With the default, `'auto'`, the kit follows your app. Set `dir` on `` and every component lays out to match. This is the recommended setup for an app that is itself right to left. + +```html + +``` + +The kit never writes ``. If your app switches language at runtime, set the page's direction from the language yourself. Direction and language are separate settings: the kit's language picks its strings, `dir` picks the layout. + +```typescript +import { CometChatLocalize } from '@cometchat/chat-uikit-angular'; + +export function applyLanguage(language: string): void { + CometChatLocalize.setCurrentLanguage(language); + // Your app sets the page's language and direction, not the kit. + document.documentElement.lang = language; + document.documentElement.dir = CometChatLocalize.getDirection(language); // 'rtl' for 'ar' +} +``` + +`CometChatLocalize.getDirection()` only reports a direction; it changes nothing. It returns `'rtl'` for Arabic (`ar`), Hebrew (`he`), Persian (`fa`) and Urdu (`ur`), in any region (`ar-SA`, `ar-EG`, ...), and `'ltr'` otherwise. Called with no argument, it uses the kit's current language. + + +`CometChatUIKit.init()` selects the browser's language. To use a language your user picked, call `CometChatLocalize.setCurrentLanguage()` after `init()`, then set `` before your app renders, so the first frame already has the right direction. Components work out some text (dates, previews, labels) when they are created, so after a language change, recreate the screen or reload the page. + + +--- + +## Set the Direction for the Whole Kit + +To lay out every kit component in one direction whatever your app's direction, set it when you initialize the kit: + +```typescript +import { CometChatUIKit, UIKitSettingsBuilder } from '@cometchat/chat-uikit-angular'; + +const uiKitSettings = new UIKitSettingsBuilder() + .setAppId('YOUR_APP_ID') + .setRegion('YOUR_REGION') + .setAuthKey('YOUR_AUTH_KEY') + .subscribePresenceForAllUsers() + .setLayoutDirection('rtl') // 'auto' (default) | 'ltr' | 'rtl' + .build(); + +CometChatUIKit.init(uiKitSettings)?.then(() => { + // Log in and bootstrap your app +}); +``` + +The setting doesn't change ``: the rest of your page keeps its own direction. + +### Changing It Later + +```typescript +import { CometChatUIKit } from '@cometchat/chat-uikit-angular'; + +CometChatUIKit.setLayoutDirection('ltr'); +``` + +The new direction applies to components created afterwards. Components already on screen keep their direction until they are created again, for example when the user reopens the screen. + +--- + +## Set the Direction of One Component + +Every public component takes a `layoutDirection` input, `'ltr'` or `'rtl'`. It wins over the global setting, and the components inside it, including the menus, popovers and dialogs it opens, follow it unless they set their own: + +```html + + + +``` + +Leave it unset to inherit. Changing the input updates the component at once. + + +When the global setting is `'ltr'` or `'rtl'`, wrapping a component in an element with its own `dir` does **not** change the component's direction: + +```html + +
+ +
+``` + +The kit applies the global setting on each component's host element, so it wins over the wrapper. Use the component's input instead: ``. A `dir` wrapper only works while the global setting is `'auto'`. +
+ +--- + +## Arabic + +Arabic (`ar`) is one of the kit's built-in languages; regional tags such as `ar-SA` and `ar-EG` use it too. Select it after `init()`: + +```typescript +import { CometChatLocalize } from '@cometchat/chat-uikit-angular'; + +CometChatLocalize.setCurrentLanguage('ar'); +document.documentElement.lang = 'ar'; +document.documentElement.dir = CometChatLocalize.getDirection('ar'); // 'rtl' +``` + +The language doesn't change the layout. With the global setting `'auto'`, the kit lays out right to left when your app does, which is what setting `` above does. To lay out the kit right to left without changing your page, leave out the `dir` line and use `setLayoutDirection('rtl')` instead. + +In Arabic, dates, times and counts use Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩). A regional tag such as `ar-MA` uses that region's own digits. To change any Arabic string, override it as you would for any other language: see [Global Translation Overrides](/ui-kit/angular/customization/localization#global-translation-overrides). + +--- + +## What Mirrors + +In a right-to-left layout: + +- Lists, headers, the composer and toolbars run right to left. Outgoing messages move to the left and incoming messages to the right. +- Menus, popovers, dialogs, sheets and toasts take the direction of the component that opens them, and stay on screen near both edges. +- The left and right arrow keys follow the layout: in a right-to-left list, the left arrow moves to the next item. +- Directional icons mirror. Icons that don't point a direction stay as drawn: + +| Icons | In a right-to-left layout | +| --- | --- | +| Back and forward arrows, sideways chevrons, send, reply, call-direction arrows (incoming, outgoing, missed), video camera, copy, chat, sticker | Mirror | +| Phone handset, microphone, attach, emoji, close, search, sent/delivered/read ticks, pin, media controls (play, pause), file types, logos | Stay as drawn | + +### Audio and Video Players Stay Left to Right + +Audio and video players, including voice notes, always lay out left to right, whatever the setting: the timeline and play controls read the way the media plays, as they do in other apps. The bubble around the player still follows the layout. + +--- + +## Text Direction + +Layout direction and text direction are separate: + +- **Message text keeps its own direction.** An English message in a right-to-left chat reads left to right, and an Arabic message reads right to left even in a left-to-right app. Conversation previews and subtitles do the same, and sender names keep their own order in mixed Arabic and English text. +- **Typed text** in the composer and other text fields takes the direction of what is typed. +- **Code blocks, URLs and email addresses** stay left to right. +- **The kit's own labels** (empty and error states, dialog text, placeholders) read in the UI language's direction, so an English label in a right-to-left layout keeps its punctuation at the end. Their position still follows the layout. +- **Digits:** in Arabic, dates, times and counts use Arabic-Indic digits. + +--- + +## Custom Views, Slots and CSS + +The kit's stylesheets use logical properties, so they mirror on their own. Templates you pass to a component (custom item, subtitle or header views) render inside its host element and inherit its direction; write them and your CSS overrides so they mirror too. + +**Use logical properties.** Physical ones still apply in a left-to-right layout exactly as before, but don't mirror. + +| Instead of | Use | +| --- | --- | +| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` | +| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` | +| `left` / `right` | `inset-inline-start` / `inset-inline-end` | +| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` | +| `text-align: left` / `right` | `text-align: start` / `end` | + +**Style by direction with `:dir(rtl)`, not `[dir="rtl"] .x`** (or `:host-context([dir="rtl"])`). A component set to `'ltr'` on a right-to-left page is still inside ``, so an attribute selector matches it wrongly. `:dir()` matches the direction the element actually lays out in. + +```css +/* Matches the direction the icon actually lays out in */ +.my-forward-icon:dir(rtl) { + scale: -1 1; +} + +/* Avoid: also matches inside a component set to 'ltr' on an RTL page */ +[dir="rtl"] .my-forward-icon { + scale: -1 1; +} +``` + +For a directional icon in your own template, you can also add the kit's `cometchat-icon--mirror` class (from `css-variables.css`), which flips it in a right-to-left layout. `:dir()` needs Chrome 120, Safari 16.4, Firefox 49 or later. + +**Read the direction from the element** in code, not from `` or the global setting: + +```typescript +const isRtl = getComputedStyle(element).direction === 'rtl'; +``` + +**Pass the direction to overlays you open yourself.** The kit's own menus and dialogs carry the direction of the component that opens them. An overlay you attach to `document.body`, such as an Angular CDK overlay, leaves that component's DOM, so copy the direction from the element it opens from. With the CDK, pass it as the overlay's `direction`: + +```typescript +import { Component, inject } from '@angular/core'; +import { Overlay } from '@angular/cdk/overlay'; +import type { Direction } from '@angular/cdk/bidi'; + +@Component({ + selector: 'app-more-button', + standalone: true, + template: ``, +}) +export class MoreButtonComponent { + private readonly overlay = inject(Overlay); + + openMenu(anchor: HTMLElement): void { + // The direction the button lays out in: from the kit setting, a wrapper or . + const direction = getComputedStyle(anchor).direction as Direction; + + const overlayRef = this.overlay.create({ + direction, + positionStrategy: this.overlay + .position() + .flexibleConnectedTo(anchor) + .withPositions([{ originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'top' }]), + }); + // Attach your menu to overlayRef + } +} +``` + +Or set `dir` on the overlay's pane yourself: `overlayRef.overlayElement.setAttribute('dir', direction)`. + +--- + +## Common Scenarios + +| You want | Global setting | Component setting | +| --- | --- | --- | +| Your app is already in Arabic and right to left | `'auto'` (the default) and `` | None | +| An English app, with the chat in Arabic and right to left | `'rtl'`, plus `CometChatLocalize.setCurrentLanguage('ar')` | None | +| Everything right to left except one component | `'rtl'` | `'ltr'` on that component | +| A right-to-left app with one component left to right | `'auto'` | `'ltr'` on that component | +| Only the chat screen right to left, in a left-to-right app | `'auto'` | `'rtl'` on the screen's outer component | + +In the last case, the components inside the outer one follow it. For components side by side, such as a header, message list and composer, set the input on each, or wrap them in `
`: a wrapper works because the global setting is `'auto'`. + +--- + +## Next Steps + + + + Built-in languages, runtime switching and custom translations. + + + Customize colors, fonts, and spacing. + + + Control how dates and times are displayed. + + + Configure global UIKit settings. + + diff --git a/ui-kit/angular/llms-angular-v5.mdx b/ui-kit/angular/llms-angular-v5.mdx index 4be4c090f..7c1951029 100644 --- a/ui-kit/angular/llms-angular-v5.mdx +++ b/ui-kit/angular/llms-angular-v5.mdx @@ -68,6 +68,7 @@ exhaustive inputs, long-tail components, theming tokens, or feature enablement. - [Theming](/ui-kit/angular/customization/theming) - [Global Configuration](/ui-kit/angular/customization/global-config) - [Localization](/ui-kit/angular/customization/localization) +- [Right-to-Left Layout](/ui-kit/angular/customization/right-to-left) - [Date & Time Formatting](/ui-kit/angular/customization/date-time-formatting) - [Message Bubble Styling](/ui-kit/angular/message-bubble-styling) diff --git a/ui-kit/react/cometchat-provider.mdx b/ui-kit/react/cometchat-provider.mdx index 669713707..a847ab801 100644 --- a/ui-kit/react/cometchat-provider.mdx +++ b/ui-kit/react/cometchat-provider.mdx @@ -61,6 +61,7 @@ For production, use `CometChatUIKit.loginWithAuthToken(token)` instead of `login | `config` | `CometChatGlobalConfig` | No | `{}` | Global flags (`hideReceipts`, `hideUserStatus`, etc.) | | `theme` | `"light" \| "dark"` | No | `"light"` | Active theme | | `locale` | `string` | No | `"en-us"` | Language code for localization | +| `layoutDirection` | `"auto" \| "ltr" \| "rtl"` | No | `"auto"` | Layout direction for every kit component inside the provider; `"auto"` follows your app's `dir`. When passed, it overrides the init setting (`UIKitSettingsBuilder.setLayoutDirection()`), even as `"auto"`, and changing it updates components already on screen; leave it out to use the init setting. See [Right-to-Left Layout](/ui-kit/react/right-to-left) | | `children` | `ReactNode` | Yes | — | Your app content | --- diff --git a/ui-kit/react/llms-react-v7.mdx b/ui-kit/react/llms-react-v7.mdx index d5ac71012..fe7c60152 100644 --- a/ui-kit/react/llms-react-v7.mdx +++ b/ui-kit/react/llms-react-v7.mdx @@ -52,6 +52,7 @@ components, theming tokens, or feature enablement. - [Event System](/ui-kit/react/event-system) - [Sound Manager](/ui-kit/react/sound-manager) - [Localization](/ui-kit/react/localization) +- [Right-to-Left Layout](/ui-kit/react/right-to-left) - [Extensions](/ui-kit/react/extensions) - [Troubleshooting](/ui-kit/react/troubleshooting) diff --git a/ui-kit/react/localization.mdx b/ui-kit/react/localization.mdx index e7b179d0c..5684f6ece 100644 --- a/ui-kit/react/localization.mdx +++ b/ui-kit/react/localization.mdx @@ -1,6 +1,6 @@ --- title: "Localization" -description: "19 built-in languages with support for custom translations, fallback languages, and date/time formatting." +description: "20 built-in languages with support for custom translations, fallback languages, and date/time formatting." --- @@ -9,16 +9,17 @@ description: "19 built-in languages with support for custom translations, fallba | --- | --- | | Locale prop | `locale="fr"` on `CometChatProvider` | | Default | `en-us` | -| Languages | 19 built-in: de, en-gb, en-us, es, fr, hi, hu, it, ja, ko, lt, ms, nl, pt, ru, sv, tr, zh, zh-tw | +| Languages | 20 built-in: ar, de, en-gb, en-us, es, fr, hi, hu, it, ja, ko, lt, ms, nl, pt, ru, sv, tr, zh, zh-tw | | Hook | `useLocale()` → `{ getLocalizedString, language }` | | Static access | `CometChatLocalize.getSharedInstance()?.t(key)` | | Custom translations | Pass via `CometChatLocalize` constructor or `addTranslation()` | +| Right-to-left | Language and layout direction are separate settings. See [Right-to-Left Layout](/ui-kit/react/right-to-left) | ## Overview -The UI Kit ships with translations for 19 languages. All user-facing text (button labels, status messages, timestamps, error messages) is resolved through translation keys. Set the `locale` prop on `CometChatProvider` to switch languages. +The UI Kit ships with translations for 20 languages. All user-facing text (button labels, status messages, timestamps, error messages) is resolved through translation keys. Set the `locale` prop on `CometChatProvider` to switch languages. --- @@ -38,6 +39,7 @@ The UI Kit ships with translations for 19 languages. All user-facing text (butto | --- | --- | | `en-us` | English (US) — default | | `en-gb` | English (UK) | +| `ar` | Arabic | | `de` | German | | `es` | Spanish | | `fr` | French | @@ -56,6 +58,10 @@ The UI Kit ships with translations for 19 languages. All user-facing text (butto | `zh` | Chinese (Simplified) | | `zh-tw` | Chinese (Traditional) | + +Arabic is written right to left, but `locale="ar"` changes the kit's language, not its layout direction. To lay the kit out right to left, see [Right-to-Left Layout](/ui-kit/react/right-to-left). + + --- ## Accessing Translations in Components @@ -135,4 +141,4 @@ const text = t?.("message_deleted") ?? "This message was deleted"; | `CometChatLocalize.setLanguage("fr")` | `locale="fr"` prop on `CometChatProvider` | | Global static state | React context via provider | | Manual init required | Provider handles locale context | -| Same 19 languages | Same 19 languages | +| 19 languages | 20 languages: adds Arabic (`ar`) | diff --git a/ui-kit/react/right-to-left.mdx b/ui-kit/react/right-to-left.mdx new file mode 100644 index 000000000..c21171a27 --- /dev/null +++ b/ui-kit/react/right-to-left.mdx @@ -0,0 +1,302 @@ +--- +title: "Right-to-Left Layout" +description: "Lay out the React UI Kit right to left for Arabic and other RTL languages: from your app's direction, for the whole kit, or per component." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-uikit-react` | +| Default | `"auto"`: components follow your app's own direction (``) | +| Global setting | `UIKitSettingsBuilder.setLayoutDirection("auto" \| "ltr" \| "rtl")` at init, or `layoutDirection` on `CometChatProvider` | +| Change later | `CometChatUIKit.setLayoutDirection("ltr")`: applies to components mounted afterwards | +| Per component | `layoutDirection="ltr"` or `"rtl"` on every public component. Unset: inherit | +| Language → direction | `CometChatLocalize.getDirection(language)` returns `"rtl"` for `ar`, `he`, `fa`, `ur` and other right-to-left languages | +| Arabic strings | `locale="ar"` on `CometChatProvider` | +| Who sets `` | Your app. The kit never changes it. | +| Related | [Localization](/ui-kit/react/localization) \| [CometChatProvider](/ui-kit/react/cometchat-provider) \| [Theming](/ui-kit/react/theming) | + + + +## Overview + +Every UI Kit component can lay out right to left. Lists, headers, message bubbles, the composer, menus and dialogs mirror, and directional icons such as the back arrow and send point the other way. Text keeps its own direction, so an English message in an Arabic chat still reads left to right. + +Two settings control the layout direction: + +| Setting | Values | Where you set it | +| --- | --- | --- | +| Global | `"auto"` (default), `"ltr"`, `"rtl"` | `UIKitSettingsBuilder.setLayoutDirection()` at init, or `layoutDirection` on `CometChatProvider` | +| Component | `"ltr"`, `"rtl"`. Unset: inherit | The `layoutDirection` prop on every public component | + +A component takes its direction from the first of these that is set: + +1. Its own `layoutDirection` prop. +2. The `layoutDirection` of the nearest kit component it sits inside. +3. The global setting, when it is `"ltr"` or `"rtl"`. +4. Your app's direction: the `dir` of ``, or of an element the component is inside (global `"auto"`). + +The kit writes the result as `dir` on the component's root element. Base components (avatar, badge, button, list item, date, receipts, popover, ...) have no setting of their own: they follow the component they sit in, and used on their own they follow the global setting. Audio and video players are the one exception: they always lay out left to right (see [Audio and Video Players](#audio-and-video-players-stay-left-to-right)). + +An app that sets no direction and has no `dir="rtl"` on its page lays out left to right, as before. + +--- + +## Follow Your App's Direction (Default) + +With the default, `"auto"`, the kit follows your app. Set `dir` on `` and every component lays out to match. This is the recommended setup for an app that is itself right to left. + +```html + +``` + +The kit never writes ``. If your app switches language at runtime, set the page's direction from the language yourself. Direction and language are separate settings: `locale` picks the kit's strings, `dir` picks the layout. + +```tsx title="src/App.tsx" +import { useLayoutEffect, useState } from "react"; +import { CometChatLocalize, CometChatProvider } from "@cometchat/chat-uikit-react"; + +function App() { + const [language, setLanguage] = useState("ar"); + + // Your app sets the page's language and direction, not the kit. + // useLayoutEffect: the page has its direction before the first paint. + useLayoutEffect(() => { + document.documentElement.lang = language; + document.documentElement.dir = CometChatLocalize.getDirection(language); // "rtl" for "ar" + }, [language]); + + return ( + + + + ); +} +``` + +`CometChatLocalize.getDirection()` only reports a direction; it changes nothing. It returns `"rtl"` for Arabic (`ar`), Hebrew (`he`), Persian (`fa`), Urdu (`ur`) and other languages written in a right-to-left script, in any region (`ar-SA`, `ar-EG`, ...), and `"ltr"` otherwise. Called with no argument, it uses the kit's current language. + +--- + +## Set the Direction for the Whole Kit + +To lay out every kit component in one direction whatever your app's direction, set it when you initialize the kit: + +```tsx title="src/main.tsx" +import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react"; + +const settings = new UIKitSettingsBuilder() + .setAppId("YOUR_APP_ID") + .setRegion("YOUR_REGION") + .setAuthKey("YOUR_AUTH_KEY") + .subscribePresenceForAllUsers() + .setLayoutDirection("rtl") // "auto" (default) | "ltr" | "rtl" + .build(); + +CometChatUIKit.init(settings).then(() => { + // Log in and render your app +}); +``` + +Or pass it to the provider, next to `locale`: + +```tsx + + + +``` + +These are the same setting, so use one of them. When `CometChatProvider` has a `layoutDirection` prop, it takes precedence over the init setting, including when it is `"auto"`: leave the prop out to keep the init setting. + +Neither changes ``: the rest of your page keeps its own direction. + +### Changing It Later + +```tsx +import { CometChatUIKit } from "@cometchat/chat-uikit-react"; + +CometChatUIKit.setLayoutDirection("ltr"); +``` + +The new direction applies to components mounted afterwards. Components already on screen keep their direction until they mount again, for example when the user reopens the screen. + + +Inside a `CometChatProvider` that has a `layoutDirection` prop, change the prop instead: it wins over `setLayoutDirection()`, and because it is a React prop, components already on screen update straight away. + + +--- + +## Set the Direction of One Component + +Every public component takes a `layoutDirection` prop, `"ltr"` or `"rtl"`. It wins over the global setting, and the components inside it, including the menus, popovers and dialogs it opens, follow it unless they set their own: + +```tsx + + + +``` + +Leave it unset to inherit. Changing the prop updates the component at once. + + +When the global setting is `"ltr"` or `"rtl"`, wrapping a component in an element with its own `dir` does **not** change the component's direction: + +```tsx +// With setLayoutDirection("rtl"), this list still lays out right to left +
+ +
+``` + +The kit applies the global setting on each component's root element, so it wins over the wrapper. Use the component's prop instead: ``. A `dir` wrapper only works while the global setting is `"auto"`. +
+ +--- + +## Arabic + +Arabic (`ar`) is one of the kit's built-in languages; regional tags such as `ar-SA` and `ar-EG` use it too. Pass it to the provider: + +```tsx + + + +``` + +The language doesn't change the layout. With the global setting `"auto"`, the kit lays out right to left when your app does, so set `` from the language, as in the example above. To lay out the kit right to left without changing your page, add `layoutDirection="rtl"` to the provider as well. + +In Arabic, dates and times use Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩). A regional tag such as `ar-MA` uses that region's own digits. To change any Arabic string, override it as you would for any other language: see [Adding Custom Translations](/ui-kit/react/localization#adding-custom-translations). + +--- + +## What Mirrors + +In a right-to-left layout: + +- Lists, headers, the composer and toolbars run right to left. Outgoing messages move to the left and incoming messages to the right. +- Menus, popovers, dialogs, sheets and toasts take the direction of the component that opens them, and stay on screen near both edges. +- The left and right arrow keys follow the layout: in a right-to-left list, the left arrow moves to the next item. +- Directional icons mirror. Icons that don't point a direction stay as drawn: + +| Icons | In a right-to-left layout | +| --- | --- | +| Back and forward arrows, sideways chevrons, send, reply, call-direction arrows (incoming, outgoing, missed), video camera, copy, chat, sticker | Mirror | +| Phone handset, microphone, attach, emoji, close, search, sent/delivered/read ticks, pin, media controls (play, pause), file types, logos | Stay as drawn | + +### Audio and Video Players Stay Left to Right + +Audio and video players, including voice notes, always lay out left to right, whatever the setting: the timeline and play controls read the way the media plays, as they do in other apps. The bubble around the player still follows the layout. + +--- + +## Text Direction + +Layout direction and text direction are separate: + +- **Message text keeps its own direction.** An English message in a right-to-left chat reads left to right, and an Arabic message reads right to left even in a left-to-right app. Conversation previews and subtitles do the same, and names, mentions and file names keep their own order in mixed Arabic and English text. +- **Typed text** in the composer and other text fields takes the direction of what is typed. +- **Code blocks, URLs and email addresses** stay left to right. +- **The kit's own labels** (empty and error states, dialog text, placeholders) read in the UI language's direction, so an English label in a right-to-left layout keeps its punctuation at the end. Their position still follows the layout. +- **Digits:** in Arabic, dates and times use Arabic-Indic digits. + +--- + +## Custom Views, Slots and CSS + +The kit's stylesheets use logical properties, so they mirror on their own. Views you pass to a component (custom item, subtitle or header views) render inside its root element and inherit its direction; write them and your CSS overrides so they mirror too. + +**Use logical properties.** Physical ones still apply in a left-to-right layout exactly as before, but don't mirror. + +| Instead of | Use | +| --- | --- | +| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` | +| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` | +| `left` / `right` | `inset-inline-start` / `inset-inline-end` | +| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` | +| `text-align: left` / `right` | `text-align: start` / `end` | + +**Style by direction with `:dir(rtl)`, not `[dir="rtl"] .x`.** A component set to `"ltr"` on a right-to-left page is still inside ``, so an attribute selector matches it wrongly. `:dir()` matches the direction the element actually lays out in. + +```css +/* Matches the direction the icon actually lays out in */ +.my-forward-icon:dir(rtl) { + transform: scaleX(-1); +} + +/* Avoid: also matches inside a component set to "ltr" on an RTL page */ +[dir="rtl"] .my-forward-icon { + transform: scaleX(-1); +} +``` + +For a directional icon in your own view, you can also add the kit's `cometchat-icon--mirror` class, which flips it in a right-to-left layout. `:dir()` needs Chrome 120, Safari 16.4, Firefox 49 or later. + +**Read the direction from the element** in code, not from `` or the global setting: + +```tsx +const isRtl = getComputedStyle(element).direction === "rtl"; +``` + +**Pass the direction to overlays you open yourself.** The kit's own menus and dialogs carry the direction of the component that opens them. A menu or popover you render through a portal into `document.body` leaves that component's DOM, so copy the direction from the element it opens from: + +```tsx +import { useState } from "react"; +import type { MouseEvent } from "react"; +import { createPortal } from "react-dom"; + +function MoreButton() { + const [menuDir, setMenuDir] = useState(null); + + function openMenu(event: MouseEvent) { + // The direction the button lays out in: from the kit setting, a wrapper or . + setMenuDir(getComputedStyle(event.currentTarget).direction); + } + + return ( + <> + + {menuDir && + createPortal( +
+ {/* menu items */} +
, + document.body + )} + + ); +} +``` + +--- + +## Common Scenarios + +| You want | Global setting | Component setting | +| --- | --- | --- | +| Your app is already in Arabic and right to left | `"auto"` (the default) and `` | None | +| An English app, with the chat in Arabic and right to left | `"rtl"`, plus `locale="ar"` on `CometChatProvider` | None | +| Everything right to left except one component | `"rtl"` | `"ltr"` on that component | +| A right-to-left app with one component left to right | `"auto"` | `"ltr"` on that component | +| Only the chat screen right to left, in a left-to-right app | `"auto"` | `"rtl"` on the screen's outer component | + +In the last case, the components inside the outer one follow it. For components side by side, such as a header, message list and composer, set the prop on each, or wrap them in `
`: a wrapper works because the global setting is `"auto"`. + +--- + +## Next Steps + + + + Built-in languages, custom translations and fallbacks + + + Theme, locale and other provider props + + + Colors, fonts and dark mode with CSS variables + + + Customize bubble appearance, alignment and spacing + +