toQuranicBrackets

⚠️ 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.

Converts standard Latin parentheses () into ornate Quranic brackets ﴿ ﴾. This function is highly requested for Quranic applications, Islamic texts, and religious publications where standard parentheses look visually out of place next to Arabic script.

Because this function is designed for Right-to-Left (RTL) text, it correctly maps the standard opening parenthesis ( to the visual right-side bracket ﴿ (U+FD3F), and the standard closing parenthesis ) to the visual left-side bracket ﴾ (U+FD3E).

📝 Syntax

toQuranicBrackets(text: string): string

Parameters

Name	Type	Description
text	string	The text containing standard parentheses to convert.

Returns

• string : Returns the text with standard parentheses replaced by ornate Quranic brackets. Returns the original string unchanged if it is empty, null, or contains no standard parentheses.

💡 Examples

Basic Usage

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

toQuranicBrackets("(البقرة)");         
// Output: "﴿البقرة﴾"

toQuranicBrackets("سورة الفاتحة (1)"); 
// Output: "سورة الفاتحة ﴿1﴾"

toQuranicBrackets("Hello (world)");    
// Output: "Hello ﴿world﴾" (Note: visually flipped in RTL context)

Real-World Quranic Context

When rendering verse numbers or Surah names, standard parentheses often look too small or disconnected from the Arabic text. Quranic brackets provide a much more professional and traditional appearance:

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

const verseNumber = toArabicDigits("(255)"); // "(٢٥٥)"
const quranicVerse = toQuranicBrackets(verseNumber); 
// Output: "﴿٢٥٥﴾" (Ayat al-Kursi verse number)

⚙️ Technical Details & Compatibility

• RTL Visual Ordering: In standard LTR typing, you type ( then text then ). In an RTL context, the opening bracket appears on the right, and the closing bracket appears on the left. This function maps:
  • ( (U+0028) ➔ ﴿ (U+FD3E ORNATE LEFT PARENTHESIS / visually right in RTL)
  • ) (U+0029) ➔ ﴾ (U+FD3F ORNATE RIGHT PARENTHESIS / visually left in RTL)
• Global Replacement: It uses global regular expressions (/\(/g and /\)/g) to ensure all parentheses in the string are converted, not just the first occurrence.
• IE11 Compatibility: The function relies on standard String.prototype.replace() and intentionally avoids modern methods like String.prototype.replaceAll() to ensure full compatibility with legacy browsers like IE11.
• Safe Execution: If the input is falsy (e.g., null, undefined, or ""), it immediately returns the input without throwing an error.

📜 Version History

• v1.2.0: Added toQuranicBrackets() to convert standard brackets to ornate Quranic brackets as part of the Arabic enhancements update.