expo-bluesky-gif-view#

An Expo module for displaying animated GIFs and WebP images with optimized performance and playback controls.

Overview#

This module provides a custom view component for rendering animated GIFs with support for:

Autoplay control
Placeholder images while loading
Programmatic playback control (play/pause/toggle)
Image prefetching
Efficient memory management
Player state change events

Platform Support#

iOS (13.4+)
Android (API 21+)
Web

Architecture#

The module uses native platform libraries for optimal GIF rendering performance:

iOS Implementation#

Library: SDWebImage with SDWebImageWebPCoder
Key Files:
- ios/GifView.swift - Main view implementation using SDAnimatedImageView
- ios/ExpoBlueskyGifViewModule.swift - Module definition and prop bindings
- ios/Util.swift - Cache configuration utilities

Approach: Uses SDAnimatedImageView for hardware-accelerated GIF rendering. Images are cached to disk only (not memory) to avoid performance issues with SDAnimatedImage when loaded from memory. The view automatically cancels pending requests when scrolled off-screen and resumes loading when visible.

Android Implementation#

Library: Glide
Key Files:
- android/src/main/java/expo/modules/blueskygifview/GifView.kt - Main view implementation
- android/src/main/java/expo/modules/blueskygifview/ExpoBlueskyGifViewModule.kt - Module definition
- android/src/main/java/expo/modules/blueskygifview/AppCompatImageViewExtended.kt - Custom ImageView with playback control

Approach: Uses Glide's disk cache strategy for loading animated GIFs. Placeholders are loaded with skipMemoryCache(true) to avoid cache bloat. The custom AppCompatImageViewExtended detects when animations are loaded via onDraw and manages the Animatable drawable lifecycle.

Web Implementation#

Library: Native HTML5 <video> element
Key File: src/GifView.web.tsx

Approach: Uses a looping, muted video element to display GIFs. This provides better performance than image-based approaches on the web. The implementation tracks load state to fire the onPlayerStateChange event only once (since onCanPlay fires on every loop).

Usage#

import {GifView} from 'expo-bluesky-gif-view'

function MyComponent() {
  const gifRef = React.useRef<GifView>(null)

  return (
    <GifView
      source="https://example.com/animated.gif"
      placeholderSource="https://example.com/thumbnail.jpg"
      autoplay={true}
      onPlayerStateChange={(event) => {
        console.log('Playing:', event.nativeEvent.isPlaying)
        console.log('Loaded:', event.nativeEvent.isLoaded)
      }}
      ref={gifRef}
    />
  )
}

API#

Props#

source?: string - URL of the animated GIF/WebP
placeholderSource?: string - URL of a static placeholder image to show while loading
autoplay?: boolean - Whether to start playing automatically (default: true)
onPlayerStateChange?: (event: GifViewStateChangeEvent) => void - Callback fired when playback state changes

Methods#

All methods are async and return a Promise:

await gifRef.current?.playAsync()
await gifRef.current?.pauseAsync()
await gifRef.current?.toggleAsync()

Static Methods#

// Prefetch GIFs into the cache (not supported on web)
await GifView.prefetchAsync([
  'https://example.com/gif1.gif',
  'https://example.com/gif2.gif'
])

Configuration#

iOS Dependencies#

The module requires SDWebImage and SDWebImageWebPCoder:

# ios/ExpoBlueskyGifView.podspec
s.dependency 'SDWebImage', '~> 5.21.0'
s.dependency 'SDWebImageWebPCoder', '~> 0.14.6'

Android Dependencies#

The module uses Glide, kept in sync with expo-image version:

# android/build.gradle
implementation 'com.github.bumptech.glide:glide:4.13.2'

Key Implementation Details#

Lifecycle Management#

iOS: Cancels pending requests in willMove(toWindow:) when scrolled off-screen
Android: Pauses playback in onDetachedFromWindow(), resumes in onAttachedToWindow()
Web: Uses React lifecycle methods to manage video element state

Cache Strategy#

iOS: Disk-only caching to work around SDAnimatedImage memory issues
Android: DATA disk cache for main images, skips memory cache for placeholders
Web: Relies on browser cache

Animation Control#

iOS: SDAnimatedImageView.autoPlayAnimatedImage is explicitly set to false to prevent automatic animation on viewport entry
Android: Custom AppCompatImageViewExtended manages Animatable drawable state
Web: Uses HTMLMediaElement play/pause APIs

Files Overview#

expo-bluesky-gif-view/
├── index.ts                              # Module entry point
├── expo-module.config.json               # Expo module configuration
├── src/
│   ├── GifView.types.ts                  # TypeScript type definitions
│   ├── GifView.tsx                       # Native implementation (iOS/Android)
│   └── GifView.web.tsx                   # Web implementation
├── ios/
│   ├── ExpoBlueskyGifView.podspec        # CocoaPods spec
│   ├── ExpoBlueskyGifViewModule.swift    # Module and prop definitions
│   ├── GifView.swift                     # iOS view implementation
│   └── Util.swift                        # Cache configuration
└── android/
    ├── build.gradle                      # Gradle build configuration
    └── src/main/java/expo/modules/blueskygifview/
        ├── ExpoBlueskyGifViewModule.kt   # Module and prop definitions
        ├── GifView.kt                    # Android view implementation
        └── AppCompatImageViewExtended.kt # Custom ImageView for playback

Configure Feed