React Integration
This guide explains how to integrate FileZen with React applications using the @filezen/react package. This package offers two providers to handle different use cases: one for simple client-side uploads (when you have a backend) and another for more advanced, direct-to-cloud uploads.
📁 Code Example: View the complete working example at github.com/FileZen/filezen/tree/main/apps/react-with-provider
Installation
Install the required FileZen packages:
# With npm
npm install @filezen/js @filezen/react
# With yarn
yarn add @filezen/js @filezen/react
# With pnpm
pnpm add @filezen/js @filezen/react1. Client-side Uploads with a Backend
This is the recommended approach for most applications, especially when using a framework like Next.js. It involves using a backend to handle authentication and file processing, which is more secure.
ZenClientProvider and useZenClient
The ZenClientProvider should wrap your application. It provides a ZenClient instance via the useZenClient hook, which communicates with your own backend API routes for signing uploads.
Backend Required: The ZenClientProvider is designed for client-side use but requires a backend to handle the upload signing logic. For a full Next.js example, see the Next.js Integration guide.
Provider Setup
import { ZenClientProvider } from '@filezen/react';
function App() {
return (
<ZenClientProvider signUrl="/api/my-custom-signer">
{/* Your app components */}
</ZenClientProvider>
);
}Usage
import { useZenClient } from '@filezen/react';
function FileUpload() {
const zenClient = useZenClient();
const handleFileChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
const file = event.target.files?.[0];
if (file) {
const result = await zenClient.upload(file);
if (result.file) {
console.log('Upload successful:', result.file.url);
} else {
console.error('Upload failed:', result.error);
}
}
};
return <input type="file" onChange={handleFileChange} />;
};2. Advanced Usage (Direct to Cloud)
For applications without a dedicated backend or for more complex scenarios, you can use the ZenStorageProvider. This provider handles uploads directly to the FileZen storage service from the client.
ZenStorageProvider and useFileZen
The ZenStorageProvider gives you access to the ZenStorage instance for managing complex upload scenarios, including progress tracking, bulk uploads, and a built-in file picker.
API Key Exposure: This method requires your public FileZen API key to be exposed on the client-side. Ensure you have configured appropriate security rules in your FileZen project to prevent unauthorized access.
Provider Setup
import { ZenStorageProvider } from '@filezen/react';
function App() {
return (
<ZenStorageProvider apiKey={process.env.REACT_APP_FILEZEN_API_KEY}>
{/* Your app components */}
</ZenStorageProvider>
);
}Usage
import { useFileZen } from '@filezen/react';
import React from 'react';
export const Uploader = () => {
const { openPicker, uploads, activeUploads, cancel } = useFileZen();
return (
<div>
<button onClick={() => openPicker({ accept: 'image/*' })}>
Upload Image
</button>
<h3>Active Uploads: {activeUploads.length}</h3>
<ul>
{uploads.map(upload => (
<li key={upload.localId}>
{upload.file?.name || 'New Upload'} - {Math.round(upload.progress)}%
<button onClick={() => cancel(upload)}>Cancel</button>
</li>
))}
</ul>
</div>
);
};The useFileZen hook provides access to the openPicker function, a list of current uploads, activeUploads, and more.
useFileZen Hook API Reference
The useFileZen hook returns an object with the following properties and methods for interacting with the ZenStorageProvider.
| Name | Type | Description |
|---|---|---|
openPicker | (options?) => void | Programmatically opens the browser’s file picker. |
upload | (source, options?) => Promise<ZenUpload> | Uploads a single file directly. |
bulkUpload | (...items) => Promise<ZenUpload[]> | Uploads multiple files at once. |
cancel | (upload) => void | Cancels an ongoing upload. |
uploads | ZenUpload[] | (Readonly) An array of all uploads tracked by the provider. |
activeUploads | ZenUpload[] | (Readonly) An array of uploads that are currently in progress. |
addListener | (listener) => void | Adds a listener for storage-wide events. |
removeListener | (listener) => void | Removes a previously added listener. |
storage | ZenStorage | The raw ZenStorage instance for advanced use cases. |
openPicker(options?)
You can use openPicker to trigger the file selection dialog programmatically.
const { openPicker } = useFileZen();
<button
onClick={() => openPicker({ accept: 'image/*', multiple: false })}
>
Choose Profile Picture
</button>upload(source, options?)
To upload a file directly without using the picker (e.g., from a drag-and-drop area), use the upload method.
const { upload } = useFileZen();
const handleDrop = async (acceptedFiles) => {
if (acceptedFiles.length > 0) {
const result = await upload(acceptedFiles[0], { folder: 'user-uploads' });
console.log('Upload complete:', result.file.url);
}
}FileZenStorage API
Configuration Options