FAQ and Troubleshooting

Welcome to the FAQ and Troubleshooting guide for rtl-text-tools. If you are experiencing unexpected behavior, rendering issues, or just have general questions about the library, you will likely find your answer here.

📖 Frequently Asked Questions (FAQ)

1. Why isn't fixRTL() changing my text?

Answer: As of v1.1.0, fixRTL() is strictly precise. Before applying any transformations, it runs a quick hasRTL() check. If your text does not contain any actual RTL characters (Arabic, Persian, Hebrew, etc.), the function will return the original string completely unchanged. This is a deliberate design choice to prevent accidentally modifying English or LTR text.

• Fix: Ensure your text actually contains RTL characters. If you want to force digit conversion on purely English text, use the specific functions directly (e.g., toPersianDigits("123")) instead of fixRTL().

2. My numbers are converting to Persian (۱۲۳), but I want Arabic (١٢٣). How do I change this?

Answer: By default, fixRTL() targets Persian. You need to explicitly tell it to use Arabic.

• Fix: Pass the lang option:

  fixRTL("مرحبا 123", { lang: 'arabic' }); 
  // or simply: fixRTL("مرحبا 123", 'arabic');

3. Does this library work in Node.js, Next.js, or Server-Side Rendering (SSR)?

Answer: Yes! All text processing functions (fixRTL, hasRTL, toPersianDigits, etc.) are pure JavaScript and have zero dependencies. They work perfectly in Node.js, Next.js SSR, and edge environments.

• Note: The only function that requires the browser DOM is setDirAttribute(). If you are using Next.js, make sure to call setDirAttribute() inside a useEffect hook or a client-side event handler so it doesn't throw a window/document is undefined error during server rendering.

4. Do I need to include the "dom" library in my tsconfig.json to use this?

Answer: No. While setDirAttribute() interacts with the DOM, its TypeScript definition uses structural typing (it just looks for an object with a setAttribute method). This means you can use the library in non-DOM TypeScript projects (like Node.js backend or React Native) without forcing the "dom" lib into your tsconfig.json.

5. Is this library compatible with Internet Explorer 11 (IE11)?

Answer: Yes, fully. The compiled output targets ES5. It uses var instead of const/let, regular functions instead of arrow functions, and standard String.prototype.replace() with global regexes instead of modern methods like String.prototype.replaceAll(). It also avoids the ES6 u (unicode) regex flag to ensure maximum legacy browser compatibility.

🛠️ Troubleshooting Common Issues

Issue: Text in my <textarea> or Email Client is still rendering backwards/mixed up.

The Cause: CSS properties like direction: rtl and unicode-bidi do not work in plain-text environments like <textarea>, <input>, terminal outputs, or the body of HTML emails (where CSS is often stripped). The Solution: You must inject invisible Unicode bidirectional control characters directly into the text string.

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

// Option 1: Use the addBidiMarkers option
const emailText = fixRTL("مرحبا 123", { addBidiMarkers: true });

// Option 2: Wrap specific parts manually
const safeText = wrapRTL("مرحبا") + " " + wrapLTR("https://example.com");

Issue: My parentheses/brackets are flipped )( instead of ().

The Cause: The Unicode Bidirectional Algorithm often struggles with neutral characters like brackets when they are surrounded by RTL text, causing them to visually reverse. The Solution: Use the bracket fixing utility. It injects an invisible Left-to-Right Mark (LRM) inside the brackets to force the browser to render them correctly.

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

// Or just ensure fixBrackets is enabled (it is by default) in fixRTL
const fixedText = fixRTL("هذا نص (مختلط)"); 

Issue: The ellipsis ... is appearing on the wrong side of the text.

The Cause: In RTL languages, truncation ellipses should visually appear at the start (the right side) of the text, which is the logical beginning of the string. The Solution: fixRTL() handles this automatically via moveEllipsis(). If you are using individual functions, make sure you are calling moveEllipsis().

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

moveEllipsis("مرحبا..."); // Output: "...مرحبا"

Issue: React component is flickering or text direction is jumping on load.

The Cause: This usually happens when you are applying RTL styles via JavaScript after the component mounts, rather than rendering it with the correct styles initially. The Solution: Instead of using setDirAttribute on mount, use the getRTLStyles() helper to apply the styles synchronously during the initial React render.

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

function MyComponent() {
  // Applied immediately on first render, no flickering
  return <div style={getRTLStyles()}>مرحبا</div>;
}

🌐 Framework-Specific Tips

Framework	Recommendation
React	Use getRTLStyles() for inline styles. Use fixRTL() directly inside your JSX {fixRTL(text)}.
Next.js	All text functions are SSR-safe. Wrap setDirAttribute() in a useEffect to avoid hydration errors.
Vue.js	Create a custom directive (e.g., v-rtl) that applies getRTLStyles() or calls setDirAttribute() in the mounted hook.
Angular	Use a custom pipe (e.g., `{{ text
React Native	Text functions work perfectly. For styling, use the returned objects from getRTLStyles() directly in your StyleSheet.

🐛 Still Need Help?

If you've tried the solutions above and are still facing issues, or if you've found a bug in the library:

1. Check the API Reference to ensure you are passing the correct parameters.
2. Search existing discussions on the GitHub Issues page.
3. If it's a new bug, please open a new issue and include:
   • The exact string you are passing to the function.
   • The options you are using.
   • The expected output vs. the actual output.
   • Your environment (Browser, Node.js version, React version, etc.).