Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

The attach row

Use the attach row for one file; the field shows a thumbnail, name and size once a file is chosen.

Browse, then thumbnail and name
Show code
<app-file-attachment name="ticketAttachment" label="Ticket attachment" optional="true" />

Accepted types

Narrow accept to the formats you handle, so the field rejects others before the choice is reported.

PNG and JPG only
Show code
<app-file-attachment name="ticketAttachment" label="Ticket attachment" accept="image/png,image/jpeg" optional="true" />

Multiple and file types

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

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

Optional and errors

Mark the field optional, and show a submit-time error below the row when a value is missing.

Optional, and a submit-time error
File is required
Show code
<app-file-attachment name="ticketAttachment" label="Ticket attachment" optional="true" />
<app-file-attachment name="photo" label="Photo" error="File is required" />

Filled, uploading and failed

Show a file's size, upload progress and error on its row, each only when it is set.

Filled, uploading and failed
site-photo.jpg1.5 MB
scan.tiff5.2 MB
This file is larger than 5 MB.
Show code
<app-file-attachment name="attachments" label="Attachments" multiple="true" accept="">
  <app-file-attachment-file name="invoice-march.pdf" url="#" size-bytes="248320" />
  <app-file-attachment-file name="site-photo.jpg" size-bytes="1572864" progress="45" />
  <app-file-attachment-file name="scan.tiff" size-bytes="5452595" error="This file is larger than 5 MB." />
</app-file-attachment>

Every option

Every value of every prop, one cell each.

label

label="Photo": the label shown above the field

value

value={null} (default): React form, an empty field
value={EXISTING_IMAGE}: React form, a stored image as a child element
value={EXISTING_DOC}: React form, a stored file as a child element

name

name="optName": the form field name the file posts under

onChange

onChange: React calls it with each pick, Razor posts the file under name

multiple

multiple="false" (default): one file, one drop row
multiple="true": a stacked list, each with its own remove

accept

accept="image/png,image/jpeg,image/webp" (default)
accept="image/png,image/jpeg"
accept="image/png,image/jpeg,application/pdf"
accept="application/pdf"
accept="": any file type, and the hint names no types

maxSizeMb / max-size-mb

max-size-mb="5" (default): a 5 MB limit
max-size-mb="0": no size limit, and the hint names no size

optional

optional="false" (default): no hint after the label
optional="true": adds (optional) after the label

validate

validate="true" (default): each pick is checked against accept and max-size-mb
validate="false": every pick reaches the page unchecked

error

error="File is required": a message from the page under the field
File is required

id

id="ticketFile", React only: the tag helper makes its own input id

browseLabel / browse-label

browse-label="Choose file": the button text on the drop row

removeLabel / remove-label

remove-label="Remove logo": the remove button on a stored image

uploadingLabel / uploading-label

uploading-label="Sending {name}": the progress bar name while a file uploads

maxSizeText / max-size-text

max-size-text="Limit {size} MB": the size hint when accept names no types

typesAndMaxSizeText / types-and-max-size-text

types-and-max-size-text="{types}, at most {size} MB": the hint when a type list and a size limit both apply

removeFileLabel / remove-file-label

remove-file-label="Delete {name}": the remove button on a file row

optionalLabel / optional-label

optional-label="(not required)": the text after the label when optional

dropTitle / drop-title

drop-title="Attach your invoice": the title of the drop row

<app-file-attachment-file>

url="#": the url links the name
to="#quote": the name opens this in-app address in place of url
size-bytes="248320": a size line is shown
invoice-march.pdf242.5 KB
progress="45": a bar shows while 0 to 99
site-photo.jpg1.5 MB
error="This file is larger than 5 MB.": the error shows under the row, which is marked failed
scan.tiff5.2 MB
This file is larger than 5 MB.

Guidance

What to do, and what to avoid.

Use it when

  • A file is attached to a record, such as a ticket, a message or a comment, as evidence.
  • The filename and size matter more than seeing the picture large.
  • You want type and size validation and preview handling done for you in a compact row.

