Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -1425,6 +1425,7 @@
"ui-kit/ios/component-styling",
"ui-kit/ios/message-bubble-styling",
"ui-kit/ios/localize",
"ui-kit/ios/rtl-support",
"ui-kit/ios/sound-manager"
]
},
Expand Down
4 changes: 4 additions & 0 deletions ui-kit/ios/localize.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ CometChat UI Kit provides language localization to adapt to the language of a sp

`CometChatLocalize` is a class that includes methods related to locale. Developers can use these methods to change the language of the UI Kit library.

<Note>
Setting a language does not change the layout direction. To lay out the UI Kit right to left, see [RTL Support](/ui-kit/ios/rtl-support).
</Note>

### Supported Languages

The UI Kit supports 17 languages for localization:
Expand Down
262 changes: 262 additions & 0 deletions ui-kit/ios/rtl-support.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,262 @@
---
title: "RTL Support"
sidebarTitle: "RTL Support"
description: "Set the layout direction of the CometChat iOS UI Kit for right-to-left languages, for the whole kit or for a single component"
---

<Accordion title="AI Integration Quick Reference">

| Field | Value |
| --- | --- |
| Platform | iOS UI Kit |
| Kit-Level Direction | `CometChatUIKit.set(layoutDirection: .rightToLeft)` |
| Direction at Start-Up | `UIKitSettings().set(layoutDirection: .rightToLeft)` |
| Component-Level Direction | `messageList.set(layoutDirection: .leftToRight)` |
| Type (Kit and Component Level) | `UIUserInterfaceLayoutDirection?` (`.rightToLeft`, `.leftToRight`, `nil`) |
| Type (Start-Up) | `UIUserInterfaceLayoutDirection`, not optional (`.rightToLeft`, `.leftToRight`) |
| Default | `nil`: the kit follows your app's layout direction |
| Language | Separate setting: `CometChatLocalize.set(locale:)` does not change the layout direction |
| Applies To | Kit-level value applies to components created after the call |
| Always Left to Right | Audio and video players, waveforms, playback controls, durations, code blocks |

</Accordion>

## Overview

CometChat UI Kit supports layouts for right-to-left (RTL) languages such as Arabic. You choose the layout direction of the kit's components with `set(layoutDirection:)`, either for the whole kit or for a single component.

The direction is a `UIUserInterfaceLayoutDirection?` value:

| Value | Behavior |
|-------|----------|
| `.rightToLeft` | The kit's components lay out right to left |
| `.leftToRight` | The kit's components lay out left to right |
| `nil` | Not set. The kit follows your app's layout direction. This is the default |

A direction you set applies to the kit's components only. Your app's own screens do not change.

<Note>
With no direction set, the kit follows your app, as any other UIKit view does. iOS lays out an app right to left when the app runs in a right-to-left language, which requires your app to include that localization, or when your app sets `UIView.appearance().semanticContentAttribute`.
</Note>

---

## Language and Direction Are Separate

Language and layout direction are two independent settings:

| Setting | Method | What it changes |
|---------|--------|-----------------|
| Language | `CometChatLocalize.set(locale:)` | The text the kit shows. It does not change the layout direction |
| Direction | `CometChatUIKit.set(layoutDirection:)` | How the kit's components lay out. It does not change the language |

Combine them to get the result you need:

| Goal | Language | Direction |
|------|----------|-----------|
| Arabic text in an RTL kit | `CometChatLocalize.set(locale: .arabic)` | `CometChatUIKit.set(layoutDirection: .rightToLeft)` |
| RTL kit with English text | `CometChatLocalize.set(locale: .english)` | `CometChatUIKit.set(layoutDirection: .rightToLeft)` |
| Arabic text in an LTR kit | `CometChatLocalize.set(locale: .arabic)` | `CometChatUIKit.set(layoutDirection: .leftToRight)` |
| Kit follows your app | Any | Not set (`nil`) |

<Tabs>
<Tab title="Swift">
```swift lines
// Show Arabic text and lay the kit out right to left
CometChatLocalize.set(locale: .arabic)
CometChatUIKit.set(layoutDirection: .rightToLeft)
```
</Tab>
</Tabs>

See [Localization](/ui-kit/ios/localize) for the language setting.

