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: ^1.0.2

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.

ArabicJustifiedRichText #

For complex text with multiple styles.

💡 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 #

• Last word wrapping with certain fonts (e.g., Amiri Quran) - With some Quranic fonts, the last word of a line may wrap to the next line due to Kashida width calculations. This happens because Kashida characters in Quranic fonts are wider than in regular fonts
• 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!