​
Installation

npm install @apexxcloud/react

​
useApexxCloud Hook

A custom hook for granular control over the upload process.

​
Basic Usage

import { useApexxCloud } from "@apexxcloud/react";
import { useEffect, useRef } from "react";
import { useState } from "react";

export default function CustomUploader() {
  const { upload, uploadMultipart } = useApexxCloud();
  const [progress, setProgress] = useState(0);
  const abortController = useRef(new AbortController());

  const getSignedUrl = async (type: string, params: any) => {
    const response = await fetch(
      `http://localhost:5000/api/files/get-signed-url/${type}`,
      {
        method: "POST",
        body: JSON.stringify(params),
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
    const data = await response.json();
    return data.url;
  };

  const handleUpload = async (file) => {
    setProgress(0);
    abortController.current = new AbortController();

    try {
      await upload(getSignedUrl, file, {
        signal: abortController.current.signal,
        onStart: (event) => {
          console.log(`Starting upload: ${event.file.name}`);
        },
        onProgress: (event) => {
          setProgress(event.progress);
        },
        onComplete: (event) => {
          console.log("Upload complete:", event.response);
          setProgress(0);
        },
        onError: (event) => {
          if (event.type === "abort") {
            console.log("Upload cancelled");
            setProgress(0);
          } else {
            console.error("Upload failed:", event.error);
          }
        },
      });
    } catch (error) {
      if (error instanceof DOMException && error.name === "AbortError") {
        console.log("Upload aborted");
      } else {
        console.error("Upload failed:", error);
      }
      setProgress(0);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) handleUpload(file);
        }}
      />
      <button
        onClick={() => {
          abortController.current.abort();
          setProgress(0);
        }}
      >
        Cancel Upload
      </button>
      <progress value={progress} max="100" />
    </div>
  );
}

​
Multipart Upload Example

import { useApexxCloud } from "@apexxcloud/react";
import { useEffect, useRef } from "react";
import { useState } from "react";

export default function MultipartUploader() {
  const { upload, uploadMultipart } = useApexxCloud();
  const [progress, setProgress] = useState(0);
  const abortController = useRef(new AbortController());

  const getSignedUrl = async (type: string, params: any) => {
    const response = await fetch(
      `http://localhost:5000/api/files/get-signed-url/${type}`,
      {
        method: "POST",
        body: JSON.stringify(params),
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
    const data = await response.json();
    return data.url;
  };

  const handleUpload = async (file) => {
    setProgress(0);
    abortController.current = new AbortController();

    try {
      //  just replace upload with uploadMultipart
      await uploadMultipart(getSignedUrl, file, {
        signal: abortController.current.signal,
        onStart: (event) => {
          console.log(`Starting upload: ${event.file.name}`);
        },
        onProgress: (event) => {
          setProgress(event.progress);
        },
        onComplete: (event) => {
          console.log("Upload complete:", event.response);
          setProgress(0);
        },
        onError: (event) => {
          if (event.type === "abort") {
            console.log("Upload cancelled");
            setProgress(0);
          } else {
            console.error("Upload failed:", event.error);
          }
        },
      });
    } catch (error) {
      if (error instanceof DOMException && error.name === "AbortError") {
        console.log("Upload aborted");
      } else {
        console.error("Upload failed:", error);
      }
      setProgress(0);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) handleUpload(file);
        }}
      />
      <button
        onClick={() => {
          abortController.current.abort();
          setProgress(0);
        }}
      >
        Cancel Upload
      </button>
      <progress value={progress} max="100" />
    </div>
  );
}

​
Hook Return Value

PropertyTypeDescription
upload(getSignedUrl: GetSignedUrlFn, file: File, options?: UploadOptions) => Promise<any>Function for single file upload
uploadMultipart(getSignedUrl: GetSignedUrlFn, file: File, options?: MultipartUploadOptions) => Promise<any>Function for multipart upload
transformImageTransformBuilderBuilder for image transformations
transformVideoVideoTransformBuilderBuilder for video transformations
transformDocumentDocumentTransformBuilderBuilder for document transformations
transformWithString(path: string, transformations: string | string[]) => stringDirect transformation using strings

​
Upload Options

OptionTypeDescription
signalAbortSignalAbortSignal for cancelling upload
onStart(event: StartEvent) => voidCalled when upload starts
onProgress(event: ProgressEvent) => voidCalled during upload progress
onComplete(event: CompleteEvent) => voidCalled when upload completes
onError(event: ErrorEvent) => voidCalled if upload fails

