Table of contents

• Why TeleImage?
• Features
• Requirements
• Installation
• Quick start
• API
• Prefetch & cache
• Architecture
• Lineage & license
• Contributing

Why TeleImage?

React Native's <Image> works well for many screens, but large grids (galleries, chat attachments, photo feeds) often show long blank frames, GC jank, and memory pressure.

TeleImage targets the same class of optimizations Telegram uses: near-instant ThumbHash placeholders, background decode and caching, bitmap pooling on Android, and releasing backing stores when list cells recycle.

| | <Image> (RN) | <TeleImage> | | --- | --- | --- | | Drawing | UIImageView / ImageView | CALayer / Canvas + BitmapShader | | Placeholder | Often empty until load | ThumbHash decoded in sub‑millisecond time | | Memory | Limited bitmap reuse control | BitmapPool + LRU (Android), budgeted caches (iOS) | | Fade | Often JS Animated | Native crossfade (fewer bridge trips for the transition) |

Features

• ThumbHash / BlurHash strings — blurred preview without waiting on the network.
• Download priority (priority) — mark on-screen images as high.
• resizeMode — cover | contain | stretch.
• Crossfade — fadeDuration in ms; use 0 to disable. JS default is 150ms.
• Native rendering — Android: Canvas + shader; iOS: CALayer / CGImageSource style pipeline (not the default ImageView path).
• List-friendly — Fabric prepareForRecycle drops bitmap / backing when cells leave the viewport.
• Prefetch (Android) — native TeleImageModule can warm disk + memory cache (see below).

Lower-level details (HTTP/2, SHA-256 disk keys, etc.) live in source comments and evolve per release.

Requirements

• React Native New Architecture (Fabric) — uses Codegen; Legacy Architecture is not supported.
• Recommended: React Native ≥ 0.76 (the example app in this repo uses 0.85).
• iOS & Android — standard CocoaPods / Gradle setup for native modules.

Installation

npm install react-native-tele-image
# or
yarn add react-native-tele-image

iOS — install pods in your app:

cd ios && pod install

Rebuild your app. For monorepos or Expo prebuild, follow your usual native-module workflow.

Quick start

import { TeleImage } from 'react-native-tele-image';

export function Banner() {
  return (
    <TeleImage
      source={{
        uri: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800',
        thumbhash: 'HBkSHYSIeHiPiHh4eJd4eFeEd3',
      }}
      style={{ width: 300, height: 200, borderRadius: 12 }}
      priority="high"
      resizeMode="cover"
      fadeDuration={150}
      onLoad={({ nativeEvent }) =>
        console.log(`Loaded ${nativeEvent.width}×${nativeEvent.height}`)
      }
      onError={({ nativeEvent }) =>
        console.warn('Failed:', nativeEvent.error)
      }
    />
  );
}

Tip: Generate a ThumbHash (~25–30 character base64-ish compact string) from the source image or return it from your API with image metadata — see ThumbHash.

API

TeleImage

| Prop | Type | Default | Description | | --- | --- | --- | --- | | source | { uri: string; thumbhash?: string } | required | Remote URL and optional ThumbHash | | style | ViewStyle | — | Layout: width, height, borderRadius, etc. | | resizeMode | 'cover' \| 'contain' \| 'stretch' | 'cover' | How the image fits the view | | priority | 'high' \| 'normal' \| 'low' | 'normal' | Download scheduling priority | | fadeDuration | number | 150 | Crossfade ms; 0 disables | | onLoad | (e) => void | — | nativeEvent: { width, height, source } | | onError | (e) => void | — | nativeEvent: { error, source } |

Exported types

import type {
  TeleImageProps,
  TeleImageSource,
  ImagePriority,
  ImageResizeMode,
  OnLoadEvent,
  OnErrorEvent,
} from 'react-native-tele-image';

Prefetch & cache

TeleImagePrefetch

Prefetch the next page before the user scrolls:

import { TeleImagePrefetch } from 'react-native-tele-image';

await TeleImagePrefetch.prefetch([
  { uri: 'https://example.com/a.jpg' },
  { uri: 'https://example.com/b.jpg', priority: 'low' },
]);

TeleImagePrefetch.cancel('https://example.com/a.jpg');
TeleImagePrefetch.cancelAll();

Android: When NativeModules.TeleImageModule is present, calls delegate to native (OkHttp + caches).

iOS: There is no equivalent native module in this package yet — prefetch may be a no-op until iOS support lands.

TeleImageCache

Public JS API:

import { TeleImageCache } from 'react-native-tele-image';

await TeleImageCache.clearMemory();
await TeleImageCache.clearDisk();
await TeleImageCache.clear();

const size = await TeleImageCache.getSize();
// { memory: number; disk: number; bitmapPool?: number }

Current status: The TypeScript implementation is a stub (resolved promises / zero sizes). Android already implements clearMemory, clearDisk, and getSize on TeleImageModule. Until the stub is wired, call NativeModules.TeleImageModule on Android if you need real cache control.

Architecture

┌─────────────────────────────────────────┐
│ JavaScript / TypeScript                 │
│ TeleImage · TeleImagePrefetch · Cache   │
└──────────────────┬──────────────────────┘
                   │ Fabric (Codegen)
┌──────────────────▼──────────────────────┐
│ Native                                  │
│  iOS: TeleImageView (+ ThumbHash, …)    │
│  Android: TeleImageView + HttpTask,     │
│           MemCache, BitmapPool, Module  │
└─────────────────────────────────────────┘

For line-by-line lineage to Telegram sources, see comments and native code in the repository.

Lineage & license

Algorithms and caching ideas are ported or referenced from Telegram's open-source Android/iOS clients. This project uses the same license as Telegram's official clients.

Package license: GNU General Public License v2.0 (GPL-2.0) — the same license used by Telegram for Android and Telegram for iOS.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Telegram is a trademark of Telegram FZ-LLC.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for workflow, pull requests, and community guidelines.

Repository: github.com/bonnguyenitc/react-native-tele-image