wrapRTL

⚠️ Version Recommendation: Always install and use the latest version of rtl-text-tools (npm install rtl-text-tools@latest). While this specific feature was introduced in an earlier version, the latest release includes crucial bug fixes, better edge-case handling, and improved legacy browser compatibility. Avoid pinning your project to an old version just to use this function.

Wraps text with invisible Unicode bidirectional (bidi) control characters to force RTL rendering. This is essential for plain-text contexts where CSS properties like direction or unicode-bidi cannot be applied, such as in email clients, <textarea> elements, terminal outputs, or plain text files.

It uses the RLE (Right-to-Left Embedding) and PDF (Pop Directional Formatting) characters, prefixed with an RLM (Right-to-Left Mark), ensuring maximum compatibility even in very old browsers (IE8+).

📝 Syntax

wrapRTL(text: string): string

Parameters

Name	Type	Description
text	string	The text to wrap with bidi control characters.

Returns

• string : The text wrapped with RTL bidi markers.
• Returns the original string unchanged if it is empty, null, or undefined.

💡 Examples

Basic Usage

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

wrapRTL("مرحبا"); 
// Output: "\u200F\u202Bمرحبا\u202C"
// (Visually looks exactly like "مرحبا", but is forced to render RTL)

Plain-Text Email Context

When sending an email, you often cannot rely on CSS. Wrapping the text ensures it renders correctly in the recipient's email client:

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

const emailBody = `
Hello,
Here is the tracking number and name: ${wrapRTL("مرحبا, رقم 123")}
Thank you!
`;

Combining with fixRTL

You can use the addBidiMarkers option in the main fixRTL() function to achieve the exact same result while also fixing digits and punctuation:

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

fixRTL("مرحبا, رقم 123", { addBidiMarkers: true });
// Output: "\u200F\u202B...مرحبا، رقم ۱۲۳\u202C"

⚙️ Technical Details & Compatibility

• How It Works: It prepends the Right-to-Left Mark (RLM, \u200F) and Right-to-Left Embedding (RLE, \u202B) characters, and appends the Pop Directional Formatting (PDF, \u202C) character. These are zero-width, invisible characters that instruct the Unicode Bidirectional Algorithm to treat the enclosed text as strictly RTL.
• Legacy Compatibility: The RLE/PDF control characters are widely supported (IE8+) and are the most reliable way to force correct bidi rendering in older browsers or environments that lack CSS support.
• Safe Execution: If the input is falsy (e.g., null, undefined, or ""), it immediately returns the input without throwing an error.

📜 Version History

• v1.0.0: Added wrapRTL to provide Unicode bidi markers for plain-text contexts.