​
Multipart Upload Options

Includes all Upload Options plus:

OptionTypeDescription
partSizenumberSize of each part in bytes (default: 5MB)
concurrencynumberNumber of concurrent part uploads (default: 3)
onPartComplete(part: PartCompleteEvent) => voidCalled when a part completes

​
Backend Implementation

See the JavaScript SDK documentation for details on implementing the backend signed URL endpoint.

​
File Uploader Component

The SDK provides a pre-built FileUploader component that you can use out of the box:

import { FileUploader } from "@apexxcloud/react";

function App() {
  const getSignedUrl = async (type, params) => {
    // Your signed URL implementation
  };

  return (
    <FileUploader
      getSignedUrl={getSignedUrl}
      onUploadComplete={(response) => console.log("Upload complete:", response)}
      onUploadError={(error) => console.error("Upload failed:", error)}
      multipart={false}
      accept={{ "image/*": [".png", ".jpg", ".jpeg"] }}
      maxSize={10} // MB
    />
  );
}

​
Component Props

PropTypeDescription
getSignedUrlGetSignedUrlFnFunction to get signed URLs from your backend
onUploadComplete(response: any) => voidCalled when upload completes successfully
onUploadError(error: Error) => voidCalled when upload fails
multipartbooleanEnable multipart upload for large files
acceptRecord<string, string[]>Accepted file types
maxSizenumberMaximum file size in MB

​
Custom Implementation

If you want to customize the uploader or build your own, here’s the complete implementation of our FileUploader component that you can use as a reference:

import React, { useCallback, useState, useRef } from "react";
import { useDropzone } from "react-dropzone";
import { useApexxCloud } from "../hooks/useApexxCloud";
import {
  GetSignedUrlFn,
  ProgressEvent,
  MultipartProgressEvent,
} from "@apexxcloud/sdk-js";
import clsx from "clsx";
import "./FileUploader.css";

interface FileUploaderProps {
  getSignedUrl: GetSignedUrlFn;
  onUploadComplete?: (response: any) => void;
  onUploadError?: (error: Error) => void;
  multipart?: boolean;
  accept?: Record<string, string[]>;
  maxSize?: number;
}

