ImageUploader

A cross-platform React image uploader component supporting click-to-pick, drag-and-drop (web), controlled and uncontrolled usage, image preview with hover-to-remove, automatic loading state from async onUpload, error states, and a wide horizontal layout.

A specialised upload control for images. Renders as a square or landscape rectangle that acts as both the upload trigger and the image preview container. Once an image is uploaded, the zone fills with the image thumbnail; hovering over it reveals controls to replace or remove the image. Supports five sizes, two aspect ratios, and eight states covering the full upload lifecycle.

When to use

When the user must upload a single image — a profile photo, cover image, product thumbnail, brand logo, avatar, or banner

• When the uploaded image should be previewed in place immediately after selection
• When image replacement or removal must be available without navigating away
• In profile settings, onboarding flows, CMS editors, and product or entity configuration forms

When not to use

For uploading non-image files (PDFs, CSVs, documents) — use FileUploader or Drag & Drop Uploader

When multiple images must be uploaded simultaneously — use a Drag & Drop Uploader with multiple file support or a dedicated gallery uploader

When the image upload is part of a broader drag-and-drop area — use Drag & Drop Uploader

When cropping or editing the image after selection is required — pair ImageUploader with a dedicated image crop modal triggered after selection

Content guidelines

Upload hint — inside the zone in Default state, use a short hint below the icon: "Upload photo", "Add cover image", "Choose image". Keep to one line.

Size and format hint — show accepted formats and max size as helper text below the zone (not inside it): "PNG, JPG, WebP — max 5 MB", "Recommended: 1200 × 630 px". At small sizes (S, XS) this may be omitted if space is too tight. Error messages — be specific:

• "File type not supported. Use JPG, PNG, or WebP."

• "Image exceeds the 5 MB limit."

• "Upload failed. Try again."

• "Please upload a profile photo to continue." (required field)

• Replace / Remove labels — use exactly "Replace" and "Remove" in the overlay. Do not use "Edit" for replace or "Delete" for remove in this context — the terms are specific to the image slot, not the entity.

• Field label — always provide a visible label above the component: "Profile photo", "Cover image", "Company logo". Do not rely on the hint inside the zone alone.

• Behaviour guidelines (from industry practice)

• Click to upload — clicking the zone in Default, Hover, or Focus state opens the native file dialog filtered to image types (e.g. accept="image/jpeg,image/png,image/webp,image/gif"). After the user selects a file, begin validation immediately.

• File validation — validate client-side before uploading:

• File type: accept only image formats supported by the product

• File size: reject files above the maximum (e.g. 5 MB, 10 MB) If validation fails, switch to State=Error with a specific message. Do not start the upload for invalid files.

• Uploading — after successful validation, transition to State=Uploading and begin the upload. The zone becomes non-interactive.

• Upload success — on successful upload response, transition to State=Uploaded. The server-returned image URL (or the local object URL) fills the zone as a cropped preview.

• Upload failure — on network error or server rejection, transition to State=Error with a specific message. The zone becomes interactive again — the user can click to retry.

• Image fitting — the preview image fills the entire zone using object-fit: cover and object-position: center so the image is always fully visible and cropped to fit, regardless of the original aspect ratio. Do not letterbox or pillarbox.

• Replace — clicking Replace in State=Uploaded-hover opens the file dialog. The current image stays visible until the new image is successfully uploaded. If the new upload fails, revert to showing the previous image (not the error state) and surface the error as a Toast or inline message.

• Remove — clicking Remove deletes the image from the selection and returns to State=Default. If the image was already uploaded to a server, also trigger a server-side deletion request. Optionally confirm before removing if the action is irreversible.

• Touch devices — State=Uploaded-hover is not reachable on touch. Provide always-visible controls below the zone (small icon buttons for Replace and Remove) when the component is used on mobile.

• Disabled state — the zone cannot be clicked or focused. Provide a tooltip or nearby label explaining why upload is unavailable.

Accessibility

The upload zone must be implemented as a or a wrapping a hidden <input type="file" accept="image/"*>. It must be keyboard-focusable and activate on Enter / Space.

The zone must have aria-label describing its purpose — e.g. aria-label="Upload profile photo".

When State=Uploading, set aria-busy="true" on the zone and update aria-label to "Uploading profile photo…". The zone must not be focusable during upload.

When State=Uploaded, update aria-label to "Profile photo uploaded. Hover or focus to replace or remove." This tells keyboard users there are hidden actions available.

