On this page
@addTagHelper *, Webority.Ui.RazorThe dropzone
Use the dropzone for one file, a click or a drop, and a preview once a file is picked.
Preview and remove
Show a large preview once a file is picked, so the person can check it and remove it.
Multiple files
Add multiple to stack several picked files in a list, each with its own remove control.
Errors and helper text
Mark the field required, and show helper text or an error in the slot below the zone.
Loading
Set loading while the chosen file uploads, so a spinner blocks picking until it settles.
Width
Cap the zone to a fixed width with a width class, or leave it full width to match the fields beside it.
Every option
Every value of every prop, one cell each.
label
label="Structure photo"value
value={null} (default), React only: the field starts empty herevalue={File}: image thumbnail, React onlyvalue={{ url, name }}: existing image, React onlyvalue={File}: PDF first page, React onlyonChange
onChange={…} (React only): called with the validated File, or null when clearedmultiple
multiple="false" (default)multiple="true", emptymultiple, populated (image and pdf): React only, value={[File, File]}maxFiles
max-files="1": caps the total files acceptedvariant
variant="dropzone" (default)variant="button"buttonLabel
button-label="Add file" (default, with variant="button")browseLabel
browse-label="Click to upload" (default)optionalLabel
optional-label="(optional)" (default, with optional)changeImageLabel
change-image-label="Change image" (default): hover text on a picked imagechangeFileLabel
change-file-label="Change file" (default): hover text on a picked filemaxFilesText
max-files-text="Up to {count} files." (default, with multiple)removeFileLabel
remove-file-label="Remove {name}" (default): the remove control on each picked filerequired
required="false" (default)required="true"optional
optional="false" (default)optional="true"error
error="This field is required."helperText
helper-text="PNG or JPG, up to 5 MB."helper-text and error (the error takes the slot)loading
loading="false" (default)loading="true"disabled
disabled="false" (default)disabled="true"help
help="Photograph the whole structure."helpLabel
help-label="More information" (default): the info tip button namename
name="structurePhoto"id
id="structurePhoto": React only, the DOM id of the file inputaccept
accept=".jpg,.jpeg,.png" (default)accept="image/*"accept="image/*,application/pdf"accept="application/pdf"accept=".csv,.xlsx"dropLabel
drop-label="or drag & drop" (default)maxSizeText
max-size-text="up to {size} MB" (default)readOnly
read-only="false" (default)read-only="true"size
size="sm"size="md" (default)size="lg"maxSizeMb
max-size-mb="5" (default)max-size-mb="0": no size limit, the format line names no sizeclassName
input-class: extra classes on the control element (React className)fieldClassName
class (default): no width presetclass="file-w-sm"class="file-w-md"class="file-w-lg"class="file-w-full"Guidance
What to do, and what to avoid.
Use it when
- A single, visually important image is being uploaded: a photo, a cover, a scan.
- The preview matters: the user should see the picture they chose, large.
- You want drag and drop plus a click target in one field, with type and size validation handled.
Reach for something else when
- You are attaching a file where the name and size matter more than a big preview. → AppFileAttachment
- The upload is a round avatar or a company logo in a header. → AppImagePicker
- It is a plain, non-image file input with no preview. → a labelled AppInput
- You hand-roll a raw <input type="file"> with custom styling. → AppFilePicker
Give the field a specific label
Give the field a specific label, "Structure photo" rather than "Upload", so the user knows what image belongs here.
A vague "File" label leaves the user guessing what to drop, and mixes with the format line already in the zone.
Show validation beside the field
Surface validation with a message below the zone, in the field's own error style, so the eye lands on it next to the control.
A required field with no message on submit leaves the user unsure why the form will not save.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
28 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The label shown above the field. |
| namedefault - | string | - | Form field name. |
| acceptdefault .jpg,.jpeg,.png | string | .jpg,.jpeg,.png | Accepted file types (the accept attribute). Widen it, for example image/*,application/pdf, and non-image files show a file-type icon instead of a thumbnail. |
| multipledefault false | bool | false | Lets the person pick several files. They stack in a list inside the dropzone. |
Less common 24 props
| Prop | Type | Default | Description |
|---|---|---|---|
| max-filesdefault - | int | - | Cap on total files in multiple mode. |
| variantdefault dropzone | dropzone | button | dropzone | dropzone is the tall drop target. button is a small outline button that opens the file dialog, with no preview and no list. |
| button-labeldefault Add file | string | Add file | The button form's text. |
| 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 | Follows the browse text in the dropzone. Replaces the built-in English text, for other languages. |
| change-image-labeldefault Change image | string | Change image | Replaces the built-in English text, for other languages. |
| change-file-labeldefault Change file | string | Change file | Replaces the built-in English text, for other languages. |
| max-files-textdefault Up to {count} files. | string | Up to {count} files. | Replaces the built-in English text, for other languages. {count} is replaced with the cap. |
| remove-file-labeldefault Remove {name} | string | Remove {name} | Replaces the built-in English text, for other languages. Token: {name}, the file name. |
| max-size-textdefault up to {size} MB | string | up to {size} MB | The size cap in the helper text; {size} is the limit in MB. Replaces the built-in English text, for other languages. |
| optional-labeldefault (optional) | string | (optional) | Replaces the built-in English text, for other languages. |
| requireddefault false | bool | false | Marks the field as required in its label. |
| optionaldefault false | bool | false | Ends the label with (optional) when the field is not required. Required wins when both are set. |
| errordefault - | string | - | A message from the page, shown below the control. |
| helper-textdefault - | string | - | Helper text below the control. An error (the page's or a rejected pick's) replaces it while it shows. |
| disableddefault false | bool | false | Locks the picker and keeps it out of the form post. |
| read-onlydefault false | bool | false | Shows the value but blocks picking, dropping, changing and removing. |
| helpdefault - | string | - | Info-tip content shown beside the label. |
| help-labeldefault More information | string | More information | The accessible name of the info-tip button. |
| loadingdefault false | bool | false | Spinner over the control and picking blocked, for example while the chosen file uploads. |
| max-size-mbdefault 5 | int | 5 | The size limit in megabytes. Defaults to the shared limit. 0 means no size limit: nothing is rejected for its size, and the helper text names no size. |
| classdefault - | string | - | Extra class on the field wrapper, for example a file-w-* width preset. |
| input-classdefault - | string | - | Extra classes on the control itself (the dropzone), the React className counterpart. The plain class attribute styles the field wrapper instead. |
| sizedefault md | sm | md | lg | md | The control height: sm, md or lg. |
Screen reader
4 notes- The label is tied to the file input, and the dropzone is a label for the same input, so the zone opens the picker by click or keyboard.
- A shown error or helper text is linked to the file input through aria-describedby.
- While loading, the control is marked aria-busy and a spinner with the status role named Loading shows.
- In single mode the preview has a button to change the file and a separate remove button, each with an accessible name.
Do and avoid
2 pairsGive the field a specific label
Give the field a specific label, "Structure photo" rather than "Upload", so the user knows what image belongs here.
A vague "File" label leaves the user guessing what to drop, and mixes with the format line already in the zone.
Show validation beside the field
Surface validation with a message below the zone, in the field's own error style, so the eye lands on it next to the control.
A required field with no message on submit leaves the user unsure why the form will not save.