Package Exports

@bubblystorage/react
@bubblystorage/react/styles.css

Readme

@bubblystorage/react

React hooks and components for Bubbly Storage file uploads.

Installation

npm install @bubblystorage/react
# or
yarn add @bubblystorage/react
# or
pnpm add @bubblystorage/react

Features

✅ React 18+ with TypeScript support
✅ Pre-built UI components
✅ Drag & drop file uploads
✅ Progress tracking
✅ File validation (type, size)
✅ Multi-file uploads
✅ Error handling
✅ Customizable styling
✅ Works with Next.js, Remix, and all React frameworks

Quick Start

1. Import Styles

Import the CSS file in your app:

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

2. Use Components

FileUploader (Complete Solution)

The easiest way to get started - includes dropzone, file list, and progress bar:

import { FileUploader } from '@bubblystorage/react';

function App() {
  return (
    <FileUploader
      apiKey="your-api-key"
      accept="image/*,application/pdf"
      maxSize={10 * 1024 * 1024} // 10MB
      maxFiles={5}
      onSuccess={(files) => {
        console.log('Uploaded files:', files);
      }}
      onError={(error) => {
        console.error('Upload error:', error);
      }}
    />
  );
}

UploadButton (Simple Upload)

A simple button for file uploads:

import { UploadButton } from '@bubblystorage/react';

function App() {
  return (
    <UploadButton
      apiKey="your-api-key"
      accept="image/*"
      autoUpload
      onSuccess={(files) => console.log('Uploaded:', files)}
    >
      Choose Files
    </UploadButton>
  );
}

UploadDropzone (Drag & Drop)

A drag-and-drop area for file uploads:

import { UploadDropzone } from '@bubblystorage/react';

function App() {
  return (
    <UploadDropzone
      apiKey="your-api-key"
      accept="image/*"
      multiple
      autoUpload
      maxSize={5 * 1024 * 1024}
      onSuccess={(files) => console.log('Uploaded:', files)}
    />
  );
}

Custom Implementation with Hook

For full control, use the useFileUpload hook:

import { useFileUpload, UploadProgressBar } from '@bubblystorage/react';

function CustomUploader() {
  const {
    files,
    isUploading,
    progress,
    addFiles,
    removeFile,
    upload,
    reset,
    errors,
  } = useFileUpload({
    apiKey: 'your-api-key',
    onSuccess: (uploadedFiles) => {
      console.log('Success!', uploadedFiles);
    },
    onError: (error) => {
      console.error('Error:', error);
    },
  });

  return (
    <div>
      <input
        type="file"
        multiple
        onChange={(e) => {
          if (e.target.files) {
            addFiles(e.target.files);
          }
        }}
      />

      {files.map((file, index) => (
        <div key={index}>
          {file.name} - {file.size} bytes
          <button onClick={() => removeFile(index)}>Remove</button>
        </div>
      ))}

      {isUploading && progress && (
        <UploadProgressBar progress={progress} showDetails />
      )}

      {errors.length > 0 && (
        <div>
          {errors.map((error, i) => (
            <p key={i} style={{ color: 'red' }}>{error.message}</p>
          ))}
        </div>
      )}

      <button onClick={upload} disabled={isUploading || files.length === 0}>
        Upload {files.length} file(s)
      </button>

      <button onClick={reset}>Clear</button>
    </div>
  );
}

API Reference

Components

`<FileUploader />`

Complete file upload interface with all features.

Props:

Prop	Type	Default	Description
`apiKey`	`string`	required	Your Bubbly Storage API key
`apiUrl`	`string`	API URL	Custom API endpoint
`accept`	`string`	undefined	Accepted file types (e.g., "image/*")
`multiple`	`boolean`	`true`	Allow multiple file selection
`maxSize`	`number`	undefined	Maximum file size in bytes
`maxFiles`	`number`	undefined	Maximum number of files
`showFileList`	`boolean`	`true`	Show selected files list
`showUploadButton`	`boolean`	`true`	Show upload button
`autoUpload`	`boolean`	`false`	Auto-upload on file selection
`onSuccess`	`(files) => void`	undefined	Success callback
`onError`	`(error) => void`	undefined	Error callback
`onProgress`	`(progress) => void`	undefined	Progress callback

`<UploadButton />`

Simple button for file uploads.

Props:

Prop	Type	Default	Description
`apiKey`	`string`	required	Your Bubbly Storage API key
`children`	`ReactNode`	"Upload Files"	Button text/content
`accept`	`string`	undefined	Accepted file types
`multiple`	`boolean`	`true`	Allow multiple files
`autoUpload`	`boolean`	`false`	Auto-upload on selection
`variant`	`'primary' \| 'secondary' \| 'outline'`	`'primary'`	Button style
`disabled`	`boolean`	`false`	Disable button
`onFilesSelected`	`(files) => void`	undefined	File selection callback
`onSuccess`	`(files) => void`	undefined	Success callback

