UploadPreview

Package

@rpldy/upload-preview

Installation

npm

npm install @rpldy/upload-preview

OR

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

Yarn

yarn add @rpldy/upload-preview

OR

yarn add @rpldy/uploady @rpldy/upload-preview

pnpm

pnpm add @rpldy/upload-preview

OR

pnpm add @rpldy/uploady @rpldy/upload-preview

note

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

Props

Name (* = mandatory)	Type	Default	Description
loadFirstOnly	boolean	false	load preview only for the first item in a batch
maxPreviewImageSize	number	2e+7	maximum size of image to preview
maxPreviewVideoSize	number	1e+8	maximum size of video to preview
fallbackUrl	string | FallbackMethod	undefined	static URL or function that returns fallback in case failed to load preview or when file over max size
imageMimeTypes	string[]	see list	image mime types to load preview for
videoMimeTypes	string[]	see list	video mime types to load preview for
previewComponentProps	PreviewComponentPropsOrMethod	undefined	object or function to generate object as additional props for the preview component
PreviewComponent	React.ComponentType<any>	img | video	The component that will show the preview
rememberPreviousBatches	boolean	false	show previous batches' previews as opposed to just the last
previewMethodsRef	React Ref	undefined	ref will be set with preview helper methods
onPreviewsChanged	(PreviewItem[]) => void	undefined	callback will be called whenever preview items array changes

fallbackUrl

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;

• See: PreviewItem
• See: FileLike

previewComponentProps

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

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

• See: PreviewType
• See: BatchItem

previewMethodsRef

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

note

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

Examples

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;
};

note

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

note

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: "my-server.com/upload" }}>
		<UploadButton />
		<UploadPreview
			PreviewComponent={MyPreview}
			previewComponentProps={{
				foo: "bar"
			}}
		/>
	</Uploady>;
};

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) => {
		setPreviews(previews);
	}, []);

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

	return <>
		<button onClick={onClear}>
            Clear {previews.length} previews
        </button>
		<br/>
        <UploadPreview
            rememberPreviousBatches
            previewMethodsRef={previewMethodsRef}
            onPreviewsChanged={onPreviewsChanged}
        />
	</>;
};

export const App = () => {
	return <Uploady destination={{ url: "my-server.com/upload" }}>
		<UploadButton />
		<PreviewsWithClear />
	</Uploady>;
};