Getting Started with BucketKit React

@nilovon/bucketkit-react provides React components and hooks for building beautiful file upload interfaces. Built with shadcn/ui patterns for easy customization.

Installation

pnpm add @nilovon/bucketkit-react

Prerequisites

React 18+
Tailwind CSS (for default styling)
A backend API endpoint using @nilovon/bucketkit-core

Basic Setup

1. Wrap your app with BucketKitProvider

import { BucketKitProvider } from '@nilovon/bucketkit-react';

function App() {
  return (
    <BucketKitProvider
      endpoint="/api/upload"
      onUploadComplete={(file) => {
        console.log('Uploaded:', file.url);
      }}
      onError={(error, file) => {
        console.error('Upload failed:', error.message);
      }}
    >
      <YourApp />
    </BucketKitProvider>
  );
}

2. Add upload components

import {
  BucketKitDropzone,
  BucketKitUploadButton,
  BucketKitUploadList,
} from '@nilovon/bucketkit-react';

function UploadPage() {
  return (
    <div className="space-y-4">
      <BucketKitDropzone
        multiple
        accept={['image/*', 'application/pdf']}
        maxSize={10 * 1024 * 1024}
      />
      
      <BucketKitUploadButton>
        Or click to upload
      </BucketKitUploadButton>
      
      <BucketKitUploadList
        showCancel
        showRetry
        showRemove
      />
    </div>
  );
}

Provider Options

Option	Type	Default	Description
`endpoint`	`string`	required	API endpoint for presigned URLs
`headers`	`Record<string, string>`	-	Additional headers (e.g., auth)
`onUploadComplete`	`(item: UploadItem) => void`	-	Called when upload succeeds
`onError`	`(error: Error, item: UploadItem) => void`	-	Called when upload fails
`autoUpload`	`boolean`	`true`	Start upload immediately
`maxConcurrent`	`number`	`3`	Max parallel uploads

With Authentication

import { useAuth } from 'your-auth-library';

function App() {
  const { token } = useAuth();

  return (
    <BucketKitProvider
      endpoint="/api/upload"
      headers={{
        Authorization: `Bearer ${token}`,
      }}
    >
      <YourApp />
    </BucketKitProvider>
  );
}

Upload Flow

User drops or selects files
Files are validated client-side (size, type)
For each file, request presigned URL from your API
Upload directly to S3 using presigned URL
Progress is tracked and displayed
onUploadComplete is called with the final URL

Next Steps

Components - Explore all components
Hooks - Use hooks for custom UIs
Styling - Customize the appearance

Getting Started

On this page