Referensi Nilai Return

Semua yang dikembalikan oleh hook useDropup.

Gambaran Umum

const {
  files,          // Array objek file
  state,          // State saat ini
  actions,        // Actions yang tersedia
  getDropProps,   // Props untuk zona drop
  getInputProps,  // Props untuk elemen input
  openFileDialog, // Buka file picker
} = useDropup();

files

Array objek DropupFile yang mewakili semua file yang ditambahkan.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "foto.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://..." (hanya gambar)
  console.log(file.uploadedUrl); // "https://..." (setelah upload)
  console.log(file.error);       // DropupError (jika gagal)
});

Properti DropupFile

Properti	Tipe	Deskripsi
id	string	Identifier unik
file	File	Objek File browser asli
name	string	Nama file
size	number	Ukuran dalam bytes
type	string	Tipe MIME
status	FileStatus	Status saat ini
progress	number	Progres upload (0-100)
preview	string | undefined	URL preview untuk gambar
uploadedUrl	string | undefined	URL setelah upload berhasil
response	unknown	Data response server
error	DropupError | undefined	Error jika upload gagal
meta	Record<string, unknown>	Metadata kustom

Nilai FileStatus

Status	Deskripsi
'idle'	File ditambahkan, belum diupload
'uploading'	Upload sedang berlangsung
'complete'	Upload berhasil
'error'	Upload gagal
'paused'	Upload dijeda (upload yang dapat dilanjutkan)

state

State saat ini dari dropzone.

const { state } = useDropup();

console.log(state.isDragging);   // true saat menyeret
console.log(state.isDragAccept); // true saat file yang diseret valid
console.log(state.isDragReject); // true saat file yang diseret tidak valid
console.log(state.isUploading);  // true saat ada file yang diupload
console.log(state.progress);     // progres keseluruhan 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Properti State

Properti	Tipe	Deskripsi
isDragging	boolean	File sedang diseret di atas zona drop
isDragAccept	boolean	File yang diseret lulus validasi
isDragReject	boolean	File yang diseret gagal validasi
isUploading	boolean	Ada file yang sedang diupload
progress	number	Rata-rata progres semua file (0-100)
status	DropupStatus	Status upload keseluruhan

Nilai DropupStatus

Status	Deskripsi
'idle'	Tidak ada upload yang berlangsung
'uploading'	Satu atau lebih file sedang diupload
'complete'	Semua upload selesai dengan sukses
'error'	Satu atau lebih upload gagal

actions

Objek yang berisi semua actions yang tersedia.

const { actions } = useDropup();

// Mulai upload
actions.upload();              // Upload semua file idle
actions.upload(['id1', 'id2']); // Upload file tertentu

// Batalkan upload
actions.cancel();              // Batalkan semua upload
actions.cancel('file-id');     // Batalkan file tertentu

// Hapus file
actions.remove('file-id');     // Hapus file tertentu
actions.reset();               // Hapus semua file

// Coba ulang upload yang gagal
actions.retry();               // Coba ulang semua yang gagal
actions.retry(['id1']);        // Coba ulang file tertentu

// Tambahkan file secara programatik
actions.addFiles(fileList);    // Tambahkan File[] atau FileList

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

Method Action

upload(fileIds?)

Mulai mengupload file.

// Upload semua file idle
actions.upload();

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

Parameter	Tipe	Deskripsi
fileIds	string[] (opsional)	ID file tertentu untuk diupload

cancel(fileId?)

Batalkan upload yang sedang berlangsung.

// Batalkan semua upload
actions.cancel();

// Batalkan file tertentu
actions.cancel('file-id');

Parameter	Tipe	Deskripsi
fileId	string (opsional)	ID file tertentu untuk dibatalkan

remove(fileId)

Hapus file dari daftar.

actions.remove('file-id');

Parameter	Tipe	Deskripsi
fileId	string	ID file untuk dihapus

reset()

Hapus semua file dan reset state.

actions.reset();

retry(fileIds?)

Coba ulang upload yang gagal.

// Coba ulang semua upload yang gagal
actions.retry();

// Coba ulang file tertentu
actions.retry(['file-id-1']);

Parameter	Tipe	Deskripsi
fileIds	string[] (opsional)	ID file tertentu untuk dicoba ulang

addFiles(files)

Tambahkan file secara programatik.

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

// Dari sumber lain
actions.addFiles([file1, file2]);

Parameter	Tipe	Deskripsi
files	File[] | FileList	File untuk ditambahkan

updateFileMeta(fileId, meta)

Perbarui metadata file.

actions.updateFileMeta('file-id', {
  description: 'Foto saya',
  tags: ['liburan', '2024'],
});

Parameter	Tipe	Deskripsi
fileId	string	ID file untuk diperbarui
meta	Record<string, unknown>	Metadata untuk digabungkan

getDropProps

Mengembalikan props untuk disebarkan pada elemen zona drop.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Lepas file di sini
</div>

Dengan Props Kustom

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Handler klik kustom Anda
      console.log('Diklik!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Props yang Dikembalikan

Properti	Tipe	Deskripsi
onDragEnter	function	Handler drag enter
onDragOver	function	Handler drag over
onDragLeave	function	Handler drag leave
onDrop	function	Handler drop
onClick	function	Handler klik (buka dialog)
role	string	Role aksesibilitas
tabIndex	number	Tab index untuk fokus

getInputProps

Mengembalikan props untuk disebarkan pada input file tersembunyi.

const { getInputProps } = useDropup();

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

Dengan Props Kustom

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

Props yang Dikembalikan

Properti	Tipe	Deskripsi
type	'file'	Tipe input
accept	string	Tipe file yang diterima
multiple	boolean	Izinkan multiple file
onChange	function	Handler change
style	object	Style tersembunyi

openFileDialog

Fungsi untuk membuka file picker secara programatik.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Jelajahi File
</button>

Contoh Penggunaan

Daftar File Lengkap

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

  return (
    <div>
      <h3>File ({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])}>Coba Ulang</button>
            </>
          )}

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

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

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

      <button onClick={() => actions.reset()}>
        Bersihkan Semua
      </button>
    </div>
  );
}

Styling State Seret

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>Hanya gambar yang diterima!</p>
      ) : (
        <p>Lepas gambar di sini</p>
      )}
    </div>
  );
}