@twinedo/react-native-image-placeholder

A zero-config React Native wrapper that automatically shows a blur or placeholder while images load, then fades it out smoothly.

Installation

npm install @twinedo/react-native-image-placeholder react-native-reanimated

Optional blur support (install one):

npm install @react-native-community/blur

npm install expo-blur

Basic usage

import { Image } from 'react-native';
import { ImagePlaceholder } from '@twinedo/react-native-image-placeholder';

<ImagePlaceholder>
  <Image
    source={{ uri: 'https://example.com/hero.jpg' }}
    style={{ width: 240, height: 160, borderRadius: 12 }}
  />
</ImagePlaceholder>;

Children must be a single Image-like element (React Native Image, expo-image, FastImage, or any component that forwards load events).

Props

<ImagePlaceholder
  enabled?: boolean // default true
  minDelay?: number // default 150
  fadeDuration?: number // default 600
  overlay?: ReactNode
  blurAmount?: number
  overlayColor?: string
  logoUri?: string | ImageSourcePropType
  logoWidth?: number
  logoHeight?: number
  fallback?: 'auto' | 'delay' | 'none'
  style?: ViewStyle
>
  {childImage}
</ImagePlaceholder>

API

| Prop | Type | Optional | Default | Description | | --- | --- | --- | --- | --- | | children | ReactElement | false | — | Single Image-like element (Image, expo-image, FastImage, or custom). | | enabled | boolean | true | true | Toggle the overlay behavior on/off. | | minDelay | number | true | 150 | Minimum time (ms) the overlay stays visible when using fallback delay. | | fadeDuration | number | true | 600 | Fade-out duration (ms) for the overlay. | | overlay | ReactNode | true | — | Custom overlay; overrides blur/placeholder rendering. | | blurAmount | number | true | — | Blur intensity when BlurView is available. | | overlayColor | string | true | rgba(0, 0, 0, 0.08) | Tint color for the default placeholder/blur overlay. | | logoUri | string | ImageSourcePropType | true | — | Centered logo shown during loading. | | logoWidth | number | true | 56 | Logo width in pixels. | | logoHeight | number | true | 56 | Logo height in pixels. | | fallback | 'auto' | 'delay' | 'none' | true | auto | How to behave when lifecycle events are unavailable. | | style | ViewStyle | true | — | Style applied to the wrapper container. |

Notes:

• overlay replaces the default placeholder/blur entirely.
• overlay renders inside an absolute-fill container; use StyleSheet.absoluteFillObject if you want it to cover the image.
• blurAmount uses an optional BlurView if installed; otherwise the default placeholder is used.
• overlayColor tints the default placeholder/blur (use a darker rgba to deepen the dim effect).
• logoUri adds a centered logo on top of the default placeholder/blur. It accepts a remote uri string or a static require() asset.
• fallback controls the behavior when lifecycle events are unavailable:
  • auto: use load events when available, otherwise fall back to a timed delay.
  • delay: always use the timed delay (useful for custom images that never emit events).
  • none: only use lifecycle events and never fall back.

Fallback delay behavior

When fallback is active, the overlay stays visible for at least minDelay and then fades out over fadeDuration. This prevents flashes for cached images and still feels responsive for fast loads.

Blur overlay

<ImagePlaceholder blurAmount={12}>
  <Image source={{ uri: 'https://example.com/hero.jpg' }} style={{ width: 240, height: 160 }} />
</ImagePlaceholder>

If you want full control, pass a custom overlay:

import { StyleSheet } from 'react-native';
import { BlurView } from '@react-native-community/blur';

<ImagePlaceholder
  overlay={<BlurView blurAmount={16} style={{ ...StyleSheet.absoluteFillObject }} />}
>
  <Image source={{ uri: 'https://example.com/hero.jpg' }} style={{ width: 240, height: 160 }} />
</ImagePlaceholder>

Logo overlay

const logo = require('./assets/icon.png');

<ImagePlaceholder blurAmount={12} logoUri={logo} logoWidth={64} logoHeight={64}>
  <Image source={{ uri: 'https://example.com/hero.jpg' }} style={{ width: 240, height: 160 }} />
</ImagePlaceholder>

Expo + Bare React Native notes

• react-native-reanimated is required. Ensure the Reanimated Babel plugin is installed and configured.
• Bare React Native: after installing native deps, run pod install in the ios directory.
• Expo: use expo-blur for blur overlays or pass a custom overlay. Expo already configures Reanimated for managed projects.

Example usage snippet

import { Image } from 'react-native';
import { ImagePlaceholder } from '@twinedo/react-native-image-placeholder';

export function Avatar() {
  return (
    <ImagePlaceholder fadeDuration={500} minDelay={120} blurAmount={10}>
      <Image
        source={{ uri: 'https://images.example.com/avatar.png' }}
        style={{ width: 80, height: 80, borderRadius: 40 }}
      />
    </ImagePlaceholder>
  );
}

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library