Upload API

Every public member of <oge-file-uploader>, its two companion directives and the transport contract. Back to the demos →

Properties Methods Events Types

OgeFileUploader

oge-file-uploader

Properties 40

Selection

Name	Type	Default	Description
`accept`	`string`	`''`	The `accept` attribute of the file input. Also filters drops and pastes, which the browser does not do for you.
`multiple`	`boolean`	`true`	Allows several files. With `false` a new selection replaces the list, which is what every reference does.
`directory`	`boolean`	`false`	Lets the dialog pick a folder, and descends into dropped folders. Falls back to the flat file list where the entry API is unavailable.
`pastable`	`boolean`	`false`	Adds files from a paste while the uploader has focus — a pasted screenshot included.
`allowDrop`	`boolean`	`true`	Turns drag & drop off without hiding the browse affordance.
`dropZone`	`string \| undefined`	`undefined`	Name this uploader answers to, so `[ogeUploadDropZone]` and `[ogeUploadTrigger]` elsewhere can reach it. dx `dropZone`, Kendo `zoneId`, Syncfusion `dropArea`.
`dropEffect`	`'copy' \| 'move' \| 'link' \| 'none' \| 'default'`	`'copy'`	Pointer feedback while files hover the zone.
`fieldName`	`string`	`'files[]'`	Multipart field name, and the `name` attribute of the file input. Called `fieldName` because `name` belongs to the Angular forms contract — Kendo splits it the same way with `saveField`.
`openFileDialogOnClick`	`boolean`	`true`	Ant’s option. `false` makes the zone drop-only — and stops it being a button, because a button that does nothing on Enter is worse than none; the separate browse button appears instead so the keyboard path survives.
`capture`	`boolean \| 'user' \| 'environment'`	`undefined`	The native `capture` attribute: opens the camera or microphone directly on mobile instead of the file browser.
`transformFile`	`((file: File) => File \| Promise<File>) \| undefined`	`undefined`	Rewrites each file — compression, watermarking, EXIF stripping. Ant folds this into `beforeUpload`; keeping it separate from `validateFile` means a transform cannot accidentally reject. Applied before validation, so the restrictions judge the bytes that will be sent.
`thumbnailFor`	`((file: OgeUploadFile) => string \| null \| Promise<string \| null>) \| undefined`	`undefined`	Supplies a preview the browser cannot make itself — a server-rendered PDF thumbnail, a downscaled canvas image. Ant’s `previewFile` plus `isImageUrl`: returning `null` is the "not an image" half.
`inputAttributes`	`Record<string, string>`	`{}`	Extra attributes for the internal file input, which no Angular binding can reach.

Restrictions

Name	Type	Default	Description
`allowedFileExtensions`	`readonly string[]`	`[]`	`.png`-style or bare `png`-style; empty allows everything.
`maxFileSize / minFileSize`	`number \| undefined`	`undefined`	Inclusive bounds in bytes. `undefined` means no limit — an explicit `0` is a real limit, unlike dx, where it is the sentinel.
`maxFileCount`	`number \| undefined`	`undefined`	Only the files past the limit are rejected, and a rejected file never spends a count slot.
`maxTotalFileSize`	`number \| undefined`	`undefined`	Budget across the whole list. OGE extra.
`validateFile`	`((file: File) => string \| null) \| undefined`	`undefined`	Returns a message to reject, or `null` to accept — the validation half of Ant’s `beforeUpload`.

Transport

Name	Type	Default	Description
`uploadUrl`	`string \| ((files: readonly File[]) => string)`	`''`	Empty means there is nowhere to send to, and nothing is sent — the uploader stays a picker.
`uploadMode`	`'instantly' \| 'useButtons' \| 'useForm' \| 'select'`	`'instantly'`	`select` never uploads: Kendo’s FileSelect as a mode rather than a second component.
`uploadMethod / uploadHeaders / uploadCustomData`	`'post' \| 'put' \| 'patch' / Record / Record \| fn`	`'post' / {} / {}`	`uploadCustomData` also takes a per-file function — Ant’s `data` in both shapes.
`withCredentials / responseType / timeout`	`boolean / 'json' \| 'text' \| 'blob' / number`	`false / json / undefined`	Standard request knobs.
`batch`	`boolean`	`false`	Every file in one request.
`concurrency`	`number \| undefined`	`3 (config)`	One number replaces two booleans: Kendo’s `concurrent: false` and Syncfusion’s `sequentialUpload: true` are both `1`.
`chunk`	`boolean \| OgeUploadChunkOptions`	`false`	Kendo’s `ChunkSettings` defaults: `size: 1 MiB`, `autoRetryAfter: 100`, `maxAutoRetries: 1`, `resumable: true`.
`autoRetry`	`boolean \| OgeUploadRetryOptions`	`false`	Whole-file retry; defaults `{ count: 3, delayMs: 500 }`. A run serving its backoff frees its concurrency slot.
`uploadAdapter`	`OgeUploadAdapter \| undefined`	`undefined`	Replaces the transport wholesale. See `createHttpClientUploadAdapter` for interceptor support.
`abortable`	`boolean`	`true`	dx’s `allowCanceling`.
`removeUrl / removeMethod / removeHeaders / removeField`	`string / 'post' \| 'delete' / Record / string`	`undefined / 'post' / {} / 'fileNames'`	Server-side delete. Only files that actually reached the server are deleted there.

