Skip to main content

​
Overview

Uploads an image to Replyke storage. The server processes the image using Sharp, generates named variants according to the specified mode, and returns an Image object with proxy URLs for all variants. Works in both browser and React Native environments. Provides upload progress tracking.
Requires an authenticated user. The hook uses the private axios instance and will throw if no session is active.

​
Usage Example

import { useUploadImage } from "@replyke/react-js";

function AvatarUploader() {
  const { uploadImage, uploading, progress } = useUploadImage();

  const handleFile = async (file: File) => {
    const image = await uploadImage(file, {
      mode: "exact-dimensions",
      dimensions: {
        avatar: { width: 200, height: 200 },
        thumbnail: { width: 64, height: 64 },
      },
      format: "webp",
      quality: 85,
    });

    console.log(image.original.publicPath);
    console.log(image.variants.avatar.publicPath);
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={e => e.target.files && handleFile(e.target.files[0])} />
      {uploading && <p>Uploading... {progress}%</p>}
    </div>
  );
}

​
Parameters

uploadImage(file, options) accepts two arguments:
​
file
BrowserFile | RNFile
required
The image to upload. In the browser, pass a standard File object. In React Native, pass { uri, name, type? }.
​
options
UploadImageOptions
required
Processing configuration. Must include a mode field. See Processing Modes below.

​
Common Options (all modes)

​
quality
number
JPEG/WebP quality, 1–100. Defaults to 85.
​
format
"webp" | "jpeg" | "png" | "original"
Output format for all variants. Defaults to "webp".
​
stripExif
boolean
Whether to remove EXIF metadata from the output. Defaults to true.
​
pathParts
string[]
Storage path segments. The file is stored under the joined path. Defaults to ["images", <fileId>].
​
entityId
string
Associates the file with an entity for cascade deletion.
​
commentId
string
Associates the file with a comment for cascade deletion.
​
spaceId
string
Associates the file with a space for cascade deletion.
​
onProgress
(progress: number) => void
Called with upload percentage (0–100) during the multipart upload.

​
Processing Modes

​
exact-dimensions

Each variant has an explicit pixel width and height. 
{
  mode: "exact-dimensions",
  dimensions: {
    thumbnail: { width: 64, height: 64 },
    card:      { width: 400, height: 300 },
  },
  fit?: "cover" | "contain" | "inside" | "outside", // default: "cover"
}

​
aspect-ratio-width-based

All variants share a fixed aspect ratio. You specify widths; heights are computed. 
{
  mode: "aspect-ratio-width-based",
  aspectRatio: { width: 16, height: 9 },
  widths: { small: 320, medium: 640, large: 1280 },
  fit?: "cover" | "contain" | "inside" | "outside",
}

​
aspect-ratio-height-based

All variants share a fixed aspect ratio. You specify heights; widths are computed. 
{
  mode: "aspect-ratio-height-based",
  aspectRatio: { width: 1, height: 1 },
  heights: { small: 100, medium: 200 },
  fit?: "cover" | "contain" | "inside" | "outside",
}

​
original-aspect

Preserves the original image’s aspect ratio. You specify the longest-edge size for each variant. 
{
  mode: "original-aspect",
  sizes: { thumbnail: 100, medium: 400, full: 1200 },
  fit?: "inside" | "outside",
}

​
multi-aspect-ratio

Generates variants across multiple aspect ratios with explicit sizes. 
{
  mode: "multi-aspect-ratio",
  aspectRatios: [{ width: 1, height: 1 }, { width: 16, height: 9 }],
  sizes: { small: 200, large: 800 },
  fit?: "cover" | "contain" | "inside" | "outside",
}

​
Returns

​
uploadImage
(file, options) => Promise<Image>
Async function that performs the upload and returns an Image object on success.
​
uploading
boolean
true while the upload is in progress.
​
progress
number
Upload percentage (0–100). Resets to 0 when the upload finishes.

​
Return Value Shape (Image)

{
  fileId: string;
  imageId: string;         // Same as fileId
  status: "completed" | "failed";
  original: ImageVariant;  // { path, publicPath, width, height, size, format }
  variants: Record<string, ImageVariant>;
  metadata: {
    originalFormat: string;
    originalSize: number;
    exifStripped: boolean;
    processingTime: number; // ms
  };
  createdAt: string;       // ISO 8601
}