Upload image

Upload an image with server-side processing and named variant generation

Overview

Uploads an image to Sublay 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 "@sublay/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
}