Skip to main content


The Video component is a versatile tool for displaying videos in your application. It supports both local and remote videos, and includes built-in features for video fallback and progressive loading. The Video component is built on top of the Expo Video component.


import { Video } from "pearl-ui";


// Displaying a local video<Video  width={200}  height={200}  source={require("<path-to-local-video>.mp4")}/>
// Displaying a video from a remote source<Video  width={200}  height={200}  source={{    uri: "",  }}/>

Aspect Ratio#

The aspectRatio style prop can be used to maintain the aspect ratio of a video and prevent it from being cropped.

// Maintains aspect ratio for a video having fixed width<Video  width={200}  aspectRatio={4/3}  source={require("<path-to-local-video>.mp4")}/>
// Maintains aspect ratio for a video having relative width<Video  width="70%"  aspectRatio={16/9}  source={{    uri: "",  }}/>

Video loading indicators#

While a remote video is being downloaded, a temporary placeholder can be displayed as a loading indicator. This can significantly improve the user experience of your application. The Video component supports two types of loading indicators: progressive video loading and spinner loading.

Progressive video loading#

Progressive video loading displays a blurred low-quality image that gradually improves in resolution as the video is downloaded.

The loaderType and previewSource props can be used to enable progressive loading. The previewSource should be a low-resolution version of the source video.

// The loaderType prop specifies that this video needs to be loaded progressively<Video  width={100}  height={100}  loaderType="progressive"  source={{    uri: "",  }}  previewSource={{    uri: "<url-of-the-preview-image>",  }}/>

If you do not have a preview source image, you can use the previewColor prop to emulate the progressive video loading behavior.

// The loaderType prop specifies that this video needs to be loaded progressively<Video  width={100}  height={100}  loaderType="progressive"  source={{    uri: "",  }}  previewColor="#934a9a"/>

If both previewSource and previewColor props are specified, previewSource has a higher precedence.

Spinner loading#

You can also display a Spinner while the video is loading by setting the loaderType prop to "spinner". The appearance of the spinner can be customized using the default component configuration.

// The loaderType prop specifies that a spinner should be displayed while this video is being loaded<Video  width={100}  height={100}  loaderType="spinner"  source={{    uri: "",  }}/>

Video Fallback#

If a video cannot be displayed due to network issues or because it does not exist, a fallback image or component can be displayed instead. This can be achieved using the fallbackSource and fallbackComponent props.

// Displays an image saying 'No Video Available' if the source video doesn't exist<Video  width={100}  height={100}  fallbackSource={{    uri: "",  }}  source={{    uri: "",  }}/>;
// Displays a custom component with an error icon if the source video doesn't existimport { Icon } from "pearl-ui";
<Video  width={100}  height={100}  fallbackComponent={    <Icon      iconFamily="MaterialIcons"      iconName="error-outline"      size="l"      color="neutral.50"    />  }  source={{    uri: "",  }}/>;

If both fallbackComponent and fallbackSource props are specified, fallbackComponent has a higher precedence.

Override Styles#

The Video component supports a variety of style props that can be used to override the default component style. Any style props passed to the component will take precedence over the default component configuration.

<Video  mt="5"  boxShadow="xl"  borderRadius="m"  width="50%"  height={200}  source={{    uri: "",  }}/>



  • Video has the role of video.

Component Properties#

Supported Styling Properties#

The Video component is built upon the Box component, hence all properties of Box can be applied to it.

Additional Properties#

Apart from the properties listed below, the Video component also inherits all properties of the Expo Video component from Expo.

sizeNoPearlTheme.components.Video["sizes"]Defines the size of the video.
variantNoPearlTheme.components.Video["variants"]Specifies the variant of the video.
loaderTypeNo"progressive" | "spinner""spinner"Specifies the type of loader to display until the video is fully loaded.
previewSourceNoImageSourceSpecifies the source of the placeholder image while the remote video is loading.
previewColorNostringDefines the color of the video container while the remote video is loading.
overlayTransitionDurationNonumber300Specifies the duration (in ms) for the progressive loading overlay to fade after the video loads.
sourceDelayNonumber0Delay (in ms) before the source video starts loading. This can be useful when you want to display a placeholder for a certain amount of time before starting to load the video.
tintNo"dark" | "light" | "default""dark"Specifies the tint of the progressive loading overlay.
fallbackComponentNoReact.ReactElementSpecifies a custom component to display if an error occurs while loading the video.
fallbackSourceNoImageSourceSpecifies the source of the fallback image to display if an error occurs while loading the video.