FileUpload

Out of the box the BitFileUpload offers three ways to hand a file over: click the browse button to open the file dialog, drag a file out of the OS and drop it anywhere on the component, or focus the component and paste a file from the clipboard. The selected file appears in the built-in file list with its name, its human-readable size and an upload button that starts sending it to the UploadUrl; while files hover over the component the browse button turns into a dashed drop indicator. During the upload the item shows a progress bar with pause and cancel buttons, and once it settles, a status message reports the outcome.

The two alternative selection routes can be switched off independently. AllowDrop controls dragging files out of the OS onto the component: turning it off keeps the drop from being handled and shows a "no drop" cursor, while still swallowing the event so the browser does not navigate away to the dropped file and lose the page state. AllowPaste controls pasting files from the clipboard; a paste is only delivered to the component while the focus is inside it, so the browse button has to be focused first. Both take effect immediately when toggled at runtime, as the checkboxes below demonstrate.

Telling the user the rules before they run into them is the single biggest usability win an uploader can offer. Description renders a short hint under the browse button and - the part that is easy to forget - wires it to that button through aria-describedby, so a screen reader reads the constraints out together with the button instead of leaving them to be discovered by trial and error. Spell out the accepted types and the size ceiling there, matching whatever Accept, AllowedExtensions and MaxSize actually enforce. DescriptionTemplate takes over when the hint needs markup of its own, such as the icon below, and Classes.Description / Styles.Description restyle it.

Multiple lets the file dialog hand over several files at once and lets a single drop or paste carry several files, each uploading independently with its own progress, pause, cancel and status. Without it the dialog is limited to one file and only the first file of a multi-file drop is taken.

AutoUpload starts sending the files the moment they are selected, skipping the per-file upload button entirely - the pattern to reach for when selection itself expresses the intent to upload, like an avatar picker or an attachment area.

AutoReset clears the file list and the upload state just before the file dialog opens, so every browse starts from a clean slate - the list empties even if the dialog is then cancelled. Handy when a stale, already-uploaded selection lingering behind the dialog would be misleading.

A new selection normally replaces whatever is in the list. Append keeps the existing files - along with their upload state - and adds the new selection to the end instead, letting the user build the batch up over several rounds of browsing, dropping or pasting.

Building a batch up over several rounds of browsing makes it easy to pick the same file twice without noticing, and uploading it twice is rarely what anyone meant. Turning AllowDuplicates off rejects a newly selected file that matches one already in the list - by name, size and last modified time, which is as close to an identity as the browser exposes for a picked file - showing the DuplicateErrorMessage under it instead of sending it a second time. The rejection is not final: remove the file it duplicates and the copy becomes eligible again, since the rule is re-evaluated over the whole list on every change. Try selecting the same file twice below.

MaxSize and MinSize bound the size of each file in bytes, while MaxTotalSize bounds what the whole list adds up to - the limit that actually matches a per-request or per-user storage quota, which a per-file ceiling alone cannot express. A file outside the allowed range is marked as not allowed right at selection time - with the MaxSizeErrorMessage, MinSizeErrorMessage or MaxTotalSizeErrorMessage shown under it - and it is never sent to the server; the file stays visible in the list so the user can see exactly what was rejected and why instead of it disappearing silently. Only the files that pass the other validations consume the total-size budget, and a file turned away by it becomes eligible again as soon as removals free up room.

Max 1 MB per file:

Min 1 KB per file:

Max 2 MB in total across the batch:

Custom error message:

The two work at different moments and are both worth setting. Accept is passed straight to the accept attribute of the underlying input, which only hints the file dialog to pre-filter what it offers - it is a convenience, never a guarantee, since a drop, a paste or a "show all files" switch walks right past it. AllowedExtensions is the actual rule: it checks every file however it arrived and marks the mismatches as not allowed with the NotAllowedExtensionErrorMessage, so they stay visible in the list with their reason and are never sent.

