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

docs/pages/component/props.mdx

@@ -437,10 +437,23 @@ Determine whether the media should continue playing when notifications or the Co
 
 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.
+> [!WARNING]
+> Value: string with a URL for the poster is deprecated, use `poster` as object instead
 
-### `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.
@@ -452,6 +465,22 @@ Determines how to resize the poster image when the frame doesn't match the raw v
 - **"repeat"** - Repeat the image to cover the frame of the view. The image will keep its size and aspect ratio. (iOS only)
 - **"stretch"** - Scale width and height independently, This may change the aspect ratio of the src.
 
+### `renderPoster`
+
+<PlatformsList types={['All']} />
+
+Allows you to create custom components to display while the video is loading. If both `renderPoster` and `posterProps` are provided, `posterProps` will be ignored.
+
+```javascript
+<Video>
+  renderPoster={() => (
+    <View>
+      <Text>Custom Poster</Text>
+    </View>
+  )}
+</Video>
+````
+
 ### `preferredForwardBufferDuration`
 
 <PlatformsList types={['iOS', 'visionOS']} />

examples/basic/src/VideoPlayer.tsx

@@ -246,7 +246,12 @@ const VideoPlayer: FC<Props> = ({}) => {
               cacheSizeMB: state.useCache ? 200 : 0,
             }}
             preventsDisplaySleepDuringVideoPlayback={true}
-            poster={state.poster}
+            poster={{
+              source: {
+                uri: state.poster,
+              },
+              resizeMode: 'contain',
+            }}
             onPlaybackRateChange={onPlaybackRateChange}
             onPlaybackStateChanged={onPlaybackStateChanged}
             bufferingStrategy={BufferingStrategyType.DEFAULT}

src/Video.tsx

@@ -15,6 +15,7 @@ import {
   type StyleProp,
   type ImageStyle,
   type NativeSyntheticEvent,
+  type ImageResizeMode,
 } from 'react-native';
 
 import NativeVideoComponent, {
@@ -77,8 +78,9 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
       source,
       style,
       resizeMode,
-      posterResizeMode,
       poster,
+      posterResizeMode,
+      renderPoster,
       fullscreen,
       drm,
       textTracks,
@@ -123,26 +125,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 (renderPoster) {
+        return true;
+      }
+
+      if (isPosterDeprecated) {
+        return !!poster;
+      }
+
+      return !!poster?.source;
+    }, [isPosterDeprecated, poster, renderPoster]);
+
+    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 +610,56 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
         : ViewType.SURFACE;
     }, [drm, useSecureView, useTextureView, viewType]);
 
+    const posterStyle = useMemo<StyleProp<ImageStyle>>(() => {
+      let _posterResizeMode: ImageResizeMode = 'contain';
+
+      if (!isPosterDeprecated && poster?.resizeMode) {
+        _posterResizeMode = poster.resizeMode;
+      } else if (posterResizeMode && posterResizeMode !== 'none') {
+        _posterResizeMode = posterResizeMode;
+      }
+
+      const baseStyle: StyleProp<ImageStyle> = {
+        ...StyleSheet.absoluteFillObject,
+        resizeMode: _posterResizeMode,
+      };
+
+      if (!isPosterDeprecated && poster?.style) {
+        const styles = Array.isArray(poster.style)
+          ? poster.style
+          : [poster.style];
+
+        return [baseStyle, ...styles];
+      }
+
+      return baseStyle;
+    }, [poster, posterResizeMode, isPosterDeprecated]);
+
+    const _renderPoster = useCallback(() => {
+      if (renderPoster) {
+        return <View style={StyleSheet.absoluteFill}>{renderPoster()}</View>;
+      }
+
+      return (
+        <Image
+          {...(isPosterDeprecated ? {} : poster)}
+          source={isPosterDeprecated ? {uri: poster} : poster?.source}
+          style={posterStyle}
+        />
+      );
+    }, [isPosterDeprecated, poster, posterStyle, renderPoster]);
+
     return (
       <View style={style}>
         <NativeVideoComponent
           ref={nativeRef}
           {...rest}
           src={src}
           drm={_drm}
-          style={StyleSheet.absoluteFill}
+          style={{
+            ...StyleSheet.absoluteFillObject,
+            ...(showPoster ? {display: 'none'} : {}),
+          }}
           resizeMode={resizeMode}
           fullscreen={isFullscreen}
           restoreUserInterfaceForPIPStopCompletionHandler={
@@ -688,9 +734,7 @@ const Video = forwardRef<VideoRef, ReactVideoProps>(
           }
           viewType={_viewType}
         />
-        {hasPoster && showPoster ? (
-          <Image style={posterStyle} source={{uri: poster}} />
-        ) : null}
+        {hasPoster && showPoster ? _renderPoster() : null}
       </View>
     );
   },

src/types/video.ts

@@ -1,6 +1,14 @@
 import type {ISO639_1} from './language';
 import type {ReactVideoEvents} from './events';
-import type {StyleProp, ViewProps, ViewStyle} from 'react-native';
+import type {
+  ImageProps,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+  ImageRequireSource,
+  ImageURISource,
+} from 'react-native';
+import type {ReactNode} from 'react';
 import type VideoResizeMode from './ResizeMode';
 import type FilterType from './FilterType';
 import type ViewType from './ViewType';
@@ -33,6 +41,13 @@ export type ReactVideoSource = Readonly<
   }
 >;
 
+export type ReactVideoPosterSource = ImageURISource | ImageRequireSource;
+
+export type ReactVideoPoster = Omit<ImageProps, 'source'> & {
+  // prevents giving source in the array
+  source?: ReactVideoPosterSource;
+};
+
 export type VideoMetadata = Readonly<{
   title?: string;
   subtitle?: string;
@@ -240,12 +255,13 @@ export interface ReactVideoProps extends ReactVideoEvents, ViewProps {
   pictureInPicture?: boolean; // iOS
   playInBackground?: boolean;
   playWhenInactive?: boolean; // iOS
-  poster?: string;
-  posterResizeMode?: EnumValues<PosterResizeModeType>;
+  poster?: string | ReactVideoPoster; // string is deprecated
+  posterResizeMode?: EnumValues<PosterResizeModeType>; // deprecated
   preferredForwardBufferDuration?: number; // iOS
   preventsDisplaySleepDuringVideoPlayback?: boolean;
   progressUpdateInterval?: number;
   rate?: number;
+  renderPoster?: () => ReactNode;
   repeat?: boolean;
   reportBandwidth?: boolean; //Android
   resizeMode?: EnumValues<VideoResizeMode>;