`<UploadDropzone />`

Drag-and-drop area for file uploads.

Props:

Prop	Type	Default	Description
`apiKey`	`string`	required	Your Bubbly Storage API key
`accept`	`string`	undefined	Accepted file types
`multiple`	`boolean`	`true`	Allow multiple files
`maxSize`	`number`	undefined	Max file size in bytes
`maxFiles`	`number`	undefined	Max number of files
`autoUpload`	`boolean`	`false`	Auto-upload on drop
`children`	`ReactNode`	Default content	Custom dropzone content
`onFilesSelected`	`(files) => void`	undefined	File selection callback
`onSuccess`	`(files) => void`	undefined	Success callback

`<UploadProgressBar />`

Progress bar for file uploads.

Props:

Prop	Type	Default	Description
`progress`	`UploadProgress \| null`	required	Progress data
`showDetails`	`boolean`	`false`	Show upload details
`variant`	`'primary' \| 'success' \| 'warning' \| 'danger'`	`'primary'`	Color variant
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size variant

Hooks

`useFileUpload(options)`

Main hook for file upload functionality.

Options:

interface UseFileUploadOptions {
  apiKey: string;
  apiUrl?: string;
  onSuccess?: (files: UploadedFile[]) => void;
  onError?: (error: UploadError) => void;
  onProgress?: (progress: UploadProgress) => void;
  validation?: {
    maxSize?: number;
    allowedTypes?: string[];
  };
}

Returns:

interface UseFileUploadReturn {
  files: File[];
  isUploading: boolean;
  progress: UploadProgress | null;
  errors: UploadError[];
  addFiles: (files: FileList | File[]) => void;
  removeFile: (index: number) => void;
  upload: () => Promise<void>;
  reset: () => void;
}

Styling

Using Default Styles

Import the default styles:

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

Custom Styling

You can customize the components using CSS classes:

/* Override button styles */
.bubbly-upload-button {
  font-family: 'Your Font', sans-serif;
}

.bubbly-btn-primary {
  background-color: #your-brand-color;
}

/* Override dropzone styles */
.bubbly-dropzone {
  border-color: #your-color;
  border-radius: 12px;
}

.bubbly-dropzone-active {
  background-color: #your-hover-color;
}

CSS Classes Reference

.bubbly-upload-button - Upload button container
.bubbly-btn-primary, .bubbly-btn-secondary, .bubbly-btn-outline - Button variants
.bubbly-dropzone - Dropzone container
.bubbly-dropzone-active - Active dropzone state
.bubbly-progress - Progress bar container
.bubbly-progress-fill - Progress bar fill
.bubbly-uploader - File uploader container
.bubbly-uploader-file-item - Individual file item

Framework-Specific Examples

Next.js App Router

// app/upload/page.tsx
'use client';

import { FileUploader } from '@bubblystorage/react';
import '@bubblystorage/react/styles.css';

export default function UploadPage() {
  return (
    <div>
      <h1>Upload Files</h1>
      <FileUploader
        apiKey={process.env.NEXT_PUBLIC_BUBBLY_API_KEY!}
        maxSize={10 * 1024 * 1024}
        onSuccess={(files) => {
          console.log('Uploaded:', files);
        }}
      />
    </div>
  );
}

Next.js Pages Router

// pages/upload.tsx
import { FileUploader } from '@bubblystorage/react';
import '@bubblystorage/react/styles.css';

export default function UploadPage() {
  return (
    <div>
      <h1>Upload Files</h1>
      <FileUploader
        apiKey={process.env.NEXT_PUBLIC_BUBBLY_API_KEY!}
        onSuccess={(files) => {
          console.log('Uploaded:', files);
        }}
      />
    </div>
  );
}

Remix

// app/routes/upload.tsx
import { FileUploader } from '@bubblystorage/react';
import styles from '@bubblystorage/react/styles.css';

export function links() {
  return [{ rel: 'stylesheet', href: styles }];
}

export default function UploadRoute() {
  return (
    <div>
      <h1>Upload Files</h1>
      <FileUploader
        apiKey={process.env.BUBBLY_API_KEY!}
        onSuccess={(files) => {
          console.log('Uploaded:', files);
        }}
      />
    </div>
  );
}

TypeScript

This package is written in TypeScript and includes type definitions. All components and hooks are fully typed.

import type {
  UploadButtonProps,
  UploadDropzoneProps,
  FileUploaderProps,
  UploadProgressBarProps,
} from '@bubblystorage/react';

import type {
  UploadedFile,
  UploadError,
  UploadProgress,
} from '@bubblystorage/shared';

JSPM