Display

Name	Type	Default	Description
`displayMode`	`'full' \| 'compact' \| 'button'`	`'full'`	PrimeNG’s advanced/basic pair, plus a slim `compact` bar (OGE extra).
`showFileList`	`boolean \| OgeUploadFileListOptions`	`true`	The boolean, or Ant’s options object (`showRemove`, `showRetry`, `showCancel`, `showPause`, …).
`listType / previewWidth`	`'text' \| 'picture' \| 'pictureCard' / number`	`'text' / 50`	Preview rendering.
`actionsLayout`	`'start' \| 'center' \| 'end' \| 'stretch'`	`'end'`	Where the action row sits.
`showUploadButton / showClearButton / showCancelButton`	`boolean \| undefined`	`undefined`	`undefined` derives visibility from `uploadMode` — no button that has nothing to do.
`initialFiles`	`readonly OgeUploadPreloadedFile[]`	`[]`	Files that already live on the server — Syncfusion’s `files`, Ant’s `defaultFileList`.
`messages`	`Partial<OgeUploadMessages>`	`undefined`	Per-instance override, layered over `provideOgeUploadConfig()`.

State and forms

Name	Type	Default	Description
`value`	`model<readonly File[]>`	`[]`	Every row that carries a real `File`, including invalid ones — hiding them would let `required` pass while a file is plainly on screen. The validator is what blocks submission.
`disabled / readonly / required / invalid / touched / dirty / name / errors`	`FormValueControl contract`	`—`	The Signal Forms member names. Never bind these alongside `[formField]` — express them in the schema.
`files`	`Signal<readonly OgeUploadFile[]>`	`—`	Read-only. Every row, invalid and preloaded included.
`progress / busy / uploadedCount / fileCount / limitExceeded / valid / validationErrors`	`Signal`	`—`	Read-only. Replaces dx’s `progress`/`isValid`/`validationErrors` and PrimeNG’s boolean methods.

Methods 12

OgeFileUploader

Name	Type	Description
`upload(uids?)`	`void`	Starts the queued transfers. Files that failed a restriction are never sent.
`abort(uid?, reason?)`	`void`	dx `abortUpload`, Kendo `cancelUploadByUid`.
`pause(uid) / resume(uid)`	`boolean`	Chunked and resumable transfers only; returns `false` otherwise rather than aborting and calling it a pause.
`retry(uid?)`	`void`	With no argument, everything that failed or was aborted.
`addFiles(files)`	`void`	Adds files through the same pipeline as a drop.
`removeFile(uid) / clear()`	`void`	Both run their cancelable pre-event first.
`openFileDialog()`	`void`	PrimeNG `choose`.
`getFiles(index?) / sortFiles(compare?)`	`readonly OgeUploadFile[] / void`	Syncfusion `getFilesData` / `sortFileList`; sorts by name unless told otherwise.
`preview(uid) / download(uid)`	`void`	Opens the built-in lightbox / downloads the file. Both fire a cancelable event first, so an app can substitute its own viewer or signed-URL flow — Ant’s `onPreview` and `onDownload`.
`reset(value?)`	`void`	dx’s `reset`: back to a pristine state, clearing touched and dirty. Fires no `clearing` pipeline — a reset is the app rewinding its form, not the user removing files.
`focus() / blur()`	`void`	Moves focus to the browse affordance.
`formatFileSize(bytes, options?)`	`string`	Exported free function — PrimeNG `formatSize`, Syncfusion `bytesToSize`.

Events 12

Selection

Name	Type	Description
`filesSelecting`	`OgeUploadFilesSelectingEvent`	Cancelable. Before anything is validated or added. Carries the source: dialog, drop, paste or api.
`filesSelected / fileRejected / filesDropped`	`event`	`fileRejected` fires once per file that failed a restriction — OGE extra; the references only render a message.
`dropZoneEntered / dropZoneLeft`	`OgeUploadDropZoneEvent`	dx `onDropZoneEnter` / `onDropZoneLeave`.

Transfers

