feat: add ability to define poster props as Image type and render poster as custom component

docs/pages/component/props.mdx

@@ -434,13 +434,26 @@ Determine whether the media should continue playing when notifications or the Co
 ### `poster`
 
 <PlatformsList types={['All']} />
+> [!WARNING]
+> Value: string with a URL for the poster is deprecated, use `poster` as object instead
 
 An image to display while the video is loading
 
-Value: string with a URL for the poster, e.g. "https://baconmockup.com/300/200/"
+Value: Props for the `Image` component. The poster is visible when the source attribute is provided.
 
-### `posterResizeMode`
+```javascript
+<Video>
+  poster={{
+    source: { uri: "https://baconmockup.com/300/200/" },
+    resizeMode: "cover",
+    // ...
+  }}
+</Video>
+````
 
+### `posterResizeMode`
+> [!WARNING]
+> deprecated, use `poster` with `resizeMode` key instead
 <PlatformsList types={['All']} />
 
 Determines how to resize the poster image when the frame doesn't match the raw video dimensions.
@@ -486,6 +499,22 @@ Speed at which the media should play.
 - **1.0** - Play at normal speed (default)
 - **Other values** - Slow down or speed up playback
 
+### `renderLoader`
+
+<PlatformsList types={['All']} />
+
+Allows you to create custom components to display while the video is loading. If both `renderLoader` and `poster` are provided, `poster` will be ignored.
+
+```javascript
+<Video>
+  renderLoader={
+    <View>
+      <Text>Custom Loader</Text>
+    </View>
+  }
+</Video>
+````
+
 ### `repeat`
 
 <PlatformsList types={['All']} />

examples/basic/src/VideoPlayer.tsx

