Installation Guide

Learn about the main capabilities of React Picture Selector and how to install it in your project.

React Picture Selector provides a complete solution for handling image uploads with a modern and responsive interface. It supports both drag-and-drop and traditional selection methods, offering real-time progress indication through a smooth progress ring or percentage display. Animations are optimized with requestAnimationFrame, ensuring fluid transitions and minimal CPU consumption even on lower-end devices. Upload operations can be safely canceled using the built-in AbortController, providing users with full control over the process.

Requirements

Node.js 18+ (Next.js 15 and React 19 ready)
React 18 or 19 with concurrent rendering enabled
Your preferred package manager (npm, pnpm, bun, or yarn)
Optional but recommended: TypeScript for strong typings on props and apiConfig

TypeScript support

The package ships with TypeScript declarations so you get prop IntelliSense out of the box.

Installation steps

npm install react-picture-selector

Peer dependencies

Package	Version	Why
`react`	`^18
`react-dom`	`^18
`axios`	`^1`	HTTP client leveraged for upload/delete requests

You can install everything at once:

npm install react-picture-selector react react-dom axios

Required dependencies

If your project already depends on React 18+ and Axios, you only need to install react-picture-selector.

Project setup checklist

Install the package using the matrix above (and ensure peer deps are in place).
Import the component wherever you handle profile or gallery images.
Pass imageUrl and onChangeImage so the component stays controlled.
Choose an integration mode:
- Provide apiConfig for real API calls, or
- Enable testMode for mocked uploads during development.
Style it by adjusting size, type, colors, or additionalClassNames.

Once those steps are complete, the selector is production-ready.

Basic Setup

import PictureSelector from "react-picture-selector";
import { useState } from "react";

function ProfilePage() {
  const [currentImage, setCurrentImage] = useState("https://example.com/avatar.jpg");

  const handleImageChange = (imageUrl: string, responseData?: any) => {
    setCurrentImage(imageUrl);
    console.log("API Response:", responseData);
  };

  return (
    <PictureSelector
      imageUrl={currentImage}
      onChangeImage={handleImageChange}
      type="profile"
      title="Profile Photo"
      size={150}
    />
  );
}

Ready to Use

Your React Picture Selector is now installed and ready! Continue to the next section to explore advanced configuration options.

Verify your setup

Run your dev server (npm run dev) and open the page containing PictureSelector.
Click or drag an image to trigger the upload flow. In test mode, you should see the progress ring animate to 100%.
Switch testMode off and provide an apiConfig to confirm real network requests succeed.
Trigger deletions to ensure your backend receives the correct HTTP method and body.

Common gotchas

Always return a URL in your upload response at the path specified by responsePath.
When using Next.js app router, keep the component on the client (e.g., use client) because it relies on browser APIs.