@leancodepl/image-uploader

React component for image uploads.

Installation

``bash
npm install @leancodepl/image-uploader
`

`bash
yarn add @leancodepl/image-uploader
`

API

$3

Manages image upload state and provides drag-and-drop functionality. Creates a complete image upload solution with file
validation, drag-and-drop support, optional cropping, and duplicate detection. Returns upload state and control
functions.

Parameters:

- value?: FileWithId[] - Current array of uploaded files with IDs
- accept?: Accept - File types to accept (defaults to image types)
- cropper?: CropperConfig - Optional cropper configuration for image editing
- onError?: (errorCode: ErrorCode) => void - Callback for handling upload errors
- onChange?: (files: FileWithId[]) => void - Callback when file list changes

Returns: Upload state and control functions including dropzone props

$3

Uploads an image file using provided upload parameters. Handles file upload by calling the getUploadParams function to
retrieve upload configuration, then performs a fetch request to upload the file. Returns early if the image is already
uploaded.

Parameters:

- image: FileWithId | UploadedFileWithId - Image file with ID or already uploaded image with URL
- getUploadParams: (image: FileWithId) => Promise - Function that returns upload
parameters (URI, method, headers) for the image

Returns: Promise resolving to uploaded image with URL

Throws: Error - When upload params are not defined, image is not defined, or upload fails

$3

Root wrapper component for image upload functionality. Provides upload context to all child UploadImages components and
renders a div container. Must wrap all other UploadImages components to provide shared state.

Parameters:

- uploader: ReturnType - Upload state and functions from useUploadImages hook
- props: HTMLAttributes - Additional HTML div attributes

Returns: JSX element wrapping children with upload context

$3

Drag-and-drop zone component for file uploads. Creates an interactive drop zone with file input capabilities. Supports
both click-to-select and drag-and-drop file uploads. Provides drag state to children for visual feedback.

Parameters:

- children: ((props: UploadZoneChildProps) => ReactNode) | ReactNode - Content or render function receiving drag state
props
- props: HTMLAttributes - Additional HTML div attributes

Returns: JSX element with drag-and-drop upload functionality

$3

Container component for displaying uploaded files. Renders a container for uploaded files and provides current file list
to children. Used to display and manage the collection of uploaded images.

Parameters:

- children: ((props: UploadFilesChildProps) => ReactNode) | ReactNode - Content or render function receiving files
array
- props: HTMLAttributes - Additional HTML div attributes

Returns: JSX element containing uploaded files

$3

Individual file item component with preview and removal functionality. Displays a single uploaded file with preview
image generation and removal capability. Automatically generates image preview data and provides remove function to
children.

Parameters:

- children: ((props: UploadFileItemChildProps) => ReactNode) | ReactNode - Content or render function receiving file,
preview, and remove function
- file: FileWithId - File object with ID to display
- props: HTMLAttributes - Additional HTML div attributes

Returns: JSX element for individual file with preview and controls

$3

Image cropper component with editing controls. Provides image cropping functionality with zoom, rotation, and crop area
controls. Processes cropped images and integrates with the upload state management.

Parameters:

- children: ((props: UploadImagesCropperEditorChildProps) => ReactNode) | ReactNode - Content or render function
receiving cropper controls

Returns: JSX element with cropper editing interface

Throws: Error - When cropper config is not defined in context

$3

Visual editor component for image cropping. Renders the interactive crop editor interface using "react-easy-crop".
Provides visual feedback for crop area, zoom, and rotation adjustments.

Parameters:

- style?: CSSProperties - CSS style object, merged with default positioning styles
- props: HTMLAttributes - Additional HTML div attributes

Returns: JSX element with interactive crop editor

Throws: Error - When cropper config is not defined in context

Render Prop Types

The following types define the props passed to render functions in various components:

$3

Props passed to the render function of UploadImages.Zone component.

Properties:

- isDragActive: boolean - True when files are being dragged over the drop zone
- isFileDialogActive: boolean - True when the native file dialog is open
- isFocused: boolean - True when the drop zone is focused (keyboard navigation)

$3

Props passed to the render function of UploadImages.Files component.

Properties:

- files?: FileWithId[] - Array of currently uploaded files with unique IDs

$3

Props passed to the render function of UploadImages.File component.

Properties:

- file: FileWithId - The file object containing the original File and unique ID
- preview?: string - Base64 data URL of the image preview (undefined while loading)
- remove: () => void - Function to remove this file from the upload list

$3

Props passed to the render function of UploadImages.Cropper component.

Properties:

- zoom: number - Current zoom level (1.0 = no zoom)
- rotation: number - Current rotation angle in degrees
- setZoom: (zoom: number) => void - Function to update zoom level
- setRotation: (rotation: number) => void - Function to update rotation angle
- accept: () => void - Function to accept the current crop and add to files
- close: () => void - Function to cancel cropping and close the editor

Usage Examples

$3

`typescript
import { useState } from "react";
import { UploadImages, useUploadImages, FileWithId } from "@leancodepl/image-uploader";

function BasicUpload() {
const [files, setFiles] = useState([]);

const uploader = useUploadImages({
value: files,
onChange: setFiles,
onError: (error) => console.error("Upload error:", error),
accept: { "image/*": [".jpg", ".png", ".gif"] }
});

return (


{({ isDragActive }) => (


)}

{({ files }) => (

{files?.map(file => (

{({ preview, remove }) => (

{file.originalFile.name}

Remove

)}

))}

)}


);
}