The Replace and Remove buttons in the overlay (State=Uploaded-hover) must always be keyboard-reachable via Tab, even when the overlay is visually hidden. Use CSS (opacity: 0; pointer-events: none) rather than display: none or visibility: hidden so they remain in the focus order.

The Replace button must have aria-label="Replace profile photo" and the Remove button aria-label="Remove profile photo" — not just "Replace" and "Remove" without context.

When State=Error, the error message must be associated via aria-describedby and placed in an aria-live="polite" region.

When State=Disable, the zone must have aria-disabled="true" and tabindex="-1".

The image preview is decorative — set aria-hidden="true" on the element inside the zone, since the zone's aria-label already communicates the current state.

For touch devices, the Replace and Remove controls that live outside the hover overlay must also have descriptive aria-label attributes.

Installation

npm install @xsolla/xui-image-uploader

Demo

Basic (Uncontrolled)

import * as React from "react";
import {
  ImageUploader,
  type ImageUploaderFile,
} from "@xsolla/xui-image-uploader";

export default function Basic() {
  const handleUpload = (file: ImageUploaderFile) => {
    console.log("Picked file:", file.name, file.size);
  };

  return <ImageUploader onUpload={handleUpload} />;
}

Controlled

import * as React from "react";
import {
  ImageUploader,
  type ImageUploaderValue,
} from "@xsolla/xui-image-uploader";

export default function Controlled() {
  const [value, setValue] = React.useState<ImageUploaderValue | null>(null);

  return (
    <ImageUploader
      value={value}
      onChange={setValue}
      placeholder="Upload avatar"
    />
  );
}

Wide View with Description

import * as React from "react";
import { ImageUploader } from "@xsolla/xui-image-uploader";

export default function WideView() {
  return (
    <ImageUploader
      wideView
      placeholder="Upload cover image"
      description="PNG or JPG, up to 5 MB"
    />
  );
}

Async Upload (Recommended)

If onUpload returns a Promise, the component automatically:

• Shows the uploading state (spinner + uploadingPlaceholder) until the promise settles.
• On resolve with { url, filename? } or a bare string URL, fires onChange(value) with the canonical value — no manual wiring needed.
• On reject, fires onChange(null, error).

You don't need async/await in the handler — just return the upload promise:

import { ImageUploader } from "@xsolla/xui-image-uploader";

export default function AutoUpload() {
  return (
    <ImageUploader
      uploadingPlaceholder="Uploading…"
      // uploadFn can return Promise<string> or Promise<{ url, filename? }>
      onUpload={(file) => uploadFn(file.file)}
      onChange={(value) => form.setFieldValue("avatar", value?.url ?? null)}
    />
  );
}

Manual Loading Control

For finer-grained control (e.g. uploads triggered outside the component, or to keep the spinner visible during post-upload work), pass loading explicitly:

import * as React from "react";
import {
  ImageUploader,
  type ImageUploaderFile,
} from "@xsolla/xui-image-uploader";

export default function WithLoading() {
  const [loading, setLoading] = React.useState(false);

  const handleUpload = async (file: ImageUploaderFile) => {
    setLoading(true);
    try {
      await uploadToServer(file.file);
    } finally {
      setLoading(false);
    }
  };

  return (
    <ImageUploader
      loading={loading}
      uploadingPlaceholder="Uploading…"
      onUpload={handleUpload}
    />
  );
}

Error State

import * as React from "react";
import { ImageUploader } from "@xsolla/xui-image-uploader";

export default function WithError() {
  return (
    <ImageUploader
      placeholder="cover.png"
      errorMessage="File is too large (max 5 MB)."
    />
  );
}

React Native (Custom Picker)

On native there is no DOM <input type="file">. Pass an openPicker prop that returns a normalized ImageUploaderFile (e.g. wrapping expo-image-picker or react-native-image-picker).

import * as React from "react";
import * as ImagePicker from "expo-image-picker";
import {
  ImageUploader,
  type ImageUploaderFile,
} from "@xsolla/xui-image-uploader";

export default function Native() {
  const openPicker = async (): Promise<ImageUploaderFile | null> => {
    const result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ImagePicker.MediaTypeOptions.Images,
    });
    if (result.canceled) return null;
    const asset = result.assets[0];
    return {
      name: asset.fileName ?? "image",
      size: asset.fileSize ?? 0,
      uri: asset.uri,
      mimeType: asset.mimeType,
    };
  };

  return <ImageUploader openPicker={openPicker} />;
}