export const FileUploader: React.FC<FileUploaderProps> = ({
  getSignedUrl,
  onUploadComplete,
  onUploadError,
  multipart = false,
  accept,
  maxSize,
}) => {
  const { upload, uploadMultipart } = useApexxCloud();
  const [progress, setProgress] = useState(0);
  const [uploading, setUploading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const abortControllerRef = useRef<AbortController | null>(null);

  const handleProgress = useCallback(
    (event: ProgressEvent | MultipartProgressEvent) => {
      setProgress(event.progress);
    },
    []
  );

  const handleUpload = useCallback(
    async (file: File) => {
      setError(null);
      setUploading(true);
      setProgress(0);
      abortControllerRef.current = new AbortController();

      try {
        const uploadFn = multipart ? uploadMultipart : upload;
        const result = await uploadFn(getSignedUrl, file, {
          onProgress: handleProgress,
          onComplete: (event) => {
            setProgress(100);
            onUploadComplete?.(event.response);
          },
          onError: (event) => {
            setError(event.error.message);
            onUploadError?.(event.error);
          },
          signal: abortControllerRef.current.signal,
          ...(multipart && {
            partSize: 5 * 1024 * 1024, // 5MB chunks
            concurrency: 3,
          }),
        });
        return result;
      } catch (error) {
        if (error instanceof Error) {
          setError(error.message);
          onUploadError?.(error);
        }
      } finally {
        setUploading(false);
      }
    },
    [
      upload,
      uploadMultipart,
      getSignedUrl,
      multipart,
      onUploadComplete,
      onUploadError,
    ]
  );

  const handleCancel = useCallback(() => {
    abortControllerRef.current?.abort();
    setUploading(false);
    setProgress(0);
  }, []);

  const { getRootProps, getInputProps, isDragActive, fileRejections } =
    useDropzone({
      onDrop: useCallback(
        (acceptedFiles: File[]) => {
          const file = acceptedFiles[0];
          if (file) handleUpload(file);
        },
        [handleUpload]
      ),
      accept,
      maxSize: maxSize ? maxSize * 1024 * 1024 : undefined,
      multiple: false,
      disabled: uploading,
    });

  const acceptedFileTypes = accept
    ? Object.values(accept).flat().join(", ")
    : "All files";
  const maxSizeFormatted = maxSize ? `${maxSize}MB` : "Unlimited";

  return (
    <div className={clsx("apexx-uploader-container")}>
      <div
        {...getRootProps()}
        className={clsx(
          "apexx-uploader-dropzone",
          isDragActive && "active",
          uploading && "disabled"
        )}
      >
        <input {...getInputProps()} />

        {uploading ? (
          <div className="apexx-uploader-progress">
            <div className="apexx-uploader-progress-bar">
              <div
                className="apexx-uploader-progress-fill"
                style={{ width: `${progress}%` }}
              />
            </div>
            <div
              style={{
                display: "flex",
                justifyContent: "space-between",
                marginTop: "0.5rem",
              }}
            >
              <span>{progress.toFixed(0)}% complete</span>
              <button
                onClick={(e) => {
                  e.stopPropagation();
                  handleCancel();
                }}
                className="apexx-uploader-cancel"
              >
                Cancel
              </button>
            </div>
          </div>
        ) : (
          <div className="apexx-uploader-content">
            <svg
              className="apexx-uploader-icon"
              fill="none"
              stroke="currentColor"
              viewBox="0 0 24 24"
            >
              <path
                strokeLinecap="round"
                strokeLinejoin="round"
                strokeWidth={2}
                d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12"
              />
            </svg>
            <p>Drop files here or click to upload</p>
            <small className="apexx-uploader-limits">
              Accepted: {acceptedFileTypes}
              <br />
              Max size: {maxSizeFormatted}
            </small>
          </div>
        )}

        {fileRejections.length > 0 && (
          <div className="apexx-uploader-error">
            {fileRejections[0].errors
              .map((err) =>
                err.code === "file-too-large"
                  ? `File is too large. Maximum size is ${maxSize}MB`
                  : err.message
              )
              .join(", ")}
          </div>
        )}

        {error && <div className="apexx-uploader-error">{error}</div>}
      </div>
    </div>
  );
};

This implementation includes:

  • Drag and drop support
  • Upload progress tracking
  • Error handling
  • File type and size validation
  • Upload cancellation
  • Responsive design
  • Accessibility features

​
Requirements

  • React 16.8+ (Hooks support)
  • @apexxcloud/sdk-js as a peer dependency

​
Transformations

​
Image Transformations

import { useApexxCloud } from "@apexxcloud/react";

function ImageTransformExample() {
  const { transformImage } = useApexxCloud();

  // Basic transformations
  const url = transformImage
    .width(800)
    .height(600)
    .crop("fill")
    .quality("auto:good")
    .buildUrl("path/to/image.jpg");

  // Chaining multiple transformations
  const complexUrl = transformImage
    .width(800)
    .height(600)
    .crop("fill")
    .chain()
    .blur(20)
    .grayscale()
    .buildUrl("path/to/image.jpg");

  return (
    <div>
      <img src={url} alt="Transformed image" />
      <img src={complexUrl} alt="Complex transformed image" />
    </div>
  );
}

​
Video Transformations

function VideoTransformExample() {
  const { transformVideo } = useApexxCloud();

  // Basic video transformation
  const videoUrl = transformVideo
    .width(1280)
    .height(720)
    .format("mp4")
    .buildUrl("path/to/video.mp4");

  // Generate video thumbnail
  const thumbnailUrl = transformVideo
    .thumbnail(5.0) // Seek to 5 seconds
    .width(400)
    .height(300)
    .crop("fill")
    .buildUrl("path/to/video.mp4");

  return (
    <div>
      <video src={videoUrl} controls />
      <img src={thumbnailUrl} alt="Video thumbnail" />
    </div>
  );
}

​
Document Transformations

function DocumentTransformExample() {
  const { transformDocument } = useApexxCloud();

  // Convert document format
  const pdfUrl = transformDocument
    .format("pdf")
    .quality("auto:high")
    .buildUrl("path/to/document.docx");

  // Generate document thumbnail
  const thumbnailUrl = transformDocument
    .thumbnail(1) // First page
    .width(800)
    .height(1200)
    .buildUrl("path/to/document.pdf");

  return (
    <div>
      <iframe src={pdfUrl} />
      <img src={thumbnailUrl} alt="Document thumbnail" />
    </div>
  );
}

For detailed information about available transformation options, see the JavaScript SDK documentation.