Table of Contents

• 🌟 Overview
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 📖 Parameters
• 💡 Examples
• 🕌 Special Features
• 🎨 Advanced Usage
• 🤝 Contributing
• 📋 Roadmap
• 🐛 Known Issues
• ⭐ Show Your Support

🌟 Overview

Arabic Justified Text is a Flutter package that provides beautiful text justification for Arabic text using Kashida (ـ) instead of adding extra spaces between words. This creates a more natural and aesthetically pleasing appearance for justified Arabic text.

✨ Features

• ✅ Smart Kashida Distribution - Intelligently distributes Kashida across words
• ✅ Diacritics Support - Properly handles Arabic diacritics (Tashkeel)
• ✅ Mixed Text Support - Works with Arabic and English text together
• ✅ Line Break Support - Respects \n characters in text
• ✅ Theme Integration - Inherits default text styles from your app theme
• ✅ RichText Support - Advanced styling with ArabicJustifiedRichText
• ✅ Sacred Text Handling - Automatically excludes "Allah" (اللّٰه) from Kashida
• ✅ Customizable Exclusions - Add your own words to exclude from Kashida
• ✅ Performance Optimized - Efficient text processing
• ✅ RTL/LTR Support - Configurable text direction (RTL by default)

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  arabic_justified_text: ^0.0.8

Then run:

flutter pub get

🚀 Quick Start

Basic Usage

import 'package:arabic_justified_text/arabic_justified_text.dart';

ArabicJustifiedText(
  'في عالم التكنولوجيا الحديثة، أصبحت تطبيقات الهاتف المحمول جزءاً أساسياً من حياتنا اليومية.',
)

With Custom Style

ArabicJustifiedText(
  'النص العربي هنا',
  style: TextStyle(
    fontSize: 18,
    fontWeight: FontWeight.bold,
    color: Colors.blue,
  ),
)

With All Options

ArabicJustifiedText(
  'أشهد أن لا إله إلا اللّٰه، وأن محمدًا رسول اللّٰه',
  style: TextStyle(fontSize: 16, height: 1.8),
  enableKashida: true,
  maxLines: 5,
  overflow: TextOverflow.ellipsis,
  textAlign: TextAlign.justify,
  textDirection: TextDirection.rtl,
  excludedWords: ['محمدا', 'رسول'], // Optional: exclude specific words
)

📖 Parameters

ArabicJustifiedText

For simple text with single style.

Parameter	Type	Default	Description
text	String	required	The text to display
style	TextStyle?	null	Text style (inherits from theme if null)
maxLines	int?	null	Maximum number of lines
overflow	TextOverflow?	null	How to handle text overflow
textDirection	TextDirection	TextDirection.rtl	Text direction (RTL/LTR)
textAlign	TextAlign	TextAlign.justify	Text alignment
enableKashida	bool	true	Enable/disable Kashida justification
excludedWords	List<String>?	null	Words to exclude from Kashida

ArabicJustifiedRichText

For complex text with multiple styles.

Parameter	Type	Default	Description
textSpan	InlineSpan	required	The text span to display
maxLines	int?	null	Maximum number of lines
overflow	TextOverflow?	null	How to handle text overflow
textDirection	TextDirection	TextDirection.rtl	Text direction (RTL/LTR)
textAlign	TextAlign	TextAlign.justify	Text alignment
enableKashida	bool	true	Enable/disable Kashida justification
excludedWords	List<String>?	null	Words to exclude from Kashida

💡 Examples

1. Simple Text

ArabicJustifiedText(
  'مرحباً بك في عالم البرمجة الجميل',
)

2. Text with Diacritics (Tashkeel)

ArabicJustifiedText(
  'بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ',
  style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
)

3. Multi-line Text with Line Breaks

ArabicJustifiedText(
  '''السطر الأول من النص
السطر الثاني من النص
السطر الثالث من النص''',
  style: TextStyle(fontSize: 16, height: 2.0),
)

4. Mixed Arabic and English

ArabicJustifiedText(
  'استخدم Flutter لبناء تطبيقات mobile رائعة',
  style: TextStyle(fontSize: 18),
)

5. With Maximum Lines

ArabicJustifiedText(
  'نص طويل جداً يحتوي على الكثير من الكلمات والجمل...',
  maxLines: 3,
  overflow: TextOverflow.ellipsis,
)

6. Toggle Kashida On/Off

bool useKashida = true;

ArabicJustifiedText(
  'النص العربي هنا',
  enableKashida: useKashida,
)

🕌 Special Features

Respectful Handling of Sacred Words

The package automatically excludes the word (اللّٰه) and its variations from Kashida application, preserving its traditional appearance.

// The word "اللّٰه" will never automatically receive Kashida
ArabicJustifiedText('بسم اللّٰه الرحمن الرحيم')
// Result: بـسـم اللّٰه الـرحمـن الـرحيـم (اللّٰه remains unchanged)

Automatically excluded variations:

• اللّٰه، اللَّه، ٱللّٰه، للّٰه، وللّٰه، واللّٰه، باللّٰه، تاللّٰه

Custom Word Exclusions

You can exclude additional words from Kashida application:

ArabicJustifiedText(
  'اللهم صل وسلم وبارك على نبينا محمد وعلى آله وصحبه أجمعين',
  excludedWords: ['محمد', 'اللهم'],
)

Use cases:

• 📖 Religious texts (prophets' names, sacred terms)
• 📚 Brand names or proper nouns
• ✍️ Technical terms that should remain unchanged

🎨 Advanced Usage

Using ArabicJustifiedRichText

⚠️ Important: ArabicJustifiedRichText currently does not support WidgetSpan. If your text contains widgets (icons, images, etc.), the Kashida justification will be disabled and it will fall back to standard RichText rendering.

For complex text with multiple styles, colors, or interactions:

ArabicJustifiedRichText(
  enableKashida: true,
  textSpan: TextSpan(
    style: TextStyle(fontSize: 18),
    children: [
      TextSpan(text: 'النص العادي '),
      TextSpan(
        text: 'النص العريض',
        style: TextStyle(fontWeight: FontWeight.bold, color: Colors.blue),
      ),
      TextSpan(text: ' المزيد من النص'),
    ],
  ),
)

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report Bugs - Open an issue describing the bug
2. 💡 Suggest Features - Share your ideas for improvements
3. 🔧 Submit Pull Requests - Fix bugs or add features
4. 📖 Improve Documentation - Help make docs better
5. ⭐ Star the Repo - Show your support!

📋 Roadmap

• WidgetSpan support for ArabicJustifiedRichText - Allow mixing text and widgets with Kashida
• Add more customization options for Kashida density
• Performance improvements for very long texts
• Support for other RTL languages (Persian, Urdu)

🐛 Known Issues

• WidgetSpan not supported in ArabicJustifiedRichText - If you need to mix text with widgets (icons, images), use enableKashida: false or use standard RichText
• Very long words might overflow on narrow screens (use maxLines to handle)
• Performance may vary with extremely long texts (>10,000 characters)

⭐ Show Your Support

If you find this package useful, please consider giving it a ⭐ on GitHub!