---

## Set the Direction

You can set the direction at three levels.

### 1. Kit Level

`CometChatUIKit.set(layoutDirection:)` sets the direction for every component the kit creates after the call. Pass `nil` to go back to following your app.

<Tabs>
<Tab title="Swift">
```swift lines
// Lay out all kit components right to left
CometChatUIKit.set(layoutDirection: .rightToLeft)

// Go back to following the app
CometChatUIKit.set(layoutDirection: nil)
```
</Tab>
</Tabs>

### 2. At Start-Up

`UIKitSettings.set(layoutDirection:)` gives the direction with the rest of your settings. The kit applies it when `CometChatUIKit.init(uiKitSettings:)` succeeds. If the initialization fails, the direction is not applied.

<Tabs>
<Tab title="Swift">
```swift lines
let uikitSettings = UIKitSettings()
.set(appID: "APP_ID") // Replace with your App ID
.set(region: "REGION") // Replace with your Region
.set(authKey: "AUTH_KEY") // Replace with your Auth Key (dev only)
.set(layoutDirection: .rightToLeft)
.build()

CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
switch result {
case .success:
debugPrint("CometChat initialized")
case .failure(let error):
debugPrint("Initialization failed: \(error.localizedDescription)")
}
}
```
</Tab>
</Tabs>

`UIKitSettings.set(layoutDirection:)` takes `.rightToLeft` or `.leftToRight`. To follow your app, leave it out.

### 3. Component Level

A component's own `set(layoutDirection:)` sets the direction of that component only, and wins over the kit-level value. Pass `nil` to inherit again.

<Tabs>
<Tab title="Swift">
```swift lines
// The kit is right to left
CometChatUIKit.set(layoutDirection: .rightToLeft)

// This conversations screen is left to right
let conversations = CometChatConversations()
conversations.set(layoutDirection: .leftToRight)

// This message list is right to left, whatever the kit-level value is
let messageList = CometChatMessageList()
messageList.set(user: user)
messageList.set(layoutDirection: .rightToLeft)
```
</Tab>
</Tabs>

`set(layoutDirection:)` is available on every list screen built on `CometChatListBase`, and on the other components below:

| Type | Components |
|------|------------|
| List screens | [CometChatConversations](/ui-kit/ios/conversations), [CometChatUsers](/ui-kit/ios/users), [CometChatGroups](/ui-kit/ios/groups), [CometChatGroupMembers](/ui-kit/ios/group-members), [CometChatCallLogs](/ui-kit/ios/call-logs), [CometChatSavedMessages](/ui-kit/ios/saved-messages), [CometChatPinnedMessages](/ui-kit/ios/pinned-messages), [CometChatNotificationFeed](/ui-kit/ios/notification-feed), `CometChatMessageInformation` |
| Messages | [CometChatMessageHeader](/ui-kit/ios/message-header), [CometChatMessageList](/ui-kit/ios/message-list), [CometChatMessageComposer](/ui-kit/ios/message-composer), [CometChatCompactMessageComposer](/ui-kit/ios/compact-message-composer), [CometChatThreadedMessageHeader](/ui-kit/ios/threaded-messages-header), `CometChatMessagePreview`, [CometChatSearch](/ui-kit/ios/search) |
| Calls | [CometChatIncomingCall](/ui-kit/ios/incoming-call), [CometChatOutgoingCall](/ui-kit/ios/outgoing-call), [CometChatOngoingCall](/ui-kit/ios/ongoing-call), [CometChatCallButtons](/ui-kit/ios/call-buttons) |
| AI | [CometChatAIAssistanceChatHistory](/ui-kit/ios/ai-assistant-chat-history), `CometChatAIConversationStarter`, `CometChatAISmartReply`, `CometChatAIConversationSummary` |
| Other screens and views | `CometChatCreatePoll`, `CometChatScopeChange`, `CometChatReactionList`, `CometChatActionSheet`, `CometChatMediaViewer`, `CometChatMediaRecorder`, `CometChatEmojiKeyboard`, `CometChatStickerKeyboard` |

Base views such as avatars, message bubbles, receipts, dates and badges do not have their own `set(layoutDirection:)`. Inside a component they take that component's direction. Used on their own, they follow the kit-level value.

