Skip to main content





npm install @rpldy/upload-preview


npm install @rpldy/uploady @rpldy/upload-preview

Must be rendered inside (child/descendant) of an Uploady instance


Name (* = mandatory)TypeDefaultDescription
loadFirstOnlybooleanfalseload preview only for the first item in a batch
maxPreviewImageSizenumber2e+7maximum size of image to preview
maxPreviewVideoSizenumber1e+8maximum size of video to preview
fallbackUrlstring | FallbackMethodundefinedstatic URL or function that returns fallback in case failed to load preview or when file over max size
imageMimeTypesstring[]see listimage mime types to load preview for
videoMimeTypesstring[]see listvideo mime types to load preview for
previewComponentPropsPreviewComponentPropsOrMethodundefinedobject or function to generate object as additional props for the preview component
PreviewComponentReact.ComponentType<any>img | videoThe component that will show the preview
rememberPreviousBatchesbooleanfalseshow previous batches' previews as opposed to just the last
previewMethodsRefReact Refundefinedref will be set with preview helper methods
onPreviewsChanged(PreviewItem[]) => voidundefinedcallback will be called whenever preview items array changes


In case you wish to return a dynamic fallback URL you can pass in a function instead of a string:

type FallbackType = string | PreviewItem;

type FallbackMethod = (file: FileLike) => FallbackType | void;


type PreviewComponentPropsMethod = (item: BatchItem, url: string, type: PreviewType) => Record<string, unknown>;

type PreviewComponentPropsOrMethod = Record<string, unknown> | PreviewComponentPropsMethod;


type PreviewMethods = {
clear: () => void;
removePreview: (id: string) => void;

Provides access to preview related methods:

  • clear - will reset all items shown in the preview
  • removePreview - will remove a single item preview

These methods do not remove the item from the upload queue. ONLY from the preview.


Custom Preview Component​

The Upload Preview can be customized in several ways. The main method is through the PreviewComponent prop. Passing a custom component will make the preview render your own UI per each file being uploaded.

The custom component is called with the following props

type PreviewProps = {
id: string;
url: string;
name: string;
type: PreviewType;
isFallback: boolean;
removePreview: () => void;

Additional props handed to the UploadPreview component using previewComponentProps Will be spread into the props given to the custom preview component


For uploaded image files, the url prop will be the result of calling URL.createObjectURL on the file.

import React from "react";
import Uploady from "@rpldy/uploady";
import UploadPreview from "@rpldy/upload-preview";
import UploadButton from "@rpldy/upload-button";

const MyPreview = ({ type, url, id, name, isFallback, foo }) => {

return <MyCustomPreviewUI/>

export const App = () => {
return <Uploady destination={{ url: "" }}>
<UploadButton />
foo: "bar"

Preview Methods & Remember Previous​

The props rememberPreviousBatches, previewMethodsRef, and onPreviewsChanged make it possible to do more with previews. Specifically, the make it possible to create a visual queue of the uploads.

This is especially useful when adding other features such as abort and retry.

The code below shows how to clear the previews with a button click:

import React from "react";
import Uploady from "@rpldy/uploady";
import UploadPreview from "@rpldy/upload-preview";
import UploadButton from "@rpldy/upload-button";

const PreviewsWithClear = () => {
const previewMethodsRef = useRef();
const [previews, setPreviews] = useState([]);

const onPreviewsChanged = useCallback((previews) => {
}, []);

const onClear = useCallback(() => {
if (previewMethodsRef.current?.clear) {
}, [previewMethodsRef]);

return <>
<button onClick={onClear}>
Clear {previews.length} previews

export const App = () => {
return <Uploady destination={{ url: "" }}>
<UploadButton />
<PreviewsWithClear />