Use Cases

Handling Right-to-Left (RTL) text isn't just about setting dir="rtl" in CSS. When you mix RTL languages (Arabic, Persian, Hebrew) with LTR content (English, URLs, numbers), the Unicode Bidirectional Algorithm often causes text to visually break, brackets to flip, and numbers to jump to the wrong side of the screen.

rtl-text-tools solves these rendering and formatting issues across a variety of real-world applications. Below are the most common use cases and how to implement the library to solve them.

📧 1. Email Clients

The Problem: Email clients (like Gmail, Outlook, or Apple Mail) notoriously strip out most CSS, including direction and unicode-bidi. If you send an Arabic email containing an English tracking number or a URL, the text will often render in the wrong order, making it completely unreadable.

The Solution: Since you cannot rely on CSS in emails, you must inject invisible Unicode bidirectional control characters directly into the text.

How to use it: Use the addBidiMarkers: true option in fixRTL, or use wrapRTL and wrapLTR for specific inline elements.

import { fixRTL, wrapLTR } from 'rtl-text-tools';

// For the main body of the email
const emailBody = fixRTL("مرحبا، رقم الشحنة الخاص بك هو...", { 
  addBidiMarkers: true 
});

// For safely embedding an English URL inside the Arabic text
const url = wrapLTR("https://example.com/track/123");
const fullText = `للتتبع الشحنة يرجى زيارة: ${url}`;

📝 2. Text Editors & CMS

The Problem: When users type in Rich Text Editors (like Draft.js, Quill, TinyMCE) or Content Management Systems, pasting English URLs, code snippets, or numbers into an RTL paragraph often causes the cursor to jump erratically, and parentheses () visually flip to )(.

The Solution: You need to normalize the direction of mixed paragraphs and fix bracket rendering without altering the underlying HTML structure.

How to use it: Use normalizeDirection for mixed paragraphs, fixBrackets to keep parentheses intact, and apply getRTLStyles() to the editor container.

import { normalizeDirection, fixBrackets, getRTLStyles } from 'rtl-text-tools';

// Fix reversed brackets in user-generated content
const userContent = fixBrackets("هذا نص (مختلط) مع أرقام 123");

// Apply styles to the editor wrapper
const editorStyles = getRTLStyles(); 
// { direction: 'rtl', unicodeBidi: 'embed' }

💬 3. Chat Applications

The Problem: In real-time messaging apps, you never know what language the next incoming message will be in. If a user switches from English to Arabic, the message bubble needs to dynamically align to the right, and the text needs to be properly formatted.

The Solution: Dynamically detect the direction of the incoming message on the fly, apply text fixes, and conditionally render the UI alignment.

How to use it: Use hasRTL to detect the message language, and fixRTL to clean up the text before rendering.

import { hasRTL, fixRTL } from 'rtl-text-tools';

function MessageBubble({ text }) {
  const isRTL = hasRTL(text);
  
  return (
    <div 
      className={isRTL ? 'message-rtl' : 'message-ltr'}
      style={{ textAlign: isRTL ? 'right' : 'left' }}
    >
      {fixRTL(text)}
    </div>
  );
}

🛒 4. E-commerce & Localization

The Problem: Displaying prices, product titles, and user reviews in regional formats. A price like 123 needs to be displayed as ۱۲۳ in Iran or ١٢٣ in Saudi Arabia. Furthermore, user reviews often contain mixed punctuation that looks unprofessional if not converted.

The Solution: Use targeted digit conversion for prices and the all-in-one fixRTL for product descriptions and reviews.

How to use it: Use toPersianDigits or toArabicDigits for financial data, and fixRTL for text content.

import { toPersianDigits, fixRTL } from 'rtl-text-tools';

// Format prices for an Iranian storefront
const price = toPersianDigits("1,250,000"); 
// Output: "۱,۲۵۰,۰۰۰"

// Clean up a user review before saving to the database
const review = fixRTL("المنتج رائع, لكن السعر عالي?");
// Output: "المنتج رائع، لكن السعر عالي؟"

🔔 5. Push Notifications & System Alerts

The Problem: Mobile OS notifications (iOS/Android lock screens) and desktop toast notifications often render plain text without any CSS context. If a notification is in Arabic but contains an English app name or number, it will visually break on the lock screen.

The Solution: Wrap the notification payload in Unicode bidi markers before sending it to the push notification service.

How to use it:

import { wrapRTL } from 'rtl-text-tools';

const notificationPayload = {
  title: wrapRTL("مرحبا بك في التطبيق"),
  body: wrapRTL("لديك 5 رسائل جديدة")
};

📊 6. Data Visualization & Charts

The Problem: When rendering charts (using Chart.js, Recharts, etc.) for RTL users, axis labels, tooltips, and legends often misalign or render numbers in Latin digits instead of the local numeral system.

The Solution: Process the chart labels and tooltip formatters through the library before passing them to the charting library.

How to use it:

import { toArabicDigits } from 'rtl-text-tools';

const chartData = {
  labels: ["يناير", "فبراير", "مارس"].map(toArabicDigits),
  datasets: [{
    data: [100, 200, 300].map(val => toArabicDigits(String(val)))
  }]
};

🚀 Summary of Functions by Use Case

Use Case	Primary Functions Needed
Email Clients	fixRTL (with addBidiMarkers), wrapRTL, wrapLTR
Text Editors	normalizeDirection, fixBrackets, getRTLStyles
Chat Apps	hasRTL, fixRTL
E-commerce	toPersianDigits, toArabicDigits, fixRTL
Notifications	wrapRTL
Charts	toPersianDigits, toArabicDigits

💡 Need help with a specific scenario?

If your use case isn't covered here, check out the API Reference for a full list of available functions, or open an issue on GitHub to discuss your requirements!