@@ -33,7 +33,7 @@ import Video, {
 import styles from './styles';
 import {AdditionalSourceInfo} from './types';
 import {bufferConfig, srcList, textTracksSelectionBy} from './constants';
-import {Overlay, toast} from './components';
+import {Overlay, toast, VideoLoader} from './components';
 
 type Props = NonNullable<unknown>;
 
@@ -66,7 +66,7 @@ const VideoPlayer: FC<Props> = ({}) => {
   const [repeat, setRepeat] = useState(false);
   const [controls, setControls] = useState(false);
   const [useCache, setUseCache] = useState(false);
-  const [poster, setPoster] = useState<string | undefined>(undefined);
+  const [showPoster, setShowPoster] = useState<boolean>(false);
   const [showNotificationControls, setShowNotificationControls] =
     useState(false);
   const [isSeeking, setIsSeeking] = useState(false);
@@ -256,7 +256,7 @@ const VideoPlayer: FC<Props> = ({}) => {
               cacheSizeMB: useCache ? 200 : 0,
             }}
             preventsDisplaySleepDuringVideoPlayback={true}
-            poster={poster}
+            renderLoader={showPoster ? <VideoLoader /> : undefined}
             onPlaybackRateChange={onPlaybackRateChange}
             onPlaybackStateChanged={onPlaybackStateChanged}
             bufferingStrategy={BufferingStrategyType.DEFAULT}
@@ -288,7 +288,7 @@ const VideoPlayer: FC<Props> = ({}) => {
         paused={paused}
         volume={volume}
         setControls={setControls}
-        poster={poster}
+        showPoster={showPoster}
         setDecoration={setDecoration}
         rate={rate}
         setFullscreen={setFullscreen}
@@ -298,7 +298,7 @@ const VideoPlayer: FC<Props> = ({}) => {
         setIsSeeking={setIsSeeking}
         repeat={repeat}
         setRepeat={setRepeat}
-        setPoster={setPoster}
+        setShowPoster={setShowPoster}
         setRate={setRate}
         setResizeMode={setResizeMode}
         setShowNotificationControls={setShowNotificationControls}

examples/basic/src/components/Indicator.tsx

@@ -1,22 +1,8 @@
-import React, {FC, memo} from 'react';
-import {ActivityIndicator, View} from 'react-native';
-import styles from '../styles.tsx';
+import React, {memo} from 'react';
+import {ActivityIndicator} from 'react-native';
 
-type Props = {
-  isLoading: boolean;
-};
-
-const _Indicator: FC<Props> = ({isLoading}) => {
-  if (!isLoading) {
-    return <View />;
-  }
-  return (
-    <ActivityIndicator
-      color="#3235fd"
-      size="large"
-      style={styles.IndicatorStyle}
-    />
-  );
+const _Indicator = () => {
+  return <ActivityIndicator color="#3235fd" size="large" />;
 };
 
 export const Indicator = memo(_Indicator);

examples/basic/src/components/Overlay.tsx

@@ -1,14 +1,8 @@
 import React, {forwardRef, memo, useCallback} from 'react';
-import {Indicator} from './Indicator.tsx';
 import {View} from 'react-native';
 import styles from '../styles.tsx';
 import ToggleControl from '../ToggleControl.tsx';
-import {
-  isAndroid,
-  isIos,
-  samplePoster,
-  textTracksSelectionBy,
-} from '../constants';
+import {isAndroid, isIos, textTracksSelectionBy} from '../constants';
 import MultiValueControl, {
   MultiValueControlPropType,
 } from '../MultiValueControl.tsx';
@@ -65,8 +59,8 @@ type Props = {
   setPaused: (value: boolean) => void;
   repeat: boolean;
   setRepeat: (value: boolean) => void;
-  poster: string | undefined;
-  setPoster: (value: string | undefined) => void;
+  showPoster: boolean;
+  setShowPoster: (value: boolean) => void;
   muted: boolean;
   setMuted: (value: boolean) => void;
   currentTime: number;
@@ -107,8 +101,8 @@ const _Overlay = forwardRef<VideoRef, Props>((props, ref) => {
     setPaused,
     setRepeat,
     repeat,
-    setPoster,
-    poster,
+    setShowPoster,
+    showPoster,
     setMuted,
     muted,
     duration,
@@ -227,13 +221,12 @@ const _Overlay = forwardRef<VideoRef, Props>((props, ref) => {
 
   const toggleRepeat = () => setRepeat(!repeat);
 
-  const togglePoster = () => setPoster(poster ? undefined : samplePoster);
+  const togglePoster = () => setShowPoster(!showPoster);
 
   const toggleMuted = () => setMuted(!muted);
 
   return (
     <>
-      <Indicator isLoading={isLoading} />
       <View style={styles.topControls}>
         <View style={styles.resizeModeControl}>
           <TopControl
@@ -279,7 +272,7 @@ const _Overlay = forwardRef<VideoRef, Props>((props, ref) => {
               <ToggleControl onPress={toggleFullscreen} text="fullscreen" />
               <ToggleControl onPress={toggleDecoration} text="decoration" />
               <ToggleControl
-                isSelected={!!poster}
+                isSelected={!!showPoster}
                 onPress={togglePoster}
                 selectedText="poster"
                 unselectedText="no poster"

examples/basic/src/components/VideoLoader.tsx

@@ -0,0 +1,15 @@
+import {Text, View} from 'react-native';
+import {Indicator} from './Indicator.tsx';
+import React, {memo} from 'react';
+import styles from '../styles.tsx';
+
+const _VideoLoader = () => {
+  return (
+    <View style={styles.indicatorContainer}>
+      <Text style={styles.indicatorText}>Loading...</Text>
+      <Indicator />
+    </View>
+  );
+};
+
+export const VideoLoader = memo(_VideoLoader);

examples/basic/src/components/index.ts

@@ -1,3 +1,4 @@
+export * from './VideoLoader';
 export * from './Indicator';
 export * from './Seeker';
 export * from './AudioTracksSelector';

examples/basic/src/constants/general.ts

@@ -149,10 +149,6 @@ export const srcAndroidList = [
   },
 ];
 
-// poster which can be displayed
-export const samplePoster =
-  'https://upload.wikimedia.org/wikipedia/commons/1/18/React_Native_Logo.png';
-
 export const srcList: SampleVideoSource[] = srcAllPlatformList.concat(
   isAndroid ? srcAndroidList : srcIosList,
 );

examples/basic/src/styles.tsx

@@ -102,9 +102,15 @@ const styles = StyleSheet.create({
     borderWidth: 1,
     borderColor: 'red',
   },
-  IndicatorStyle: {
-    flex: 1,
+  indicatorContainer: {
     justifyContent: 'center',
+    alignItems: 'center',
+    gap: 10,
+    width: '100%',
+    height: '100%',
+  },
+  indicatorText: {
+    color: 'white',
   },
   seekbarContainer: {
     flex: 1,

src/Video.tsx

@@ -15,6 +15,8 @@ import {
   type StyleProp,
   type ImageStyle,
   type NativeSyntheticEvent,
+  type ImageResizeMode,
+  type ViewStyle,
 } from 'react-native';
 
 import NativeVideoComponent, {
@@ -77,8 +79,9 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
       source,
       style,
       resizeMode,
-      posterResizeMode,
       poster,
+      posterResizeMode,
+      renderLoader,
       fullscreen,
       drm,
       textTracks,
@@ -123,26 +126,28 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
     ref,
   ) => {
     const nativeRef = useRef<ComponentRef<VideoComponentType>>(null);
-    const [showPoster, setShowPoster] = useState(!!poster);
+
+    const isPosterDeprecated = typeof poster === 'string';
+
+    const hasPoster = useMemo(() => {
+      if (renderLoader) {
+        return true;
+      }
+
+      if (isPosterDeprecated) {
+        return !!poster;
+      }
+
+      return !!poster?.source;
+    }, [isPosterDeprecated, poster, renderLoader]);
+
+    const [showPoster, setShowPoster] = useState(hasPoster);
     const [isFullscreen, setIsFullscreen] = useState(fullscreen);
     const [
       _restoreUserInterfaceForPIPStopCompletionHandler,
       setRestoreUserInterfaceForPIPStopCompletionHandler,
     ] = useState<boolean | undefined>();
 
-    const hasPoster = !!poster;
-
-    const posterStyle = useMemo<StyleProp<ImageStyle>>(
-      () => ({
-        ...StyleSheet.absoluteFillObject,
-        resizeMode:
-          posterResizeMode && posterResizeMode !== 'none'
-            ? posterResizeMode
-            : 'contain',
-      }),
-      [posterResizeMode],
-    );
-
     const src = useMemo<VideoSrc | undefined>(() => {
       if (!source) {
         return undefined;
@@ -606,14 +611,75 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
         : ViewType.SURFACE;
     }, [drm, useSecureView, useTextureView, viewType]);
 
+    const _renderPoster = useCallback(() => {
+      // poster resize mode
+      let _posterResizeMode: ImageResizeMode = 'contain';
+
+      if (!isPosterDeprecated && poster?.resizeMode) {
+        _posterResizeMode = poster.resizeMode;
+      } else if (posterResizeMode && posterResizeMode !== 'none') {
+        _posterResizeMode = posterResizeMode;
+      }
+
+      // poster style
+      const baseStyle: StyleProp<ImageStyle> = {
+        ...StyleSheet.absoluteFillObject,
+        resizeMode: _posterResizeMode,
+      };
+
+      let posterStyle: StyleProp<ImageStyle> = baseStyle;
+
+      if (!isPosterDeprecated && poster?.style) {
+        const styles = Array.isArray(poster.style)
+          ? poster.style
+          : [poster.style];
+        posterStyle = [baseStyle, ...styles];
+      }
+
+      // render poster
+      if (renderLoader && poster) {
+        console.warn(
+          'You provided both `renderLoader` and `poster` props. `Poster` props is ignored.',
+        );
+      }
+
+      if (renderLoader) {
+        // check if valid jsx
+        if (React.isValidElement(renderLoader)) {
+          console.warn(
+            'Invalid renderLoader component. Please provide a valid JSX component',
+          );
+          return;
+        }
+
+        return <View style={StyleSheet.absoluteFill}>{renderLoader}</View>;
+      }
+
+      return (
+        <Image
+          {...(isPosterDeprecated ? {} : poster)}
+          source={isPosterDeprecated ? {uri: poster} : poster?.source}
+          style={posterStyle}
+        />
+      );
+    }, [isPosterDeprecated, poster, posterResizeMode, renderLoader]);
+
+    const _style: StyleProp<ViewStyle> = useMemo(
+      () => ({
+        ...StyleSheet.absoluteFillObject,
+        ...(showPoster ? {display: 'none'} : {}),
+      }),
+      [showPoster],
+    );
+
     return (
       <View style={style}>
         <NativeVideoComponent
           ref={nativeRef}
           {...rest}
           src={src}
           drm={_drm}
-          style={StyleSheet.absoluteFill}
+          style={_style}
           resizeMode={resizeMode}
           fullscreen={isFullscreen}
           restoreUserInterfaceForPIPStopCompletionHandler={
@@ -688,9 +754,7 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
           }
           viewType={_viewType}
         />
-        {hasPoster && showPoster ? (
-          <Image style={posterStyle} source={{uri: poster}} />
-        ) : null}
+        {hasPoster && showPoster ? _renderPoster() : null}
       </View>
     );
   },