Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Receiving the file

Take the validated file as it is picked or dropped; the zone keeps nothing, so the same file fires again.

Hand the file to the page
Unlike app-file-picker the zone posts nothing with a form and shows nothing back. Show progress, a name or a viewer yourself once the event fires.

Nothing received yet.

Show code
<app-drop-zone id="receive-zone" label="Contract" accept=".pdf" />

document.addEventListener("wui:dropzone:change", (e) => upload(e.detail.file));

Multiple files

Take several files per pick or drop; rejected files are reported under the zone and left out.

A batch at a time

Nothing received yet.

Show code
<app-drop-zone id="multi-zone" label="Documents" accept=".pdf,.docx" multiple="true" />

Helper text and errors

Helper text sits below the zone; an error, yours or a rejected pick, takes that slot while it shows.

With helper text, and with an error
One signed contract per upload.
A contract is required.
Show code
<app-drop-zone label="Contract" accept=".pdf" helper-text="One signed contract per upload." />
<app-drop-zone label="Contract" error="A contract is required." />

Disabled

Disable the zone while the page cannot accept a file, such as before a required choice is made.

Not accepting files
Show code
<app-drop-zone label="Contract" disabled="true" />

Every option

Every value of every prop, one cell each.

label

label="Contract"

onChange: the validated file

wui:dropzone:change: called with the validated File (React: onChange)

multiple / maxSizeMb

multiple="false" (default)
multiple="true"
max-size-mb="5" (default)
max-size-mb="25"
max-size-mb="0": no size limit

accept: every preset

accept="" (default)
accept=".pdf"
accept=".pdf,.doc,.docx"
accept=".csv,.xlsx"
accept="image/*,application/pdf"

helper text / error / disabled

(default)
helper-text="…"
PDF only.
error="…"
This field is required.
helper text + error (the error takes the slot)
PDF only.
This field is required.
disabled

id

id="file-input": the file input DOM id, no visible change

className / input-class: width presets

input-class="file-w-sm" (React: className)
input-class="file-w-md" (React: className)
input-class="file-w-lg" (React: className)
input-class="file-w-full" (React: className)

browseLabel / dropLabel / anyTypeText / maxSizeText

browse-label="Click to upload" (default)
browse-label="Browse your computer"
drop-label="or drag & drop" (default)
drop-label="or drop it here"
any-type-text="Any file type" (default)
any-type-text="Any type of file"
max-size-text="up to {size} MB" (default)
max-size-text="at most {size} MB"

fieldClassName / class: wrapper class

class="mb-4": class on the wrapper field div (React: fieldClassName)

Guidance

What to do, and what to avoid.

Use it when

  • The page handles the file itself (upload, parse, import) and needs no preview in the field.
  • A document or spreadsheet is dropped in, not a picture the user wants to see back.
  • You want drag and drop plus a click target with type and size checks already done.

Reach for something else when

  • The field keeps a value and shows the chosen image large. → AppFilePicker
  • The file is a compact attachment on a form, listed by name and size. → AppFileAttachment
  • You hand-roll a raw file input with custom styling. → AppDropZone

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

(any file) .pdf .pdf,.doc,.docx .csv,.xlsx image/*,application/pdf
React, generated from the controls
<AppDropZone
  label="Contract"
  accept=".pdf"
  onChange={setFile}
/>
Razor, the same props
<app-drop-zone label="Contract" accept=".pdf" />

13 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
labeldefault - string - Text of the label above the zone.
multipledefault false bool false Take several files per pick or drop; the change handler then gets an array of files.
acceptdefault string Accepted file types, written as the accept attribute is. Empty takes any file.
max-size-mbdefault 5 int 5 Largest file size in megabytes, the shared limit when left out. 0 means no size limit: nothing is rejected for its size, and the format line names no size.
errordefault - string - Message below the zone; also styles the zone as errored.

Less common 8 props

PropTypeDefaultDescription
browse-labeldefault Click to upload string Click to upload Replaces the built-in English text, for other languages.
drop-labeldefault or drag & drop string or drag & drop Replaces the built-in English text, for other languages.
any-type-textdefault Any file type string Any file type Replaces the built-in English text, for other languages.
max-size-textdefault up to {size} MB string up to {size} MB The size cap in the format line; {size} is the limit in MB. Replaces the built-in English text, for other languages.
helper-textdefault - string - Helper text below the zone; an error, the caller's or a rejected pick's, replaces it while it shows.
disableddefault false bool false Blocks click and drop.
classdefault - string - Extra class on the field wrapper.
input-classdefault - string - Extra classes on the zone itself, e.g. a file-w-* width preset: the React className counterpart. The plain class attribute merges onto the .field wrapper instead.

Screen reader

3 notes
  • The zone is a label bound to a visually hidden native file input, so keyboard and screen reader users reach the same file chooser as a click.
  • The input is described by the helper text, or by the error when one shows, through aria-describedby.
  • A disabled zone sets aria-disabled, disables the input and ignores drops.