Its entries are matched leniently - an extension may be written with or without its leading dot and in any casing - and an entry containing a slash is treated as a MIME type instead, with a trailing wildcard like image/* covering a whole group. When Accept is not set, the list also generates the accept attribute on its own, which is why setting AllowedExtensions alone is usually all you need; set Accept explicitly only when the dialog filter should differ from the rule.

Accept only (the dialog filters, but a dropped file of any type is still taken and uploaded):

AllowedExtensions (the rule, which also generates the accept attribute):

MIME types (every image plus PDFs):

MaxCount caps how many files the list can hold - 3 in this example. Files arriving beyond the cap stay visible but are marked as not allowed with the MaxCountErrorMessage and never uploaded, so the user sees exactly which files did not make it instead of them disappearing silently. Only files that pass the other validations consume a slot, so a file rejected for its size or type never pushes a good file over the cap, and a file already uploading or uploaded keeps the slot it holds rather than being taken back by a later selection. Combined with Append the cap applies to the whole accumulated list, not just a single selection - and since the cap is re-evaluated on every change, removing a file takes the next one waiting behind it back in.

When the built-in checks are not enough, FileValidator runs a custom function for each newly selected file after those checks pass. Returning an error message marks the file as not allowed and shows the message under it - the file is never uploaded; returning null accepts the file. Any rule expressible over the file's metadata works - this example rejects empty (zero-byte) files. A validator that throws only invalidates its own file, using the exception message as the error text, rather than aborting the whole selection.

Directory turns the picker into a folder picker: the dialog asks for a directory instead of a file and every file inside it - and inside its subfolders, at any depth - lands in the list as a separate upload with its own progress and status. It does the same for a drag and drop, walking a dropped folder into its contents rather than ignoring it, which the plain file input cannot do on its own. The browser warns the user before handing a whole folder over, and the usual validations still apply to every file that comes out of it, so pairing it with AllowedExtensions, MaxCount or MaxTotalSize is what keeps a stray folder from turning into a thousand uploads. Pair it with ConcurrentUploads to keep the transfers orderly.

On a phone or a tablet, Capture asks the browser to open the camera or the microphone directly instead of the file browser, which turns the uploader into a one-tap "take a photo and send it" control. "user" asks for the front (selfie) camera and "environment" for the rear one; which one is actually honored is up to the device, and a desktop browser ignores the attribute altogether and opens the usual file dialog. Combine it with Accept to say what kind of capture is wanted - an image, a video or an audio recording - and with AutoUpload so the shot goes out the moment it is taken.

A file name is a poor way to tell one photo from another, so ShowPreview puts a thumbnail of every selected image at the head of its file item, letting the user confirm they picked the right picture before a single byte goes out. The thumbnail is produced entirely in the browser from an object URL, so nothing is uploaded to render it and non-image files simply keep the plain item. The URL is also handed back as soon as the file is removed or the component is reset, which is what keeps a long-lived page from holding every picture ever picked in memory. BitFileInfo.PreviewUrl exposes the same URL for a custom FileViewTemplate, and Classes.Preview / Styles.Preview restyle the built-in thumbnail.

A size limit in bytes is a poor way to say "no tiny avatars" or "nothing bigger than 4K": what matters for an image is its pixels, and a heavily compressed photo can be small in bytes and enormous on screen. ReadImageDimensions decodes every selected image right in the browser and fills the Width and Height of its BitFileInfo before the validations run, so a FileValidator can turn an image away for its dimensions without a single byte leaving the machine - and the rejected file stays in the list with its reason, exactly like any other rejection.

Decoding is not free: a folder full of photos costs time and memory to walk through, which is why it is off by default and why the decoding runs a few images at a time rather than all at once. Non-image files, and images the browser cannot decode, simply keep both values null - a validator has to treat that as "unknown" rather than as a failure. The values are also there for a custom FileViewTemplate to render, as the second uploader below does.

Between 200x200 and 4000x4000 pixels:

Showing the dimensions of each image:

ShowRemoveButton puts a remove button on each settled file item. A file whose bytes never reached the server is simply dropped from the view, while a file that has (partially or fully) uploaded is deleted from the server through a DELETE request to the RemoveUrl, carrying the file name as a query string and the file id in the BIT_FILE_ID header; a non-success response marks the file with the FailedRemoveMessage instead of pretending it is gone. RemoveButtonTitle localizes the button tooltip and its accessible label.

Every stage of the process surfaces through a callback: OnChange fires whenever a file's status changes, OnInvalid right after it whenever a selection carries rejected files - handy for driving a summary or blocking a submit button - OnUploading right before a file's first request (the natural place to attach per-file HTTP headers like below), OnProgress on every progress tick, OnUploadComplete / OnUploadFailed when a file settles, OnRemoveComplete / OnRemoveFailed for removals, and OnAllUploadsComplete once the whole batch has reached a terminal state, which is what drives the message below. Try a file over 1 MB to see OnInvalid at work.

No File

The upload and remove requests are fully customizable. Static UploadRequestHttpHeaders / RemoveRequestHttpHeaders and UploadRequestQueryStrings / RemoveRequestQueryStrings attach headers and query strings to the respective requests, and UploadRequestFormFields adds extra multipart fields next to the file content itself - the target folder, an album id, a caption - for the endpoints that read their metadata from the form rather than from the URL.

Each of the three has an async ...Provider counterpart, and the difference is not only that it is a function: a provider is invoked right before every single request - each file, and each chunk of a chunked file - while the static values are fixed once, when the files are selected. That is what makes a provider the right place for anything that expires: an access token that has to be fresh when the request actually goes out, or a presigned URL good for one upload only, which UploadUrlProvider mints for the endpoint itself. A value that never changes belongs in the static parameter instead, since a provider costs an await per request.

Requests so far: 0

The transport itself is configurable too: UploadRequestHttpMethod switches the verb ("POST" by default - a PUT is what presigned URL flows usually expect), UploadFormFieldName renames the form field carrying the file content ("file" by default), WithCredentials sends cookies and authorization headers along on cross-origin requests, and UploadTimeout fails a request - each file or chunk - that takes longer than the given time. On the other side, RemoveRequestHttpMethod does the same for the removal, whose "DELETE" some APIs would rather receive as a "POST".

ChunkedUpload slices each file and sends it as a series of sequential requests instead of one monolithic one, which is what makes pausing, resuming and recovering large uploads practical: a paused or failed file resumes from the last successfully uploaded chunk rather than starting over, so a dropped connection costs one chunk instead of the whole transfer. ChunkSize pins the size of each slice in bytes, while AutoChunkSize adapts it to the observed connection speed on the fly, between 512 KB and 10 MB - large enough on a fast link to keep the request overhead negligible, small enough on a slow one to keep the progress moving and a retry cheap.

The server side reassembles the file, and every chunk request carries what it needs to do so reliably: the BIT_FILE_ID header correlating the chunks of one file, and the byte range of the chunk both as the standard Content-Range header (bytes from-to/total) and as the plain BIT_CHUNK_FROM, BIT_CHUNK_TO and BIT_FILE_SIZE headers for the handlers that would rather not parse it. Writing each chunk at its own offset rather than blindly appending is what makes the server correct in the face of a retried chunk. Note that CORS treats these as custom request headers, so a cross-origin endpoint has to allow them.

Adaptive chunk sizing:

Networks fail, so a professional uploader plans for it. AutoRetries retries a failed upload automatically - up to the given number of times per file, waiting AutoRetryDelay before each attempt - and in the chunked mode every retry resumes from the last successfully uploaded chunk instead of starting over. Pausing or canceling a file while a retry is still waiting out its delay wins over that retry, so the outcome the user asked for is the one that stands.

Not every failure deserves another attempt, so the budget is only spent where a second try could go differently: network errors, timeouts, 408, 429 and the 5xx server errors are retried, while the other 4xx - a 404 pointing nowhere, a 413 that is simply too large, a 401 - settle the file immediately rather than repeating an identical doomed request. ShouldAutoRetry replaces that rule with your own, receiving the file and the status code and returning whether to retry.

Once the automatic budget is exhausted the file settles as failed, and the item offers a retry button - distinct from the plain upload button of a never-started file, both in its icon and in its wording, so a second attempt never reads as a first one. Pressing it tries again with a fresh automatic budget, exactly like calling Upload with that file from code does. RetryIcon, RetryIconName and RetryButtonTitle restyle and localize it, falling back to their upload counterparts when unset.

A non-existing endpoint (404): the built-in rule does not retry it, so the file fails at once and offers the manual retry button.

The same endpoint with a ShouldAutoRetry that insists: watch it retry twice before settling.

By default every file of a batch is put on the wire at once, which is the fastest option on a healthy connection but not always the kindest one: browsers only keep a handful of connections open per host, and a server behind a rate limit or a slow disk would rather not meet fifty simultaneous uploads. ConcurrentUploads caps how many files may be in flight at the same time; the rest wait in a queue in selection order and each one starts the moment a slot frees up - whether the file holding it completed, failed, was canceled or was merely paused. Set it to 0 (the default) to keep starting everything at once.

The cap counts files, not requests: a chunked file holds its single slot for the whole run of its chunks rather than going back to the end of the queue between two of them. Note that the queue only governs the start of an upload, so a file started explicitly through Upload(file) waits its turn just like a file of a batch does.

A file waiting for its turn says so rather than looking exactly like one nobody asked to upload: its item shows the QueuedUploadMessage - "Waiting to upload" by default, and the place to translate it - drops the start button, since starting something already on its way would do nothing, and keeps a cancel button so it can be called off before its turn ever comes. BitFileInfo.IsQueued exposes the same state to a custom FileViewTemplate.

Two files at a time:

One file at a time (a strictly sequential queue), with a translated waiting message:

Besides the per-file progress, the component aggregates the batch as a whole: TotalSize and TotalUploadedSize expose the combined byte counts of the files that are actually being uploaded - rejected and removed files do not count - and OverallUploadProgress turns them into a single percentage, weighting every file by its size. Rendering it is a matter of re-reading those properties whenever OnProgress or OnChange fires, which is exactly what drives the BitProgress below. Select several files and upload them all to see the combined bar move.

A percentage answers "how far along is this"; what a user waiting on a large upload actually wants to know is "how much longer". Every running file measures the speed of the request currently in flight and exposes it on its BitFileInfo: UploadSpeed in bytes per second and RemainingTime as a TimeSpan derived from it and the bytes still to send. Both are null while a file is not on the wire - before it starts, once it settles, and for the first fraction of a second of a request, where a reading taken over almost no time would say nothing but a huge number.

They are updated on every progress tick, so rendering them is a matter of re-reading them from OnProgress, as the summary below does. In the chunked mode the speed is measured over the chunk in flight, which is what makes it follow a connection that speeds up or slows down mid-file instead of averaging the whole transfer into a number that stops reacting.

The batch has the same two numbers of its own: TotalUploadSpeed adds up the speed of every file currently on the wire - what the connection as a whole is carrying, which is the honest figure when several files are uploading at once - and OverallRemainingTime divides the bytes still to go by it. Both are null while nothing is uploading, which is the difference between "not moving" and "moving at zero".

Each file item shows its uploaded and total size through a built-in humanizer that speaks English and counts in binary units. FileSizeFormatter takes that decision over: it receives a size in bytes and returns whatever text should appear, which is where a localized unit name, a different rounding, or the decimal base some platforms prefer belongs. The example below drops down to raw byte counts with thousands separators.

HideFileView takes the built-in file list away without taking the files with it: they are still selected, still validated, still uploaded and still reported through Files and the callbacks - they are simply not drawn. That is what you want when the surrounding page already shows the attachments in its own layout, when the uploader has to collapse into a single button, or when the list belongs somewhere else on the screen entirely. The example below renders its own summary from the OnChange callback while the component itself shows nothing but the browse button. Reach for FileViewTemplate instead when the list should stay where it is and only look different.

No file selected yet.

The default UI can be swapped out entirely: LabelTemplate replaces the browse button - here with a full drop-zone panel that hides itself once files are selected - and FileViewTemplate replaces each item of the file list, receiving the file info as its context with its name, size, progress, speed and status all available for rendering. The template is only asked for the files that are actually in the list, so a removed file never leaves an empty item behind. Replacing the browse button also replaces the built-in dashed drop indicator that lives on it, so a custom label should bring its own drag feedback: Classes.Dragging puts a class on the root element for as long as files hover over the component.

Two things are worth carrying over from the default UI when replacing it. The controls should be real button elements rather than clickable divs or icons, so they stay reachable with Tab and can be activated with Enter or Space, and each of them should name the file it acts on through an aria-label - a list of identical "Remove" buttons tells a screen reader user nothing about which file they are on. And since the context is the file itself, the per-file overloads are the ones to call: Upload(file) and RemoveFile(file) act on that one file, while their no-argument forms would sweep through the whole batch.

The component can be driven entirely from code: Browse opens the file dialog (here the built-in browse button is hidden with HideLabel and replaced by external BitButtons), Upload starts the upload of a specific file or every file, PauseUpload and CancelUpload stop them, RemoveFile removes files, and Reset clears the whole state. Each of them takes a single file or, with no argument, applies to the whole batch. Files exposes the current selection with each file's status and progress, and UploadStatus reports the state of the batch as a whole - pending until the first upload starts, in progress from then on, and completed once every file has reached a terminal state.

The difference between the two ways of stopping is what happens next. PauseUpload applies to the files that are actually on their way: it aborts the in-flight request and keeps the bytes that made it, so calling Upload again resumes from there - from the last completed chunk in the chunked mode - and it takes a file still waiting in the concurrency queue back out of that queue. A file nobody asked to upload has nothing to pause, so it is left exactly as it is.

CancelUpload settles the file as canceled instead, and does so immediately whether it was running, waiting in the queue, paused or merely selected, so the outcome is visible on every file rather than being recorded as an intention on some of them. Files that have already settled are left alone: a completed upload cannot be taken back from the server by anything happening on this side, and calling off a file that already failed would only replace the reason it failed with a less useful one. A canceled file can still be started again later, and its item offers the retry button for exactly that.

The BitFileUpload is accessible out of the box: the browse button is a real button - focusable with Tab and activated with Enter or Space - the hidden native input points to it via aria-labelledby, the file list carries list and listitem roles, every action button (upload, pause, cancel, remove) gets an aria-label naming the file it acts on, and the progress bar exposes its percentage through the progressbar role. A visually hidden live region announces the selection and every upload outcome, so a screen reader user hears how many files were taken, which uploads succeeded and which failed without having to go looking. AnnouncementProvider replaces that built-in English sentence with text of your own - the natural place to translate it or to word it around your domain, as the second example does. AriaLabel labels the browse button, overriding its visible text for assistive technologies when a short label does not say enough on its own.

The browse button is the visual weight the component carries on a page, and Variant decides how much of it there is. Fill - the default - paints the button in a solid block of the Color and is the right call when uploading is the main thing the screen is for. Outline keeps only the rule around it in that color and fills in on hover, for an uploader sitting among other form fields that should not shout over them. Text drops both the rule and the fill, leaving a colored label for the places where the uploader is a secondary affordance. The drop indicator and the file list follow the variant along, and a disabled component drops the role colors entirely for the neutral disabled look, whichever variant it uses.

Color picks the role color the component speaks in. It is not only the browse button: the dashed drop indicator, the progress bar of every running file, the paused status message, the removal spinner and the hovered action buttons all take it, so the whole control reads as one piece instead of a themed button next to a default-blue list. All the standard bit color roles are available - the semantic ones (Primary, Secondary, Tertiary, Info, Success, Warning, SevereWarning, Error) as well as the background, foreground and border families - each of them carrying its own hover and active shades and its own readable on-color for the label.

Background, foreground and border colors:

The action button icons are not limited to the built-in icon font: UploadIcon, RetryIcon, PauseIcon, CancelIcon and RemoveIcon take a BitIconInfo or a raw CSS class string that can point at any icon library whose stylesheet is loaded, like FontAwesome or Bootstrap Icons below. Use BitIconInfo.Fa(), BitIconInfo.Bi() or BitIconInfo.Css() to build one, or stick with the built-in font and just pick different icons via the ...IconName counterparts. Upload a file against a failing endpoint to see the retry icon take the place of the upload one.

FontAwesome:

Bootstrap:

Size scales the whole control in one move - the height, padding and font of the browse button, the text of the file items and their size line, the action buttons and their icons, and the image preview thumbnails all step together, so a Small uploader tucked into a dense form and a Large one headlining a drop area both stay internally proportioned. Medium is the default. The dimensions come from CSS custom properties on the root element, so a size can still be fine-tuned from Styles without redefining the whole scale.

Style and Class land on the root element, which inline styles and a single class cover well. For anything deeper, Styles and Classes reach the individual parts - the browse button, the description, the file list, each file item, its name, size, percentage, progress bar, status message and every action button and icon - and their Dragging entry applies to the root element only while files are being dragged over the component, which is how the examples below restyle the drop state without touching the idle look.

Component's Style & Class:

Styles & Classes:

Setting Dir to BitDir.Rtl mirrors the whole layout for right-to-left languages - the browse button, the file names, sizes, progress bars and action buttons all follow - and the localizable texts (the Label, the status messages and the button titles) complete the picture, so the BitFileUpload reads naturally inside an RTL page like the Farsi example below.