`typescript
import { tryUploadWithUploadParams } from "@leancodepl/image-uploader"

async function uploadToServer(image: FileWithId) {
try {
const uploadedImage = await tryUploadWithUploadParams(image, async img => {
// Get upload URL from your API
const response = await fetch("/api/upload-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
fileName: img.originalFile.name,
fileType: img.originalFile.type,
}),
})

const { uploadUrl, headers } = await response.json()

return {
uri: uploadUrl,
method: "PUT",
requiredHeaders: headers,
}
})

console.log("Upload successful:", uploadedImage.url)
return uploadedImage
} catch (error) {
console.error("Upload failed:", error)
throw error
}
}
`

$3

`typescript
import { ErrorCode } from "@leancodepl/image-uploader"

function handleUploadError(errorCode: ErrorCode) {
switch (errorCode) {
case ErrorCode.FileTooLarge:
alert("File is too large. Please choose a smaller file.")
break
case ErrorCode.FileInvalidType:
alert("Invalid file type. Please upload an image file.")
break
case ErrorCode.TooManyFiles:
alert("Too many files selected. Please choose fewer files.")
break
default:
alert("An error occurred while uploading the file.")
}
}

const uploader = useUploadImages({
value: files,
onChange: setFiles,
onError: handleUploadError,
})
`

Features

- Drag-and-Drop Support: Built on "react-dropzone" for intuitive file selection
- Image Cropping: Optional cropping with zoom and rotation using "react-easy-crop"
- File Validation: Automatic validation with customizable error handling
- Preview Generation: Automatic image preview generation for uploaded files
- Duplicate Detection: Prevents uploading the same file multiple times
- TypeScript Support: Full TypeScript definitions included
- Flexible UI: Render prop pattern for complete UI customization
- Server Integration: Helper utilities for uploading to any backend service

Configuration

$3

`typescript
type CropperConfig = {
aspect: number // Aspect ratio (e.g., 16/9, 1, 4/3)
maxWidth?: number // Maximum output width in pixels
maxHeight?: number // Maximum output height in pixels
withRotation?: boolean // Enable rotation controls
withZoom?: boolean // Enable zoom controls
}
`

$3

`typescript
// Accept only JPEG and PNG
const accept = {
"image/jpeg": [".jpg", ".jpeg"],
"image/png": [".png"],
}

// Accept all image types (default)
const accept = { "image/*": [] }
`

$3

`typescript
import { useState } from "react";
import { UploadImages, useUploadImages, FileWithId } from "@leancodepl/image-uploader";

function CroppableUpload() {
const [files, setFiles] = useState([]);

const uploader = useUploadImages({
value: files,
onChange: setFiles,
cropper: {
aspect: 16 / 9,
maxWidth: 800,
maxHeight: 450,
withRotation: true,
withZoom: true
}
});

return (


Drop images to crop



{({ zoom, rotation, setZoom, setRotation, accept, close }) => (


)}

{({ files }) => (

{files?.map(file => (

{({ preview, remove }) => (

Remove

)}

))}

)}


);
}

`typescript
import { tryUploadWithUploadParams } from "@leancodepl/image-uploader"

async function uploadToServer(image: FileWithId) {
try {
const uploadedImage = await tryUploadWithUploadParams(image, async img => {
// Get upload URL from your API
const response = await fetch("/api/upload-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
fileName: img.originalFile.name,
fileType: img.originalFile.type,
}),
})

const { uploadUrl, headers } = await response.json()

return {
uri: uploadUrl,
method: "PUT",
requiredHeaders: headers,
}
})

console.log("Upload successful:", uploadedImage.url)
return uploadedImage
} catch (error) {
console.error("Upload failed:", error)
throw error
}
}
`

$3

`typescript
import { ErrorCode } from "@leancodepl/image-uploader"

function handleUploadError(errorCode: ErrorCode) {
switch (errorCode) {
case ErrorCode.FileTooLarge:
alert("File is too large. Please choose a smaller file.")
break
case ErrorCode.FileInvalidType:
alert("Invalid file type. Please upload an image file.")
break
case ErrorCode.TooManyFiles:
alert("Too many files selected. Please choose fewer files.")
break
default:
alert("An error occurred while uploading the file.")
}
}

const uploader = useUploadImages({
value: files,
onChange: setFiles,
onError: handleUploadError,
})
`

Features

- Drag-and-Drop Support: Built on "react-dropzone" for intuitive file selection
- Image Cropping: Optional cropping with zoom and rotation using "react-easy-crop"
- File Validation: Automatic validation with customizable error handling
- Preview Generation: Automatic image preview generation for uploaded files
- Duplicate Detection: Prevents uploading the same file multiple times
- TypeScript Support: Full TypeScript definitions included
- Flexible UI: Render prop pattern for complete UI customization
- Server Integration: Helper utilities for uploading to any backend service

Configuration

$3

`typescript
type CropperConfig = {
aspect: number // Aspect ratio (e.g., 16/9, 1, 4/3)
maxWidth?: number // Maximum output width in pixels
maxHeight?: number // Maximum output height in pixels
withRotation?: boolean // Enable rotation controls
withZoom?: boolean // Enable zoom controls
}
`

$3

`typescript
// Accept only JPEG and PNG
const accept = {
"image/jpeg": [".jpg", ".jpeg"],
"image/png": [".png"],
}

// Accept all image types (default)
const accept = { "image/*": [] }
``