Components

BucketKit provides three main components for building upload interfaces.

BucketKitDropzone

A drag-and-drop zone for file uploads.

<BucketKitDropzone
  multiple
  accept={['image/*', 'application/pdf']}
  maxSize={10 * 1024 * 1024}
  disabled={false}
  className="min-h-[200px]"
  onFilesSelected={(files) => console.log('Selected:', files)}
>
  <p>Custom content here</p>
</BucketKitDropzone>

Props

Prop	Type	Default	Description
`multiple`	`boolean`	`true`	Accept multiple files
`accept`	`string \| string[]`	-	Accepted MIME types
`maxSize`	`number`	-	Max file size (bytes)
`disabled`	`boolean`	`false`	Disable the dropzone
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	Custom idle content
`dragActiveContent`	`ReactNode`	-	Content when dragging
`onFilesSelected`	`(files: File[]) => void`	-	Called on file selection

Custom Content

<BucketKitDropzone
  accept="image/*"
  maxSize={5 * 1024 * 1024}
>
  <div className="text-center">
    <ImageIcon className="h-12 w-12 mx-auto text-gray-400" />
    <p className="mt-2">Drag images here</p>
    <p className="text-sm text-gray-500">PNG, JPG up to 5MB</p>
  </div>
</BucketKitDropzone>

BucketKitUploadButton

A button that opens a file picker.

<BucketKitUploadButton
  multiple
  accept="image/*"
  maxSize={10 * 1024 * 1024}
  variant="default"
  size="default"
>
  <UploadIcon className="mr-2 h-4 w-4" />
  Upload Files
</BucketKitUploadButton>

Props

Prop	Type	Default	Description
`multiple`	`boolean`	`true`	Accept multiple files
`accept`	`string \| string[]`	-	Accepted MIME types
`maxSize`	`number`	-	Max file size (bytes)
`disabled`	`boolean`	`false`	Disable the button
`variant`	`'default' \| 'outline' \| ...`	`'default'`	Button style
`size`	`'default' \| 'sm' \| 'lg'`	`'default'`	Button size
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	Button content

Variants

// Primary button
<BucketKitUploadButton variant="default">Upload</BucketKitUploadButton>

// Outline style
<BucketKitUploadButton variant="outline">Upload</BucketKitUploadButton>

// Secondary
<BucketKitUploadButton variant="secondary">Upload</BucketKitUploadButton>

// Ghost
<BucketKitUploadButton variant="ghost">Upload</BucketKitUploadButton>

BucketKitUploadList

Displays the list of uploads with progress.

<BucketKitUploadList
  showCancel
  showRetry
  showRemove
  className="space-y-2"
/>

Props

Prop	Type	Default	Description
`showCancel`	`boolean`	`true`	Show cancel button
`showRetry`	`boolean`	`true`	Show retry button
`showRemove`	`boolean`	`true`	Show remove button
`className`	`string`	-	Container CSS classes
`slotClassNames`	`object`	-	Classes for sub-elements
`renderItem`	`function`	-	Custom item renderer

Custom Slot Classes

<BucketKitUploadList
  slotClassNames={{
    item: 'bg-gray-50 p-4',
    fileName: 'font-bold',
    progress: 'bg-blue-500',
    status: 'text-xs',
    actions: 'gap-2',
  }}
/>

Custom Item Renderer

<BucketKitUploadList
  renderItem={(item, actions) => (
    <div className="flex items-center justify-between p-2 border rounded">
      <div>
        <p className="font-medium">{item.fileName}</p>
        <p className="text-sm text-gray-500">
          {item.status} - {item.progress}%
        </p>
      </div>
      <div className="flex gap-2">
        {item.status === 'uploading' && (
          <button onClick={actions.cancel}>Cancel</button>
        )}
        {item.status === 'error' && (
          <button onClick={actions.retry}>Retry</button>
        )}
        <button onClick={actions.remove}>Remove</button>
      </div>
    </div>
  )}
/>

Complete Example

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

function UploadDemo() {
  return (
    <BucketKitProvider
      endpoint="/api/upload"
      onUploadComplete={(item) => toast.success(`Uploaded: ${item.fileName}`)}
      onError={(error) => toast.error(error.message)}
    >
      <div className="max-w-xl mx-auto p-6 space-y-6">
        <BucketKitDropzone
          multiple
          accept={['image/*', 'application/pdf']}
          maxSize={10 * 1024 * 1024}
        />

        <div className="flex gap-2">
          <BucketKitUploadButton variant="outline">
            Browse Files
          </BucketKitUploadButton>
        </div>

        <BucketKitUploadList showCancel showRetry showRemove />
      </div>
    </BucketKitProvider>
  );
}

Components

On this page