@tigrisdata/react

React components for Tigris Storage.

Installation

npm install @tigrisdata/react

Requirements

• React 18+
• A backend with upload endpoint using Tigris Storage SDK. You can see example here

Usage

Uploader Component

The Uploader component provides a drag-and-drop file upload interface:

import { Uploader } from '@tigrisdata/react';
import '@tigrisdata/react/styles.css'; // Optional: import default styles

function App() {
  return (
    <Uploader
      url="/api/upload"
      multipartThreshold={10 * 1024 * 1024} // Use multipart for files > 10MB
      onUploadComplete={(file, response) => {
        console.log('Uploaded:', response.url);
      }}
      onUploadError={(file, error) => {
        console.error('Failed:', error.message);
      }}
    />
  );
}

Props

| Prop | Type | Default | Description | | -------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------ | | url | string | required | Upload endpoint URL | | multiple | boolean | false | Allow multiple files | | accept | string | - | Accepted file types (e.g., "image/*") | | maxSize | number | - | Maximum file size in bytes | | disabled | boolean | false | Disable the uploader | | multipart | boolean | false | Enable multipart upload for large files | | partSize | number | 5242880 | Part size in bytes for multipart uploads (default 5MB) | | multipartThreshold | number | - | Auto-enable multipart for files larger than this size | | concurrency | number | 4 | Max concurrent uploads (files or multipart parts) | | uploadOptions | UploadOptions | - | Additional storage client options | | onUploadStart | (file: File) => void | - | Called when upload starts | | onUploadProgress | (file: File, progress: UploadProgress) => void | - | Called during upload | | onUploadComplete | (file: File, response: UploadResponse) => void | - | Called on success | | onUploadError | (file: File, error: Error) => void | - | Called on failure | | className | string | - | Custom CSS class | | style | CSSProperties | - | Custom inline styles | | children | ReactNode | - | Custom dropzone content |

useUpload Hook

For custom upload UI, use the useUpload hook:

import { useUpload } from '@tigrisdata/react';

function CustomUploader() {
  const { upload, uploads, isUploading, reset } = useUpload({
    url: '/api/upload',
    multipart: true, // Always use multipart
    partSize: 10 * 1024 * 1024, // 10MB parts
    onUploadComplete: (file, response) => {
      console.log('Done:', response.url);
    },
  });

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      upload(file);
    }
  };

  return (
    <div>
      <input type="file" onChange={handleFileChange} disabled={isUploading} />
      {Array.from(uploads.values()).map((state) => (
        <div key={state.file.name}>
          {state.file.name}: {state.progress.percentage}%
        </div>
      ))}
    </div>
  );
}

Return Value

| Property | Type | Description | | ---------------- | ------------------------------------------------------ | --------------------------------- | | upload | (file: File) => Promise<UploadResponse \| undefined> | Upload a single file | | uploadMultiple | (files: File[]) => Promise<...> | Upload multiple files | | uploads | Map<string, FileUploadState> | Current upload states | | isUploading | boolean | Whether any upload is in progress | | reset | () => void | Reset all upload states |

Styling

Default Styles

Import the default stylesheet for a ready-to-use look:

import '@tigrisdata/react/styles.css';

Default styles use CSS @layer tigris, so your custom styles will always take precedence without needing !important.

Custom Styles

The component uses tigris- prefixed class names with state modifiers:

/* Override default styles easily */
.tigris-uploader {
  border-color: purple;
}

CSS Classes

| Class | Description | | ------------------------------------ | -------------------------------------------- | | .tigris-uploader | Container element | | .tigris-uploader.is-dragging | When files are dragged over | | .tigris-uploader.is-uploading | When upload is in progress | | .tigris-uploader.is-disabled | When disabled | | .tigris-uploader-input | Hidden file input | | .tigris-uploader-text | Default text content | | .tigris-uploader-link | "Browse" link text | | .tigris-uploader-filelist | File list container | | .tigris-uploader-file | Individual file item | | .tigris-uploader-file.is-pending | File waiting in queue | | .tigris-uploader-file.is-uploading | File currently uploading | | .tigris-uploader-file.is-success | Upload succeeded | | .tigris-uploader-file.is-error | Upload failed | | .tigris-uploader-filename | File name text | | .tigris-uploader-progress | Progress bar container | | .tigris-uploader-progress-fill | Progress bar fill | | .tigris-uploader-status | Status text (Pending/0-100%/Uploaded/Failed) |

Server Setup

This package works with the @tigrisdata/storage server-side handler:

// app/api/upload/route.ts (Next.js App Router)
import { handleClientUpload } from '@tigrisdata/storage';

export async function POST(request: Request) {
  const body = await request.json();
  const result = await handleClientUpload(body);
  return Response.json(result);
}

License

MIT