react-native-arabic-autoheight-text/README.md

Smart Arabic/RTL text renderer for React Native using WebView: auto height, proper justification, line clamp, and skeleton loading.

# 🇸🇦 react-native-arabic-autoheight-text

**Beautiful Arabic & RTL text inside WebView — Auto Height + Proper Typography**

[![npm version](https://img.shields.io/npm/v/react-native-arabic-autoheight-text.svg)](https://www.npmjs.com/package/react-native-arabic-autoheight-text)
[![license](https://img.shields.io/npm/l/react-native-arabic-autoheight-text.svg)](./LICENSE)
[![platforms](https://img.shields.io/badge/platforms-ios%20%7C%20android-lightgrey.svg)]()
[![TypeScript Friendly](https://img.shields.io/badge/TypeScript-ready-blue.svg)]()

A tiny, drop-in React Native component for **Arabic / RTL text rendering** with:

* 🚀 Auto height inside WebView (no scrolling)
* 🕌 Perfect RTL direction + proper justification
* ✂️ Line clamping using CSS (`-webkit-line-clamp`)
* 🎨 Converts `TextStyle` → WebView CSS
* 🦴 Built-in / custom Skeleton loader
* 🌙 Adaptive skeleton for dark mode
* 📏 Supports fixed or dynamic layout with accuracy

Designed for:
**News, corporate content, About screens, product descriptions, long Arabic articles…**

---

## 🎥 Demo

![react-native-arabic-autoheight-text Demo](https://github.com/ahmedhegazydev/react-native-arabic-autoheight-text/blob/master/src/assets/demo.gif)

---

## 📦 Installation

```bash
yarn add react-native-arabic-autoheight-text react-native-webview react-native-skeleton-placeholder
# OR
npm install react-native-arabic-autoheight-text react-native-webview react-native-skeleton-placeholder
```

iOS

```bash
cd ios && pod install
```

---

## 🧩 Usage

### Basic Example

```tsx
<RtlTextView
  text="هذا النص سيتم ضبط ارتفاعه تلقائياً حسب المحتوى"
  textStyle={{ fontSize: 18, color: '#333' }}
/>
```

---

### Line Clamping

```tsx
<RtlTextView
  text="نص عربي طويل سيتم قصه بعد ثلاثة أسطر فقط..."
  numberOfLines={3}
  textStyle={{ fontSize: 16 }}
/>
```

---

### Custom Skeleton

```tsx
<RtlTextView
  text="جارٍ تحميل المحتوى..."
  textStyle={{ fontSize: 16 }}
  renderSkeleton={() => (
    <View style={{ height: 80, backgroundColor: '#DDD', borderRadius: 8 }} />
  )}
/>
```

---

### 🔥 Skeleton padding behavior (Recommended)

> Skeleton auto-matches **horizontal text padding**
> → perfect alignment during loading

```tsx
<RtlTextView
  text={longArabicText}
  textStyle={{ fontSize: 16, marginHorizontal: 20 }}
/>
```

💡 Skeleton width = `full width — horizontal text margins`

### Full-width Skeleton (no margin)

```tsx
<RtlTextView
  text={longArabicText}
  textStyle={{ marginHorizontal: 20 }}
  matchTextHorizontalPadding={false}
/>
```

---

### WebView custom props

```tsx
<RtlTextView
  text="Arabic Text"
  textStyle={{ fontSize: 16 }}
  webviewProps={{ showsVerticalScrollIndicator: false }}
/>
```

---

## 🔧 Props

| Prop                         | Type                                             | Default        | Description                                |
| ---------------------------- | ------------------------------------------------ | -------------- | ------------------------------------------ |
| `text`                       | `string`                                         | —              | Arabic text content                        |
| `textStyle`                  | `StyleProp<TextStyle> \| StyleProp<TextStyle>[]` | —              | Converted to CSS inside WebView            |
| `numberOfLines`              | `number`                                         | `undefined`    | Max visible lines using CSS clamp          |
| `isDark`                     | `boolean`                                        | `false`        | Changes skeleton theme                     |
| `fontFamily`                 | `string`                                         | from textStyle | Override web font                          |
| `renderSkeleton`             | `() => React.ReactNode`                          | default        | Custom skeleton UI                         |
| `skeletonHeight`             | `number`                                         | `100`          | Height during loading                      |
| `skeletonProps`              | `Record<string, any>`                            | `{}`           | Props forwarded to Skeleton                |
| `webviewProps`               | `WebViewProps`                                   | `{}`           | Forwarded to WebView                       |
| `containerStyle`             | `StyleProp<ViewStyle>`                           | `{}`           | Outer wrapper styling                      |
| `matchTextHorizontalPadding` | `boolean`                                        | `true`         | Copy text’s horizontal padding to skeleton |

---

## 🎨 Styling Details

Extracted CSS from last-defined `textStyle` value:

* `color`, `backgroundColor`
* `fontSize`, `fontWeight`, `lineHeight`, `fontFamily`
* `textAlign`, RTL alignment enhancements
* Margins: `marginStart`, `marginEnd`, `marginHorizontal`, `marginVertical`
* WebView auto background transparency while loading

> 💡 `marginStart` + `marginEnd` recommended for RTL UI

---

## 🧠 Why WebView?

React Native `<Text>` still suffers with:

❌ Justified Arabic glyph shaping
❌ Broken connections in RTL
❌ Poor multi-line rendering
❌ No CSS multi-line clamp

This component fixes all of the above ✔️

---

## 🛠 Troubleshooting

| Issue                          | Fix                                         |
| ------------------------------ | ------------------------------------------- |
| Skeleton too skinny            | remove `matchTextHorizontalPadding={false}` |
| Wrong first height             | Font loader will update automatically       |
| Background shows while loading | WebView background auto-hidden              |

---

## 🗺 Roadmap

🔹 Mixed LTR/RTL detection
🔹 “Read more” collapsed text
🔹 Full custom CSS styles
🔹 Accessibility enhancements

PRs welcome ✨

---

## 👤 Author

Built with ❤️ by **Ahmed Hegazy**
📧 [ahmedmhegazy.eg@gmail.com](mailto:ahmedmhegazy.eg@gmail.com)
🐙 GitHub: @ahmedhegazydev

---

## 📄 License

MIT — Free for commercial & open-source use