@howells/stow-react

@howells/stow-react

React components for Stow file storage.

Installation

npm install @howells/stow-react
# or
pnpm add @howells/stow-react
# or
yarn add @howells/stow-react

Quick Start

import { UploadDropzone } from "@howells/stow-react";

function MyComponent() {
  return (
    <UploadDropzone
      endpoint="/api/upload"
      onUploadComplete={(files) => {
        console.log("Uploaded:", files);
      }}
      onUploadError={(error) => {
        console.error("Error:", error.message);
      }}
    />
  );
}

Components

<UploadDropzone>

A drag-and-drop file upload zone with built-in progress tracking.

<UploadDropzone
  // Required
  endpoint="/api/upload"
  // Callbacks
  onUploadComplete={(files) => console.log(files)}
  onUploadError={(error) => console.error(error)}
  onUploadProgress={(progress) => console.log(progress.percent)}
  onUploadBegin={(files) => console.log("Starting upload...")}
  // File restrictions
  accept="image/*" // Accepted file types
  maxSize={10 * 1024 * 1024} // Max 10MB
  maxFiles={5} // Max 5 files
  multiple={true} // Allow multiple files
  // Appearance
  className="my-dropzone"
  disabled={false}
  // Optional route for organizing files
  route="avatars"
/>

Props

Prop	Type	Default	Description
endpoint	string	required	Your server upload endpoint
route	string	-	Optional route for organizing files
onUploadComplete	(files: UploadedFile[]) => void	-	Called when all files uploaded
onUploadError	(error: Error) => void	-	Called on upload error
onUploadProgress	(progress: UploadProgress) => void	-	Called with progress updates
onUploadBegin	(files: File[]) => void	-	Called when upload starts
accept	string	-	Accepted file types (e.g., "image/*")
maxSize	number	-	Maximum file size in bytes
maxFiles	number	10	Maximum number of files
multiple	boolean	true	Allow multiple file selection
className	string	-	Custom CSS class
disabled	boolean	false	Disable the dropzone

Types

type UploadedFile = {
  key: string;
  url: string | null;
  name: string;
  size: number;
  type: string;
};

type UploadProgress = {
  file: File;
  loaded: number;
  total: number;
  percent: number;
};

Styling

The component uses inline styles by default. Override with your own CSS:

<UploadDropzone endpoint="/api/upload" className="custom-dropzone" />

.custom-dropzone {
  border: 2px dashed #3b82f6;
  border-radius: 12px;
  padding: 3rem;
  background: #f8fafc;
}

Server Setup

This component requires a server endpoint. Use @howells/stow-next for easy setup:

// app/api/upload/route.ts
import { createUploadHandler } from "@howells/stow-next";
import { StowServer } from "@howells/stow-server";

const stow = new StowServer(process.env.STOW_API_KEY!);

export const POST = createUploadHandler({
  stow,
  maxSize: 10 * 1024 * 1024,
  allowedTypes: ["image/*"],
});

License

MIT