Reach for something else when

  • The image is the star and the user should see it large. → AppFilePicker
  • The upload is a round avatar or a company logo. → AppImagePicker
  • It is a plain text or number field, not a file. → AppInput
  • You hand-roll a raw <input type="file"> with custom markup. → AppFileAttachment

Name the row and limit types

Do

Give the row a specific label and restrict the accepted types, so the user knows what belongs here and what is allowed before they pick.

Avoid

A bare "Attach" label with no constraints leaves the user unsure what belongs here or what the field accepts.

Make a required file's requirement visible

Do
File is required

Surface a submit-time requirement with a message below the row, in the field's error style.

Avoid

Marking a genuinely required attachment "optional" mis-signals that it can be skipped.

Reference

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

image/png,image/jpeg,image/webp image/png,image/jpeg image/png,image/jpeg,application/pdf application/pdf
true false
React, generated from the controls
const [value, setValue] = useState(null);

<AppFileAttachment
  value={value}
  onChange={setValue}
  name="pgAttachment"
/>
Razor, the same props
<app-file-attachment name="pgAttachment" />

17 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
namedefault - string - Form field name, so an uncontrolled form can post the file.
labeldefault Attachment string Attachment The label shown above the field.
acceptdefault image/png,image/jpeg,image/webp string image/png,image/jpeg,image/webp The file types the field takes, as an accept list. Defaults to images; pass for example image/*,application/pdf for mixed. An empty string accepts any file type, and the helper text then names no types.
multipledefault false bool false Lets the person attach several files. They stack in a list and each one removes on its own.

Less common 13 props

PropTypeDefaultDescription
optionaldefault false bool false Adds (optional) after the label.
optional-labeldefault (optional) string (optional) Replaces the built-in English text, for other languages.
browse-labeldefault Browse string Browse Replaces the built-in English text, for other languages.
remove-labeldefault Remove attachment string Remove attachment Replaces the built-in English text, for other languages.
uploading-labeldefault Uploading {name} string Uploading {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 Replaces the built-in English text, for other languages. Token: {size}, the size limit in megabytes.
types-and-max-size-textdefault {types}, up to {size} MB string {types}, up to {size} MB Replaces the built-in English text, for other languages. Tokens: {types}, the accepted types, and {size}, the size limit in megabytes.
remove-file-labeldefault Remove {name} string Remove {name} Replaces the built-in English text, for other languages. Token: {name}, the file name.
drop-titledefault Add a file, Add an image, Add files or Add images, chosen from accept and multiple string Add a file, Add an image, Add files or Add images, chosen from accept and multiple Replaces the drop row's title, for other languages. Default text depends on accept and multiple.
errordefault - string - A message from the page, shown below the field beside the field's own validation messages.
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.
validatedefault true bool true Checks each pick against accept and max-size-mb and shows the field's own message for a rejected file. Set false when the page validates the files itself and shows its own message through error, so every pick reaches the page and the person never sees two messages in two voices for one problem. accept and max-size-mb still set the picker filter and the helper text.
<app-file-attachment-file>default - element - A file already attached to the field, as a child of <app-file-attachment>. Attributes: name (string), url (string; links the name and gives a stored image its picture), to (string; an in-app address the name links to in place of url, such as the product's file viewer; draws no picture), size-bytes (long; shown as a size), progress (int 0 to 100; a bar shows while it is 0 to 99), error (string; shown under the row, which is marked failed).

Screen reader

3 notes
  • The label is tied to the file input, and the drop row is a label for the same input, so clicking or pressing the row opens the picker.
  • A shown error is linked to the file input through aria-describedby.
  • The remove control is a button named Remove attachment.

Do and avoid

2 pairs

Name the row and limit types

Do

Give the row a specific label and restrict the accepted types, so the user knows what belongs here and what is allowed before they pick.

Avoid

A bare "Attach" label with no constraints leaves the user unsure what belongs here or what the field accepts.

Make a required file's requirement visible

Do
File is required

Surface a submit-time requirement with a message below the row, in the field's error style.

Avoid

Marking a genuinely required attachment "optional" mis-signals that it can be skipped.