Getting Started

Welcome to rtl-text-tools! This guide will help you install the package and get up and running with basic RTL text processing in just a few minutes.

📦 Installation

Install the package using your preferred package manager. The library has zero runtime dependencies and works all the way back to IE11.

# Using npm
npm install rtl-text-tools

# Using yarn
yarn add rtl-text-tools

# Using pnpm
pnpm add rtl-text-tools

💡 Basic Usage

The primary entry point is the fixRTL() function. By default, it runs a suite of transformations on digits, punctuation, and ellipsis, tailored for Persian text. For greater accuracy, you can specify an alternative RTL language (e.g., Arabic or Hebrew) to trigger locale-specific formatting rules.

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

// 1. Default Usage (Persian)
const persianText = fixRTL('مرحبا, رقم 123...');
console.log(persianText); 
// Output: "...مرحبا، رقم ۱۲۳" 
// (Converts to Persian digits, fixes punctuation, and moves ellipsis)

// 2. Switch to Arabic
const arabicText = fixRTL('مرحبا, رقم 123...', { lang: 'arabic' });
console.log(arabicText);
// Output: "...مرحبا، رقم ١٢٣" 
// (Converts to Arabic-Indic digits instead)

// 3. Safe for English/LTR text
const englishText = fixRTL('Hello, world!');
console.log(englishText); 
// Output: "Hello, world!" 
// (Automatically detects no RTL characters and leaves it completely unchanged)

Note: As of v1.1.0, fixRTL is strictly precise and will only apply transformations when RTL characters are actually present in the text.

⚡ Quick Examples

Here are a few quick examples of what you can do with the individual utility functions. (For a full list of parameters and return types, see the API Reference).

Fixing Punctuation

Convert standard LTR punctuation to their proper RTL equivalents.

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

convertPunctuation('مرحبا, كيف حالك?'); 
// Output: 'مرحبا، كيف حالك؟'

Handling Mixed RTL/LTR Text

Fix readability issues when English/URLs are mixed inside an RTL paragraph.

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

const mixedText = "من در پارکی راه می رفتم Do not Park here";
console.log(normalizeDirection(mixedText));
// The text will now render properly with an RTL base direction

Quick React Integration

Use the built-in style helpers to easily apply RTL direction in your React components.

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

function PriceTag({ price }) {
  return (
    <span style={getRTLStyles()}>
      {fixRTL(`قیمت: ${price}`)}
    </span>
  );
}