@vaultly/react-upload

A beautiful, easy-to-use React component for uploading files to Vaultly cloud storage with drag and drop support. Similar to uploadThing, but for Vaultly.

Installation

npm install @vaultly/react-upload
# or
yarn add @vaultly/react-upload
# or
pnpm add @vaultly/react-upload

Quick Start

1. Initialize VaultlyProvider

Wrap your app (or the part that needs upload functionality) with VaultlyProvider:

import { VaultlyProvider } from '@vaultly/react-upload';

function App() {
  return (
    <VaultlyProvider config={{ publicKey: 'YOUR_PUBLIC_KEY' }}>
      <YourComponent />
    </VaultlyProvider>
  );
}

2. Use VaultlyUpload Component

import { VaultlyUpload } from '@vaultly/react-upload';

function MyComponent() {
  return (
    <VaultlyUpload
      bucket="my-bucket" // Optional: omit to use server default
      onSuccess={(response) => {
        console.log('Upload successful!', response.url);
        // response.url contains the public URL of the uploaded file
      }}
      onError={(error) => {
        console.error('Upload failed:', error);
      }}
      onUploading={(progress) => {
        console.log('Upload progress:', progress);
      }}
    />
  );
}

Example without bucket (uses server default)

<VaultlyUpload
  onSuccess={(response) => {
    console.log('Uploaded to default bucket:', response.url);
  }}
  onError={(error) => console.error(error)}
/>

API Reference

VaultlyProvider

Provider component that initializes Vaultly with your public key.

Props

• config (required): Configuration object
  • publicKey (required): Your Vaultly public key (access key)
  • baseUrl (optional): Base URL for the API. Defaults to https://vaulty-iota.vercel.app

Example

<VaultlyProvider config={{ publicKey: 'your-public-key' }}>
  <App />
</VaultlyProvider>

VaultlyUpload

Main upload component with drag and drop support.

Props

• bucket (optional): The bucket name where files will be uploaded. If not provided, the server will use its default bucket
• key (optional): The file path/key. If not provided, the filename will be used
• file (optional): File object to upload directly. If provided, upload will start automatically
• onSuccess (optional): Callback function called when upload succeeds
  • Receives: VaultlyUploadResponse object with url, bucket, key, size, etc.
• onError (optional): Callback function called when upload fails
  • Receives: Error object or error message string
• onUploading (optional): Callback function called during upload with progress updates
  • Receives: number (progress percentage 0-100)
• className (optional): Custom CSS class name
• style (optional): Custom inline styles
• disabled (optional): Disable the upload component
• accept (optional): File input accept attribute. Defaults to image types
• maxSize (optional): Maximum file size in bytes
• children (optional): Custom content to render inside the upload area

Example with all props

<VaultlyUpload
  bucket="my-bucket"
  key="images/profile.jpg"
  file={selectedFile} // Optional: pass file directly to auto-upload
  onSuccess={(response) => {
    console.log('File uploaded:', response.url);
    // Save response.url to your database
  }}
  onError={(error) => {
    alert(`Upload failed: ${error}`);
  }}
  onUploading={(progress) => {
    console.log(`Uploading: ${progress}%`);
  }}
  maxSize={5 * 1024 * 1024} // 5MB
  disabled={false}
  className="my-upload-component"
  style={{ minHeight: '200px' }}
/>

Example with file prop (programmatic upload)

function MyComponent() {
  const [file, setFile] = useState<File | null>(null);

  const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFile = e.target.files?.[0];
    if (selectedFile) {
      setFile(selectedFile); // This will trigger automatic upload
    }
  };

  return (
    <>
      <input type="file" onChange={handleFileSelect} />
      <VaultlyUpload
        bucket="my-bucket"
        file={file}
        onSuccess={(response) => {
          console.log('Uploaded:', response.url);
          setFile(null); // Reset after upload
        }}
        onError={(error) => console.error(error)}
      />
    </>
  );
}

Response Format

The onSuccess callback receives a VaultlyUploadResponse object:

interface VaultlyUploadResponse {
  success: boolean;
  bucket: string;
  key: string;
  size: number;
  etag: string;
  isPublic: boolean;
  url: string; // Public URL of the uploaded file
  message: string;
}

Custom Styling

You can customize the appearance using className and style props, or provide custom children:

<VaultlyUpload
  bucket="my-bucket"
  onSuccess={(response) => console.log(response.url)}
  className="custom-upload-area"
  style={{ border: '2px solid blue', borderRadius: '12px' }}
>
  <div>
    <h3>Custom Upload Area</h3>
    <p>Click or drag files here</p>
  </div>
</VaultlyUpload>

File Type Restrictions

By default, only image files are supported (JPEG, PNG, GIF, WebP, SVG) as this uses the public upload endpoint which only accepts images. The component will automatically validate file types and show an error if an unsupported file is selected.

Security Note

This component uses only your public key (access key) for uploads. Secret keys are never exposed to the browser, making it safe for client-side use. The public upload endpoint only accepts image files and always makes them public.

License

MIT