Picsha.ai React SDK (@picsha-ai/react)

Overview

The strictly-typed React SDK provides ready-to-use components for securely uploading files to the Picsha AI backend and rendering assets with dynamic AI transformations.

Installation

npm install @picsha-ai/react

Components

1. <PicshaImage />

A drop-in replacement for the standard <img> tag that automatically constructs delivery URLs and applies on-the-fly transformations via the Picsha backend.

Key Features:

• Typed Transformations: Pass transformations as native React props (blur={5}, radius="max").
• AI-Powered Effects: Supports removeBackground, generativeRemove, and automatic aspectRatio cropping.
• Overlays: Supports complex arrays of text and image overlays, automatically encoding them into the delivery URL.

Usage:

import { PicshaImage } from '@picsha-ai/react';

<PicshaImage
  deliveryEndpoint="https://api.picsha.ai"
  assetId="uuid-of-asset"
  width={800}
  aspectRatio="16:9"
  crop="attention"
  radius={16}
  overlays={[
    { type: 'text', text: 'Stunning Event', gravity: 'bottom', size: 48 }
  ]}
/>

Props:

• deliveryEndpoint (string): Base API URL
• assetId (string) or url (string): The asset to render or external URL to proxy mapping to /v1/fetch
• width, height, aspectRatio (number | string): Dimensions
• blur, radius: Styling adjustments
• format, quality, fit, crop, position, background: Standard image optimizations
• removeBackground (boolean), generativeRemove (string): AI capabilities
• overlays (OverlayConfig[]): Array of text/image layers to composite
• force (boolean): Bypasses CDN cache
• cb (string): Cache-busting parameter

2. <PicshaUploadWidget />

A robust, themeable upload widget built on top of Uppy. It automatically handles secure authentication, direct-to-S3 uploads, and post-upload registration with the Picsha AI backend.

Key Features:

• Secure Integration: Automatically requests signed URLs via /v1/assets/presigned before uploading to S3.
• Resumable Uploads: Pass useResumable={true} to activate the Tus protocol for robust chunked uploads for large assets.
• Auto-Registration: After a successful upload, seamlessly calls POST /v1/assets to finalize the asset directly from the client.

Usage:

import { PicshaUploadWidget } from '@picsha-ai/react';

<PicshaUploadWidget
  apiUrl="https://api.picsha.ai"
  getToken={async () => "user-bearer-token"}
  useResumable={true}
  maxFileSize={1000 * 1024 * 1024} // 1GB
  theme="dark"
  onUploadSuccess={(asset) => console.log('Asset ready:', asset)}
/>

Props:

• apiUrl (string): Base API URL
• getToken (async function): Function to retrieve the current user's Auth JWT
• useResumable (boolean): Activates the TUS protocol for large files instead of standard presigned puts
• onUploadSuccess (function): Callback with full asset details once registered
• onError (function): Error handling callback
• maxFileSize (number): Limit maximum bytes allowed (default 1GB)
• theme ('light' | 'dark' | 'auto'): Widget theme
• orgId (string): Optional Organization tag