Return Values Reference

Everything returned by the useDropup hook.

Overview

const {
  files,          // Array of file objects
  state,          // Current state
  actions,        // Available actions
  getDropProps,   // Props for drop zone
  getInputProps,  // Props for input element
  openFileDialog, // Open file picker
} = useDropup();

files

Array of DropupFile objects representing all added files.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "photo.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (images only)
  console.log(file.uploadedUrl); // "https://..." (after upload)
  console.log(file.error);       // DropupError (if failed)
});

DropupFile Properties

Property	Type	Description
id	string	Unique identifier
file	File	Original browser File object
name	string	File name
size	number	Size in bytes
type	string	MIME type
status	FileStatus	Current status
progress	number	Upload progress (0-100)
preview	string | undefined	Preview URL for images
uploadedUrl	string | undefined	URL after successful upload
response	unknown	Server response data
error	DropupError | undefined	Error if upload failed
meta	Record<string, unknown>	Custom metadata

FileStatus Values

Status	Description
'idle'	File added, not uploading
'uploading'	Upload in progress
'complete'	Upload successful
'error'	Upload failed
'paused'	Upload paused (resumable uploads)

state

Current state of the dropzone.

const { state } = useDropup();

console.log(state.isDragging);   // true when dragging over
console.log(state.isDragAccept); // true when dragged files are valid
console.log(state.isDragReject); // true when dragged files are invalid
console.log(state.isUploading);  // true when any file is uploading
console.log(state.progress);     // overall progress 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

State Properties

Property	Type	Description
isDragging	boolean	Files being dragged over drop zone
isDragAccept	boolean	Dragged files pass validation
isDragReject	boolean	Dragged files fail validation
isUploading	boolean	Any file currently uploading
progress	number	Average progress of all files (0-100)
status	DropupStatus	Overall upload status

DropupStatus Values

Status	Description
'idle'	No uploads in progress
'uploading'	One or more files uploading
'complete'	All uploads finished successfully
'error'	One or more uploads failed

actions

Object containing all available actions.

const { actions } = useDropup();

// Start uploads
actions.upload();              // Upload all idle files
actions.upload(['id1', 'id2']); // Upload specific files

// Cancel uploads
actions.cancel();              // Cancel all uploads
actions.cancel('file-id');     // Cancel specific file

// Remove files
actions.remove('file-id');     // Remove specific file
actions.reset();               // Remove all files

// Retry failed uploads
actions.retry();               // Retry all failed
actions.retry(['id1']);        // Retry specific files

// Add files programmatically
actions.addFiles(fileList);    // Add File[] or FileList

// Update file metadata
actions.updateFileMeta('file-id', { tag: 'important' });

Action Methods

upload(fileIds?)

Start uploading files.

// Upload all idle files
actions.upload();

// Upload specific files
actions.upload(['file-id-1', 'file-id-2']);

Parameter	Type	Description
fileIds	string[] (optional)	Specific file IDs to upload

cancel(fileId?)

Cancel ongoing uploads.

// Cancel all uploads
actions.cancel();

// Cancel specific file
actions.cancel('file-id');

Parameter	Type	Description
fileId	string (optional)	Specific file ID to cancel

remove(fileId)

Remove a file from the list.

actions.remove('file-id');

Parameter	Type	Description
fileId	string	File ID to remove

reset()

Remove all files and reset state.

actions.reset();

retry(fileIds?)

Retry failed uploads.

// Retry all failed uploads
actions.retry();

// Retry specific files
actions.retry(['file-id-1']);

Parameter	Type	Description
fileIds	string[] (optional)	Specific file IDs to retry

addFiles(files)

Add files programmatically.

// From clipboard
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// From another source
actions.addFiles([file1, file2]);

Parameter	Type	Description
files	File[] | FileList	Files to add

updateFileMeta(fileId, meta)

Update file metadata.

actions.updateFileMeta('file-id', {
  description: 'My photo',
  tags: ['vacation', '2024'],
});

Parameter	Type	Description
fileId	string	File ID to update
meta	Record<string, unknown>	Metadata to merge

getDropProps

Returns props to spread on the drop zone element.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Drop files here
</div>

With Custom Props

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Your custom click handler
      console.log('Clicked!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Returned Props

Property	Type	Description
onDragEnter	function	Drag enter handler
onDragOver	function	Drag over handler
onDragLeave	function	Drag leave handler
onDrop	function	Drop handler
onClick	function	Click handler (opens dialog)
role	string	Accessibility role
tabIndex	number	Tab index for focus

getInputProps

Returns props to spread on the hidden file input.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

With Custom Props

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

Returned Props

Property	Type	Description
type	'file'	Input type
accept	string	Accepted file types
multiple	boolean	Allow multiple files
onChange	function	Change handler
style	object	Hidden styles

openFileDialog

Function to programmatically open the file picker.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Browse Files
</button>

Usage Examples

Complete File List

function FileList() {
  const { files, actions, state } = useDropup({
    upload: { url: '/api/upload' },
  });

  return (
    <div>
      <h3>Files ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>Retry</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Remove</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Uploading... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Upload All
      </button>

      <button onClick={() => actions.reset()}>
        Clear All
      </button>
    </div>
  );
}

Drag State Styling

function StyledDropzone() {
  const { state, getDropProps, getInputProps } = useDropup({
    accept: 'image/*',
  });

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>Only images are accepted!</p>
      ) : (
        <p>Drop images here</p>
      )}
    </div>
  );
}