On this page
@addTagHelper *, Webority.Ui.RazorThe attach row
Use the attach row for one file; the field shows a thumbnail, name and size once a file is chosen.
Accepted types
Narrow accept to the formats you handle, so the field rejects others before the choice is reported.
Multiple and file types
Add multiple to stack picked files in a list, each with its own remove control.
Optional and errors
Mark the field optional, and show a submit-time error below the row when a value is missing.
Filled, uploading and failed
Show a file's size, upload progress and error on its row, each only when it is set.
Every option
Every value of every prop, one cell each.
label
label="Photo": the label shown above the fieldvalue
value={null} (default): React form, an empty fieldvalue={EXISTING_IMAGE}: React form, a stored image as a child elementvalue={EXISTING_DOC}: React form, a stored file as a child elementname
name="optName": the form field name the file posts underonChange
onChange: React calls it with each pick, Razor posts the file under namemultiple
multiple="false" (default): one file, one drop rowmultiple="true": a stacked list, each with its own removeaccept
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 typesmaxSizeMb / max-size-mb
max-size-mb="5" (default): a 5 MB limitmax-size-mb="0": no size limit, and the hint names no sizeoptional
optional="false" (default): no hint after the labeloptional="true": adds (optional) after the labelvalidate
validate="true" (default): each pick is checked against accept and max-size-mbvalidate="false": every pick reaches the page uncheckederror
error="File is required": a message from the page under the fieldid
id="ticketFile", React only: the tag helper makes its own input idbrowseLabel / browse-label
browse-label="Choose file": the button text on the drop rowremoveLabel / remove-label
remove-label="Remove logo": the remove button on a stored imageuploadingLabel / uploading-label
uploading-label="Sending {name}": the progress bar name while a file uploadsmaxSizeText / max-size-text
max-size-text="Limit {size} MB": the size hint when accept names no typestypesAndMaxSizeText / 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 applyremoveFileLabel / remove-file-label
remove-file-label="Delete {name}": the remove button on a file rowoptionalLabel / optional-label
optional-label="(not required)": the text after the label when optionaldropTitle / drop-title
drop-title="Attach your invoice": the title of the drop row<app-file-attachment-file>
url="#": the url links the nameto="#quote": the name opens this in-app address in place of urlsize-bytes="248320": a size line is shownprogress="45": a bar shows while 0 to 99error="This file is larger than 5 MB.": the error shows under the row, which is marked failedGuidance
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
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.
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
Surface a submit-time requirement with a message below the row, in the field's error style.
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.
17 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsName the row and limit types
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.
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
Surface a submit-time requirement with a message below the row, in the field's error style.
Marking a genuinely required attachment "optional" mis-signals that it can be skipped.