Anatomy

+--------------------------+
|                          |
|         [Image]          |  <- icon (or Spinner while loading)
|         Upload           |  <- placeholder
|     PNG/JPG, up to 5MB   |  <- description (wideView only)
|                          |
+--------------------------+
  File is too large…         <- errorMessage (when present)

When a file has been uploaded, the box renders the image preview and reveals a trash-can affordance over a dimming scrim on hover; clicking (or tapping) removes the image. On touch and React Native devices — where there is no hover — the trash overlay is shown unconditionally so the delete affordance is always discoverable.

API Reference

ImageUploader

| Prop | Type | Default | Description | | :------------------- | :----------------------------------------------------------------------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" | "xl" | Visual size of the uploader. | | placeholder | React.ReactNode | "Upload" | Label shown under the icon (or filename in error state). Accepts a string or a custom React node. | | uploadingPlaceholder | React.ReactNode | "Uploading" | Label shown while loading is true. Accepts a string or a custom React node. | | description | React.ReactNode | - | Helper text below the placeholder. Only rendered when wideView is true. | | errorMessage | string | - | Error message — when provided, the component renders in the error state. | | wideView | boolean | false | Use the horizontal layout. The box stretches to fill its parent's width. | | disabled | boolean | false | Disabled state. | | loading | boolean | false | Controlled loading state (shows spinner + uploading label). | | value | ImageUploaderValue \| null | - | Controlled value. When provided, the component reflects this value. | | onUpload | (file: ImageUploaderFile) => void \| Promise<ImageUploaderValue \| string \| void> | - | Fires when the user picks (or drops) a file. If it returns a Promise, the component shows the uploading state until it settles, forwards a resolved value (object or bare URL string) to onChange, and forwards a rejection to onChange(null, error). | | onChange | (value: ImageUploaderValue \| null, error?: Error) => void | - | Fires when the displayed value changes — on file pick (with a local data-URL preview), after onUpload resolves (with the server value), or on remove (null). The optional error arg carries any rejection from onUpload. | | onDelete | () => void | - | Fires when the user removes the image (trash click / clear). | | accept | string | "image/*" | Accepted MIME types for the file input (web only). | | openPicker | () => Promise<ImageUploaderFile \| null> | - | Native file picker hook. Required on native (no DOM <input type="file">). On web, omit this and the component falls back to a hidden file input. | | themeMode | ThemeMode | - | Override the theme mode for this instance. | | themeProductContext | ThemeProductContext | - | Override the product theme context for this instance. |

ImageUploaderValue

Controlled value shape.

interface ImageUploaderValue {
  filename: string;
  url?: string;
}

Loading and error states are driven by the loading and errorMessage props, not by fields on ImageUploaderValue.

ImageUploaderFile

Normalized file shape produced by the platform picker / drag-drop pipeline. On web, uri is a data-URL and the original DOM File is passed through for consumers that need it (e.g. to upload via FormData / fetch). On native, uri is a file URI and file is omitted.

interface ImageUploaderFile {
  name: string;
  size: number;
  uri: string;
  mimeType?: string;
  /** The original DOM File (web only) */
  file?: File;
}

Platform Support

This package works on both web and React Native. The component uses cross-platform primitives (Box, Text, Spinner) and gates web-only APIs (DOM file input, drag-and-drop, FileReader) behind an isWeb check. On native, supply an openPicker prop to integrate with your image picker library of choice.

Touch / Mobile

On touch web (detected via matchMedia("(hover: none)")) and on React Native, the component skips the hover-only delete affordance and always shows the trash overlay over the image preview, ensuring the remove action is reachable without a pointer.

Layout

In wideView, the component stretches to fill its parent's full width (width: 100%), letting the consumer's layout (form column, grid cell, etc.) control the maximum size. The square (non-wide) variants use fixed pixel dimensions from the size tokens.

Accessibility

• The picker surface is rendered as a <button> on web with an accessible label that reflects the current state ("Upload", "Uploading", or "Remove image: <filename>").
• aria-busy is set while loading is true.
• aria-invalid is set in the error state and the error message is linked via aria-describedby (and rendered with role="alert").
• The description element (when present) is linked via aria-describedby.
• Decorative icons and the dimming scrim are marked aria-hidden.
• Focus styling only appears for keyboard focus (:focus-visible), not for pointer focus left over after the native picker is dismissed.
• The hidden file input is reset after every selection so the same file can be re-selected to retry a failed upload.