Skip to content
Devix Open Source
Search products /
devix.pk

Reference

Options, methods and events

Options

What is allowed

Option Type Default What it does
accept string | string[] the input's own accept 'image/*,.pdf', or a list. Matched on extension as well as media type.
maxSize number | string — A bare number is bytes; '5MB', '5MiB', '500 kB' say their own.
minSize number | string — The same, the other way.
maxFiles number — How many may be held at once. Rejected ones do not count.
duplicates boolean true false turns away a file already in the list, by name, size and date.
check (file) => Reason | string | null — Your own rule. Return a code, or a sentence to show.

Where they go

Option Type Default What it does
url string — Where to send them. Without it, the form posts them itself.
method string 'POST'
fieldName string 'file' The multipart field the file arrives in.
headers object | () => object — A function is called for every request, so a token can be fresh.
data object | (file) => object — Extra fields sent alongside.
withCredentials boolean false Send cookies cross-origin.
timeout number — Milliseconds.
chunkSize number — Send in pieces this big, with resume.
resume boolean true Ask the server what it already has before sending chunks.
autoUpload boolean true when there is a url Start as soon as a file is added.
concurrency number 3 How many at once.
retries number 2 Tries after a failure worth repeating.
transform (file) => Blob | Promise<Blob> — Change a file before it is sent.

How it looks and behaves

Option Type Default What it does
thumbnails boolean true Preview images.
paste boolean true Take files pasted into the page.
folders boolean true Read dropped folders, not just the files beside them.
dropOn Element | Element[] — Other elements that accept a drop — a whole page, a table row.
locale string the device's How sizes and times are written.
theme 'light' | 'dark' | 'auto' 'auto' auto follows the page.
classNames Partial<Record<ClassPart, string>> — Your classes on any part.
icons { upload, file, remove, retry, done, failed } — Your own SVG or markup.
strings Partial<UploaderStrings> English Every word it says.

Callbacks

createFileUploader(input, {
  onAdd: (file, uploader) => {},
  onReject: (rawFile, problem, uploader) => {},
  onProgress: (file, uploader) => {},     // file.progress is 0–1, file.sent is bytes
  onSuccess: (file, response, uploader) => {},
  onError: (file, message, uploader) => {},
  onRemove: (file, uploader) => {},
  onComplete: (files, uploader) => {},    // nothing left waiting or uploading
});

An UploadedFile

{
  id: string;
  file: File;               // with .relativePath when it came from a dropped folder
  status: 'waiting' | 'uploading' | 'done' | 'failed' | 'cancelled';
  progress: number;         // 0–1
  sent: number;             // bytes
  problem?: Problem;        // why it was turned away, if it was
  response?: string;        // what the server said
  error?: string;
  attempts: number;
}

Methods

uploader.addFiles(fileList);
uploader.getFiles();       // UploadedFile[]
uploader.upload();         // send everything still waiting
uploader.retry();          // or retry(id)
uploader.cancel();         // or cancel(id)
uploader.remove(id);
uploader.clear();
uploader.getResponses();   // what the server said, for the ones that made it
uploader.setOptions({ maxSize: '20MB' });
uploader.destroy();        // gives the page its own input back, untouched
uploader.input;            // the real <input type="file">
uploader.element;          // the widget root

Events

All three are CustomEvents on the widget root, and all bubble:

Event detail
dx:uploadsuccess { file, response }
dx:uploaderror { file, error, status }
dx:uploadcomplete { files }

Words

createFileUploader(input, {
  strings: {
    label: 'أفلت الملفات هنا',
    hint: 'أو اخترها',
    remove: 'إزالة',
    retry: 'حاول مرة أخرى',
    summary: (done, total) => `${done} من ${total} تم رفعها`,
    problem: (code, limit, actual) => ({
      'too-large': `كبير جدًا — ${actual}، والحد ${limit}`,
      'wrong-type': 'نوع ملف غير مقبول',
      'too-many': `عدد كبير جدًا — الحد ${limit}`,
      duplicate: 'موجود بالفعل',
      empty: 'هذا الملف فارغ',
      rejected: 'غير مقبول',
      'too-small': `صغير جدًا — ${actual}`,
    })[code],
  },
});

Sizes and times come from Intl, so they are already in the locale's script. Set locale to name the locale, or leave it and the device decides. RTL needs nothing else: the layout is written in logical properties.

Updated 12 Sep 2026