Name	Type	Description
`uploading`	`OgeUploadUploadingEvent`	Cancelable, and the one place the outgoing `request` is writable — dx’s `onBeforeSend`.
`uploadStarted / uploadProgress / uploaded / uploadFailed / uploadAborted / allUploaded`	`event`	`uploadStarted` fires when a request actually goes out — not when the file is queued, and again on a retry.
`chunkUploading / chunkUploaded / chunkFailed`	`event`	`chunkUploading` is cancelable, per slice.
`uploadPausing / uploadPaused / uploadResuming / uploadResumed`	`event`	The `-ing` halves are cancelable.

List

Name	Type	Description
`fileRemoving / fileRemoved`	`event`	`fileRemoving` is cancelable and reports whether a server delete will follow.
`clearing / cleared`	`event`	`clearing` is cancelable.
`previewShowing / previewHidden`	`event`	`previewShowing` is cancelable — veto it to open your own viewer instead of the built-in lightbox.
`fileDownloading`	`OgeUploadFileDownloadingEvent`	Cancelable. The default is an anchor click against the server `url`, or a temporary object URL for a file that only exists locally.
`thumbnailFailed / valueChange / touch`	`event`	Preview decode failure, the two-way model, and the forms contract.

Types 16

Types

Name	Type	Description
`OgeUploadFile`	`interface`	`uid`, `name`, `size`, `type`, `file`, `status`, `loaded`, `progress`, `errors`, `response`, `httpStatus`, `chunk`, `attempts`, plus `bytesPerSecond` and `secondsRemaining` (OGE extra).
`OgeUploadFileStatus`	`union`	`'pending' \| 'uploading' \| 'paused' \| 'uploaded' \| 'failed' \| 'aborted' \| 'invalid' \| 'removed'`.
`OgeUploadAdapter`	`interface`	`send(parts, request, callbacks)` and optional `remove(...)`. Batch versus per-file is the shape of the argument, not a flag.
`OgeUploadChunkMetadata`	`interface`	Kendo’s `ChunkMetadata` field for field, so a Kendo-shaped server needs no changes.
`OGE_UPLOAD_TRANSPORT`	`InjectionToken`	The default adapter. Override it in tests and demos; jsdom’s XHR performs real network I/O.
`provideOgeUploadConfig(config)`	`Provider`	App-wide defaults and messages — five nested message blocks: buttons, dropZone, status, validation, announcements.
`OgeUploadDropZone`	`directive — <code>[ogeUploadDropZone]</code>`	Turns any element into a drop target for the uploader whose `dropZone` matches the given name. Exposes an `over` signal for your own hover styling.
`OgeUploadTrigger`	`directive — <code>[ogeUploadTrigger]</code>`	Opens an uploader’s file dialog from a button elsewhere on the page — dx’s `dialogTrigger`. Disables itself while no uploader answers to that name.
`createXhrUploadAdapter()`	`() => OgeUploadAdapter`	The default transport, and the value behind `OGE_UPLOAD_TRANSPORT`. Exported so a custom adapter can delegate to it.
`createHttpClientUploadAdapter(http)`	`(http: HttpClient) => OgeUploadAdapter`	Runs transfers through Angular’s `HttpClient`, so interceptors (auth, tracing) apply. `@angular/common/http` is passed in, never imported by the package.

Template directives

Name	Type	Description
`OgeUploadFileTemplate`	`directive — <code>*ogeUploadFileTemplate</code>`	Replaces one file row. Context: `$implicit` (the file), `index`, and the pre-formatted `size` and `status`. Covers PrimeNG’s `file`/`filelabel`, Syncfusion’s `template` and Ant’s `itemRender`.
`OgeUploadHeaderTemplate`	`directive — <code>*ogeUploadHeaderTemplate</code>`	Replaces the strip above the list. Context: the files, `count`, `uploadedCount` and a pre-formatted `totalSize`.
`OgeUploadDropZoneTemplate`	`directive — <code>*ogeUploadDropZoneTemplate</code>`	Replaces the drop zone’s contents. Context: `$implicit` is `true` while files hover, plus `disabled`.
`OgeUploadEmptyTemplate`	`directive — <code>*ogeUploadEmptyTemplate</code>`	Rendered in place of the list while nothing is selected.
`OgeUploadToolbarTemplate`	`directive — <code>*ogeUploadToolbarTemplate</code>`	Replaces the Upload/Clear action row. Context: the files and `uploading`.
`OgeUploadIconTemplate`	`directive — <code>*ogeUploadIconTemplate</code>`	Replaces one glyph. `$implicit` is an `OgeUploadIconSlot` — 14 values covering PrimeNG’s four icon slots and Ant’s three, in one directive instead of seven inputs.