---

## How the Direction Is Resolved

For each view, the kit uses the first of these that applies:

1. Audio and video players, and the other parts listed in [What Stays Left to Right](#what-stays-left-to-right), are always left to right
2. The component's own `set(layoutDirection:)` value
3. The direction of the nearest enclosing kit component
4. The kit-level value
5. Your app's layout direction

Screens, alerts and sheets that a component opens take that component's direction.

### Changes Apply to New Components

A component reads the kit-level value once, when it is created. A change made with `CometChatUIKit.set(layoutDirection:)` applies to components created afterwards. Components that already exist keep the direction they were created with.

After you change the kit-level direction, build your open screens again:

<Tabs>
<Tab title="Swift">
```swift lines
func applyKitDirection(_ direction: UIUserInterfaceLayoutDirection?, in window: UIWindow) {
CometChatUIKit.set(layoutDirection: direction)

// Existing components keep their direction, so create the screen again
let conversations = CometChatConversations()
window.rootViewController = UINavigationController(rootViewController: conversations)
}
```
</Tab>
</Tabs>

### Order of Calls Around Init

`CometChatUIKit.init(uiKitSettings:)` applies the direction from its settings when the initialization succeeds. This affects a kit-level call made around it:

| When you call `CometChatUIKit.set(layoutDirection:)` | Result |
|------|--------|
| Before you call `CometChatUIKit.init(uiKitSettings:)` | Replaced when the initialization succeeds. The kit uses the direction in the settings, or follows your app if the settings have none |
| After you call `CometChatUIKit.init(uiKitSettings:)` | Wins over the direction in the settings, whether it runs before or after the initialization completes |

<Warning>
If you set the direction before you initialize the kit, give it with `UIKitSettings.set(layoutDirection:)`. A `CometChatUIKit.set(layoutDirection:)` call made before `CometChatUIKit.init(uiKitSettings:)` is replaced when the initialization succeeds.
</Warning>

---

## What Stays Left to Right

Media playback reads left to right, as in system players. The following parts do not mirror under any direction setting, including when your app itself runs right to left:

| Part | Behavior |
|------|----------|
| Audio bubble | The player, its controls and its waveform stay left to right |
| Video bubble | The play control and thumbnail overlay stay left to right |
| Video player in the media viewer | The player and its controls stay left to right |
| Audio files in a multi-attachment bubble | Each audio row and its slider stay left to right |
| Video tiles in a multi-attachment bubble | The play control and duration stay left to right |
| Attachments in the composer | The audio player, and a video's play overlay and duration, stay left to right |
| Voice recorder | The waveform, the record, play and pause controls, and the duration stay left to right |
| Code blocks | Code stays left to right |

The rest of the voice recorder does mirror. In a right-to-left layout, the row of controls is reversed: the send button is on the left, and the delete button is on the right.

---

## Message Text and Icons

### Message Text Follows Its Own Language

The kit does not force a direction on message text. Each paragraph is aligned and read from its own language: an English message in a right-to-left chat still reads left to right, and an Arabic message in a left-to-right chat still reads right to left.

### Directional Icons Mirror

The kit's built-in icons that point in a direction mirror in a right-to-left layout. Examples are the back button of the message header, the send button of the composer, the reply and thread icons, and the call direction arrows.

An icon you supply through a style is drawn as you provide it. To make your own icon mirror, use UIKit's `imageFlippedForRightToLeftLayoutDirection()`:

<Tabs>
<Tab title="Swift">
```swift lines
// A custom back icon that mirrors in a right-to-left layout
CometChatMessageHeader.style.backButtonIcon = UIImage(systemName: "arrow.left")?
.imageFlippedForRightToLeftLayoutDirection()
```
</Tab>
</Tabs>

---

## Next Steps

<CardGroup cols={3}>
<Card title="Localization" href="/ui-kit/ios/localize">
Set the language of the UI Kit and override its strings
</Card>
<Card title="Theme Introduction" href="/ui-kit/ios/theme-introduction">
Customize the visual appearance of UI components
</Card>
<Card title="Component Styling" href="/ui-kit/ios/component-styling">
Apply custom styles to individual components
</Card>
</CardGroup>
Loading