Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

The dropzone

Use the dropzone for one file, a click or a drop, and a preview once a file is picked.

Click or drag and drop
Show code
<app-file-picker label="Structure photo" name="structurePhoto" />

Preview and remove

Show a large preview once a file is picked, so the person can check it and remove it.

The chosen image, in place
Show code
<app-file-picker label="Structure photo" name="structurePhoto" />

Multiple files

Add multiple to stack several picked files in a list, each with its own remove control.

Multiple, mixed types
Show code
<app-file-picker label="Attachments" name="attachments" multiple="true" max-files="5" accept="image/png,image/jpeg,application/pdf" />

Errors and helper text

Mark the field required, and show helper text or an error in the slot below the zone.

With helper text, and required with an error
A clear photo of the whole structure, taken in daylight.
helper-text
Logo is required
required, error
Show code
<app-file-picker label="Structure photo" name="structurePhoto" helper-text="A clear photo of the whole structure, taken in daylight." />
<app-file-picker label="Company logo" name="logo" required="true" error="Logo is required" />

Loading

Set loading while the chosen file uploads, so a spinner blocks picking until it settles.

Uploading a chosen file
Show code
<app-file-picker label="Structure photo" name="structurePhoto" loading="true" />

Width

Cap the zone to a fixed width with a width class, or leave it full width to match the fields beside it.

Fixed-width dropzone
Show code
<app-file-picker label="Structure photo" name="width" class="file-w-md" />

Every option

Every value of every prop, one cell each.

label

label="Structure photo"

value

value={null} (default), React only: the field starts empty here
value={File}: image thumbnail, React only
value={{ url, name }}: existing image, React only
value={File}: PDF first page, React only

onChange

onChange={…} (React only): called with the validated File, or null when cleared

multiple

multiple="false" (default)
multiple="true", empty
multiple, populated (image and pdf): React only, value={[File, File]}

maxFiles

max-files="1": caps the total files accepted

variant

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 image

changeFileLabel

change-file-label="Change file" (default): hover text on a picked file

maxFilesText

max-files-text="Up to {count} files." (default, with multiple)

removeFileLabel

remove-file-label="Remove {name}" (default): the remove control on each picked file

required

required="false" (default)
required="true"

optional

optional="false" (default)
optional="true"

error

error="This field is required."
This field is required.

helperText

helper-text="PNG or JPG, up to 5 MB."
PNG or JPG, up to 5 MB.
helper-text and error (the error takes the slot)
PNG or JPG, up to 5 MB.
This field is required.

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 name

name

name="structurePhoto"

id

id="structurePhoto": React only, the DOM id of the file input

accept

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 size

className

input-class: extra classes on the control element (React className)

fieldClassName

class (default): no width preset
class="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

Do

Give the field a specific label, "Structure photo" rather than "Upload", so the user knows what image belongs here.

Avoid

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

Do
Logo is required

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.

Avoid

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.

.jpg,.jpeg,.png image/* image/*,application/pdf application/pdf .csv,.xlsx
dropzone button
(default) sm md lg
React, generated from the controls
<AppFilePicker
  label="Structure photo"
  name="playgroundFile"
  value={file}
  onChange={setFile}
  helpLabel="More information"
/>
Razor, the same props
<app-file-picker label="Structure photo" name="playgroundFile" />

28 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Give the field a specific label

Do

Give the field a specific label, "Structure photo" rather than "Upload", so the user knows what image belongs here.

Avoid

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

Do
Logo is required

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.

Avoid

A required field with no message on submit leaves the user unsure why the form will not save.